refactor(react): audit @pretable/react public surface; rename usePretableModel → usePretable

api-extractor.base.json

@@ -24,6 +24,9 @@
       },
       "ae-unresolved-link": {
         "logLevel": "none"
+      },
+      "ae-internal-missing-underscore": {
+        "logLevel": "none"
       }
     }
   },

apps/website/content/docs/grid/api-reference.mdx

@@ -174,7 +174,7 @@ interface SerializeRangesArgs<TRow> {
 
 ## `PretableGrid<TRow>` — model methods
 
-The `grid` returned by `usePretable` and `usePretableModel`.
+The `grid` returned by `usePretable`.
 
 | Method                                                                        | Description                                                                                     |
 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
@@ -206,7 +206,7 @@ The `grid` returned by `usePretable` and `usePretableModel`.
 | `setColumnPinned(columnId: string, pinned: "left" \| null): void`   | Explicit pin/unpin. Repositions the column to the pin-region boundary.                          |
 | `autosizeColumn(columnId: string, options?: AutosizeOptions): void` | Autosize a single column to its measured content width.                                         |
 | `resetColumnLayout(): void`                                         | Restore order, widths, and pinned state to the original `columns` prop snapshot taken at mount. |
-| `mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void`  | Internal: called by `usePretableModel` when the columns prop's id list changes structurally.    |
+| `mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void`  | Internal: called by `usePretable` when the columns prop's id list changes structurally.         |
 
 ## `PretableGridSnapshot<TRow>`
 
@@ -236,7 +236,7 @@ interface PretableGridSnapshot<TRow> {
 }
 ```
 
-Read via `grid.getSnapshot()` or directly from the `usePretableModel` return value.
+Read via `grid.getSnapshot()` or directly from the `usePretable` return value.
 
 ## `UsePretableOptions<TRow>` — `usePretable` arguments
 
@@ -251,10 +251,10 @@ interface UsePretableOptions<TRow> {
 
 `usePretable` returns just the `grid` model. Use it when you only need interaction state, not virtualization.
 
-## `UsePretableModelOptions<TRow>` — `usePretableModel` arguments
+## `UsePretableOptions<TRow>` — `usePretable` arguments
 
 ```ts
-interface UsePretableModelOptions<TRow> extends UsePretableOptions<TRow> {
+interface UsePretableOptions<TRow> extends UsePretableOptions<TRow> {
   viewportHeight: number;
   viewportWidth?: number;
   overscan?: number; // default 6
@@ -275,9 +275,9 @@ interface PretableSurfaceState {
 }
 ```
 
-`usePretableModel` returns `{grid, snapshot, renderSnapshot, telemetry}`. Use it when you need virtualization metadata for custom rendering.
+`usePretable` returns `{grid, snapshot, renderSnapshot, telemetry}`. Use it when you need virtualization metadata for custom rendering.
 
-## `PretableModel<TRow>` — `usePretableModel` return
+## `PretableModel<TRow>` — `usePretable` return
 
 ```ts
 interface PretableModel<TRow> {
@@ -344,9 +344,7 @@ Useful for instrumentation (frame budget tracking, visible-row counts, focus sur
 ```ts
 function usePretable<TRow>(opts: UsePretableOptions<TRow>): PretableGrid<TRow>;
 
-function usePretableModel<TRow>(
-  opts: UsePretableModelOptions<TRow>,
-): PretableModel<TRow>;
+function usePretable<TRow>(opts: UsePretableOptions<TRow>): PretableModel<TRow>;
 
 function useResolvedHeights(
   rowHeightProp?: number,

apps/website/content/docs/grid/custom-rendering.mdx

@@ -1,11 +1,11 @@
 ---
-title: Custom rendering with `usePretableModel`
-description: "usePretableModel exposes the engine state so you can render rows your own way."
+title: Custom rendering with `usePretable`
+description: "usePretable exposes the engine state so you can render rows your own way."
 nav: Grid
 order: 9
 ---
 
-`usePretableModel` returns the engine's full state: the grid model (with interaction methods), the snapshot (sort, filters, selection, focus), the render snapshot (which rows to render at what positions), and telemetry. You write your own JSX on top, applying the `[data-pretable-*]` attribute contract so `@pretable/ui/grid.css` styles the result.
+`usePretable` returns the engine's full state: the grid model (with interaction methods), the snapshot (sort, filters, selection, focus), the render snapshot (which rows to render at what positions), and telemetry. You write your own JSX on top, applying the `[data-pretable-*]` attribute contract so `@pretable/ui/grid.css` styles the result.
 
 This page walks through a minimal-but-complete example.
 
@@ -21,9 +21,9 @@ If none of these apply, the [\<Pretable\> drop-in](/docs/grid/pretable-component
 ## The hook
 
 ```ts
-import { usePretableModel } from "@pretable/react";
+import { usePretable } from "@pretable/react";
 
-const { grid, snapshot, renderSnapshot, telemetry } = usePretableModel({
+const { grid, snapshot, renderSnapshot, telemetry } = usePretable({
   columns,
   rows,
   viewportHeight,
@@ -49,7 +49,7 @@ See [API reference](/docs/grid/api-reference) for the full type signatures.
 ## A minimal working example
 
 ```tsx
-import { useResolvedHeights, usePretableModel } from "@pretable/react";
+import { useResolvedHeights, usePretable } from "@pretable/react";
 import type { PretableColumn, PretableRow } from "@pretable/react";
 
 interface Person extends PretableRow {
@@ -69,7 +69,7 @@ export function MyGrid({ rows }: { rows: Person[] }) {
   const { headerHeight } = useResolvedHeights();
   const viewportHeight = 480;
 
-  const { grid, snapshot, renderSnapshot } = usePretableModel({
+  const { grid, snapshot, renderSnapshot } = usePretable({
     columns,
     rows,
     viewportHeight,
@@ -220,7 +220,7 @@ The minimal example above is a starting point. For production grids, you'll like
 
 - **Keyboard navigation** — listen for `ArrowUp` / `ArrowDown` on the viewport and call `grid.moveFocus("up")` / `grid.moveFocus("down")`. The full keyboard contract (shift+arrow extend, Cmd/Ctrl+arrow jump, Tab wrap, Cmd+A, Esc) is wired by `<PretableSurface>` automatically.
 - **Pinned columns sticky positioning** — apply `position: sticky; left: ${pinnedOffset}px` to pinned cells. The bench's adapter computes pinned offsets via the same algorithm `<PretableSurface>` uses internally; see `packages/react-surface/src/rendering.ts` (function `getPinnedLeftOffsets`) for the canonical implementation.
-- **Per-row measured heights** — use `useLayoutEffect` to measure rendered row heights and pass `measuredHeights: Record<string, number>` to `usePretableModel` for content-aware sizing.
+- **Per-row measured heights** — use `useLayoutEffect` to measure rendered row heights and pass `measuredHeights: Record<string, number>` to `usePretable` for content-aware sizing.
 - **Filter inputs** — render a row of `<input>` elements above the body, debounce changes, and call `grid.setFilter(columnId, value)` per change.
 - **Telemetry instrumentation** — use the `telemetry` return value to track visible row counts, frame budget overruns, etc.
 

apps/website/content/docs/grid/density-helpers.mdx

@@ -49,7 +49,7 @@ The hook is SSR-safe. On the server (where `document` is undefined), the snapsho
 
 ### Used internally
 
-`<Pretable>` and `<PretableSurface>` (private) both use `useResolvedHeights` to compute the body viewport height (`viewportHeight - headerHeight`) and to size the sticky header. When you render with `usePretableModel`, you typically call `useResolvedHeights()` yourself to compute the same — see the example in [Custom rendering](/docs/grid/custom-rendering).
+`<Pretable>` and `<PretableSurface>` (private) both use `useResolvedHeights` to compute the body viewport height (`viewportHeight - headerHeight`) and to size the sticky header. When you render with `usePretable`, you typically call `useResolvedHeights()` yourself to compute the same — see the example in [Custom rendering](/docs/grid/custom-rendering).
 
 ## `getDensityHeights` — vanilla JS snapshot
 
@@ -76,10 +76,10 @@ Use this when:
 | React component that should re-render on density/theme change | `useResolvedHeights` from `@pretable/react`       |
 | Vanilla JS / non-React utility                                | `getDensityHeights` from `@pretable/ui`           |
 | One-shot read at component mount (no reactivity needed)       | Either; `getDensityHeights` is slightly leaner    |
-| Custom rendering with `usePretableModel`                      | `useResolvedHeights` (matches the engine's reads) |
+| Custom rendering with `usePretable`                           | `useResolvedHeights` (matches the engine's reads) |
 
 ## Where to go next
 
 - [Theming > Density switching](/docs/theming/density) — recipe for wiring `data-density` from React state.
-- [Custom rendering](/docs/grid/custom-rendering) — using `useResolvedHeights` with `usePretableModel`.
+- [Custom rendering](/docs/grid/custom-rendering) — using `useResolvedHeights` with `usePretable`.
 - [API reference](/docs/grid/api-reference) — full type signatures.

apps/website/content/docs/grid/index.mdx

@@ -29,13 +29,13 @@ What `<Pretable>` does NOT support out of the box:
 
 If you need any of the above, jump to Path 2.
 
-### Path 2: `usePretable` / `usePretableModel` hooks (custom rendering)
+### Path 2: `usePretable` hook (custom rendering)
 
 ```tsx
-import { usePretableModel } from "@pretable/react";
+import { usePretable } from "@pretable/react";
 
 function MyGrid({ rows, columns }) {
-  const { grid, snapshot, renderSnapshot, telemetry } = usePretableModel({
+  const { grid, snapshot, renderSnapshot, telemetry } = usePretable({
     columns,
     rows,
     viewportHeight: 480,
@@ -87,9 +87,9 @@ See [Density helpers](/docs/grid/density-helpers) for the hook API and SSR consi
 
 The engine has more capabilities than this section covers:
 
-- **Column autosize** — the `autosize` option on `usePretable` and `usePretableModel`; resizes columns to content. Not yet documented as a recipe.
+- **Column autosize** — the `autosize` option on `usePretable`; resizes columns to content. Not yet documented as a recipe.
 - **Streaming and transactions** — `grid.applyTransaction({add, update, remove})` for live row updates. Streaming Overview lands in a subsequent docs PR.
-- **Per-row measured heights** — pass `measuredHeights: Record<string, number>` to `usePretableModel` for content-aware row sizing. The bench's `pretable-adapter.tsx` shows this pattern.
+- **Per-row measured heights** — pass `measuredHeights: Record<string, number>` to `usePretable` for content-aware row sizing. The bench's `pretable-adapter.tsx` shows this pattern.
 
 These ship as part of `@pretable/react` today; full doc coverage lands in subsequent releases.
 
@@ -103,7 +103,7 @@ The engine ships full cell-range selection (Excel/Sheets semantics with shift-ex
 - [Selection](/docs/grid/selection) — cell-range model and three-state checkbox column.
 - [Keyboard](/docs/grid/keyboard) — full keyboard contract.
 - [Clipboard](/docs/grid/clipboard) — Cmd/Ctrl+C TSV defaults and overrides.
-- [Custom rendering](/docs/grid/custom-rendering) — `usePretableModel` walkthrough with code.
+- [Custom rendering](/docs/grid/custom-rendering) — `usePretable` walkthrough with code.
 - [Density helpers](/docs/grid/density-helpers) — `useResolvedHeights` and `getDensityHeights`.
 - [API reference](/docs/grid/api-reference) — model methods + types.
 - [Theming Overview](/docs/theming) — how the data-attribute contract gets styled.

apps/website/content/docs/grid/keyboard.mdx

@@ -46,7 +46,7 @@ Both behaviors preserve the single-tab-stop model — once Tab leaves, the grid
 
 When the focused address changes (via keyboard, click, or programmatic `grid.setFocus`), a `useLayoutEffect` calls `.focus()` on the new cell's DOM node, so the browser's focus ring follows the engine state without flicker. Scrolling adjusts to keep the focused cell on-screen if needed.
 
-This means consumers don't have to manage `tabIndex` themselves when using `<PretableSurface>`. If you're building with `usePretableModel` and rendering your own JSX, mirror the pattern:
+This means consumers don't have to manage `tabIndex` themselves when using `<PretableSurface>`. If you're building with `usePretable` and rendering your own JSX, mirror the pattern:
 
 ```tsx
 const isFocused =

apps/website/content/docs/grid/pretable-component.mdx

@@ -74,13 +74,13 @@ The grid renders with Excel's surface tones, gridlines, accent. Toggle `data-den
 - **Focus / keyboard navigation** — wire `grid.setFocus({ rowId, columnId })` and `grid.moveFocus("up" | "down" | "left" | "right", options?)` to keyboard handlers.
 - **Custom cell components** — replace the default label/value layout. Custom rendering lets you render any React tree per cell.
 - **Pinned columns rendered as sticky** — set `column.pinned: "left"` and render with the data-pinned attribute.
-- **Per-row measured heights** — provide `measuredHeights: Record<string, number>` to `usePretableModel`.
+- **Per-row measured heights** — provide `measuredHeights: Record<string, number>` to `usePretable`.
 
-All of the above are available with `usePretable` or `usePretableModel`. The drop-in component just doesn't expose the API surface for it.
+All of the above are available with `usePretable`. The drop-in component just doesn't expose the API surface for it.
 
 ## Where to go next
 
-- [Custom rendering](/docs/grid/custom-rendering) — `usePretableModel` walkthrough with code.
+- [Custom rendering](/docs/grid/custom-rendering) — `usePretable` walkthrough with code.
 - [Density helpers](/docs/grid/density-helpers) — `useResolvedHeights` and `getDensityHeights`.
 - [API reference](/docs/grid/api-reference) — `PretableColumn`, `PretableGrid`, etc.
 - [Theming Overview](/docs/theming) — how to skin the grid.

apps/website/content/docs/grid/pretable-surface.mdx

@@ -40,11 +40,11 @@ export function EventStream({ events }: { events: Event[] }) {
 
 ## When to use this vs `<Pretable>`
 
-| You want…                                                                              | Reach for                                         |
-| -------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| A grid in 3 props, sensible defaults                                                   | [`<Pretable>`](/docs/grid/pretable-component)     |
-| Custom cell renderers, telemetry, controlled interaction state, or fine-grained sizing | `<PretableSurface>`                               |
-| To drive everything yourself with hooks                                                | [`usePretableModel`](/docs/grid/custom-rendering) |
+| You want…                                                                              | Reach for                                     |
+| -------------------------------------------------------------------------------------- | --------------------------------------------- |
+| A grid in 3 props, sensible defaults                                                   | [`<Pretable>`](/docs/grid/pretable-component) |
+| Custom cell renderers, telemetry, controlled interaction state, or fine-grained sizing | `<PretableSurface>`                           |
+| To drive everything yourself with hooks                                                | [`usePretable`](/docs/grid/custom-rendering)  |
 
 `<Pretable>` is a 115-line wrapper around `<PretableSurface>` with hardcoded `viewportHeight={320}`, hardcoded cell renderers, and no telemetry. If any of that doesn't fit, drop down to the surface.
 
@@ -197,6 +197,6 @@ If your use case looks like log inspection, start with `<InspectionGrid>`. Other
 - [Selection](/docs/grid/selection) — cell-range model and checkbox column.
 - [Keyboard](/docs/grid/keyboard) — the full keyboard contract.
 - [Clipboard](/docs/grid/clipboard) — Cmd/Ctrl+C TSV defaults and overrides.
-- [Custom rendering](/docs/grid/custom-rendering) — `usePretableModel` walkthrough for headless control.
+- [Custom rendering](/docs/grid/custom-rendering) — `usePretable` walkthrough for headless control.
 - [Density helpers](/docs/grid/density-helpers) — `useResolvedHeights` for density-aware row sizing.
 - [API reference](/docs/grid/api-reference) — full type signatures.

apps/website/content/docs/grid/selection.mdx

@@ -5,7 +5,7 @@ nav: Grid
 order: 4
 ---
 
-Pretable's selection model is **cell-range first** — Excel/Sheets semantics. Row selection is derived from the cell-range state, exposed via a built-in three-state checkbox column. The same engine state powers `<Pretable>`, `<PretableSurface>`, and the `usePretableModel` hook.
+Pretable's selection model is **cell-range first** — Excel/Sheets semantics. Row selection is derived from the cell-range state, exposed via a built-in three-state checkbox column. The same engine state powers `<Pretable>`, `<PretableSurface>`, and the `usePretable` hook.
 
 ## Selection model