Slate v2 pagination architecture review

Objective

Review whether the current pagination architecture in .tmp/slate-v2 is clean, spaghetti, or needs decoupling. Close the Slate Plan only after every scheduled pass, issue/reference sync row, Evidence Kit mapping, pressure review, score gate, and final handoff is complete.

One activation completes one pass. This activation closes pass 12: closure score and final gates.

Current verdict

Strong take: it is not core spaghetti, but it is not clean enough.

Keep the direction:

• slate-layout owns derived page snapshots, projection, Pretext measurement, provider-owned boxes/units, page-break snapshots, and page mount plans.
• PagedEditable is the right public composition surface: page chrome as fixed surfaces, editable overlay as one Slate editor, page virtualization as a view policy.
• slate-react should keep DOM materialization, coverage boundaries, selection, clipboard, IME, and native-editable ownership.

Decouple the mess:

• the canonical pagination example is now a 1620-line stress harness mixing controls, URL state, fixtures, table row generation, provider layout, row windowing, DOM coverage boundaries, page chrome, renderers, and metrics;
• that is acceptable for proving the feature, but bad DX as the public example;
• the next architecture move should split the example into call-site, fixtures, controls, and provider/render modules, and only promote a helper when the same provider/windowing pattern is reused outside this example.

Do not rewrite the package architecture. Do not create raw Slate Markdown/table product packages. The useful abstraction is the generic layout/projection substrate, not a product table kit.

Start gates

Live source current state

Intent / boundary record

Status: complete in this pass after consuming issue-ledger results.

Intent:

• answer the user's actual question: is pagination spaghetti, and should we decouple?
• stop more fixes from piling onto a 1620-line example/proof harness;
• preserve the package substrate that already has a sane boundary.

Outcome:

• a user-review-ready plan that says package architecture stays;
• example/provider/proof harness gets decoupled;
• performance and issue-closure claims stay benchmark/browser-proof gated.

In scope:

• slate-layout public layout entrypoint and snapshot semantics;
• PagedEditable as the public paged rendering surface;
• EditableLayout.getVirtualizedPageItems as the current bridge into slate-react DOM materialization;
• provider-owned boxes/units/split policy for tables, media, and BFC-like blocks;
• canonical pagination example DX;
• package tests, Playwright rows, and Evidence Kit benchmark candidates needed to make future execution honest.

Non-goals:

• no .tmp/slate-v2 implementation edits while the plan is still pending;
• no raw Slate Markdown/table product package;
• no AST table splitting for visual page fragments;
• no CSS-float pagination;
• no public TanStack/virtualizer API;
• no public ignore-cursor API for #5924;
• no Fixes or Improves claim for #5944, #790, or #5924.

Hard boundaries:

Execution adoption story:

1. Split the example with no behavior change first.
2. Keep the top-level example shaped around useSlateLayout plus PagedEditable.
3. Move fixtures, controls, provider logic, renderers, and optional table-window glue one import away.
4. Add package/helper API only if a second structured-node provider repeats the same non-product pattern or the inline provider remains unreadable after the split.
5. Prove browser behavior before claim text changes.

Unresolved user-decision points:

• none for planning;
• execution still requires explicit user acceptance of the final plan.

Decision brief

Status: complete in this pass after consuming issue-ledger results.

Decision:

Keep slate-layout and PagedEditable; decouple the pagination example and proof harness. Do not rewrite packages. Do not promote product-flavored helpers into raw Slate.

Principles:

1. Slate core owns generic document and selection substrate, not product table UX.
2. Derived page layout is not document structure.
3. Page virtualization is a repeated-unit mount policy, not the editor API.
4. Examples must show the public API shape first, then advanced provider logic.
5. Promote helpers only after repeated use or real call-site complexity.

Top drivers:

Viable options:

Chosen option:

• Keep slate-layout + PagedEditable.
• Split the pagination example into:
  • pagination.tsx call-site shell;
  • pagination-controls.tsx;
  • pagination-fixtures.ts;
  • pagination-layout-provider.ts;
  • pagination-renderers.tsx;
  • optional local pagination-table-window.tsx.
• Do not promote example helpers into package API in the first cleanup unless the pass proves a repeated non-product substrate.

Invalidated alternatives:

• "Pagination is core spaghetti": false. The core package boundary is decent; the call-site/proof harness is the mess.
• "Fix by moving table pagination into Slate": wrong owner. It would turn a generic editor into a product table package.
• "Fix by exposing virtualizer knobs": wrong API. domStrategy and pageView keep this Slate-shaped.
• "Close #5944 from architecture": not enough proof. It needs browser stability rows.

Consequences:

• Future patches should reduce pagination.tsx complexity before adding new pagination features.
• Runtime fixes belong in slate-layout, PagedEditable, or slate-react only when the behavior is generic and testable outside the example.
• Benchmark work should target react-pagination-page-virtualization rather than broad "pagination is fast" claims.
• PR/issue text stays no-claim until the proof surface changes.

Source-backed architecture north star

Target shape:

const layout = useSlateLayout(editor, {
  nodeLayout,
  page: pageSettings,
  root: 'main',
  textChangeRefresh: 'deferred',
  typography,
})

return (
  <PagedEditable
    decorate={decorate}
    domStrategy={domStrategy}
    layout={layout}
    pageView={{ gap: PAGE_GAP, mode: pageLayoutMode }}
    renderElement={renderElement}
    renderLeaf={renderLeaf}
    renderPage={renderPage}
  />
)

The call-site should fit on screen. Stress fixtures and table/media providers can be one import away. The public API should still look like Slate plus a layout object, not a word processor framework.

Rejected drift:

• no CSS-float pagination;
• no AST table splitting for visual page fragments;
• no raw Slate TableKit;
• no public TanStack options;
• no example-only hit-testing hacks once a reusable layout projection exists.

Initial scorecard

Weighted score: 0.76.

Current weighted score after related issue discovery: 0.78.

Current weighted score after issue-ledger pass: 0.80.

Current weighted score after intent/boundary and decision brief: 0.82.

Current weighted score after research/ecosystem/live-source refresh: 0.84.

Current weighted score after pressure pass: 0.86.

Current weighted score after maintainer-objection pass: 0.88.

Current weighted score after high-risk deliberate mode: 0.90.

Current weighted score after ecosystem maintainer pass: 0.92.

Current weighted score after revision pass: 0.94.

Current weighted score after issue sync accounting: 0.96.

Current weighted score after closure/final gates: 0.98.

Closure threshold is met. The remaining 0.02 risk is execution proof, browser traces, and benchmark evidence after implementation, not planning incompleteness.

Evidence Kit benchmark mapping

Read:

• benchmarks/editor/research/benchmark-registry.json
• benchmarks/editor/benchmarks/results/benchmark-health-latest.json

Current health:

• active artifacts: 23
• required active artifacts missing: 0
• row count: 801
• next actions: optional core-transaction-current, optional history-retained-memory, ignore/delete historical unregistered artifacts.

Mapping:

Candidate benchmark:

• react-pagination-page-virtualization: page count, mounted page surfaces, mounted rows/cells, scroll frames, middle typing p95/p99, fast-scroll recovery.

Related issue discovery

Status: complete for this pass.

Decision: do not run broad live issue discovery or ClawSweeper again in this activation. The same pagination/page-virtualization surface is already covered by completed durable ledger sections, and this plan changes no fixed/improved claim text.

Evidence read:

• generated live current rows: docs/slate-issues/gitcrawl-live-open-ledger.md:37, :41, :646
• fast-scroll pagination sync: docs/slate-issues/gitcrawl-v2-sync-ledger.md:110-148
• Pretext pagination/page virtualization sync: docs/slate-issues/gitcrawl-v2-sync-ledger.md:623-647
• coverage matrix: docs/slate-v2/ledgers/issue-coverage-matrix.md:426-475
• fork dossier: docs/slate-v2/ledgers/fork-issue-dossier.md:7828-7857
• test-candidate maps: docs/slate-issues/test-candidate-map/5994-5918.md:317-329, :402-414, docs/slate-issues/test-candidate-map/2694-790.md:409-418
• PR reference: docs/slate-v2/references/pr-description.md:295-315

ClawSweeper related-issue pass:

• status: reused existing completed coverage;
• trigger: pagination architecture touches browser/runtime/example issue-facing behavior;
• reason no new run: existing Pretext pagination and fast-scroll sync rows cover #5944, #790, #5924, accessibility/custom-surface guards, and large-doc carryover claims; this pass only reviews architecture cleanliness and does not add a fixed or improved issue claim.

Issue matrix:

Reference sync status:

• generated live gitcrawl rows read: complete for #5944, #5924, #790.
• manual v2 sync ledger update: unchanged; existing rows already cover this no-claim architecture surface.
• fork issue dossier update: unchanged; existing Pretext pagination section covers this surface.
• issue coverage matrix update: unchanged; existing Pretext pagination and provider-fragment sections cover this surface.
• PR description sync: unchanged; current PR reference already says pagination remains a small beta API target and adds no fixed/improved issue claim.

The full issue-ledger pass below closes the remaining ledger-family scan.

Issue-ledger pass

Status: complete.

Decision: no durable ledger or PR-reference edit is needed for this architecture review. The existing issue sync rows already say the correct thing: pagination is related architecture pressure, page virtualization is proof-route backlog, and this review adds no fixed or improved issue claim.

Full ledger family read:

Issue-accounting decision table:

Architectural consequence:

• The package graph is not spaghetti.
• The example/proof harness is too tangled.
• Decoupling should happen at example/provider/proof boundaries first.
• slate-layout and PagedEditable should stay as the public substrate.
• Table/media/paged-fragment behavior should stay provider-owned until a second structured-node consumer proves a reusable helper is worth promoting.

Follow-up status: the intent/boundary record and decision brief are now refreshed; the next runnable pass is the React/performance/TDD/DX pressure pass.

Research / ecosystem / live-source refresh

Status: complete.

Read:

• docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md:28-52, :82-117, :119-187
• docs/research/sources/editor-architecture/tanstack-virtual-and-github-large-surface-virtualization.md:24-76, :81-122, :160-178
• docs/solutions/developer-experience/2026-05-21-slate-layout-source-entry-and-paged-editable-dx.md:88-125, :361-391, :444-498
• docs/solutions/developer-experience/2026-05-22-raw-slate-should-not-own-markdown-table-product-packages.md:18-70
• live .tmp/slate-v2 source rows for useSlateLayout, PagedEditable, EditableLayout, page overlay rendering, pageBreaks, table/media nodeLayout, table row windowing, and TanStack virtualized root planning.

Current live-source corrections:

Ecosystem synthesis:

Research-backed architecture decision:

• Pretext stays the default layout engine.
• Page/spread virtualization is the repeated unit in paged mode; block virtualization remains for continuous/pathological documents.
• pageView and domStrategy stay the public knobs; TanStack stays internal.
• pageBreaks remains opt-in authoritative metadata for strict collaboration and export.
• Tables/media/BFC-like blocks route through provider-owned boxes, units, and split policy.
• Browser/device proof must cover page-boundary editing, table/image bounds, mixed font metrics, clipboard, IME, a11y/missing DOM, and profile drift before native-parity or issue-closure claims.

Performance / DX / migration / regression / simplicity pressure

Status: complete.

Read:

• live pressure source: .tmp/slate-v2/packages/slate-layout/src/react.tsx:520-684, .tmp/slate-v2/site/examples/ts/pagination.tsx:906-1008, :1067-1184, :1206-1220, :1430-1465, :1488-1498, .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:1758-1858, :1894-1995, :2115-2205, :2220-2295
• package/browser proof rows: .tmp/slate-v2/packages/slate-layout/test/page-layout-contract.test.ts:477-509, :973-1035, :1602-1822, .tmp/slate-v2/playwright/integration/examples/pagination.test.ts:2295-2335, :2566-2710, :2792-2968, :2970-3192, :3431-3570, .tmp/slate-v2/playwright/integration/examples/query-controls.test.ts:118-160
• pressure lenses: .agents/skills/performance/SKILL.md, .agents/skills/performance-oracle/SKILL.md, .agents/skills/tdd/SKILL.md, .agents/skills/react-useeffect/SKILL.md

Applicable implementation-skill review matrix:

Pressure verdict:

The architecture survives pressure. The package graph is still the right shape. The part that fails pressure is the example/proof harness and one bridge detail: EditableLayout currently exposes getter functions that allocate mapped arrays when EditableTextBlocks reads them during render. That is tolerable as an internal bridge while the feature is experimental, but execution should either return memoized arrays or prove the getter calls are bounded in React profiler traces before calling this production-grade.

Performance

• applicability: applied
• Vercel rules used:
  • client-passive-event-listeners: PagedEditable scroll listener is passive.
  • rerender-dependencies: layout/page effects use primitive option deps where practical; pressure remains around broad snapshot/projection dependencies.
  • rerender-defer-reads: callbacks and materialization should avoid subscribing to data that only event handlers need.
  • js-index-maps / js-set-map-lookups: existing layout maps are the right direction for block/path/page lookup pressure.
  • advanced-event-handler-refs / advanced-use-latest: candidate if scroll or materialization handlers start reattaching because callbacks need fresh state.
• extra rules used:
  • cohort segmentation
  • repeated-unit budget
  • interaction INP matrix
  • memory/DOM tagging
  • degradation contract
  • editor-native behavior proof
  • effect/subscription budget
• repeated unit:
  • paged mode: page/spread mount item first;
  • structured blocks: provider-owned units such as table rows;
  • continuous/pathological mode: top-level runtime id.
• cohorts:
  • normal: staged/default pagination route with the rich Markdown fixture;
  • large: multi-page table with 240 rows;
  • stress: virtualized 1000-page document plus 10-page table;
  • pathological: 1000 rows, 2000 stress pages, 960px rows, 1200px media, or high overscan.
• current budgets from browser proof:
  • virtualized dropdown readiness: selectReturnedMs <= 5000, readyMs <= 5000;
  • 1000-page stress default: total elements < 1000, page surfaces <= 8;
  • table scrolled into range: total elements < 1400, page surfaces <= 8, rows <= 80, cells <= 240;
  • overscan 4: total elements < 3600, page surfaces <= 14;
  • selected row retention: page surfaces <= 18, rows <= 220, cells <= 660, total elements < 3600;
  • middle typing: p95 event-to-paint <= 80ms;
  • fast wheel scroll: p50 event-to-paint <= 80ms, p95 <= 500ms.
• target budget:
  • preserve the current browser budgets after decoupling;
  • add Evidence Kit react-pagination-page-virtualization before any PR claims "fast pagination" broadly.
• degradation contract:
  • virtualized mode is opt-in;
  • missing DOM uses content boundaries and model-backed materialization;
  • native browser find/screen-reader/native traversal are not native-parity claims until assistive tech and missing-DOM proof exists.
• dashboard/RUM gap:
  • not required for plan readiness, but production adoption should tag document page count, table row count, strategy, overscan, mounted pages, DOM nodes, event-to-paint, browser, mobile, IME, and degradation mode.

React / Effects

Keep:

• useSyncExternalStore for layout snapshots.
• Passive scroll listener plus ResizeObserver in PagedEditable, because that effect synchronizes with external browser scroll/resize state.
• flushSync only as an explicit scroll-position correctness tradeoff; it needs trace proof, not blind expansion.

Pressure:

• PagedEditable computes viewport on scroll with layout reads and synchronous state on the scroll path. If traces show dropped frames, move viewport tracking into a requestAnimationFrame / external-store bridge while preserving no blank page gaps during fast scroll.
• EditableLayout.getVirtualizedPageItems() maps pageMountPlan.items whenever EditableTextBlocks reads it. Keep it internal, but either memoize returned arrays or prove render frequency and allocation stay bounded.
• The example's applyTableRows and applyStressPages effects mutate the editor model from controls. That is acceptable as a stress harness, not as canonical example DX. The split should make control -> fixture mutation ownership explicit and idempotent.

TDD / Regression

Current coverage is stronger than a typical experiment:

• package contracts cover deferred text refresh, provider-owned table row units without AST splitting, single/spread page mount plans, viewport filtering, and selected/promoted/composing page retention;
• browser rows cover route smoke, URL controls, virtualized dropdown startup, split projected paragraph click/navigation/editing, 1000-page table bounds, middle-document typing latency, burst typing, deferred input offset reset, fast wheel scrolling, scaled page-surface alignment, fixture shape, and rich Markdown bounds.

Required execution test stance:

• split files without adding tests that assert filenames or helper names;
• keep tests behavior-first through package APIs and /examples/pagination;
• add focused package coverage only if a new helper/API is promoted;
• rerun focused package tests and pagination Playwright rows before claiming the split is behavior-preserving.

Remaining regression gaps:

• Chromium-only rows are not device/a11y proof.
• #5944 still needs page-boundary flicker/stability proof.
• strict pageBreaks policy is answered, but production collab/export fidelity still needs app-authority proof before any parity claim.
• native find/screen-reader traversal remain degradation/non-claim territory.

DX / Simplicity

• pagination.tsx is currently 1620 lines. That is the DX problem.
• The cleanup should keep one canonical /examples/pagination route; do not add another fake pagination-basic route.
• Split into controls, fixtures, provider/renderers, and optional local table-window glue.
• Keep the public call-site centered on useSlateLayout and PagedEditable.
• Promote no helper until it either removes repeated complexity after the split or a second structured-node provider proves the pattern.

Migration

• Plate/app packages can own product Markdown/table behavior on top of the same provider layout substrate.
• slate-yjs/export strictness can use pageBreaks snapshots with measurement profile, root, version, document key, and writer id.
• Do not require current Plate/slate-yjs adapters for raw Slate plan readiness; the required substrate is generic boxes/units/split policy plus optional authoritative page-break metadata.

Slate maintainer objection ledger

Status: complete.

Verdict: the plan still stands under maintainer pressure. The strongest objection is not "pagination is spaghetti"; it is "the example and proof harness are teaching too much local policy as if it were the API." That is a real problem and it is exactly where the decoupling should happen.

Maintainer decision record:

• Keep: slate-layout, useSlateLayout, PagedEditable, provider-owned boxes/units/split policy, page/spread virtualization, opt-in pageBreaks.
• Split: canonical pagination example, controls, fixtures, provider/renderers, stress mutation, row-windowing glue, metrics/debug chrome.
• Defer: reusable structured-node row-window helper until reuse or call-site proof.
• Reject: pages as AST nodes, raw Slate table/Markdown product APIs, public TanStack option pass-through, native/a11y parity claims without proof, issue closure from architecture alone.

Maintainer acceptance conditions for this plan:

• The public call-site stays centered on useSlateLayout plus PagedEditable.
• Package APIs remain generic and documented as derived layout state.
• The example split proves the API shape without hiding essential complexity in magical helpers.
• Browser proof covers page-boundary clicking, margin hit testing, text selection, table spanning, fast scroll, middle typing, and virtualized DOM counts.
• Performance proof covers p95/p99 interaction latency, DOM count, mounted page surfaces, rows/cells, and memory pressure for the 1000-page route.
• Issue/reference text keeps #5944, #790, and native/a11y rows as related or proof-route backlog until the proof exists.

High-risk deliberate mode

Status: complete.

Triggered because this lane touches browser runtime, selection, virtualization, rendering contracts, strict page-break metadata, and package/example boundaries.

Deliberate-mode verdict:

• no package rewrite;
• no public TanStack API;
• no AST page/table fragments;
• no raw Slate product table/Markdown APIs;
• no native find, screen-reader, or strict export parity claim without direct proof;
• yes to example/proof-harness split first;
• yes to proof gates before any #5944, #790, native/a11y, or production-fast claim.

High-risk gates:

Proof commands for execution mode:

Release blockers created by this pass:

• #5944 stays related until page-boundary editing, margin hit testing, and flicker/stability rows cover the exact failure.
• #790 stays proof-route backlog until the 1000-page route has active benchmark evidence, not only Playwright assertions.
• Native find/screen-reader parity stays not claimed.
• Strict collab/export page-break fidelity stays opt-in; app-level authority owns writer policy.
• Example cleanup is required before new pagination features. Otherwise we keep pouring concrete into a 1620-line stress harness.

Ecosystem maintainer pass

Status: complete.

Ecosystem verdict:

• Pretext is still the right default engine, but only with an honest measurement contract.
• Premirror remains the rendering shape to preserve: derived snapshot, measurement, composition, page chrome outside the document, one editable overlay.
• TanStack Virtual stays internal range machinery.
• Tiptap Pages remains negative evidence: steal the failure taxonomy, reject the CSS-float/page-gap mechanism and product table kit.
• Raw Slate owns generic layout/projection substrate; Plate/app packages own Markdown syntax, table UX, export policy, and app-specific collaboration guarantees.

Evidence used:

• docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md:28-52 says Pretext avoids hot-path DOM reflow but still depends on canvas/browser measurement, so Slate must not promise cross-client or server-stable page breaks by default.
• docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md:54-80 records profile-sensitive drift and requires measurement-profile vocabulary before strict fidelity claims.
• docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md:119-157 maps Tiptap page-limit failures to Slate proof requirements while rejecting CSS floats, AST node splitting, and raw product TableKit scope.
• docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md:159-187 keeps Premirror's derived layout shape, TanStack as internal range machinery, page-level virtualization, opt-in authoritative page breaks, and browser proof before native parity.
• docs/research/sources/editor-architecture/layout-measurement-and-ime-lanes.md:24-64 keeps layout derived and measurement separate from ordinary overlay policy.
• docs/solutions/developer-experience/2026-05-22-raw-slate-should-not-own-markdown-table-product-packages.md:45-79 keeps raw Slate focused on substrate and leaves Markdown/table product UX to Plate/app packages.
• .tmp/slate-v2/packages/slate-layout/test/page-layout-contract.test.ts:364-437 proves opt-in, profile-checked, shared, persistent page-break snapshots.
• .tmp/slate-v2/packages/slate-layout/test/page-layout-contract.test.ts:1064-1143 proves provider-owned unit fragments can write/read authoritative page breaks without splitting the table node.

Authoritative page-break policy

Best long-term API/DX decision: raw Slate exposes the pageBreaks protocol; the app chooses the authority.

Raw Slate should not choose one authority because that turns an editor substrate into a collaboration/export product. The substrate should make the policy easy: read, write, writerId, documentKey, version, root, measurementProfile, accepted/stale status, and history-skipped shared state.

Collab/export answer

• Page breaks are derived metadata, not document value and not undo history.
• pageBreaks may be shared and persisted, but it must be profile-checked.
• If the snapshot is stale by document key, root, version, or measurement profile, clients ignore it for strict layout and recompute locally.
• Strict collab/export must name the authority before claiming exact page agreement.
• A future headless Pretext engine can improve authority choice, but the current API should already support server/client authority without changing the Slate value shape.

Ecosystem answers

Plan change from this pass:

• The open pageBreaks owner question is answered: app-level authority owns strict policy; raw Slate owns only the protocol and stale/accepted state.
• Strict collab/export becomes a clean extension point, not a reason to put page fragments in the Slate document.
• Ecosystem evidence strengthens the existing decision: decouple the example, keep the package substrate, and do not promote product table/Markdown APIs.

Issue sync accounting

Status: complete.

Final sync decision: update the manual sync ledger and PR reference; no coverage matrix or fork dossier edit is needed because the related/not-claimed issue classifications already match the final plan.

Evidence re-read:

• Live generated open rows still list #5944, #5924, and #790 as singleton current rows: docs/slate-issues/gitcrawl-live-open-ledger.md:37, :41, :646.
• Existing manual sync already had the fast-scroll and Pretext pagination no-claim rows: docs/slate-issues/gitcrawl-v2-sync-ledger.md:110-150, :623-647.
• Issue coverage matrix already classifies Pretext/pagination rows correctly: docs/slate-v2/ledgers/issue-coverage-matrix.md:426-475.
• Coverage matrix exact issue rows keep #5924 not claimed and #790 proof-route backlog: docs/slate-v2/ledgers/issue-coverage-matrix.md:589, :757.
• Fork issue dossier already has Pretext pagination issue accounting: docs/slate-v2/ledgers/fork-issue-dossier.md:7828-7857.
• PR reference already described the small beta pagination API and no issue claim: docs/slate-v2/references/pr-description.md:304-317.

Edits made:

• Added 2026-05-30 Pagination Architecture Review Final Sync Notes to docs/slate-issues/gitcrawl-v2-sync-ledger.md:649-673.
• Updated docs/slate-v2/references/pr-description.md:312-317 to say apps or export pipelines own authoritative pageBreaks writer policy while raw Slate owns only the protocol and accepted/stale status.

Final classification table:

Reference-sync consequence:

• The plan remains a no-new-claim architecture review.
• PR/reference wording now matches the final strict-fidelity policy.
• Closure can now decide final readiness without another issue-ledger pass.

Execution phases after user acceptance

Planning only. Execution requires user acceptance of the final plan.

1. Split the example with no behavior change.
2. Keep /examples/pagination as the canonical route.
3. Preserve package APIs: useSlateLayout, PagedEditable, provider boxes/units/split policy, internal DOM strategy bridge, and opt-in pageBreaks.
4. Decide whether table row windowing remains local or becomes a tiny generic helper.
5. Rerun package tests, focused pagination Playwright rows, query controls, and the Evidence Kit benchmark if registered or if a broad performance claim is made.
6. Sync issue/reference rows only if proof changes a claim; otherwise keep #5944, #790, and native/a11y rows as non-claims.

Fast driver gates

Pass schedule and state

Plan deltas from this pass

• Added hard verdict: not core spaghetti; example/provider layer needs decoupling.
• Added source-backed boundary between slate-layout, PagedEditable, slate-react, and the example.
• Added initial score 0.76.
• Added candidate benchmark for pagination page virtualization.
• Added no-raw-Slate-table-package guardrail from docs/solutions.
• Left final issue/reference sync for the dedicated sync pass, then closed it before final gates.
• Related issue discovery pass reused existing ledger coverage for #5944, #790, #5924, a11y/custom-surface guards, and large-doc carryover; no fixed/improved issue claims changed.
• Full issue-ledger pass read the live rows, frozen ledger rows, macro clusters, package impact matrix, requirements, benchmark candidate map, current sync ledger, and PR reference.
• Confirmed no new durable no-claim row is useful: existing sync and PR text already cover this pagination architecture review.
• Raised score to 0.80 because issue accounting is closed; kept the lane pending because intent/decision refresh, pressure lenses, objection ledger, and final gates remain.
• Refreshed the intent/boundary record after issue-ledger accounting: package graph stays, example/proof harness splits, issue closure stays proof-gated.
• Refreshed the decision brief with drivers, invalidated alternatives, adoption story, and consequences.
• Raised score to 0.82; kept the lane pending because ecosystem synthesis, pressure lenses, maintainer objections, revision, sync recheck, and final gates remain.
• Refreshed research/ecosystem/live-source evidence: Pretext stays the engine, Premirror stays the page-overlay shape, TanStack stays internal and is already on the targeted version, Tiptap remains negative evidence, and Plate/app packages keep product table/Markdown ownership.
• Confirmed pageBreaks read/write already supplies the strict-fidelity extension point without polluting Slate document values.
• Raised score to 0.84; kept the lane pending because pressure lenses, maintainer objections, revision, sync recheck, and final gates remain.
• Applied React/performance/TDD/effect/DX pressure: package architecture survives, but flushSync scroll correctness, EditableLayout getter allocations, and the 1620-line example/proof harness stay high-pressure execution concerns.
• Converted the strongest maintainer objections into explicit keep/split/defer and reject decisions: keep generic layout substrate, split example/proof glue, defer reusable row-window helpers, reject AST page/table fragments and public TanStack option pass-through.
• Raised score to 0.88; kept the lane pending because high-risk proof gates, ecosystem maintainer pass, revision, issue sync recheck, and final gates remain.
• Closed high-risk deliberate mode with execution proof gates for hidden DOM selection drift, table fragment integrity, scroll latency, middle-document typing, page-surface alignment, over-decoupling, premature API promotion, strict page-break drift, native/a11y non-claims, and issue-claim inflation.
• Raised score to 0.90; kept the lane pending because ecosystem/collab/export answers, revision, issue sync recheck, and closure gates remain.
• Closed the ecosystem maintainer pass: Pretext stays default with profile-aware local layout; strict collab/export uses opt-in authoritative pageBreaks; app-level authority owns writer policy; raw Slate owns protocol only.
• Raised score to 0.92; kept the lane pending because revision, issue sync recheck, and closure gates remain.
• Closed the revision pass by removing stale current-state language around the EditableLayout bridge, strict page-break ownership, regression mapping, execution phases, fast driver gates, and open questions.
• Raised score to 0.94; kept the lane pending because issue sync accounting and closure gates remain.
• Closed issue sync accounting by adding the final manual ledger row, updating the PR reference for app/export pageBreaks authority, and preserving all related/not-claimed classifications.
• Raised score to 0.96; kept the lane pending because closure audit and final handoff remain.
• Closed the final gates: every scheduled pass is complete, issue/reference accounting is synced, execution-only risks have owners, and no planning pass remains runnable.
• Raised score to 0.98; the lane is ready for user review.

Execution-only follow-up

• react-pagination-page-virtualization is required before any broad performance or #790 claim, not before the behavior-preserving example split.
• EditableLayout stays an internal bridge unless profiler proof or a second consumer justifies a smaller named contract.
• Table row windowing stays example-local unless execution proves reuse or unreadable call-site complexity after the split.

Closure score and final gates

Status: complete.

Closure audit:

Closure score: 0.98.

The plan does not score 1.00 because execution still needs browser traces, focused Playwright rows, and benchmark evidence before production-fast, native/a11y, strict export, #5944, or #790 claims. That is execution risk, not planning incompleteness.

No planning pass remains runnable.

Final handoff

Verdict: pagination is not core spaghetti. The packages are mostly right; the canonical example/proof harness is the mess and should be split before more features land.

Keep:

• slate-layout as the derived layout/projection substrate.
• useSlateLayout as the public layout entrypoint.
• PagedEditable as page chrome plus one Slate editable overlay.
• Provider-owned boxes, units, split policy, and measurement profile handling.
• Page/spread virtualization behind virtualized domStrategy.
• Opt-in pageBreaks for strict-fidelity metadata.

Split first:

• pagination.tsx call-site shell.
• controls and URL state.
• rich fixtures and stress mutation.
• layout provider logic.
• renderers/page chrome/metrics.
• optional local table row-window glue.

Do not do:

• no package rewrite;
• no extra /examples/pagination-basic;
• no raw Slate Markdown/table product packages;
• no public TanStack options;
• no AST table splitting for visual fragments;
• no public ignore-cursor API;
• no native find, screen-reader, strict export, #5944, or #790 claim from architecture alone.

Authority rules:

• raw Slate owns the pageBreaks protocol, profile checks, and accepted/stale status;
• apps or export pipelines own the authoritative writer policy for collaboration/export;
• table/media/BFC-like layout policy stays provider-owned until reuse proves a generic helper is worth promoting.

Execution proof gates:

• keep package contract coverage for layout, provider units, page mount plans, and pageBreaks;
• keep focused pagination Playwright rows for click, selection, margin hit testing, table fragments, middle typing, fast scroll, and virtualized DOM counts;
• keep query-control rows for URL-backed controls;
• register or run react-pagination-page-virtualization before broad perf or #790 claims.

Ready for user review. Execution starts only after explicit acceptance.

Execution closeout

Status: complete.

Implementation:

• Split /examples/pagination without changing the canonical route or package APIs.
• Kept site/examples/ts/pagination.tsx as the visible call-site around useSlateLayout and PagedEditable; it is now 539 lines instead of the prior 1620.
• Added example-local modules:
  • site/examples/ts/pagination-constants.ts for state field, query parsers, control types, and layout constants.
  • site/examples/ts/pagination-controls.tsx for URL-backed toolbar controls.
  • site/examples/ts/pagination-fixtures.ts for rich Markdown/stress/table fixtures.
  • site/examples/ts/pagination-renderers.tsx for projected renderers, leaf rendering, and local table row-window glue.
  • site/examples/ts/pagination-page-view.tsx for page chrome and PagedEditable viewport composition.
• Accepted autoreview's stale-path finding in packages/slate-react/src/editable/root-interaction-controller.ts: coordinate placement now returns null when a stale DOM data-slate-path no longer exists, allowing the existing event-range fallback instead of throwing.

Issue/reference sync:

• No new Fixes #... or Improves #... claim.
• #5944, #790, #5924, native/a11y, and strict export remain proof-gated as documented above.
• No PR-reference or issue-ledger claim text changed during execution.

Verification:

No accepted execution item remains runnable.