Slate v2 DOM Selection, Focus, And Bridge Ralplan

1. Current Verdict

Do this lane, but do not repeat the closed DOM selection boundary proof.

docs/plans/2026-05-06-slate-v2-dom-selection-boundary-proof-ralplan.md already closed the first strict boundary pass at 0.96. It claims exact browser fixes for the high-confidence rows such as outside-to-inside selection and parent-to-nested-editor selection. The second DOM selection lane should start where that plan stops:

• parent/child editor ownership that still lacks exact closure, especially #5947 and #4842;
• focus restore and scroll behavior, especially #5867, #5826, #5538, #5568, #3497, #5537, #4961, and #3634;
• shadow DOM event-to-range behavior, especially #5107, #5749, and #4337;
• fail-closed DOM point/range import for foreign, stale, external, or app-owned DOM, especially #5711, #3834, #3836, #3723, #4564, #4643, #4088, #3918, and #4851;
• custom inline, void, and table selection leftovers, especially #5806, #3449, and #2558.

The plan is ready for ralph. Pass 12 completed closure scoring. The private bridge still wins, the execution shape is concrete, and the ledgers match the claim policy: no new fixed issue claims from this planning pass, #5947 stays improves-only, and the rest of the DOM/focus surface stays related or not claimed until exact proof exists.

2. Intent And Boundary Record

Intent:

• Turn the remaining selection/focus/DOM bridge pressure into one execution plan that does not create hundreds of issue-sized plans.

Desired outcome:

• Slate v2 has explicit runtime ownership for native DOM selection import, model selection export, focus/scroll restoration, nested-editor ownership, shadow DOM event ranges, and fail-closed DOM point/range conversion.

In scope:

• slate-dom DOM point/range conversion, event range resolution, shadow DOM roots, nested editor containment, and fail-closed conversion policy.
• slate-react selection controller/reconciler behavior, focus state, selectionchange ownership, model-vs-DOM selection preference, and scroll timing.
• Browser rows copied or adapted from Lexical and ProseMirror where they express portable editor behavior.
• Issue-ledger accounting for exact fixed, improved, related, and not-claimed rows.

Non-goals:

• No Android/iOS closure without raw device proof.
• No public normalizePoint or app-authored DOM selection hook.
• No Plate-owned workaround as the answer.
• No claim that Slate v2 implements Lexical's whole-table selection model unless Slate v2 deliberately adds that model.
• No implementation code in this Slate Ralplan pass.

Decision boundaries:

• The plan may choose private runtime structure and test/proof ownership.
• Public API changes are rejected for this lane unless a later browser proof shows private ownership cannot express a supported raw-Slate behavior.
• Exact GitHub Fixes #... claims require matching Slate v2 proof in /Users/zbeyens/git/slate-v2.
• Related issues can be grouped by behavior family, not one plan per issue.
• slate-dom owns DOM root, target, point, range, shadow, nested-editor, and stale/foreign classification.
• slate-react owns when a classified DOM selection is imported, when the model selection is exported, focus-state timing, scroll timing, and React listener lifecycle.
• slate core owns logical caret movement and transforms such as soft-break vertical navigation unless browser proof shows the model/DOM bridge is the actual failure.
• Ecosystem or product models stay outside this lane: Web Components, custom table rowspan semantics, whole-table multi-cell selection, and structural ignore-cursor APIs.

Unresolved user-decision points:

• None. Public API remains unchanged for this plan. A future exact repro may reopen that, but this pass found no row that justifies exposing app-authored DOM selection policy.

3. Decision Brief

Principles:

• One owner per native selection decision.
• Runtime paths fail closed; strict low-level helpers may still throw.
• Browser proof beats confident architecture prose.
• Slate core stays model-first and unopinionated.
• Mobile and IME claims need honest transport, not desktop simulation dressed up as device proof.

Top drivers:

• Selection, Focus, And DOM Bridge is the biggest issue theme at 172 issues in docs/slate-issues/requirements-from-issues.md:40-42.
• The requirements file assigns DOM point/path translation, selection bridge, shadow DOM, and nested editor DOM boundaries to slate-dom-v2, while slate-react-v2 owns lifecycle, focus timing, and React-facing events (docs/slate-issues/requirements-from-issues.md:188-198).
• Live source already has separate DOMEditor conversion primitives and React selection controller/reconciler policy; this is a consolidation and proof plan, not a blank rewrite.

Viable options:

Chosen option:

• Keep strict helpers in DOMEditor, but make runtime event/focus paths consume one private result-oriented selection bridge with explicit ownership reasons. slate-react decides when to import/export/reconcile. slate-dom decides how DOM points, ranges, roots, and foreign targets are classified.

Pass 4 refinement:

• Do not create a public normalizePoint, cursor-exclusion, table-selection, or app-authored DOM classifier API.
• Do not move all bridge behavior into slate-react; slate-react should consume classification and make timing/policy decisions.
• Do not hide strict DOMEditor.toSlatePoint / toSlateRange errors globally; only runtime event paths should fail closed.
• Do not treat #5524 as a DOM bridge fix until proof shows native selection import/export is the failure rather than core caret movement.
• Do not treat #5550/#5551/#5924 as raw Slate closure targets.

Consequences:

• Most work should be private architecture plus browser/unit proof.
• Public API should stay unchanged unless a leftover issue proves private ownership is insufficient.
• Some related issues will remain related, not fixed. That is correct.

Follow-ups:

• Related-issue discovery pass with ClawSweeper.
• Maintainer objection pass against the accepted private bridge.
• Browser proof pass before implementation handoff.

4. Confidence Scorecard

| Dimension | Score | Evidence | | -------------------------------------------------------- | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | React 19.2 runtime performance | 0.91 | Current runtime already filters selector fanout by commit/runtime facts and throttles selectionchange. Ecosystem pass rejects importing broad ProseMirror/Lexical runtime machinery. | | Slate-close unopinionated DX | 0.91 | Public API remains unchanged; strict helpers stay strict for direct callers, while runtime paths classify and fail closed. | | Plate and slate-yjs migration backbone | 0.85 | Plate/Yjs pressure validates deterministic model Range | null output and focus/null cursor semantics; pass 8 rejects raw DOM range leakage as a migration rollback trigger. | | Regression-proof testing | 0.95 | Proof ownership is split into vertical TDD rows, browser rows, rollback gates, explicit claim gates, ecosystem keep/defer/reject rows, and concrete .tmp/slate-v2 command groups. | | Research evidence completeness | 0.95 | Added live Slate v2 selection runtime/source, strict DOM helper source, selector fanout, Plate editor shape, Yjs cursor overlays, objection proof anchors, ecosystem maintainer challenge rows, and ledger sync rows. | | shadcn-style composability and hook/component minimalism | 0.88 | No UI props, component flags, or public bridge hooks are introduced; revision keeps customization at existing extension points and blocks app-authored DOM classifier APIs. |

Total: 0.94.

Score status: done. Closure gates passed at 0.94.

5. Source-Backed Architecture North Star

Current live owners:

Target flow:

native selection / focus / event range
  -> slate-dom classification
     ok | ignored | repair | stale | foreign | nested-editor | shadow-root | unsupported
  -> slate-react selection controller policy
     import DOM | export model | preserve model | clear | repair | no-op
  -> browser proof row or explicit non-claim

6. Ecosystem Strategy Synthesis

Pass 5 verdict:

• ProseMirror is the strongest reference for this lane. Its selection tests should drive DOM import/export, focus/scroll, coords, fallback, and BR-hack rows.
• Lexical is still the strongest proof-style reference. Use its browser-first regression shape and explicit deferrals.
• Tiptap adds useful focus timing pressure, especially mobile synchronous focus, Safari preventScroll, and React RAF. It does not justify new public Slate API.
• Most IME, clipboard, and table-model rows discovered here should be routed to their own lanes unless they directly pressure DOM selection ownership.

6a. Exact Tests To Steal Or Reject

6b. Ecosystem Maintainer Challenge

Pass 9 verdict:

• ProseMirror stays the strongest behavioral reference, but not an architecture template. Steal its selection import/export, focus/scroll, fallback, and BR cursor invariants from ../prosemirror/view/test/webtest-selection.ts:64-110, ../prosemirror/view/test/webtest-selection.ts:321-356, and ../prosemirror/view/test/webtest-view.ts:50-58. Reject integer-position assumptions, docView/view-desc internals, and direct ports of scrollRectIntoView or focusPreventScroll from ../prosemirror/view/src/domcoords.ts:32-140.
• ProseMirror coordinate rows are not closure blockers for this lane unless the implementation edits a public or private Slate coords surface. Otherwise, route them to a coords-specific lane.
• ProseMirror NodeView.ignoreMutation is only evidence that app-owned DOM needs a private classification reason. Do not copy NodeView/MarkView APIs; keep Slate renderers and DOM ownership separate (../prosemirror/view/test/webtest-nodeview.ts:77-101).
• Lexical remains the proof-style source. Steal native browser rows and explicit deferrals from docs/editor-test-harvester/lexical/report.md:120-147 and the apply ledger at docs/editor-test-harvester/lexical/report.md:163-176. Do not steal Lexical's node classes, command registry, Composer model, private MIME details, or whole-table selection semantics.
• The Lexical table drag row is narrowed. Current Slate proof should assert containment/no document spill; whole-table promotion remains a separate table-model decision, not part of this DOM bridge lane.
• Tiptap focus behavior is useful pressure only. Steal the timing distinctions from ../tiptap/packages/core/src/commands/focus.ts:44-69 and the unsupported selection-kind guard from ../tiptap/packages/core/src/commands/focus.ts:82-86. Do not copy the command API, ProseMirror selection classes, or treat Tiptap jsdom renderer churn as mobile/IME proof.

Accepted ecosystem revisions:

• Add no new public API from any ecosystem reference.
• Keep coords rows deferred unless the implementation touches coords.
• Keep table rows containment-only unless the user accepts a separate table selection model.
• Keep Mobile/IME rows out unless raw device or honest browser IME transport is available.
• During implementation, every external test copied must be rewritten as a Slate behavior row with a Slate owner and a .tmp/slate-v2 command.

7. Public API Target

Status: unchanged for this lane.

• No public normalizePoint.
• No public app-authored DOM selection classifier.
• No new renderer props.
• No Plate-specific selection affordance in raw Slate.
• No public ignore-cursor or structural DOM exclusion API for #5924.
• No public Web Component boundary model for #5550.
• No raw Slate table selection model for #2558/#5551.
• Keep strict DOM helpers public/internal as they are unless the next pass proves a breaking API is required.

The accepted change is private runtime structure and proof, not public API.

8. Internal Runtime Target

Accepted private target:

type DOMSelectionBridgeResult =
  | { type: "ok"; range: Range | null; reason: "native" | "event-range" }
  | { type: "ignored"; reason: "foreign-target" | "nested-editor" | "readonly" }
  | { type: "repair"; reason: "stale-dom" | "dirty-node-map" | "focus-reset" }
  | { type: "unsupported"; reason: "app-owned-dom" | "raw-device-required" };

This is a private proof shape, not a final API proposal.

Runtime rules to prove:

• toSlatePoint / toSlateRange stay strict low-level helpers.
• Selectionchange, beforeinput target ranges, focus restoration, and findEventRange consume non-throwing classification in runtime paths.
• Parent editor, nested editor, and shadow root ownership is decided before DOM point conversion.
• Focus restoration may preserve model selection, import DOM selection, or clear selection, but it must name the reason.
• Scroll happens because the policy says so, not as incidental fallout of focus.

Relationship to current v2 code:

• DOMEditor.toSlatePoint and toSlateRange already accept suppressThrow; this plan should centralize when runtime paths use that non-throwing mode.
• selection-controller.ts already has explicit import/export execution keyed by EditableSelectionPolicy.
• editing-kernel.ts already names policy kinds such as import-dom, export-model, preserve-model, none, and shell.
• The missing piece is a finite DOM-side classification result that feeds those policies without leaking into public app APIs.

9. Hook / Component / Render DX Target

• No new app-facing selection props.
• No product toolbar state in raw Slate.
• Renderers should not need to know why a DOM point imported or failed.
• Hooks may expose selection/focus state only if existing external-store contracts already justify it.

10. Plate Migration Backbone

Plate should benefit from:

• deterministic model selection after native selection import;
• explicit ignored/repair reasons for debugging table, void, and inline UI;
• fewer app workarounds around focus and scroll;
• no dependence on current Plate editor.api / editor.tf shape.

No Plate adapter work is in scope.

11. slate-yjs Migration Backbone

Collab relevance:

• local DOM selection import must become either a deterministic model selection or an explicit ignored/repair state;
• remote selection/cursor adapters should never consume raw DOM ranges;
• no Yjs protocol or awareness API is changed by this lane.

This remains a substrate answer, not a slate-yjs integration claim.

11a. Owner Split After Intent Pass

12. Issue-Ledger Accounting

ClawSweeper related-issue pass: applied.

Trigger:

• This plan touches issue-facing browser/runtime/focus behavior, so the related issue surface was routed before the plan can score ready.

Discovery evidence:

• gitcrawl --version: 0.2.1.
• gitcrawl doctor --json: 617 clusters, 659 open threads, 659 total threads, archive last synced 2026-05-04T14:58:11.123944Z, no GitHub token.
• gitcrawl threads ianstormtaylor/slate --numbers 5947,4842,5867,5826,5538,5568,3497,5171,5107,5711,5806,2558 --include-closed --json.
• gitcrawl cluster-detail ianstormtaylor/slate --id 1 --member-limit 20 --body-chars 280 --json.
• gitcrawl cluster-detail ianstormtaylor/slate --id 3 --member-limit 20 --body-chars 280 --json.
• gitcrawl cluster-detail ianstormtaylor/slate --id 14 --member-limit 20 --body-chars 280 --json.
• gitcrawl cluster-detail ianstormtaylor/slate --id 20 --member-limit 20 --body-chars 280 --json.

ClawSweeper verdict:

• #5947: Improves, bucket v2-dom-selection; keep Improves #5947, exact parent/child browser or unit proof required before Fixes.
• #4842: Related; nested-editor DOM offset/history closure is not exact.
• #5867: Related; selected-inline/mention focus restore belongs here, but DOMEditor.focus exact proof is missing.
• #5826: Related; long-editor refocus autoscroll exact proof is missing.
• #5538: Related; focus-scroll restoration exact proof is missing.
• #5568: Related / issue-reviewed; mostly React runtime focus initialization, not pure DOM bridge.
• #3497: Related; mostly React focus/subscription runtime.
• #5171: Related; Firefox unfocused selection update needs a Firefox row.
• #5107: Related; shadow DOM findEventRange needs an exact shadow row.
• #5711: Related; iOS/mobile DOM point crash needs matching mobile proof.
• #5806: Related; custom inline gesture selection proof is missing.
• #2558: Not claimed; multi-cell table selection requires an explicit table selection model.

Already closed floor:

Candidate leftover issue matrix:

No new Fixes #... lines are legal from this pass.

Issue-ledger full scan: applied.

Evidence read:

• docs/slate-issues/gitcrawl-live-open-ledger.md
• docs/slate-issues/gitcrawl-clusters.md
• docs/slate-issues/issue-clusters.md
• docs/slate-issues/test-candidate-map/
• docs/slate-issues/benchmark-candidate-map.md
• docs/slate-issues/package-impact-matrix.md
• docs/slate-issues/requirements-from-issues.md
• docs/slate-v2/ledgers/issue-coverage-matrix.md
• docs/slate-v2/ledgers/fork-issue-dossier.md

Corpus-level verdict:

• the frozen macro taxonomy still makes Selection, Focus, And DOM Bridge the largest raw theme at 172 issues;
• package pressure still says slate-dom-v2 + slate-react-v2 jointly own this lane: DOM point/path translation, native selection bridge, focus timing, shadow DOM, nested editor ownership, tables, and inline/void boundaries;
• gitcrawl multi-member clusters already cover the obvious high-signal groups, but the singleton ledger and test-candidate maps expose more DOM/focus rows than the first ClawSweeper candidate list;
• the benchmark map adds no new DOM-selection benchmark beyond existing selection/rerender lanes, so this pass should not invent a perf harness here.

Newly surfaced gaps for focused ClawSweeper:

This pass does not add PR claim text. It adds a focused gap owner before the plan can move to intent/boundary closure.

Focused ledger-gap ClawSweeper pass: applied.

Focused verdict:

No new Fixes #... lines are legal from this pass.

13. Legacy Regression Proof Matrix

14. Browser Stress / Parity Strategy

Browser proof should be issue-shaped:

• Chromium: nested editor ownership, custom inline gesture, basic focus restore.
• Firefox: unfocused selectionchange and table multi-range behavior.
• WebKit/Safari: focus/scroll and table/selection edge behavior when Playwright transport is honest.
• Raw mobile: only for issue claims explicitly requiring Android/iOS.

Do not mark raw-device issues fixed from Playwright mobile viewport rows.

15. Applicable Implementation-Skill Review Matrix

15a. Performance, DX, Migration, And Regression Pressure

Performance verdict:

• Do not model the bridge as a fresh object graph on every selectionchange. The hot path already runs through createRuntimeSelectionChangeHandler, which throttles native selectionchange at .tmp/slate-v2/packages/slate-react/src/editable/runtime-selection-engine.ts:46-108 and then calls applyEditableDOMSelectionChange.
• Keep the classification reasons finite and primitive. A string enum plus existing Range | null is enough for traceability; allocation-heavy result objects should be reserved for debug/test output if needed.
• Preserve current fanout filters. DOM export is already limited by commit facts in .tmp/slate-v2/packages/slate-react/src/editable/selection-runtime.ts:99-185, and React selector fanout is runtime-id scoped in .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selector.tsx:212-343.
• Do not add full DOM scans to classification. Current expensive work is already explicit: createFastDOMSelectionRange only handles same-path text and full-document cases before falling back at .tmp/slate-v2/packages/slate-react/src/editable/selection-controller.ts:169-210, while shell/coverage exports are isolated at .tmp/slate-v2/packages/slate-react/src/editable/selection-controller.ts:593-676.
• Keep scroll separate from classification. scrollSelectionIntoView should run only on model-to-DOM export, as it does at .tmp/slate-v2/packages/slate-react/src/editable/selection-controller.ts:669.

React/DX verdict:

• The native selectionchange listener belongs behind the runtime root because React's onSelect is not enough; that is already stated in .tmp/slate-v2/packages/slate-react/src/editable/selection-reconciler.ts:177-213.
• The bridge should not create a new public hook. Existing public state should stay through selector contracts such as useEditorSelection at .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selection.tsx:10-15.
• Effects are acceptable for external synchronization only: cleanup of range refs, autofocus, native listener attachment, selector subscription, repair runtime, and Android/composition runtime setup in .tmp/slate-v2/packages/slate-react/src/editable/runtime-root-engine.ts:154-287. Do not move user-event selection decisions into effects.
• FocusedContext remains coarse. Do not expand it with bridge reasons; that would turn a private runtime fact into app-facing rerender pressure.

Migration verdict:

• Plate currently exposes mutable editor.selection and command surfaces (packages/slate/src/interfaces/editor/editor-type.ts:11-37). Slate v2 does not need to preserve that public shape. It needs deterministic model selection output that an adapter can read.
• Plate Yjs cursor support currently wraps slate-yjs cursor APIs and sends model selections (packages/yjs/src/lib/withTCursors.ts:12-28, packages/yjs/src/lib/withPlateYjs.ts:32-63). The DOM bridge must therefore produce stable Range | null, not raw DOM ranges.
• Cursor overlays in Plate calculate DOM rects from model ranges (packages/cursor/src/hooks/useCursorOverlayPositions.ts:18-111). That reinforces the rule: DOM selection import/export is local runtime work; collaboration and overlay layers consume model ranges after the bridge.
• slate-yjs remote cursors also decorate model ranges and compute overlay positions after paint (../slate-yjs/packages/react/src/hooks/useDecorateRemoteCursors.ts:87-124, ../slate-yjs/packages/react/src/hooks/useRemoteCursorOverlayPositions.tsx:77-143). This lane must not leak browser DOM selection objects into awareness state.

Regression/TDD verdict:

• Start implementation with the smallest failing row. No horizontal "write all tests first" sweep.
• First vertical row: classify foreign/stale/app-owned DOM before conversion, proving runtime paths do not throw while strict DOMEditor.toSlatePoint / toSlateRange stay strict.
• Second vertical row: selectionchange ownership policy, using .tmp/slate-v2/packages/slate-react/test/selection-controller-contract.ts and .tmp/slate-v2/packages/slate-react/test/selection-runtime-contract.test.ts.
• Third vertical row: browser proof for one issue-shaped behavior, preferably parent/nested editor ownership or focus-scroll. Do not mark any issue fixed until the browser row matches the issue.
• Browser proof must keep the previous lessons: selectionchange traceability is not programmatic import proof, foreign DOM selections must fail closed before import, and Firefox table/multi-range claims need real native selection.

16. High-Risk Deliberate-Mode Pre-Mortem

High-risk trigger:

• Native selection import/export, focus timing, scroll behavior, nested-editor containment, table containment, browser proof, and issue claims are all browser-sensitive runtime behavior. A bad change is user-visible and hard to debug.

Blast radius:

| Surface | In blast radius | Guardrail | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------- | | Packages | slate-dom, slate-react, slate-browser proof helpers | No public API change; private runtime bridge only. | | Files | .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts, .tmp/slate-v2/packages/slate-react/src/editable/runtime-selection-engine.ts, .tmp/slate-v2/packages/slate-react/src/editable/selection-controller.ts, .tmp/slate-v2/packages/slate-react/src/editable/selection-reconciler.ts, .tmp/slate-v2/packages/slate-react/src/editable/runtime-root-engine.ts | Edits later must cite the owner and keep strict helper defaults. | | Consumers | Raw Slate React apps, Plate adapters, slate-yjs cursor consumers, browser examples | Consumers see model Range | null, not bridge reasons or DOM ranges. | | Behavior | Native selectionchange, model-to-DOM selection export, focus restore, scroll-to-selection, nested editor containment, table containment | Each behavior needs focused unit/contract proof plus one issue-shaped browser row. | | Docs/tests | Issue coverage matrix, fork dossier, PR reference, browser tests, package contracts | No Fixes #... claim without exact matching proof from /Users/zbeyens/git/slate-v2. |

Three-scenario pre-mortem:

1. Strict helper regression:
   • Failure: direct DOMEditor.toSlatePoint / toSlateRange callers stop throwing and bad rendered DOM becomes silent null.
   • Current evidence: helper APIs still default through strict behavior (.tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:90-104, .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:300-325, .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:1520-1542).
   • Guard: add strict-helper unit proof before runtime fail-closed browser proof. Roll back by removing runtime classifier call sites, not by weakening strict helpers.
2. Browser event ownership regression:
   • Failure: a delayed selectionchange overwrites model-owned text repair or a valid user selection cannot import because the runtime stays too defensive.
   • Current evidence: selectionchange is throttled and traced in runtime-selection-engine.ts:46-108; existing contracts cover native, repair-induced, and programmatic origins in selection-controller-contract.ts:56-260 and selection export policy in selection-runtime-contract.test.ts:42-260.
   • Guard: classifier rows must prove positive import and negative ignore cases. Browser proof must assert model text, DOM text, DOM selection, follow-up typing, and kernel trace.
3. Product semantics leak:
   • Failure: copying Lexical table behavior turns raw Slate into a hidden whole-table selection model, or focus-scroll work steals app scroll customization.
   • Current evidence: current table rows prove containment/triple-click only (.tmp/slate-v2/playwright/integration/examples/tables.test.ts:129-179); scrollSelectionIntoView remains injected at selection-controller.ts:593-676.
   • Guard: whole-table selection stays out of this lane; scroll fixes must keep the callback extension point and pass scrollable-root/parent browser rows.

Expanded proof plan:

| Layer | Required proof | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | Unit | slate-dom strict helper throws by default; runtime classifier returns finite primitive reasons for foreign, stale, app-owned, nested, and shadow-root selections. | | Runtime contract | selection-controller-contract.ts proves import/ignore/export transitions, repair-induced model ownership, and no public hook/API expansion. | | Browser | Richtext outside-to-inside, editable-void parent/nested, selected mention focus, scrollable long editor/root, table containment/triple-click/drag, and shadow DOM event range rows. | | Migration/adoption | Plate/Yjs/cursor overlays consume model Range | null; no raw DOM ranges or bridge reasons cross adapters. | | Docs/examples | Coverage matrix and fork dossier classify each issue as Fixes, Improves, Related, or Not claimed; PR reference carries exact claim counts only. | | Performance | Selectionchange hot path keeps throttle/debounce, finite primitive classification, no broad DOM scan, no per-event rich result objects. | | Mobile/device | Android/iOS rows remain related unless bun test:mobile-device-proof:raw has real device artifacts. |

Rollback/remediation:

• If strict helper proof fails, drop the runtime bridge edit and restore direct helper throws first.
• If positive DOM import regresses toolbar, paste, or mouse selection, split the classifier into narrower ownership reasons instead of globally ignoring DOM selection.
• If focus-scroll proof needs app-specific behavior, keep the existing scrollSelectionIntoView extension point and downgrade exact issue closure.
• If table proof requires whole-table range semantics, move that to a separate table-model plan and keep this lane containment-only.

High-risk verdict:

• Keep the plan. Revise nothing public. The execution lane should start with strict-helper and runtime-contract TDD, then one issue-shaped browser proof. Do not batch broad browser rows before the first positive and negative ownership pair is green.

17. Hard Cuts And Rejected Alternatives

• No one plan per issue or cluster.
• No public normalizePoint.
• No "catch all DOMEditor errors and ignore" patch.
• No Plate workaround as core architecture.
• No whole-table selection model unless a separate public model decision says Slate v2 owns it.
• No raw mobile fixed claims without raw mobile proof.

18. Slate Maintainer Objection Ledger

Accepted revisions from pass 7:

• Runtime fail-closed behavior must be named as runtime-only. Direct DOMEditor helper calls keep strict failures by default.
• Focus/scroll ownership must preserve scrollSelectionIntoView as the app extension point.
• Table rows are containment/no-crash only unless a later table-model plan explicitly accepts whole-table selection semantics.
• Parent/child and nested-editor claims stay Improves / Related until exact #5947/#4842 proof exists.

19. Pass Schedule And Pass-State Ledger

20. Plan Deltas From Review

Pass 1 created this plan and deliberately scoped it as the second DOM selection lane, not the already-closed 2026-05-06 boundary proof.

Pass 2 split the remaining issue surface:

• nested-editor DOM point ownership remains slate-dom plus focused slate-react browser proof;
• focus and scroll rows are shared DOM focus plus React selection timing;
• #3497 and #5568 are mostly React runtime pressure, not pure DOM bridge work;
• #2558 is not claimed without a separate table selection model decision.

Pass 3 proved the first DOM/focus candidate set was not comprehensive enough. The important additions are #5690/#5689 gesture-selection rows, #4995 scroll-selection customization, #5632/#5559 inline/void selection behavior, #3909/#3893 focus/target ownership, and #5550/#5551/#5924 non-claim boundary rows. No new fixed claim is legal; the next owner is a focused ClawSweeper sync pass.

Pass 3b applied that focused sync. Coverage and dossier now explicitly classify #5690/#5689/#4995/#5632/#5559/#3909/#3893/#5524 as related pressure and #5550/#5551/#5924 as not claimed. The next owner is Slate Ralplan intent, boundary, and decision-brief cleanup.

Pass 4 locked the architecture boundary. The plan keeps public API unchanged, uses a private DOM classification result as the bridge into current React selection policy, routes #5524 to core caret/navigation unless DOM proof says otherwise, and leaves #5550/#5551/#5924 outside raw Slate closure.

Pass 5 completed ecosystem synthesis. The plan now says exactly what to steal: ProseMirror's DOM selection import/export, fallback, BR-hack, selectionchange, focus/scroll, and coordinate rows; Lexical's issue-shaped browser proof style; and Tiptap's focus timing pressure. It also says what not to steal: ProseMirror NodeView APIs, Tiptap command APIs, Lexical product/editor-state internals, clipboard rows for this lane, and jsdom composition as mobile/IME proof.

Pass 6 completed performance, React DX, migration, and regression pressure. The private bridge still wins, but it is constrained: no per-event object churn in selectionchange, no public hook/API expansion, no raw DOM range leakage to Plate/Yjs/collaboration, and no issue claim without vertical TDD plus browser proof. The reusable hot-path rule is captured in docs/solutions/performance-issues/2026-05-08-dom-selection-bridges-must-stay-cheap-on-selectionchange.md.

Pass 7 completed the maintainer objection ledger. The plan keeps the private bridge, but now explicitly preserves strict DOMEditor helper errors for direct callers, limits fail-closed behavior to runtime event/focus paths, preserves scrollSelectionIntoView as the app extension point, keeps #5947/#4842 below fixed without exact proof, and rejects whole-table selection as a hidden raw Slate requirement.

Pass 8 completed high-risk deliberate review. The plan stays alive, but the implementation blast radius is capped: no public API, no blanket DOM conversion swallowing, no whole-table selection semantics, no raw mobile claims, and no new Fixes #... line before exact package/browser proof passes in /Users/zbeyens/git/slate-v2. The next pass should challenge the ecosystem borrowings before revision and issue-sync closure.

Pass 9 completed the ecosystem maintainer challenge. The plan now treats ProseMirror, Lexical, and Tiptap as behavior/proof references only. It narrows ProseMirror coords to a deferred coords lane unless touched, keeps Lexical table rows containment-only, rejects ProseMirror view-desc and Tiptap command APIs, and keeps jsdom/mobile proof confusion out of this DOM bridge plan.

Pass 10 completed revision. The implementation plan is no longer a loose owner list: it is a vertical execution map with first proof, browser proof, claim gate, rollback boundary, and exact .tmp/slate-v2 command groups. The next pass must sync the issue ledgers and PR reference against that concrete claim map.

Pass 11 completed issue-sync accounting. The issue coverage matrix now routes #5711, #3634, and #4961 through this DOM selection/focus bridge plan instead of the Mobile/IME macro plan. The fork dossier records the lane-level claim map: no new fixed claims, #5947 improves-only, related rows stay related until exact proof, and table/Web Component/structural cursor rows stay not claimed. The live gitcrawl ledger is a generated live-field mirror, so it was intentionally left unchanged. The PR reference was also left unchanged because this pass adds no fixed issue claim.

Pass 12 completed closure. The score is 0.94, no scorecard dimension is below 0.85, the issue-sync pass is recorded, the public API target is explicit (no new public API), implementation phases have owner/proof/claim gates, and all Slate v2 behavior proof commands are named with /Users/zbeyens/git/slate-v2 as the required workspace.

21. Open Questions And What Would Change The Decision

• If implementation cannot keep classification cheap on selectionchange, drop structured return objects from the hot path and keep only primitive reason codes plus debug-only expansion.
• If maintainer objections prove focus/scroll should remain app-owned, keep scrollSelectionIntoView as the app extension point and limit runtime changes to deterministic selection import/export.
• If React runtime identity owns more focus rows than DOM classification, split those rows into the React runtime lane.
• If #5947/#4842 are already covered by live browser rows not seen in pass 1, lower the nested-editor phase to ledger/test cleanup only.
• If focus/scroll needs browser fallback beyond preventScroll, add a private focus-scroll helper; otherwise keep it inside current focus code.
• If Lexical whole-table selection is the only way to satisfy #2558, keep #2558 related unless the user chooses a table selection model.
• If ProseMirror coordinate rows map to a currently unsupported Slate surface, defer them instead of expanding this DOM bridge lane.

22. Implementation Phases With Owners

Execution-ready for ralph. Each implementation slice must land as a vertical behavior row: unit/contract proof first, one user-path browser proof second when the claim is browser-facing, then ledger sync. Expanding the next phase before the current positive and negative ownership pair is green is busywork.

Phase rollback rules:

• If phase 1 weakens strict helper failures, stop and restore strict defaults.
• If phase 2 blocks valid user selection import, split the classifier reason instead of broadening ignore policy.
• If phase 4 needs app-specific scroll behavior, keep scrollSelectionIntoView as the only app extension point and downgrade the issue claim.
• If phase 6 needs whole-table range semantics, move it to a table-model plan.

23. Fast Driver Gates

Planning artifact gates:

cd /Users/zbeyens/git/plate-2
bun run completion-check -- --file .tmp/completion-checks/slate-v2-dom-selection-focus-bridge-ralplan.md

Expected after closure: passes with status: done.

Focused Slate v2 gates for later implementation. These must run from /Users/zbeyens/git/slate-v2; the same command text in plate-2 proves nothing about Slate v2 behavior.

cd /Users/zbeyens/git/slate-v2

# Unit/contract floor for phases 1-3.
bun test ./packages/slate-dom/test/bridge.ts ./packages/slate-dom/test/dom-coverage.ts
bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-reconciler-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts ./packages/slate-react/test/dom-repair-policy-contract.ts

# App-owned scroll and rendering-strategy guard for phases 2 and 4.
bun test ./packages/slate-react/test/rendering-strategy-and-scroll.tsx ./packages/slate-react/test/app-owned-customization.tsx

# Browser rows for native selection import, repair, movement, and triple-click.
PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/richtext.test.ts --project=chromium --grep "selectionchange|programmatic DOM selection|repair trace|browser word movement|browser line extension|triple click"

# Browser rows for editable void internal controls and nested editor ownership.
PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/editable-voids.test.ts --project=chromium --grep "outer editor selection|ArrowLeft inside editable void|selectionchange noise|nested editor|parent selection"

# Browser rows for shadow-root range and movement behavior.
PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/shadow-dom.test.ts --project=chromium

# Browser rows for containment-only table behavior.
PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/tables.test.ts --project=chromium --grep "triple-clicking the last table cell|dragging from a table cell"

# Browser rows for covered-range placeholders and inline mention movement.
PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/dom-coverage-boundaries.test.ts --project=chromium --grep "native drag selection|model-backed covered ranges"
PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/mentions.test.ts --project=chromium --grep "arrow keys select mentions"

# Fast repo gate after the touched slice is green.
bun check

bun check:full is reserved for release-quality browser closure. Raw mobile claims remain out of this lane unless bun test:mobile-device-proof:raw runs on a real-device lane with artifacts.

23b. Issue Sync Accounting Checklist

Pass 11 result:

• docs/slate-issues/gitcrawl-live-open-ledger.md: cluster rows reflect this lane's exact fixed/improved/related/not-claimed classification. No-op: the file is a generated live-field mirror and has no claim columns.
• docs/slate-v2/ledgers/issue-coverage-matrix.md: every exact claim appears as Fixes #...; every pressure row stays under related/improves/not claimed. Updated: #5711, #3634, and #4961 now point at this DOM selection/focus plan.
• docs/slate-v2/ledgers/fork-issue-dossier.md: one self-contained section for each reviewed related issue family, not one giant vague blob. Updated: added the revision issue-sync accounting section for this lane.
• docs/slate-v2/references/pr-description.md: fixed issue counts, proof references, and not-claimed release gates match the coverage matrix. No-op: no new fixed issue claims were added by this pass.
• This plan's issue table and phase gates agree with the ledgers. If they do not, the ledgers win only after the plan is patched with the reason. Done: plan phases match the ledger claim policy.

24. Final User-Review Handoff Outline

Execution handoff:

• exact accepted private architecture;
• exact public API changes, ideally none;
• issue matrix with fixed/improved/related/not-claimed rows;
• external tests copied or deliberately rejected;
• implementation phases for ralph;
• exact .tmp/slate-v2 verification commands.

25. Final Completion Gates

Completion gates met:

• score >= 0.92;
• no dimension below 0.85;
• ClawSweeper related-issue pass complete;
• issue-sync accounting pass complete across live ledger, coverage matrix, fork dossier, and PR reference;
• ecosystem strategy complete for Lexical, ProseMirror, and any Tiptap evidence used;
• public API target is explicit: no new public API for this lane;
• implementation phases have owner, first proof, browser proof, and claim gate;
• relevant .tmp/slate-v2 commands are named and tied to the phases above;
• final closure pass records the accepted score and flips the completion file only when no scheduled pass remains.

26. Ralph Execution Ledger

Slice 1 - Bridge Classifier Boundary - 2026-05-08

Status: complete.

Owner:

• .tmp/slate-v2/packages/slate-dom/test/bridge.ts
• .tmp/slate-v2/packages/slate-react/test/selection-controller-contract.ts

Scope:

• Preserve strict DOMEditor helper failures for direct callers.
• Prove runtime import policy can fail closed after ownership checks.
• Do not add public DOM classifier, hook, or API.
• Do not add new Fixes #... claims.

Driver gates:

• bun test ./packages/slate-dom/test/bridge.ts ./packages/slate-dom/test/dom-coverage.ts
• bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-reconciler-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts ./packages/slate-react/test/dom-repair-policy-contract.ts

Reference docs:

• No issue-claim or PR-reference change expected for phase 1 unless tests expose a broader behavior claim.

Result:

• Added Slate v2 proof that empty DOM selections still throw for strict direct callers but return null with suppressThrow: true.
• Patched DOMEditor.toSlateRange to honor suppressThrow for missing DOM endpoints.
• Verified in .tmp/slate-v2:
  • bun lint:fix
  • bun test ./packages/slate-dom/test/bridge.ts ./packages/slate-dom/test/dom-coverage.ts
  • bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-reconciler-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts ./packages/slate-react/test/dom-repair-policy-contract.ts
  • bun check

Slice 2 - Fail-Closed DOM Import - 2026-05-08

Status: complete.

Owner:

• .tmp/slate-v2/packages/slate-react/src/editable/selection-controller.ts
• .tmp/slate-v2/packages/slate-react/test/selection-controller-contract.ts

Scope:

• Keep model-owned selection preference when editor-owned DOM endpoints cannot resolve to a Slate range.
• Clear model preference only when runtime import can actually import a Slate range.
• No public API change and no issue claim promotion.

Driver gates:

• bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-reconciler-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts ./packages/slate-react/test/dom-repair-policy-contract.ts

Result:

• Added controller proof that editor-owned DOM selections with unresolved Slate ranges keep model selection preference.
• Patched selection import preparation so native selectionchange only clears model preference when the DOM selection is editor-owned and resolves to a Slate range.
• Verified in .tmp/slate-v2:
  • bun lint:fix
  • bun test ./packages/slate-dom/test/bridge.ts ./packages/slate-dom/test/dom-coverage.ts
  • bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-reconciler-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts ./packages/slate-react/test/dom-repair-policy-contract.ts
  • bun check

Reference docs:

• No issue claim, PR reference, coverage matrix, or fork dossier change. This slice hardens private runtime policy only.

Next:

• Slice 3: parent and nested editor ownership.
• Keep #5947/#4842 below fixed unless exact repro-matching proof lands.

Slice 3 - Parent And Nested Editor Ownership - 2026-05-08

Status: complete.

Owner:

• .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts
• .tmp/slate-v2/packages/slate-dom/test/bridge.ts
• .tmp/slate-v2/playwright/integration/examples/editable-voids.test.ts

Scope:

• Keep nested editor DOM nodes owned by the nested editor.
• Prevent parent editor toSlateNode from returning nested Slate nodes through global DOM weak maps.
• Keep #5947/#4842 below fixed unless exact repro-matching proof lands.

Result:

• Added package proof that parent hasDOMNode rejects nested editor text, nested editor import still works, parent strict import throws, and parent suppressed import returns null.
• Patched DOMEditor.toSlateNode so global DOM-to-Slate weak-map hits are accepted only when the DOM node belongs to the current editor root.
• Verified in .tmp/slate-v2:
  • bun lint:fix
  • bun test ./packages/slate-dom/test/bridge.ts ./packages/slate-dom/test/dom-coverage.ts
  • bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-reconciler-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts ./packages/slate-react/test/dom-repair-policy-contract.ts
  • PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/editable-voids.test.ts --project=chromium --grep "outer editor selection|ArrowLeft inside editable void|selectionchange noise|nested editor|parent selection"
  • bun check

Reference docs:

• No issue claim, PR reference, coverage matrix, or fork dossier change. The slice strengthens nested ownership proof but does not exact-close #5947 or #4842.

Next:

• Slice 4: focus and scroll restoration.
• Preserve scrollSelectionIntoView as the app extension point.

Slice 4 - Focus And Scroll Restoration - 2026-05-08

Status: complete.

Owner:

• .tmp/slate-v2/packages/slate-react/test/rendering-strategy-and-scroll.tsx
• .tmp/slate-v2/packages/slate-react/test/app-owned-customization.tsx
• .tmp/slate-v2/packages/slate-react/test/selection-controller-contract.ts
• .tmp/slate-v2/packages/slate-react/test/selection-runtime-contract.test.ts

Scope:

• Preserve scrollSelectionIntoView as the app-owned extension point.
• Keep focus-scroll issue rows related unless exact browser proof lands.
• Avoid new public DOM/focus API.

Result:

• Verified existing package contracts for scroll forwarding, app-owned customization, and selection controller/runtime behavior without code changes.
• Kept #5867/#5826/#5538/#5568/#3497/#5537/#4961 as related/non-claimed rows.
• Verified in .tmp/slate-v2:
  • bun test ./packages/slate-react/test/rendering-strategy-and-scroll.tsx ./packages/slate-react/test/app-owned-customization.tsx
  • bun test ./packages/slate-react/test/selection-controller-contract.ts ./packages/slate-react/test/selection-runtime-contract.test.ts

Reference docs:

• No issue claim, PR reference, coverage matrix, or fork dossier change. Phase 4 proves the extension boundary only.

Next:

• Slice 5: shadow DOM event range proof.
• Keep #5107/#5749/#4337 related unless exact event-to-range proof lands.

Slice 5 - Shadow DOM Event Range - 2026-05-08

Status: complete.

Owner:

• .tmp/slate-v2/playwright/integration/examples/shadow-dom.test.ts

Scope:

• Prove existing shadow DOM behavior in the browser.
• Keep #5107/#5749/#4337 related unless exact event-to-range closure proof lands.
• Avoid new public DOM classifier or shadow DOM API.

Result:

• Verified nested shadow rendering, nested shadow editing, generated shadow DOM typing gauntlet, model-owned ArrowLeft movement, and newline editing rows without code changes.
• Kept #5107/#5749/#4337 related.
• Verified in .tmp/slate-v2:
  • PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/shadow-dom.test.ts --project=chromium

Reference docs:

• No issue claim, PR reference, coverage matrix, or fork dossier change. Phase 5 confirms existing shadow DOM coverage only.

Next:

• Slice 6: inline, void, table, and covered-range leftovers.
• Keep table proof containment-only and reject raw mobile claims.

Slice 6 - Inline, Void, Table, And Covered-Range Leftovers - 2026-05-08

Status: complete.

Owner:

• .tmp/slate-v2/playwright/integration/examples/tables.test.ts
• .tmp/slate-v2/playwright/integration/examples/dom-coverage-boundaries.test.ts
• .tmp/slate-v2/playwright/integration/examples/mentions.test.ts

Scope:

• Prove containment-only table behavior, covered-range placeholder behavior, and inline mention movement.
• Keep whole-table selection and table model semantics out of scope.
• Do not cite mention movement as raw mobile proof.

Result:

• Verified table containment rows: triple-clicking the last table cell selects only that cell text, and dragging from a table cell toward trailing text does not select the intro paragraph.
• Verified covered-range rows: model-backed covered ranges and native drag selection across a boundary placeholder.
• Verified mention atomic arrow-key movement from both sides.
• Verified in .tmp/slate-v2:
  • PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/tables.test.ts --project=chromium --grep "triple-clicking the last table cell|dragging from a table cell"
  • PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/dom-coverage-boundaries.test.ts --project=chromium --grep "native drag selection|model-backed covered ranges"
  • PLAYWRIGHT_RETRIES=0 bunx playwright test playwright/integration/examples/mentions.test.ts --project=chromium --grep "arrow keys select mentions"

Reference docs:

• No issue claim, PR reference, coverage matrix, or fork dossier change. Phase 6 is containment and movement proof only.

Next:

• Slice 7: docs/reference sync and final verification.
• Run final bun check in .tmp/slate-v2, then mark this execution lane done if no scheduled pass remains.

Slice 7 - Docs Reference Sync And Final Verification - 2026-05-08

Status: complete.

Owner:

• docs/plans/2026-05-08-slate-v2-dom-selection-focus-bridge-ralplan.md
• .tmp/completion-checks/slate-v2-dom-selection-focus-bridge-ralplan.md
• active goal state
• .tmp/slate-v2

Scope:

• Sync the execution ledger and completion state with slices 4-6.
• Keep issue claims unchanged because the last slices were proof-only.
• Run the final fast Slate v2 gate from the sibling repo.

Result:

• Synced this plan and completion state with phase 4 focus/scroll, phase 5 shadow DOM, and phase 6 table/covered-range/mention proof.
• No issue claim, PR reference, coverage matrix, or fork dossier update was needed: no new fixed issue claim was added.
• Verified in .tmp/slate-v2:
  • bun lint:fix
  • bun check

Final execution result:

• Done. The DOM selection/focus bridge execution lane has no scheduled pass remaining.