Slate v2 TanStack Virtual iOS/perf refresh ralplan

Current Verdict

Upgrade TanStack Virtual. Do not change Slate's public API.

The 2026-05-19 TanStack Virtual release is not "just inner" for Slate because our virtualized mode currently bypasses TanStack for one layout-backed scroll branch. The right plan is:

1. bump .tmp/slate-v2 from @tanstack/[email protected] / @tanstack/[email protected] to @tanstack/[email protected] / @tanstack/[email protected];
2. keep domStrategy={{ type: 'virtualized', threshold, overscan, estimatedBlockSize }} as the public Slate-shaped API;
3. keep TanStack raw options private;
4. route internal layout-backed scrollToTopLevelIndex through TanStack's scrollToOffset / scrollToIndex path where practical instead of direct rootElement.scrollTo;
5. do not override shouldAdjustScrollPositionOnItemSizeChange;
6. do not expose takeSnapshot() publicly yet.

Blunt take: the public usage is already mostly right. The internal scroll bypass is the only thing I would change now.

Current score after pass 3: 0.92. Target score: >= 0.92, with no dimension below 0.85.

This lane is done and ready for Ralph execution.

Intent

Refresh Slate v2 virtualization strategy against the latest TanStack Virtual performance/iOS work and decide whether Slate usage should change.

Outcome

Ralph should get a narrow implementation handoff:

• update the TanStack Virtual dependency;
• keep Slate public API unchanged;
• route internal virtualized scroll writes through TanStack where that preserves Slate layout offsets;
• add browser/proof rows for backward scroll and iOS/momentum behavior;
• keep virtualized mode experimental.

Source Grounding

External:

• TanStack blog https://tanstack.com/blog/tanstack-virtual-perf-and-ios, published 2026-05-19 and read 2026-05-23.
• NPM current metadata read on 2026-05-23: @tanstack/[email protected] depends on @tanstack/[email protected].
• TanStack Virtual latest Virtualizer API docs read on 2026-05-23.

Live .tmp/slate-v2:

• packages/slate-react/package.json:18-24 declares @tanstack/react-virtual as a slate-react dependency with range ^3.13.24.
• bun.lock:563-565 resolves @tanstack/[email protected] and @tanstack/[email protected], so the latest core perf/iOS fixes are not installed.
• packages/slate-react/src/dom-strategy/use-virtualized-root-plan.ts:95-115 retains selected/promoted indexes through a custom rangeExtractor.
• packages/slate-react/src/dom-strategy/use-virtualized-root-plan.ts:242-268 uses estimateSize, runtime-id getItemKey, getScrollElement, initialRect, overscan, and rangeExtractor.
• packages/slate-react/src/dom-strategy/use-virtualized-root-plan.ts:345-367 directly calls rootElement.scrollTo(...) for layout-backed targets before falling back to virtualizer.scrollToIndex(...).
• docs/libraries/slate-react/experimental-virtualized-rendering.md:20-44 keeps TanStack Virtual internal and does not expose raw virtualizer options.
• docs/libraries/slate-react/experimental-virtualized-rendering.md:46-61 explicitly labels native find, screen-reader, IME, and mobile limitations.

Decision Brief

Principles:

1. TanStack owns viewport math, not editor semantics.
2. Slate owns DOM coverage, materialization, selection, copy/paste, IME, mobile, browser-find, a11y, and metrics.
3. The default editor path stays native/DOM-present.
4. virtualized stays explicit and experimental.
5. Public Slate API stays editor-shaped, not TanStack-shaped.

Top drivers:

• latest upstream iOS and backward-scroll fixes;
• extreme document performance;
• native contenteditable behavior under missing DOM;
• public API cleanliness.

TanStack Update Implications

Public API Target

Keep:

<Editable
  domStrategy={{
    estimatedBlockSize: 32,
    overscan: 4,
    threshold: 25_000,
    type: 'virtualized',
  }}
  style={{ height: 480, overflowY: 'auto' }}
/>

Do not expose:

• getScrollElement
• measureElement
• rangeExtractor
• shouldAdjustScrollPositionOnItemSizeChange
• takeSnapshot
• initialMeasurementsCache
• lanes
• raw TanStack Virtualizer instance

Internal Runtime Target

Ralph implementation target:

• run the package manager update in .tmp/slate-v2 so bun.lock resolves @tanstack/[email protected] and @tanstack/[email protected];
• change layout-backed scrollToTopLevelIndex to call virtualizer.scrollToOffset(Math.max(0, top)) or an equivalent TanStack-owned scroll path when it preserves Slate layout offsets;
• keep the fallback virtualizer.scrollToIndex(index, { align });
• memoize getItemKey / getScrollElement if the new package makes option identity churn visible in tests or profiles;
• keep selected/promoted index retention as Slate-owned rangeExtractor logic;
• do not add custom shouldAdjustScrollPositionOnItemSizeChange by default;
• keep takeSnapshot() private and unshipped unless a remount restoration test proves the need.

Performance Lens

• applicability: applied
• Vercel rules used: event/listener and subscription minimalism by existing Slate virtualized adapter shape
• extra rules used: repeated-unit budget, degradation contract, editor-native-behavior proof
• repeated unit: top-level Slate runtime block
• cohorts: normal DOM-present, large staged, pathological virtualized
• budget: virtualized mode must reduce mounted top-level blocks without global selection/copy/paste semantic loss
• React/runtime primitive: TanStack Virtual remains range engine; React is not editor semantics
• degradation contract: native find and full screen-reader traversal remain limited until mounted
• plan delta: upgrade dependency and remove direct scroll-write bypass

Regression Proof Required From .tmp/slate-v2

Focused commands for Ralph:

bun update @tanstack/react-virtual
bun test ./packages/slate-react/test/dom-strategy-and-scroll.tsx
bun --filter ./packages/slate-react typecheck
PLAYWRIGHT_RETRIES=0 bun run playwright playwright/integration/examples/huge-document.test.ts --project=chromium --workers=1 --grep virtualized
PLAYWRIGHT_RETRIES=0 bun run playwright playwright/integration/examples/pagination.test.ts --project=chromium --workers=1 --grep virtualized
bun lint:fix

Add or preserve proof rows:

• virtualized backward-scroll with dynamic heights does not jump upward;
• layout-backed scrollToTopLevelIndex keeps exact Slate layout offsets;
• browser/iOS lane is semantic until real iOS proof exists;
• virtualized mode stays explicit and degraded;
• native find/a11y limits stay documented.

Issue Accounting

Pass 2 classification:

• New fixed claims: 0.
• New improved claims: 0.
• #790: related performance/virtualization proof-route backlog only.
• #5826, #5538, #4995, #5088, #5473: related scroll/focus rows only. Upstream iOS momentum scroll deferral supports the internal scroll-routing implementation route, but exact Slate repro closure still needs targeted proof.
• #5391, #5095, #4751, #4354, #3760: related/non-claimed mobile rows only. TanStack iOS scroll handling is not proof of Slate iOS selection, IME, spellcheck, or native toolbar correctness.

Synced artifacts:

• docs/slate-issues/gitcrawl-v2-sync-ledger.md: added 2026-05-23 TanStack Virtual iOS/perf sync notes and corrected stale virtualized adapter paths.
• docs/slate-v2/ledgers/issue-coverage-matrix.md: updated #790 policy row to reference latest TanStack Virtual as internal proof-route work, not a closure claim.
• docs/slate-v2/ledgers/fork-issue-dossier.md: added a TanStack Virtual iOS/perf refresh section with issue classifications and zero new claims.
• docs/slate-v2/references/pr-description.md: unchanged; this pass changes no public API shape, no exact fixed issue claim, and no release-ready proof row. Ralph implementation may update it after package/browser proof.

Pass 3 must run maintainer/high-risk/performance closure pressure before this can become a Ralph-ready handoff.

Confidence Scorecard

Weighted total after pass 1: 0.88.

Still pending because regression-proof testing is below 0.85, issue sync is not complete, and closure gates have not run.

Score After Pass 2

Total rises from 0.88 to 0.89.

Weighted total: 0.89.

Still pending because the maintainer/high-risk pass and closure gates are open.

Pass 3 - Maintainer / High-Risk / Performance Closure Pressure

Steelman, high-risk deliberate, and performance pressure pass applied.

Maintainer Objection Ledger

High-Risk Trigger

This pass touches a browser-sensitive runtime dependency and virtualized scroll behavior. The blast radius is limited to experimental virtualized mode, but the failure modes are visible: jumpy scroll, wrong target materialization, broken copy/selection over missing DOM, and false iOS confidence.

Blast Radius

Three-Scenario Pre-Mortem

1. Dependency upgrade looks green but scroll jumps in a real editor.

   Cause: package tests only prove mounted ranges, not dynamic-height backward scroll after measurement. Guardrail: browser row for backward scroll with measured variable-height blocks.

2. iOS blog headline creates false confidence.

   Cause: TanStack fixed scrollTop writes during momentum scroll, not Slate's iOS selection handles, IME, spellcheck, or toolbar behavior. Guardrail: issue ledger keeps iOS rows related/non-claimed and Ralph proof names iOS as semantic until raw-device proof exists.

3. Slate leaks TanStack API to solve one edge case.

   Cause: a user asks for shouldAdjustScrollPositionOnItemSizeChange or takeSnapshot directly. Guardrail: keep raw options private; add internal targeted behavior only after a failing Slate test proves need.

Final Proof Matrix For Ralph

Performance Verdict

The best architecture is unchanged:

• normal editors use DOM-present/staged rendering;
• pathological documents may opt into explicit virtualized;
• TanStack Virtual owns visible range, measurement, overscan, and scroll writes;
• Slate owns DOM coverage, materialization, model-backed copy/paste, selection, IME/mobile policy, browser-find/a11y limits, and RUM metrics.

The only implementation revision is internal: avoid direct scroll writes in the virtualized adapter when TanStack can perform the same offset write.

Score After Pass 3

Total rises from 0.89 to 0.92.

Weighted total: 0.92.

The score threshold is met, but completion is still pending. Closure is the only remaining pass, and it must run separately.

Pass State

Pass 4 - Closure Score And Final Gates

Closure pass applied.

Closure Audit

Done Handoff

• Public API: keep domStrategy={{ type: 'virtualized', threshold, overscan, estimatedBlockSize }}.
• Public API: do not expose getScrollElement, measureElement, rangeExtractor, shouldAdjustScrollPositionOnItemSizeChange, takeSnapshot, initialMeasurementsCache, lanes, or raw TanStack Virtualizer.
• Dependency: upgrade .tmp/slate-v2 to @tanstack/[email protected], which resolves @tanstack/[email protected].
• Internal runtime: route layout-backed scrollToTopLevelIndex through TanStack's scroll path where practical instead of direct rootElement.scrollTo.
• Internal runtime: keep Slate layout offsets authoritative; pass exact offsets through scrollToOffset when using TanStack for the scroll write.
• Internal runtime: keep selected/promoted index retention as Slate-owned rangeExtractor logic.
• Internal runtime: do not override shouldAdjustScrollPositionOnItemSizeChange by default.
• Internal runtime: keep takeSnapshot() private and unshipped unless a remount/restoration test proves the need.
• Rendering strategy: keep virtualized mode explicit, degraded, and experimental.
• Native behavior: native find and full screen-reader traversal remain limited until mounted.
• iOS: TanStack's iOS scrollTop deferral is useful for scroll writes, but it is not Slate iOS selection/IME/spellcheck proof.
• Issue accounting: #790 remains related proof-route backlog.
• Issue accounting: #5826, #5538, #4995, #5088, and #5473 remain related scroll/focus rows only.
• Issue accounting: #5391, #5095, #4751, #4354, and #3760 remain related/non-claimed mobile rows only.
• Claim counts: new fixed claims 0; new improved claims 0.
• Ralph verification:

bun update @tanstack/react-virtual
bun test ./packages/slate-react/test/dom-strategy-and-scroll.tsx
bun --filter ./packages/slate-react typecheck
PLAYWRIGHT_RETRIES=0 bun run playwright playwright/integration/examples/huge-document.test.ts --project=chromium --workers=1 --grep virtualized
PLAYWRIGHT_RETRIES=0 bun run playwright playwright/integration/examples/pagination.test.ts --project=chromium --workers=1 --grep virtualized
bun lint:fix

• Ralph proof additions: backward-scroll dynamic-height row and layout-backed virtualized scroll offset row.

Ralph Execution Log

• 2026-05-23 08:32 CEST: Ralph execution started. Completion state reset to pending for runtime id 019e5374-b6ff-78f3-848c-dda660d40b64; active implementation owner is .tmp/slate-v2.
• 2026-05-23 08:40 CEST: Ralph execution complete. .tmp/slate-v2 updated slate-react to @tanstack/[email protected] / @tanstack/[email protected], routed layout-backed virtualized scroll through virtualizer.scrollToOffset, added exact-offset and dynamic-height backward-scroll proof rows, and added a slate-react patch changeset. Verification passed: bun install --frozen-lockfile; package Vitest dom-strategy-and-scroll.test.tsx with 37 tests; bun --filter ./packages/slate-react typecheck; huge-document virtualized Playwright grep with 2 tests; pagination virtualized Playwright grep with 1 test; and final bun lint:fix. The raw plan command bun test ./packages/slate-react/test/dom-strategy-and-scroll.tsx was not the right runner for this Vitest-backed file.