Name the type that exists, and guard the prose that names types

[blove]

First pass of the #321 fallout audit, plus the one live defect it turned up.

The defect

grid/keyboard.mdx told readers: "renderSnapshot.rowMetrics is public and fully typed, but its interface is not exported under a name — take it as PretableRenderSnapshot["rowMetrics"] if you need to write the type down."

#321 renamed that type to PretableIndexedRenderSnapshot. Anyone following that sentence got a compile error, and had been for a release.

Everything the existing guard covers behaved perfectly through the rename: reports regenerated, every bound member table moved with them, the import check passed. The sentence is prose — and prose is exactly where escape hatches live. "Not exported under a name, take it as X" is a claim about the API that no table can express.

The guard

Every Pretable* identifier named anywhere in the docs must be a real export of some reported package.

Run across the whole corpus it found exactly one violation — this one — so it lands fail-closed with no allowlist, which is the shape a guard should have. Mutation-checked: restoring the old sentence fails it with grid/keyboard.mdx: PretableRenderSnapshot. It also carries the same non-empty assertion the neighbouring checks use, so a corpus it can no longer read fails loudly instead of passing clean.

It reads the whole page rather than prose only: a name is a name wherever it's written, and the narrower version would need the fence-tracking machinery this one doesn't.

Also from the audit

heroGrid/selection.ts still documented its inputs as grid.getColumns() and grid.getSnapshot().visibleRows. Both were removed by #321; the code moved to columnLayout and range(0, visibleRowCount) in #336 and the comment didn't. A comment naming a removed API is a wrong instruction to the next reader — which is how this class propagates.

What the audit checked and found clean

• Per-slice re-render subscriptions (the Unblock CI, and put the hero's selection summary back on the drawn grid #336/Stop repainting the grid on every rebuild slice; stop the bench calling a stalled interaction settled #352 shape) — every other useSyncExternalStore call site is either UI-event driven or already snapshot-scoped. The row-layout controller publishes rebuilding once and ready once, not per slice; this also corrects a claim in Stop repainting the grid on every rebuild slice; stop the bench calling a stalled interaction settled #352's description, where I named it a suspected second amplifier. The residual scheduler hops are its own legitimate slices, not amplification.
• Consumers of APIs feat: complete incremental row-model migration #321 removed — enumerated by diffing the API reports across the migration (PretableGrid, PretableGridSnapshot, PretableRenderSnapshot, UsePretableOptions, RowMetricsReader, PretableBaseColumn, PlannedColumn). All remaining references are in dated docs/superpowers/plans/, which are historical execution recipes, except the one fixed here.
• Casts hiding query shape mismatches — one left in production (pretable-adapter.tsx:328, setQuery(surfaceQuery as never)). It is not hiding a defect: bench: the group script applies no grouping and reports completed #327 proved the payload correct. Left as-is rather than widened into this PR.
• Sync-settle assumptions on setQuery — all remaining callers are fire-and-forget or await finished.

Verification

pnpm test (full monorepo; the one multi-sort-surface failure is the known load flake — the package passes 829/829 on its own), lint, typecheck, format all clean. Rebased onto #353 and re-verified, since that renamed public types: the new guard passes, which is itself a small piece of evidence for it.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pretable	Ready	Preview	Aug 13, 2026 2:40pm

[github-actions]

Vercel preview ready

Preview: https://pretable-7ba7q9o0o-cacheplane.vercel.app
Commit: 4d6d7944022bce16b9561dfc4d58f42a77a44241

_{Updated automatically by the deploy-preview job.}