Slate v2 Absolute Architecture Cleanliness Review

status: done owner: slate-ralplan created: 2026-05-11 completion: active goal state continuation: active goal state

Verdict

No. Slate v2 has the right core bet, but it is not the cleanest possible architecture yet.

Do not rewrite the editor kernel. Keep the JSON document model, deterministic operations, commit metadata, editor.read, editor.update, state and tx extension namespaces, internal command middleware, and explicit stress rendering modes. That shape is better than legacy Slate and closer to the right ProseMirror/Lexical lesson: transaction-owned state changes, explicit dirty regions, and runtime-owned browser bridges.

The remaining architecture debt is narrower and more useful:

1. Prove or replace the custom selector substrate.
2. Split the root runtime coordinator into smaller owners.
3. Keep huge-document direct comparison as a regression gate, not a blocker: the fresh narrowed run makes default auto strong enough for architecture planning, while DOM-present staged and experimental modes still need honest native-behavior/proof rows.

Anything broader than that is architecture theater.

Intent Boundary

Current Source Evidence

Current Verification

Commands were run from the live sibling repo, not from plate-2.

Fresh benchmark highlights:

• selection breadth: broad renders 0, left block renders 0, right block renders 0, selection p95 4.6ms
• many leaf edit: block renders 0, sibling leaf renders 0, edited leaf renders 1, edit p95 4.27ms
• deep ancestor edit: ancestor render events 0, sibling branch/leaf renders 0, deep leaf renders 1, edit p95 4.33ms
• source-scoped invalidation: unrelated source recomputes stay 0 for text, selection, and external lanes

This is real evidence for the current invalidation direction. It does not close the direct huge-document typing/select gate against legacy chunking.

Final Score

Threshold for done: 0.92 with no P0 unresolved architecture item.

Keep

Rewrite Or Prove

P0: selector substrate

Current source:

• useGenericSelector uses useReducer force-render and ref-cached selector state.
• useEditorSelector wires that helper into editor/global/runtime/deferred listener fanout.
• Adjacent annotation/projection/widget stores use useSyncExternalStore.

Plan:

1. Build a tiny useEditorExternalStoreSelector adapter in the execution slice.
2. Compare it against current useGenericSelector for:
   • same-turn commit coalescing
   • selector error replay behavior
   • runtime-id scoped invalidation
   • deferred selector flush
   • React 19 compatibility under hidden/activity panels
3. Keep the current helper only if the execution proof records why useSyncExternalStore makes behavior worse or cannot model operations/change metadata cleanly.
4. If external-store wins, migrate editor and decoration selectors behind one adapter and keep the public hook surface unchanged.

Decision:

• Do not rewrite every selector blindly.
• Execute a proof spike first.
• The cleanest final architecture is one editor selector store adapter that can explain why it is or is not useSyncExternalStore-based. A custom force-render helper is acceptable only if it is explicitly defended by tests and benchmarks.

Proof:

cd /Users/zbeyens/git/slate-v2
bun --filter slate-react typecheck
cd /Users/zbeyens/git/slate-v2/packages/slate-react
bun test:vitest test/provider-hooks-contract.test.tsx test/surface-contract.test.tsx
cd /Users/zbeyens/git/slate-v2
bun run bench:react:rerender-breadth:local

P0: root runtime coordinator

Current source:

• useEditableRootRuntime is 405 lines and wires almost every browser-runtime subsystem.
• Several subsystems already exist as separate modules, but the composition owner is still a dense dependency hub.

Plan:

1. Keep the public <Editable> API stable.
2. Split by ownership, not by file-size vanity:
   • composition and pending marks
   • Android/native input import
   • selection import/export/reconcile
   • repair and trace
   • input rules
   • event runtime bindings
   • scroll intent/export handoff
3. Add package contract rows before each split so behavior is pinned.
4. Do not split if the extracted owner just becomes a bag of refs.

Decision:

• Split ownership, not just files.
• The root hook may remain a coordinator, but it should stop owning every browser subsystem directly.
• A split that merely exports a giant mutable context is worse than doing nothing.

Proof:

cd /Users/zbeyens/git/slate-v2/packages/slate-react
bun test:vitest test/rendering-strategy-and-scroll.test.tsx
cd /Users/zbeyens/git/slate-v2
bun --filter slate-react typecheck

P0: huge-document typing/select gate

Current docs explicitly said the direct legacy comparison was open for typing/select lanes. This pass reran a narrowed fresh comparison for the release-relevant current surfaces.

Fresh command:

cd /Users/zbeyens/git/slate-v2
REACT_HUGE_COMPARE_SKIP_BUILD=1 REACT_HUGE_COMPARE_SURFACES=v2DefaultRenderAuto,v2DomPresent,v2VirtualizedExperimental REACT_HUGE_COMPARE_BLOCKS=5000 REACT_HUGE_COMPARE_ITERATIONS=5 REACT_HUGE_COMPARE_TYPE_OPS=10 bun run bench:react:huge-document:legacy-compare:local

Result:

selectAllMs has a tiny mean regression for default auto (1.16ms versus 0.94ms) caused by one 4.65ms sample; median is still better (0.30ms versus 0.93ms). That is not an architecture blocker.

v2DomPresent still has a few small middle-selection mean losses against legacy chunking-on, and v2VirtualizedExperimental is still an explicit degradation tier. Keep those as proof rows, not default-architecture blockers.

Cut

Ecosystem Synthesis

Applicable Skill Review Notes

Issue Accounting

No issue claims change in this pass.

Broad GitHub issue rediscovery was not run. Cached ledgers were read first:

• 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/gitcrawl-v2-sync-ledger.md
• docs/slate-issues/gitcrawl-live-open-ledger.md

ClawSweeper result:

No changes were needed in issue-coverage-matrix.md, fork-issue-dossier.md, gitcrawl-v2-sync-ledger.md, or pr-description.md.

Pass Schedule

Future Ralph Execution Queue

Run with ralph if the user wants execution.

1. Selector substrate proof spike.
2. Root runtime split with contract-first tests.
3. Huge-document direct comparison regression guard sync if implementation changes selector/runtime behavior.
4. PR reference and issue-ledger sync only if public claims change.

Current Handoff

The plan is done as a review/planning gate. The current answer is:

Best core architecture: yes. Cleanest final implementation: not yet. The next execution work is selector substrate proof, root runtime ownership cleanup, and regression-guarded huge-doc verification.

Ralph Execution Ledger

2026-05-11: selector substrate proof started

• Trigger: user requested ralph full.
• Current owner: .tmp/slate-v2/packages/slate-react/src/hooks.
• Scope: prove or replace useGenericSelector as the substrate for useEditorSelector and useDecorationSelector.
• Known starting point: useGenericSelector uses a reducer-based force-render path; projection, annotation, and widget stores already use useSyncExternalStore.
• First gates:
  • bun test:vitest test/provider-hooks-contract.test.tsx
  • bun --filter slate-react typecheck
  • bun run bench:react:rerender-breadth:local
• Issue/reference status: no public claim change yet; no ClawSweeper rerun needed until behavior or issue claims change.

2026-05-11: Ralph execution closed

• Selector substrate result: .tmp/slate-v2/packages/slate-react/src/hooks/use-generic-selector.tsx now uses useSyncExternalStore as the subscription primitive instead of useReducer force-rendering.
• Selector contracts: .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx now pins the external-store substrate; provider/decorator contracts stayed green.
• Root runtime result: .tmp/slate-v2/packages/slate-react/src/editable/runtime-root-selection-import.ts owns selectionchange handler, scheduler, and import-controller construction.
• Root runtime contract: .tmp/slate-v2/packages/slate-react/test/kernel-authority-audit-contract.ts now pins selection import ownership to the root selection import module.
• Reference/issue sync: no change needed. The slice changed internal runtime ownership and selector substrate only; public API and issue claims did not change.
• Verification:
  • bun run lint:fix: pass; formatted three files.
  • bun --filter slate-react typecheck: pass after lint.
  • bun test:vitest test/provider-hooks-contract.test.tsx test/surface-contract.test.tsx test/projections-and-selection-contract.test.tsx test/kernel-authority-audit-contract.test.ts test/rendering-strategy-and-scroll.test.tsx: pass, 5 files / 91 tests.
  • bun run bench:react:rerender-breadth:local: pass; broad/sibling/ancestor render counts remain zero in the measured rows.
  • REACT_HUGE_COMPARE_SKIP_BUILD=1 REACT_HUGE_COMPARE_DISPOSE_DELAY_MS=0 REACT_HUGE_COMPARE_SURFACES=v2DefaultRenderAuto,v2DomPresent,v2VirtualizedExperimental REACT_HUGE_COMPARE_BLOCKS=5000 REACT_HUGE_COMPARE_ITERATIONS=5 REACT_HUGE_COMPARE_TYPE_OPS=10 bun run bench:react:huge-document:legacy-compare:local: pass. v2DefaultRenderAuto beat legacy chunking-on on every recorded mean: ready 22.82ms vs 332.03ms, select all 0.31ms vs 0.98ms, start type 11.64ms vs 51.02ms, middle type 10.88ms vs 56.47ms, middle select then type 45.61ms vs 48.6ms, promote then type 33.18ms vs 54.5ms, full replace 5.35ms vs 117.34ms, fragment insert 6.52ms vs 115.96ms.