Slate v2 Pretext Pagination Virtualization Feedback

Objective: Close the Slate Plan lane for the virtualization / pagination feedback before user review. The plan must cover Pretext as the layout engine, current canvas.measureText() determinism limits, cross-platform line-break drift, opt-in authoritative page-break snapshots for collab/export fidelity, page-level virtualization when pagination is enabled, Tiptap pagination edge cases for tables/images/font variability/padding, Slate v2 public API/runtime proof gates, issue/reference accounting, score deltas, maintainer objections, and final handoff.

Goal plan: docs/plans/2026-05-25-slate-v2-pretext-pagination-virtualization-feedback.md

Template: docs/plans/templates/slate-plan.md

Primary template: docs/plans/templates/slate-plan.md

Applied packs:

• slate-plan

Completion threshold:

• Score >= 0.92, no dimension below 0.85.
• Every pass row complete or intentionally skipped with evidence.
• Related issue accounting closed against live/current ledgers.
• Final handoff emitted and no runnable plan-hardening action remains.
• node .agents/rules/autogoal/scripts/check-complete.mjs docs/plans/2026-05-25-slate-v2-pretext-pagination-virtualization-feedback.md passes.

Verification surface:

• Planning artifacts in plate-2: this plan, related issue ledgers, research notes if updated, and completion check.
• Slate v2 source/API/runtime claims must cite live .tmp/slate-v2 source reads or a .tmp/slate-v2 command.
• Browser/runtime behavior claims require .tmp/slate-v2 browser proof in a later pass. This pass records source evidence only.

Constraints:

• Planning mode only. Do not patch .tmp/slate-v2 implementation.
• Allowed edit scope: docs/plans/**, docs/research/**, docs/slate-issues/**, docs/slate-v2/ledgers/**, docs/slate-v2/references/**.
• Keep Slate core Pretext-free. Layout is optional derived view data.
• Do not claim headless deterministic pagination until the measurement layer is actually headless and cross-platform-stable.

Boundaries:

• Local source of truth: .tmp/slate-v2, ../pretext, existing plan/ledger artifacts.
• External sources: Cyrus Radfar Pretext article, local ../tiptap-docs Pages docs, official Tiptap Pages docs, and Romik Makavana Tiptap pagination article URL, read only as evidence.
• GitHub Pretext source was read from local ../pretext, not browsed.

Blocked condition:

• Block only if the same external source or workspace access failure prevents issue discovery, source grounding, score closure, or final verification for three consecutive activations.
• Do not use blocked while another research, ledger, objection, scoring, or plan-hardening move remains runnable.

Slate Plan lane state:

• slate_plan_lane_status: complete
• current_pass: Closure score and final gates
• current_pass_status: complete
• next_pass: none
• next_action: none
• final_handoff_status: complete

Current verdict:

• verdict: ready for user review
• confidence: 0.94 for planning readiness; implementation/browser proof remains execution-gated
• keep / cut / revise call:
  • Keep Pretext as the default slate-layout engine.
  • Cut any language that implies Pretext gives cross-client/server page-break determinism today.
  • Revise pagination virtualization: paged mode virtualizes pages/spreads first, not top-level blocks.
  • Add an opt-in authoritative page-break snapshot channel for strict collab and export fidelity.
  • Keep block virtualization for continuous/pathological documents, fed by layout when available.
• reason: current Slate v2 already has page snapshots, fragments, projections, Pretext-backed line layout, state fields, and TanStack-backed top-level virtualization, but those pieces are wired in the wrong repeated unit for paged documents and the determinism contract is currently too optimistic. Maintainer pressure keeps the plan but narrows ownership: raw Slate exposes substrate, slate-layout exposes derived layout and provider protocols, React owns DOM materialization, and apps/Plate own product UI and export policy. The ecosystem maintainer pass confirms there is no strategy reversal: Tiptap is negative evidence for CSS pagination, Premirror supports derived layout fragments, TanStack stays an internal range engine, and DOMCoverage stays Slate-owned browser-policy infrastructure. The revision pass locks the public beta direction: pageView replaces scattered page display props, domStrategy remains the only public incomplete-DOM switch, page virtualization is internal to PagedEditable, measurementProfile is metadata not a required user knob, and pageBreaks stays opt-in strict-fidelity metadata. High-risk pressure keeps implementation claims gated until the missing release proofs exist; adjacent tests are good evidence, not final proof. Issue sync accounting confirms the final API/proof wording changes no fixed/improved issue counts and is now reflected in the v2 sync ledger, coverage matrix, fork dossier, and PR reference. The closure pass verified the score threshold, pass table, planning-only verification surface, issue/reference sync, final handoff, and no-runnable-planning-work state.

Completion rule:

• Do not call update_goal(status: complete) while any pass/checklist/gate remains pending.
• Goal completion is legal only in the closure score/final gates pass.

Start Gates:

Work Checklist:

• Objective includes lane outcome, pass schedule, one-pass-per-activation policy, completion threshold, verification surface, constraints, boundaries, and blocked condition.
• One-pass-per-activation policy respected: this activation closes only the Closure score and final gates pass.
• Live source grounding recorded for current implementation claims.
• Issue ledger / ClawSweeper pass applied: gitcrawl-v2 sync ledger, issue coverage matrix, and fork dossier updated; PR reference inspected and left unchanged because this planning pass adds no fixed/improved claims.
• Research and ecosystem synthesis complete for every external system used as evidence in this pass.
• Intent/boundary record and decision brief complete.
• Scorecard recorded with evidence; total score >= 0.92 and no dimension below 0.85 before closure.
• Applicable implementation-skill review matrix applied or skipped with concrete reason.
• Slate maintainer objection ledger complete.
• Verification workspace gate recorded for every Slate v2 source, runtime, browser, package, public API, or issue-fix claim.
• TDD marked N/A for this pass: no implementation or behavior proof edited.
• Browser proof marked N/A for this pass: source-only planning pass.

Completion Gates:

Phase / pass table:

Scorecard:

Current weighted score after closure score and final gates: 0.92.

Source-backed architecture north star:

• target shape: slate-layout owns derived layout snapshots, page fragments, page-break snapshots, and optional measurement profiles; slate-react owns DOM materialization, page/block mount plans, selection, clipboard, IME, a11y, and browser proof.
• source evidence: .tmp/slate-v2/packages/slate-layout/src/index.ts:236 defines snapshots with blocks/fragments/pages; :277 defines engine boundary; :1349 starts the Pretext page engine; :1698 paginates measured blocks into fragments/pages.
• rejected drift: do not make slate core depend on Pretext, do not make virtualized mode default, and do not persist local page breaks by default.
• migration posture: layout settings can be shared/persisted document metadata; page-break snapshots are opt-in shared metadata with a profile hash and invalidation rules.

Public API target:

Authoritative page-break snapshot sketch:

const pageBreaks = defineStateField<SlatePageBreakSnapshot>({
  key: 'layout.pageBreaks',
  collab: 'shared',
  history: 'skip',
  initial: () => null,
  persist: true,
})

const layout = useSlateLayout(editor, {
  page: pageSettings,
  pageBreaks: {
    mode: 'write',
    source: pageBreaks,
  },
  typography,
})

Rules:

• default mode is local derived layout, no shared page-break writes.
• authoritative mode stores page/fragment break decisions, not rendered DOM.
• mode: 'read' consumes accepted breaks for strict view/export; mode: 'write' is reserved for the chosen client/server authority. Do not make every peer a writer.
• snapshots include engine id, measurement profile, font set id, typography hash, page settings hash, document version/range, and invalidation reason.
• peers may recompute locally for speed, but strict rendering/export reads the accepted snapshot when the profile matches.
• if profile/hash mismatches, the snapshot is stale and must not be silently used.
• measurementProfile is produced by the layout engine and stored in snapshots; users should not have to configure a browser/font engine to get ordinary pagination.
• write mode requires explicit writer identity and must use history-skipped derived updates. Read mode is the default strict-consumer shape.

Internal runtime target:

Hook / component / render DX target:

Revision pass: Pass verdict:

• The final public shape should be boring: useSlateLayout, PagedEditable, pageView, domStrategy, optional pageBreaks. Anything else is machinery.
• pageVirtualization is cut as public API. In paged mode, virtualized domStrategy means "I accept incomplete DOM"; PagedEditable decides the page/spread mount plan internally.
• measurementProfile is not a call-site feature. It is snapshot metadata used for stale detection and authoritative break validation.
• The EditableLayout bridge must grow internally, but users should not write virtualizer item adapters. PagedEditable owns page/spread items.
• The Tiptap lesson lands in tests and provider protocols, not in public pagination props.

Revision API decisions:

Revision proof deltas:

Revision issue-sync impact:

• No new Fixes #... or Improves #... claim is justified by this revision.
• #5944 stays related/issue-reviewed until page-boundary flicker, caret mapping, and page-break stability browser proof lands.
• #790 stays proof-route backlog until mounted-page/block-count, edit latency, scroll, DOMCoverage, and native behavior proof lands.
• #2793/#2572 stay release guards for missing-DOM/native-equivalence language.
• The next pass only needs to verify and, if needed, align ledger wording with the final API target: no public pageVirtualization, pageView, metadata-only measurementProfile, opt-in pageBreaks, and provider/split protocol.

Intent / boundary record:

• intent: accept the feedback as architecture pressure, not as a footnote. The long-term call is Pretext-backed derived layout, page/spread virtualization for paged mode, and an opt-in authority channel for users who need export/collab page-break fidelity.
• outcome: the plan should let implementation proceed without reopening the core question of "block virtualizer plus page chrome" vs "page mount plan". Paged mode uses a page/spread mount plan; continuous mode may still use block/fragment virtualization.
• in-scope:
  • slate-layout measurement profiles, page snapshots, fragments, split policy protocols, and optional authoritative page-break snapshot shape.
  • slate-react DOM materialization, retained active pages, IME/selection/a11y behavior, clipboard behavior, and page-level virtualizer integration.
  • public API naming for layout, pageView, and domStrategy; page virtualization is internal behavior behind virtualized domStrategy.
  • proof routes for line-break drift, table/image splits, padding/content rects, mixed font metrics, collab/export authority, and missing-DOM accessibility.
  • issue non-claim posture for pagination, virtualization, a11y, and large-doc benchmarks.
• non-goals:
  • implementation in this planning pass.
  • claiming same page breaks across OS/browser/server while Pretext measurement still depends on canvas.
  • persisting local page breaks as default document truth.
  • exposing TanStack Virtual, Pretext internals, or measurement-cache plumbing as the main Slate API.
  • making virtualization default for ordinary editors.
  • putting product export policy, page toolbar UI, or Plate-specific document editor behavior into raw Slate.
  • solving all table layout inside raw Slate; the target is a provider/split protocol that table/media plugins can satisfy.
• owner boundaries:

• decision boundaries:
  • If a datum is required to edit the document, it belongs to core.
  • If it can be recomputed from document + layout settings, it is derived layout, not document value.
  • If two clients can validly compute different breaks, strict consumers need an explicit authority; Slate must not pretend local layout is universal.
  • If a page is the repeated visual unit, virtualization uses pages/spreads first. Blocks remain the continuous-editor unit.
  • If an API requires users to understand TanStack or Pretext internals, it is the wrong public DX.
• unresolved user-decision points: none before issue sync. Revision pass decides pageVirtualization is internal behavior behind virtualized domStrategy. Exact provider type names can be finalized during implementation, but the architecture is fixed: generic box providers and split policies, no raw Slate product TableKit.

Decision brief:

• principles:
  1. Layout is derived, versioned, and profile-aware; document value is not page geometry.
  2. Page mode's repeated unit is page/spread, not block.
  3. Strict fidelity needs an authority; local recompute is not enough until measurement is truly headless/deterministic.
  4. Missing DOM stays explicit and measured.
  5. Public DX should say "layout and page view", not "virtualizer cache and Pretext measurement internals."
• top drivers:
  • Pretext's hot path is excellent, but prepare() is not headless today.
  • Current paged mode already has pages/fragments, so block virtualization is the wrong abstraction for pagination.
  • Tiptap's failures are mostly split-policy, box-model, and nested structure failures, not just "needs faster measurement."
  • Live collaboration and export cannot share hand-wavy page breaks. They need either same-profile local layout or a recorded authority.
• viable options:

• chosen architecture:
  • useSlateLayout creates a derived, profile-aware layout snapshot.
  • PagedEditable consumes page/spread mount items, not block items, when pagination is enabled.
  • active/selected/composing pages are retained even when outside the viewport.
  • pageBreaks is an optional shared state field with profile/hash/version metadata; default mode never writes page breaks.
  • export/collab strict mode reads accepted breaks only when the profile is valid, and falls back to recompute/stale handling when it is not.
• consequences:
  • PagedEditable needs a page mount plan.
  • EditableLayout needs a richer protocol than top-level items.
  • Export/collab docs must distinguish local layout from authoritative layout.
  • Page virtualization proof must include selection, IME, clipboard, screen reader/missing-DOM risk, and page-boundary editing, not only scroll FPS.
  • Table/image correctness needs box-provider and split-policy tests, not just text measurement tests.
• follow-ups:
  • issue-sync accounting and closure passes.

Issue accounting:

Related issue discovery pass:

• sources read:
  • docs/slate-issues/gitcrawl-live-open-ledger.md
  • docs/slate-issues/gitcrawl-v2-sync-ledger.md
  • docs/slate-v2/ledgers/issue-coverage-matrix.md
  • docs/slate-v2/ledgers/fork-issue-dossier.md
  • docs/slate-v2/references/pr-description.md
  • docs/slate-issues/benchmark-candidate-map.md
  • docs/slate-issues/open-issues-ledger.md
• live open rows:
  • #5992, #5945, #5944, #5924, #5131, #4141, #4056, #3892, #2793, #2572, #2051, and #790 are all present in the current generated live ledger.
• current classification:
  • #5944 is the only direct pagination issue. Keep it related and issue-reviewed until page-boundary flicker/caret mapping has current browser proof.
  • #790 is the direct dynamic rendering / virtualization issue. Keep it related proof-route backlog until mount/edit/scroll benchmark, DOM coverage, and browser native-behavior proof exist.
  • #5924 is adjacent because page/table/debug structural DOM exists around the editor. Keep it not claimed; DOM coverage and mount policy are the answer, not a new ignore-cursor public API from this plan.
  • #4141, #5131, and #2051 are invalidation/subscription guardrails. Layout snapshots and page virtualization must not widen rerender breadth.
  • #2793 is the stronger screen-reader guard for missing-DOM modes. #2572 stays accessibility/docs pressure, but #2793 is the row that blocks native equivalence claims for virtualized pages.
  • #5945, #4056, and #5992 stay owned by large-document operation/clipboard benchmarks. This pagination plan must not promote their existing Improves rows.
• discovery decision:
  • no new Fixes #... claims.
  • no new Improves #... claims.
  • manual sync ledgers now record the #2793 addition and this plan's no-claim posture.

Issue-ledger sync status:

• ClawSweeper related-issue pass: complete
• generated live gitcrawl rows read: complete for the current related surface
• manual v2 sync ledger update: complete and revised to final API/proof wording in docs/slate-issues/gitcrawl-v2-sync-ledger.md
• fork issue dossier update: complete and revised to final API/proof wording in docs/slate-v2/ledgers/fork-issue-dossier.md
• issue coverage matrix update: complete and revised to final API/proof wording in docs/slate-v2/ledgers/issue-coverage-matrix.md
• PR description sync: complete in docs/slate-v2/references/pr-description.md; planning target wording added, fixed/improved claim counts unchanged

Issue sync accounting pass: Pass verdict:

• The final API/proof revision changes planning wording, not issue claim status.
• docs/slate-issues/gitcrawl-v2-sync-ledger.md, docs/slate-v2/ledgers/issue-coverage-matrix.md, docs/slate-v2/ledgers/fork-issue-dossier.md, and docs/slate-v2/references/pr-description.md now agree on the final target: no public pageVirtualization, pageView for page display settings, metadata-only measurementProfile, opt-in pageBreaks, internal page/spread virtualization behind virtualized domStrategy, and generic provider/split protocols for table/media/BFC pagination.
• Claim count remains zero for this plan: no new Fixes #... and no new Improves #....

Issue sync accounting decisions:

Ecosystem strategy synthesis:

Ecosystem maintainer pass: Pass verdict:

• No ecosystem source changes the target architecture. The right move is still Pretext for layout, Premirror's derived-fragment shape, TanStack as an internal range engine, DOMCoverage as Slate-owned browser policy, and Tiptap as a warning label.
• The user feedback is correct and worth making sharper: Tiptap's public Pages docs say the CSS-float model breaks on BFC-style blocks and proposes caps or manual node splitting. That is exactly the failure mode Slate must avoid.
• The pushback is also important: this is not an argument against pagination or page-level virtualization. It is an argument against making CSS page gaps, product TableKits, or semantic manual splits the substrate.

Ecosystem final keep/reject decisions:

Tiptap-specific correction:

• The official limitations page and local source now make the CSS trick look worse, not better. If a block cannot split because it creates a BFC, max-height is not real pagination; it is a content authoring constraint wearing a layout hat.
• Manual node splitting is also not acceptable as a raw Slate answer because it mutates document semantics to satisfy a view problem.
• PagesTableKit is useful proof that tables need special split logic. It is not a model for raw Slate; raw Slate should expose a generic box provider and split policy, while table/media packages provide table-specific behavior.

Ecosystem pass deltas:

• Strengthened the Tiptap row from "negative evidence" to "hard reject the CSS-float mechanism; steal only its failure taxonomy."
• Added DOMCoverage as an explicit ecosystem strategy row so virtualization does not get treated as layout-only.
• Added the GitHub large-surface sequence as performance discipline: reduce repeated-unit cost first, then virtualize the large tail.
• Kept the TanStack upgrade note as implementation fuel only. The public API still must not expose TanStack's option model.
• Left issue/PR fixed-claim counts unchanged; this pass changes planning confidence, not fixed issue scope.

Research, ecosystem strategy, and live-source refresh pass:

• compiled research artifact:
  • docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md added and indexed from the editor-architecture README and research index.
• local Pretext source refresh:
  • ../pretext/src/measurement.ts:36 still creates an OffscreenCanvas or DOM canvas context.
  • ../pretext/src/measurement.ts:49 still throws without canvas access.
  • ../pretext/src/measurement.ts:61 still calls ctx.measureText(seg).width.
  • ../pretext/src/measurement.ts:74 now makes browser engine profile knobs explicit, which strengthens the plan's measurement-profile requirement.
  • ../pretext/src/layout.ts:668 keeps prepare() as the segment measurement and cache phase.
  • ../pretext/src/layout.ts:696 keeps layout() arithmetic-only on cached widths.
• local Pretext research refresh:
  • ../pretext/RESEARCH.md:55 records system-ui canvas/DOM font-resolution mismatch.
  • ../pretext/RESEARCH.md:131 records emoji canvas/DOM width discrepancy.
  • ../pretext/RESEARCH.md:142 treats the HarfBuzz headless probe as useful research, not runtime direction.
  • ../pretext/RESEARCH.md:156 keeps final parity work in prepare() / browser diagnostics / small browser-specific tolerance, while layout() stays arithmetic-only.
• external Pretext refresh:
  • Cyrus Radfar article fetched 2026-05-25: https://cyrusradfar.com/thoughts/pretext-beyond-the-browser
  • the article supports the same split: portable hot layout is plausible, but initial measurement still depends on canvas.measureText() and matching browser font metrics outside the browser is hard work.
• current Slate v2 source refresh:
  • .tmp/slate-v2/packages/slate-layout/src/index.ts:105 has box kinds for block, code line, image, table, table cell, and thematic break.
  • .tmp/slate-v2/packages/slate-layout/src/index.ts:113 already names avoid, line, page, and row split policy vocabulary.
  • .tmp/slate-v2/packages/slate-layout/src/index.ts:236 has blocks, fragments, page, pages, root, settings, and version in snapshots.
  • .tmp/slate-v2/packages/slate-layout/src/index.ts:1349 still uses the Pretext page layout engine.
  • .tmp/slate-v2/packages/slate-layout/src/react.tsx:185 still maps projected blocks into top-level virtualized layout items.
  • .tmp/slate-v2/packages/slate-layout/src/react.tsx:219 still renders all page surfaces.
  • .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:548 still exposes only getVirtualizedTopLevelItems.
  • .tmp/slate-v2/packages/slate-react/src/dom-strategy/use-virtualized-root-plan.ts:95 retains selected/promoted top-level indexes through the range extractor.
• Premirror refresh:
  • ../premirror/README.md:14 describes measured snapshot -> deterministic layout with pages, frames, line boxes, and placed runs.
  • ../premirror/docs/milestone-1-implementation-plan.md:20 keeps a single contenteditable root and renders visual pagination from composed output.
  • ../premirror/docs/milestone-1-implementation-plan.md:22 represents page splits as layout fragments, not ProseMirror node splits.
• Tiptap refresh:
  • the Medium article URL currently returns a Cloudflare challenge to curl, so the plan treats the user's summary as review context, not independently refreshed text.
  • local ../tiptap-docs/src/content/pages/core-concepts/limitations.mdx:17 says Tiptap Pages uses CSS floats around page gaps; BFC blocks such as tables, figures, and styled containers cannot split across pages and can break pagination when too large.
  • local ../tiptap-docs/src/content/pages/core-concepts/limitations.mdx:18 uses max-height / --page-max-height as a mitigation for non-splittable blocks.
  • local ../tiptap-docs/src/content/pages/core-concepts/limitations.mdx:19 suggests manual node splitting and warns it changes document structure and may affect semantics.
  • local ../tiptap-docs/src/content/pages/guides/table-with-pages.mdx:16 says table pagination needs @tiptap-pro/extension-pages-tablekit because table behavior and layout were heavily modified to split across pages.
  • local ../tiptap-docs/src/content/pages/guides/table-with-pages.mdx:52 warns the open-source TableKit is not compatible with Pages layout; :63 warns extension authors can break the splitting logic.
  • official Tiptap Pages limitations fetched 2026-05-25: https://tiptap.dev/docs/pages/core-concepts/limitations
  • official Tiptap Pages table guide fetched 2026-05-25: https://tiptap.dev/docs/pages/guides/table-with-pages
  • current Tiptap docs validate the core pressure but not the mechanism: steal the failure taxonomy; reject the CSS-float/page-gap pagination model.
• pass decision:
  • keep Pretext.
  • add profile-aware layout vocabulary.
  • keep page-level virtualization as the paged-mode repeated unit.
  • do not expose TanStack, Pretext measurement caches, or Tiptap-style product table kits as raw Slate public API.
  • do not copy Tiptap's CSS-float pagination trick.
  • require provider/split-policy tests for table/media and page content rects.

Performance/DX/migration/regression/simplicity pressure pass:

• pressure verdict:
  • the architecture survives, but the public API needed a cut: no public pageVirtualization prop before beta.
  • domStrategy is already the public "I accept incomplete DOM" switch. PagedEditable should internally choose a page/spread mount plan when that strategy is virtualized.
  • authoritative breaks need read/write authority roles; a blanket read-write peer mode is too noisy for collaboration.
  • Tiptap Pages is useful as warning material, not as a model: the local docs confirm the CSS-float/BFC approach forces max-height hacks, manual semantic splits, and specialized table layout.
• performance pressure:

• DX pressure:

• migration pressure:

• regression pressure:

• simplicity pressure:
  • keep one public layout hook: useSlateLayout(editor, options).
  • keep one paged component: PagedEditable.
  • keep one public incomplete-DOM switch: domStrategy.
  • keep one page-view grouping: pageView.
  • keep pageBreaks advanced and optional.
  • use Tiptap Pages as a failure taxonomy only.
  • do not copy Tiptap's CSS-float/page-gap pagination model.
  • do not add a Tiptap-like TableKit to raw Slate; add provider/split protocol and let table/media packages satisfy it.
• implementation-skill pressure:
  • performance-oracle: applied. The hot loop is not React rendering; the risk is wrong repeated unit and page-surface overmounting.
  • performance: applied. Benchmark must count mounted pages/surfaces and edit latency, not only scroll range math.
  • vercel-react-best-practices: skipped for this planning pass; no React code edited, but execution must review effect dependencies and external-store subscriptions in useSlateLayout / PagedEditable.
  • react-useeffect: skipped for this planning pass; same reason.
  • tdd: N/A for planning, but proof gates are now test-shaped.
  • shadcn: skipped; no UI implementation and raw Slate public API is the issue.
• pass decision:
  • chosen public beta target:

const layout = useSlateLayout(editor, {
  page,
  pageBreaks: strictMode
    ? { mode: 'read', source: pageBreaks }
    : undefined,
  typography,
})

<PagedEditable
  domStrategy={{ type: 'virtualized', estimatedBlockSize: 48, overscan: 3, threshold: 80 }}
  layout={layout}
  pageView={{ gap: 24, mode: 'single' }}
/>

• PagedEditable may internally virtualize pages/spreads first when paged and virtualized. Block virtualization remains the continuous-editor repeated unit.

Legacy regression proof matrix:

Browser stress / parity strategy:

Verification workspace gate:

Final completion gates:

Applicable implementation-skill review matrix:

High-risk deliberate-mode pre-mortem: Pass verdict:

• Adjacent proof is strong enough to keep the direction, not strong enough to call the plan ready.
• The riskiest gap is not Pretext. It is the missing page/spread mount-plan contract inside PagedEditable: current code still feeds block layout items to Editable and renders every page surface.
• The second riskiest gap is authoritative break authority. The state-field substrate exists, but the page-break snapshot API, writer election, stale profile invalidation, and history/collab semantics do not.
• The third riskiest gap is truth-in-advertising for missing DOM. DOMCoverage has model-backed clipboard/find policies and materialization hooks, but paged virtualized mode still needs its own browser rows before any native-parity claim.

High-risk proof queue:

Slate maintainer objection ledger: Pass verdict:

• The architecture survives maintainer pressure, but only if the API stays brutally small and the ownership boundaries stay explicit.
• The biggest correction is page-break authority: strict snapshots are read-only for most peers; only a chosen writer writes derived break metadata, and those writes must be profile-hashed, stale-safe, and history-skipped by default.
• The second correction is table/media scope: raw slate-layout defines a provider/split protocol, not a Tiptap-style product TableKit.
• The third correction is runtime honesty: virtualized paged mode is a degraded DOM mode until browser find, clipboard, IME, and assistive-tech proof says otherwise.

Hard cuts and rejected alternatives:

Plan deltas from review:

• Added explicit Pretext determinism caveat.
• Added page-level virtualization as the paged-mode target.
• Added opt-in authoritative page-break snapshot extension point.
• Added Tiptap edge-case rows for paragraph splitting, tables, images, font variability, and padding.
• Kept Pretext as the right call; the revision is about contracts and repeated units, not about abandoning Pretext.
• Added related issue discovery and manual ledger sync classification for #5944, #790, #5924, #4141, #5131, #2051, #2793, #2572, #3892, #5945, #4056, and #5992.
• Added #2793 as the sharper screen-reader release guard for page/block virtualization.
• Hardened the intent/boundary pass into an owner-boundary contract and option matrix: raw Slate owns document/state; layout owns derived profiles/pages; React owns DOM mounting; collab/export owns authority; Plate/apps own product UI.
• Rejected server-only pagination authority as a default while keeping it as an opt-in writer for strict export/compliance flows.
• Cut public pageVirtualization before beta. domStrategy remains the public incomplete-DOM switch; paged mode chooses page/spread mount items internally.
• Split authoritative page-break snapshots into read/write authority roles to avoid every peer writing layout metadata.
• Added pushback on Tiptap Pages: its docs are negative evidence for CSS-float pagination, max-height hacks, manual semantic splits, and specialized table layout. Slate should steal the failure taxonomy, not the mechanism.
• Completed the maintainer objection ledger. The result keeps the architecture but narrows the public contract: strict breaks are read-mostly/elected-writer metadata, table/media logic is provider-owned, virtualized paged DOM stays explicit/degraded until browser proof, and examples split canonical DX from stress harness.
• Completed high-risk deliberate mode. Adjacent tests keep the direction alive, but the final proof queue is explicit: page/spread mount plan, authoritative break authority, provider split protocol, paged missing-DOM policy, canonical DX split, and .tmp/slate-v2 release gates.

Open questions and decision-changing evidence:

Implementation phases with owners:

Fast driver gates:

Final user-review handoff outline:

• accepted plan items: Pretext default layout engine, page/spread virtualization for paged mode, block/fragment virtualization for continuous/pathological docs, opt-in pageBreaks, metadata-only measurementProfile, provider/split protocols for table/media/BFC content, and explicit missing-DOM caveats.
• before / after API shape: replace scattered page display props with pageView; keep virtualized domStrategy as the only public incomplete-DOM switch; cut public pageVirtualization.
• hard cuts: no cross-client/server page-break determinism claim today, no CSS-float pagination model, no raw Slate product TableKit, no exposed TanStack or Pretext cache API, and no native-equivalence claim for unmounted pages.
• issue claims and non-claims: no new Fixes #...; no new Improves #...; #5944, #790, #2793/#2572, #5924, rerender guardrails, and large-doc rows remain proof-gated.
• proof gates: page/spread mount contract, mounted-count/edit-latency proof, authoritative break replay/stale checks, table/media fixtures, DOMCoverage browser rows, canonical example split, and .tmp/slate-v2 release commands.
• accepted-plan execution handoff: implementation starts only after explicit user acceptance and a new execution-shaped slate-plan invocation naming this plan.

Final completion gates:

Findings:

• Pretext is the right engine because it splits one-time preparation from hot-path arithmetic layout.
• Pretext is not fully headless today because measurement still requires OffscreenCanvas or DOM canvas.
• Current Slate v2 already has the right raw ingredients: page settings, fragments, pages, projections, Pretext engine, PagedEditable, state fields, and virtualized DOM strategy.
• Current paged virtualization shape is wrong for long-term architecture: PagedEditable feeds block geometry into Editable and renders every page surface.
• The feedback's authoritative-source idea is the correct strict-fidelity extension point. Make it opt-in, shared state, profile-hashed, and stale-safe.
• Related issue discovery found no basis for new fixed or improved issue claims.
• #2793 should be treated as a release guard for virtualized/missing-DOM modes; #2572 is too broad/docs-shaped to carry that alone.

Decisions and tradeoffs:

• Decision: paged mode virtualizes pages/spreads first.
• Decision: continuous/pathological mode may virtualize top-level blocks or layout fragments.
• Decision: strict collab/export reads an authoritative page-break snapshot when supplied and valid.
• Tradeoff: more API vocabulary, but it prevents the worse mistake: pretending local browser layout is document truth.

External/browser findings:

• Cyrus Radfar article, read 2026-05-25: https://cyrusradfar.com/thoughts/pretext-beyond-the-browser
  • Pretext improves virtual scrolling by predicting variable text heights before rendering.
  • Server/CI use cases are plausible because the hot path is arithmetic.
  • The catch is still prepare(): measurement depends on canvas.measureText() unless a matching headless/native measurement layer exists.
• Romik Makavana Tiptap article, attempted 2026-05-25: https://romik-mk.medium.com/tiptap-pagination-problems-solutions-31f1a0b51e08
  • curl returned a Cloudflare challenge, so this remains user-summary context.
  • Paragraph breaks fail when inline widths/font sizes/line heights/emoji/inline nodes vary.
  • Tables fail around row splitting, merged cells, nested structures, and footer overlap.
  • Padding/blank spacer hacks lose lines and corrupt page geometry.
• Local Tiptap Pages docs, read 2026-05-25 from ../tiptap-docs:
  • Pages limitations use CSS floats around page gaps; BFC blocks such as tables, figures, and styled containers cannot split and can break pagination.
  • the documented mitigations are max-height/--page-max-height and manual node splitting, which is exactly why Slate should not copy the mechanism.
  • the table guide requires a Pages-specific TableKit with heavily modified behavior/layout and warns the open-source TableKit is incompatible.

Source evidence:

• ../pretext/RESEARCH.md:20 says the goal is expensive text work once in prepare() and arithmetic-only layout().
• ../pretext/RESEARCH.md:55 documents system-ui canvas/DOM resolution mismatch on macOS and recommends named fonts for accuracy.
• ../pretext/RESEARCH.md:131 documents emoji canvas/DOM discrepancy.
• ../pretext/RESEARCH.md:142 says the HarfBuzz headless probe was useful but not runtime direction.
• ../pretext/src/measurement.ts:36 requires OffscreenCanvas or DOM canvas and throws without one.
• ../pretext/src/measurement.ts:61 calls ctx.measureText(seg).width.
• .tmp/slate-v2/packages/slate-layout/src/index.ts:113 already has split policy vocabulary: avoid, line, page, row.
• .tmp/slate-v2/packages/slate-layout/src/index.ts:236 defines the page layout snapshot with blocks, fragments, pages, root, settings, and version.
• .tmp/slate-v2/packages/slate-layout/src/index.ts:1349 implements the Pretext page layout engine.
• .tmp/slate-v2/packages/slate-layout/src/react.tsx:185 maps projection blocks into top-level virtualized items.
• .tmp/slate-v2/packages/slate-layout/src/react.tsx:219 renders all page surfaces.
• .tmp/slate-v2/packages/slate-react/src/dom-strategy/use-virtualized-root-plan.ts:212 consumes top-level runtime ids and block layout items.
• .tmp/slate-v2/site/examples/ts/pagination.tsx:41 keeps page settings in a shared, persisted state field.
• docs/research/sources/editor-architecture/pretext-pagination-page-virtualization.md records the current Pretext / page virtualization / Tiptap Pages research synthesis.
• local and official Tiptap Pages docs read/fetched 2026-05-25 record CSS-float page gaps, oversized non-splittable BFC blocks, max-height/manual split mitigations, figures, and specialized table extensions as current pagination constraints.

Timeline:

• 2026-05-25: Slate Plan goal created for virtualization/pagination feedback.
• 2026-05-25: Current-state pass completed with local Pretext source, external article evidence, live .tmp/slate-v2 source, existing plan/ledger evidence, and initial score.
• 2026-05-25: Related issue discovery completed from live/current ledgers. No new fixed/improved claims found; #2793 added as screen-reader release guard.
• 2026-05-25: Issue-ledger pass completed. Manual sync rows were appended to gitcrawl-v2 sync ledger, issue coverage matrix, and fork dossier; PR reference was inspected and left unchanged because this plan adds no fixed/improved claims.
• 2026-05-25: Intent/boundary and decision brief pass completed. The plan now has owner boundaries, non-goals, decision rules, option matrix, chosen architecture, consequences, and next research owner.
• 2026-05-25: Research, ecosystem strategy, and live-source refresh pass completed. Added a compiled research source page, refreshed current Pretext and Slate v2 source lines, fetched Cyrus, read local/official Tiptap Pages docs, and recorded the Medium current-access caveat.
• 2026-05-25: Performance/DX/migration/regression/simplicity pressure pass completed. Cut public pageVirtualization, kept domStrategy as the public incomplete-DOM switch, split authoritative page-break roles, and sharpened package/browser/a11y/IME/clipboard/table/media proof gates. Applied the Tiptap correction: use Pages as negative evidence, not as a CSS-float model to steal.
• 2026-05-25: Slate maintainer objection ledger completed. Kept the architecture but narrowed the public contract: no core Pretext dependency, no default shared page-break writes, no raw Slate product TableKit, no native-equivalence claim for missing DOM, and no proof-harness complexity in canonical DX.
• 2026-05-25: High-risk deliberate mode completed. Expanded the pre-mortem into release-blocking failure rows, separated adjacent proof from missing final proof, and named package/browser/release gates for every risky claim.
• 2026-05-25: Ecosystem maintainer pass completed. Confirmed no strategy reversal; hardened Tiptap Pages into negative evidence against CSS-float pagination, added DOMCoverage and GitHub large-surface rows to the ecosystem strategy table, and kept TanStack upgrades as implementation fuel only.
• 2026-05-25: Revision pass completed. Locked the public beta target around pageView, virtualized domStrategy, internal page/spread virtualization, metadata-only measurement profiles, opt-in pageBreaks, generic provider split policies, and no new fixed/improved issue claims.
• 2026-05-25: Issue sync accounting completed. Synced final API/proof wording into the v2 sync ledger, issue coverage matrix, fork dossier, and PR reference; fixed/improved claim counts remain unchanged.

Verification evidence:

• Active goal: get_goal returned the matching Slate Plan objective for this virtualization/pagination feedback lane.
• Skill gate: .agents/skills/slate-plan/SKILL.md was read in this closure pass; closure is legal because all previous scheduled pass rows were already complete.
• Planning artifact gate: this plan records current-state source reads, ecosystem research, issue/reference accounting, maintainer objections, high-risk proof gates, final API revision, issue sync accounting, scorecard, and handoff.
• Behavior/browser proof boundary: no Slate v2 tests or browser proof were run in this planning closure because this lane does not change implementation or claim behavior. The plan names the exact package/browser proof gates required before accepted implementation, release-quality browser claims, or issue closure.
• Final checker: node .agents/rules/autogoal/scripts/check-complete.mjs docs/plans/2026-05-25-slate-v2-pretext-pagination-virtualization-feedback.md returned [autogoal] complete: docs/plans/2026-05-25-slate-v2-pretext-pagination-virtualization-feedback.md.

Final user-review handoff:

• Recommended architecture: keep Pretext as the default slate-layout engine, but state the measurement contract honestly. prepare() still depends on canvas/browser/font profile behavior, so cross-client/server page-break determinism is not a default promise.
• Public API target: useSlateLayout, PagedEditable, pageView, virtualized domStrategy, and optional pageBreaks. Cut public pageVirtualization; do not expose TanStack, Pretext caches, or product TableKit mechanics.
• Runtime target: paged mode virtualizes pages/spreads first; continuous or pathological documents can keep block/fragment virtualization.
• Strict fidelity: pageBreaks is opt-in metadata with read/write authority, measurement/profile hashes, stale rejection, writer identity, history-skip derived writes, and export-reader proof.
• Tiptap lesson: steal the failure taxonomy for BFC blocks, tables, figures, styled containers, oversized media, padding/content rects, extension breakage, export, and collab. Reject CSS-float pagination, max-height correctness hacks, manual semantic splitting, and raw Slate product TableKit.
• Issue posture: no new Fixes #... and no new Improves #.... #5944, #790, #2793/#2572, #5924, rerender guardrails, and large-doc rows remain proof-gated exactly as recorded.
• Execution boundary: implementation begins only after explicit user acceptance and a new execution-shaped slate-plan invocation naming this plan. Execution must run focused package tests and pagination/DOMCoverage browser rows from .tmp/slate-v2 before any release or issue-closure claim.

Reboot status:

Open risks:

• None for planning closure. Implementation risks remain intentionally execution-gated: page/spread mount planning, authoritative break replay, provider/split fixtures, missing-DOM browser proof, canonical example split, and release command proof.