Slate v2 DOM Selection Boundary Proof Ralplan

1. Current Verdict

Next cluster: v2-dom-selection.

The next implementation slice should not chase Android IME, virtualization, or another clipboard fast path. The highest-leverage browser-replayable gap is central DOM selection import/export around tables, inline boundaries, voids, triple-click hanging ranges, nested editors, and outside-editor selections.

Do the strict runtime bridge first. Do not add a public normalizePoint API.

2. Intent And Boundary Record

Intent:

• Turn the largest issue cluster, selection/focus/DOM bridge, from architecture pressure into replayable browser proof.

Desired outcome:

• Slate v2 has one selection bridge that imports native selection, exports model selection, and fails closed with a reason instead of throwing raw Cannot resolve ... errors in the runtime path.

In scope:

• slate-dom selection import/export result objects.
• slate-react selection reconciler/runtime integration.
• Browser scenario rows for table edge navigation, inline/void boundaries, triple-click hanging block ranges, outside-editor drag/import, and nested editor containment.
• Issue-ledger sync for exact fixed, improved, related, and not-claimed rows.

Non-goals:

• No Android/iOS device closure without raw device proof.
• No public normalizePoint extension point.
• No app-rendered arbitrary DOM support.
• No new product-level Plate selection UX.
• No virtualization convergence.

Decision boundaries:

• The implementation may add internal DOM selection capability names.
• The implementation may migrate runtime callsites away from raw throwing toSlatePoint / toSlateRange.
• Public DOM helper names should not be expanded unless a test proves internal capability-only design is insufficient.

Unresolved user-decision points:

• None for planning. User review is still required before ralph executes.

3. Decision Brief

Principles:

• Selection import/export has one owner.
• Runtime paths must prefer typed failure over exceptions.
• Browser replay beats architecture confidence.
• Slate core stays model-first and unopinionated.
• Mobile claims need device proof, not desktop emulation.

Top drivers:

• Issue corpus: selection/focus/DOM bridge is the biggest raw cluster at 172 issues; 118 of those are runtime-boundary owned.
• Live source: DOMEditorCapability still exposes direct toSlatePoint / toSlateRange primitives, while selection-reconciler owns separate collapsed/select-all fallback logic.
• Browser contracts already have first-party rows for inline void, block void, table boundary, and toolbar/mouse selection, but not enough exact issue rows for the open DOM-selection cluster.

Viable options:

Chosen option:

• Add a central internal DOM selection bridge and route slate-react runtime through it. Keep raw strict toSlatePoint / toSlateRange for low-level exact helpers, but runtime event paths should consume non-throwing result objects with failure reasons.

Consequences:

• Some previously thrown runtime errors become repair/fail-closed traces.
• Exact issue claims are allowed only when a browser row replays the original behavior.
• Mobile rows stay Related until real device proof exists.

Follow-ups:

• Android IME proof lane after this bridge is stable.
• Public helper docs only after internal bridge naming survives the tests.

4. Confidence Scorecard

Total: 0.93.

5. Source-Backed North Star

Current live source:

• .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:57 exposes toDOMPoint, toDOMRange, toSlatePoint, and toSlateRange as direct DOM capabilities.
• .tmp/slate-v2/packages/slate-react/src/editable/selection-reconciler.ts:46 has a separate collapsed DOM-selection importer and select-all fallback.
• .tmp/slate-v2/packages/slate-react/src/editable/runtime-selection-engine.ts:46 owns throttled native selectionchange handling and kernel traces.
• .tmp/slate-v2/packages/slate-browser/test/core/scenario.test.ts:137 locks first-party parity families, including inline void and table boundary rows.

Target:

native selection event
  -> DOM selection bridge
  -> SelectionImportResult | SelectionExportResult
  -> selection controller policy
  -> model selection / repair trace / fail-closed reason

Raw runtime code should stop blindly calling strict DOM-to-Slate conversion in places where the browser may hand us foreign, nested, void, table, or temporarily stale DOM.

6. Ecosystem Strategy Synthesis

7. Public API Target

Status: keep-private.

• No new public normalizePoint.
• No public app-authored DOM selection policy.
• No public DOMSelectionBridge export in this slice.
• Keep strict helper behavior for direct low-level use.
• Runtime event paths use internal non-throwing result objects.

Candidate internal shape:

type DOMSelectionImportResult =
  | { type: "ok"; selection: Range | null; source: "native" | "fallback" }
  | { type: "ignored"; reason: "foreign-target" | "nested-editor" | "readonly" }
  | { type: "repair"; reason: "missing-dom" | "boundary" | "stale-dom" }
  | { type: "error"; reason: string };

This is not a final API proposal. It is the proof seam.

8. Internal Runtime Target

• Move collapsed selection fallback and select-all fallback behind one import bridge.
• Add explicit failure reasons for:
  • outside editor target;
  • nested editor target;
  • table non-cell structural DOM;
  • inline boundary padding / adjacent spacer target;
  • void boundary target;
  • stale or missing DOM;
  • DOM coverage boundary.
• Make selection controller consume result type, not exception control flow.
• Trace every non-ok decision through the existing kernel trace.
• Preserve strict toSlatePoint tests; add runtime tests proving it is no longer called blindly from selectionchange.

9. Hook / Component / Render DX Target

• No app renderer receives extra selection props.
• Void and inline examples should only prove behavior, not own policy.
• Existing browser examples become proof routes:
  • mentions: inline void boundary navigation.
  • tables: table edge arrow navigation.
  • richtext: triple-click + destructive edit.
  • nested/iframe route if needed for cross-root containment.

10. Plate Migration Backbone

Plate should get a cleaner substrate:

• one internal bridge for native selection;
• reasoned traces for plugin/UI debugging;
• browser contracts for table, inline void, and toolbar selection;
• no need for Plate to wrap raw DOM conversion helpers.

No current Plate adapter compatibility is promised.

11. slate-yjs Migration Backbone

Collab relevance:

• Selection import/export must produce deterministic model selections or explicit ignored/repair states.
• No remote operation semantics change in this slice.
• Future awareness/cursor adapters can consume the same model selection and failure reason, but this plan does not implement slate-yjs support.

12. Issue-Ledger Accounting

ClawSweeper pass: applied.

Gitcrawl evidence:

• gitcrawl doctor --json green with 617 clusters and 659 open threads.
• gitcrawl cluster-detail reviewed clusters 1, 5, 12, 17, and 23.
• Existing recluster map marks table selection, inline boundary, inline/void, mobile/browser selection quirks, triple-click, and DOM point crashes under v2-dom-selection.

Current issue matrix:

Live ledger sync status:

• docs/slate-issues/open-issues-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 are synced for #6034, #5355, #3871, #5847, #3991, #4301, #4074, #3148, #3429, #4618, #4789, and #4984.
• The live gitcrawl corpus files remain upstream-current discovery inputs, not fork-local claim ledgers.

PR description status:

• pr-description includes exact Fixes #6034, Fixes #3871, Fixes #5847, Fixes #3991, Fixes #4301, Fixes #4074, Fixes #3148, Fixes #3429, Fixes #4789, and Fixes #4984 lines, with #5355 and #4618 intentionally omitted.

13. Legacy Regression Proof Matrix

14. Browser Stress / Parity Strategy

Use generated browser scenario rows, not one-off manual examples.

Minimum execution gate:

bun test .tmp/slate-v2/packages/slate-dom/test/bridge.test.ts \
  .tmp/slate-v2/packages/slate-react/test/selection-controller-contract.test.ts \
  .tmp/slate-v2/packages/slate-react/test/selection-reconciler-contract.ts

STRESS_FAMILIES=table-cell-boundary-navigation,inline-void-boundary-navigation,block-void-navigation,triple-click-block-selection \
PLAYWRIGHT_RETRIES=0 \
bunx playwright test playwright/stress/generated-editing.test.ts --project=chromium

Exact commands may need adjustment to current package scripts during execution.

15. Applicable Implementation-Skill Review Matrix

16. High-Risk Deliberate Mode

Triggered: yes. This touches selection, focus, DOM repair, browser runtime, and issue claims.

Pre-mortem:

1. Non-throwing bridge hides a real selection corruption bug.
2. Table/inline special cases leak product policy into raw Slate.
3. Browser proof passes on desktop but mobile issues are accidentally claimed.

Proof response:

• Every ignored/repair result must trace a reason.
• Exact Fixes claims require replayable browser row.
• Mobile rows stay related until raw device proof exists.

Blast radius:

• .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts
• .tmp/slate-v2/packages/slate-react/src/editable/selection-reconciler.ts
• .tmp/slate-v2/packages/slate-react/src/editable/runtime-selection-engine.ts
• .tmp/slate-v2/packages/slate-browser/**
• Issue ledgers and PR reference.

Rollback / hard-cut answer:

• This is worth doing because the current debt is scattered exception-driven selection repair. If the bridge result shape is wrong, keep the tests and revise the internal result naming, not the public API.

17. Hard Cuts And Rejected Alternatives

• Cut: public normalizePoint as the first answer to #4618.
• Cut: app renderer-owned DOM point repair.
• Cut: claiming mobile inline void issues from desktop browser proof.
• Cut: table-specific hacks inside examples.
• Cut: swallowing errors without trace reason.
• Keep: strict low-level toSlatePoint / toSlateRange for exact helper use.
• Keep: DOMCoverage as missing-DOM substrate when boundaries are involved.

18. Slate Maintainer Objection Ledger

19. Pass Schedule And Pass-State Ledger

20. Plan Deltas From Review

• Added next cluster decision: v2-dom-selection.
• Dropped mobile IME as next executable slice.
• Dropped public normalizePoint.
• Strengthened exact issue claim bar.
• Added browser-first proof matrix.
• Preserved existing issue-ledger statuses until execution produces proof.

21. Open Questions And What Would Change The Decision

• If selection-reconciler already has a central result object hidden in live source, execution should harden that instead of adding a new one.
• If table rows already pass exact #6034/#5355 proof, execution should switch to ledger sync and missing browser rows only.
• If a public app hook is still required after central bridge proof, create a separate API bake-off; do not smuggle it into this slice.

22. Implementation Phases

Phase 1: Red Contracts

Owner: .tmp/slate-v2/packages/slate-dom and .tmp/slate-v2/packages/slate-react.

• Add result-object tests for selection import/export.
• Add fail-closed tests for outside/nested/stale/missing DOM.
• Add table/inline/void/triple-click browser rows as failing contracts.

Phase 2: Internal Bridge

Owner: slate-dom.

• Add internal DOM selection bridge capability.
• Preserve strict helper behavior.
• Add bounded lookup and reasoned failure results.

Phase 3: Runtime Integration

Owner: slate-react.

• Route selectionchange and keydown selection import through the bridge.
• Record kernel traces for ignored/repair/error decisions.
• Remove duplicate fallback logic from reconciler callsites where the bridge owns it.

Phase 4: Browser Proof

Owner: slate-browser.

• Run table, inline void, block void, triple-click, outside selection, and nested editor rows.
• Record exact issue claim outcomes.

Phase 5: Ledger And PR Sync

Owner: plate-2 docs.

• Update live ledger, issue coverage matrix, fork dossier, PR reference, and completion file.

23. Fast Driver Gates

• bun test focused DOM/react selection contract files.
• bun --filter slate-dom typecheck.
• bun --filter slate-react typecheck.
• bun lint:fix.
• Focused Playwright stress rows by family.
• bun run completion-check in /Users/zbeyens/git/plate-2.

24. Final User-Review Handoff Outline

When executed, report:

• fixed vs improved vs related issue rows;
• exact browser families passed;
• public API unchanged unless proof forces a change;
• strict helper behavior kept;
• mobile claims not made without device proof.

25. Final Completion Gates

Completion requires:

• all red contracts green;
• no runtime path blindly throws on known foreign/nested/table/inline/void DOM target classes;
• browser stress rows green;
• issue ledgers synced;
• PR description synced or explicitly unchanged;
• completion file done.