Slate v2 History Selection Precondition Ralplan

Date: 2026-05-13

Status: done

Owner: slate-ralplan

Completion: active goal state

Ralph Execution Ledger

Implementation files:

• .tmp/slate-v2/packages/slate-history/src/with-history.ts
• .tmp/slate-v2/packages/slate-history/test/history-contract.ts
• .tmp/slate-v2/packages/slate-react/src/editable/input-controller.ts
• .tmp/slate-v2/packages/slate-react/src/editable/keyboard-input-strategy.ts
• .tmp/slate-v2/packages/slate-react/src/editable/mutation-controller.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/playwright/integration/examples/scroll-into-view.test.ts

Implementation proof:

• bun test ./packages/slate-history/test/history-contract.ts --bail 1
  • red before fix: undo restored [0,0]@0 instead of [0,0]@3.
  • green after fix: 26 pass.
• bun test ./packages/slate/test/commit-metadata-contract.ts ./packages/slate/test/collab-history-runtime-contract.ts --bail 1
  • 14 pass.
• bun --filter slate-history typecheck
  • exited 0.
• bun --filter slate typecheck
  • exited 0.
• bun --filter slate-react typecheck
  • exited 0.
• PLAYWRIGHT_BASE_URL=http://localhost:3100 PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/plaintext.test.ts playwright/integration/examples/richtext.test.ts --project=chromium --grep "keyboard undo restores caret after middle-line typing|undoes inserted text|undo restores deleted selected text"
  • 3 passed.
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/scroll-into-view.test.ts --project=chromium --grep "keeps caret at the edited block end" --reporter=line --trace=off
  • red before final repair/test hardening: delayed undo left selection at [4,0]@0.
  • green after fix: 1 passed.
• PLAYWRIGHT_BASE_URL=http://localhost:3100 PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/scroll-into-view.test.ts --project=chromium --grep "keeps caret at the edited block end" --reporter=line --trace=off
  • 1 passed.
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/scroll-into-view.test.ts --project=chromium --reporter=line --trace=off
  • 2 passed.
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/plaintext.test.ts playwright/integration/examples/richtext.test.ts --project=chromium --grep "keyboard undo restores caret after middle-line typing|undoes inserted text|undo restores deleted selected text|repairs DOM after Mac keyboard undo" --reporter=line --trace=off
  • 4 passed.
• bun --filter slate-react build
  • exited 0.
• bun --filter slate-react test:vitest -- selection-side-effect-policy-contract
  • 2 passed.
• bun lint:fix
  • exited 0; Biome fixed one file.

Implementation verdict:

• Batch.selectionAfter stayed deferred.
• Public history API stayed unchanged.
• Leading selection imports are trimmed from stored batch operations after they update batch.selectionBefore.
• Selection operations after the first saveable operation remain replayed and preserve redo's explicit post-edit selection.
• udecode/slate#9 stays fork-local accounting only; no upstream PR claim line was added.
• Compound note captured at docs/solutions/logic-errors/2026-05-13-slate-history-leading-selection-imports-are-batch-preconditions.md.
• Scroll-into-view caret proof now asserts the restored model selection and follow-up typing target after delayed undo; the previous text-visible-only row was too weak.

Current Verdict

The undo/redo selection regression is real, but it is not a reason to rewrite the whole history model.

Accepted target:

history batch selectionBefore
  = selection immediately before the first saveable operation
  not the commit-wide selectionBefore when leading set_selection ops import DOM

The first implementation slice should:

1. Add a failing package test where one commit replays set_selection(start -> middle) followed by insert_text and undo must restore middle, not start.
2. Build each new history batch from the first saveable operation.
3. Apply leading non-saveable set_selection operations to the commit selectionBefore before storing batch.selectionBefore.
4. Trim those leading set_selection operations out of batch.operations.
5. Keep set_selection operations that occur after the first saveable operation, because they are part of the edit result and matter for redo.

Do not add a public history API. Do not add Batch.selectionAfter in the first slice unless redo proof fails after the precondition fix.

Closure verdict: Ralph execution complete.

Intent Boundary

Pressure test:

• If this only fixed the one browser example by forcing DOM export after undo, it would be too shallow. The failing package repro proves the bad selection is already stored in the history batch before React gets involved.

Live Source Evidence

Verification evidence from /Users/zbeyens/git/slate-v2:

PLAYWRIGHT_BASE_URL=http://localhost:3100 PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/plaintext.test.ts --project=chromium --grep "keyboard undo restores caret after middle-line typing" --reporter=line

Result: passed, 1 passed (8.1s).

Inline package repro:

bun --eval "/* set_selection(start->middle) then insert_text, undo expects middle */"

Result: failed as expected. Actual undo selection was [0,0]@0; expected was [0,0]@3.

Decision Brief

Principles:

1. History units follow saveable model operations, not incidental selection import operations.
2. Selection-only operations before the first content operation are preconditions for that content operation.
3. Selection operations after content operations are part of the user-visible edit result and must remain replayable.
4. History remains operation-first for collaboration and replay.
5. Browser repair is not allowed to hide a bad package-level history batch.

Top drivers:

• The failing repro matches the user report: undo restores the stale start of the block.
• Legacy Slate captured selectionBefore at the first saveable operation.
• ProseMirror stores a bookmark at the start of a history event, not at an earlier selection-only precondition.
• Lexical snapshot history avoids this by storing full editor states, but that would be too heavy and not Slate-like for v2.

Viable options:

Chosen consequence:

• withHistory needs a small pure helper, not a public API:

prepareHistoryBatch(change.selectionBefore, committedOps);

It should return:

{
  operations: committedOps.slice(firstSaveableIndex),
  selectionBefore: applyLeadingSelectionOps(
    change.selectionBefore,
    committedOps.slice(0, firstSaveableIndex)
  ),
}

Public API Target

No public API change.

Keep:

• withHistory(editor)
• HistoryEditor.undo(editor) / HistoryEditor.redo(editor)
• editor.undo() / editor.redo() compatibility methods
• update tags and metadata already accepted by the runtime

Reject:

• public SelectionBookmark
• public historyTransaction
• public Batch.selectionAfter
• public normalizeSelection
• browser-only undo hooks as the primary fix

Internal Runtime Target

Target algorithm:

on commit
  committedOps = change.operations
  firstSaveable = index of first operation where shouldSave(op)
  if none: do not push history
  batchSelectionBefore =
    apply leading set_selection ops to change.selectionBefore
  batchOperations = committedOps from firstSaveable onward
  merge decision uses saveable operations as today
  if merge: append batchOperations to last batch
  else: push { operations: batchOperations, selectionBefore: batchSelectionBefore }

Required details:

• applyLeadingSelectionOps must support newProperties: null, full range creation from null, and partial anchor/focus patches against an existing range.
• It must reject or ignore impossible selection patches the same way operation apply does; do not invent permissive history-only selection semantics.
• Rebase logic must transform the new selectionBefore as it already does in rebaseBatch.
• Redo must pass for:
  • leading selection import plus text insert;
  • text insert plus trailing explicit selection;
  • structural range replacement;
  • remote rebase after local history.

Hook And Browser Runtime Target

React/browser work is a verification surface, not the first fix owner.

Keep current history hotkey paths:

• keyboard-input-strategy.ts handles undo/redo hotkeys.
• mutation-controller.ts dispatches editor.undo() / editor.redo().
• selection-reconciler.ts exports model selection to DOM after model-owned changes.

Add browser proof only after package red/green passes:

• Plaintext middle-line typing undo.
• Richtext middle-block typing after mouse/DOM selection undo.
• Repeat flow: type in middle, undo, type again, undo again.
• Partial selected text replacement undo.

Plate Migration Backbone

Plate needs operation-based history that treats toolbar/imported selection as the precondition for the content command, not as a separate undoable edit. This plan strengthens the substrate without adding Plate input-rule or command-chain policy to raw Slate.

Slate-Yjs Migration Backbone

The plan keeps serialized operation records unchanged. It also preserves the current remote-rebase path in with-history.ts:457-497, where local undo/redo batches and selectionBefore are transformed across remote operations.

Ralph must keep collab-history-runtime-contract.ts green and add no runtime id or DOM data to history entries.

Ecosystem Strategy Synthesis

Issue-Ledger Accounting

ClawSweeper status: skipped as a live GitHub pass. This is a local fork issue regression slice, and cached ledgers already contain the relevant upstream history clusters and udecode/slate#9 dossier rows. No broad gh issue list or gh search issues was needed.

PR reference status: unchanged. This plan adds no new upstream fixed issue claim until Ralph proof passes and the user accepts claim wording.

Fork dossier status: appended a new udecode/slate#9 regression planning row.

Regression Proof Matrix

Applicable Review Matrix

High-Risk Deliberate Mode

Trigger: history selection semantics and undo/redo replay behavior.

Pre-mortem:

1. Trimming leading set_selection fixes undo but breaks redo after structural commands that rely on a selection precondition.
2. Partial set_selection patches against null become silently accepted and hide invalid operation logs.
3. Collaboration rebase transforms the adjusted selectionBefore incorrectly after remote edits.

Expanded proof plan:

• Unit/package: new mixed-commit red/green in slate-history.
• Unit/package: redo counterpart and trailing-selection preservation.
• Existing package sweep: history-contract.ts, collab-history-runtime-contract.ts, commit-metadata-contract.ts.
• Browser: plaintext and richtext undo selection rows on Chromium; expand to WebKit/Firefox if the model fix changes React history behavior.
• Typecheck: slate, slate-history, slate-react.

Rollback/hard-cut answer:

• If trimming leading selection ops breaks redo, revise to store selectionAfter internally. Do not expose it publicly.

Slate Maintainer Objection Ledger

Hard Cuts And Rejected Alternatives

• Cut: browser-only repair as the root fix.
• Cut: public selection bookmark API.
• Cut: full snapshot history.
• Cut: changing operation serialization.
• Cut: using stale plan facts from docs/plans/2026-05-06-slate-v2-core-history-selection-undo-ralplan.md as current source evidence; live with-history.ts is the authority.

Implementation Phases For Ralph

1. Add red tests in .tmp/slate-v2/packages/slate-history/test/history-contract.ts:
   • leading set_selection plus insert_text undo restores the imported caret;
   • redo returns to the post-insert caret;
   • trailing set_selection after saveable op remains replayed.
2. Add a pure helper in with-history.ts for leading selection preconditions.
3. Use the helper when creating new batches.
4. Keep merge behavior stable by using existing saveable-op filtering.
5. Run package gates.
6. Run focused browser gates.
7. Update fork dossier and PR reference only after proof; no upstream fixed issue claim by default.

Fast Driver Gates

From /Users/zbeyens/git/slate-v2:

bun test ./packages/slate-history/test/history-contract.ts --bail 1
bun test ./packages/slate/test/commit-metadata-contract.ts ./packages/slate/test/collab-history-runtime-contract.ts --bail 1
bun --filter slate-history typecheck
bun --filter slate typecheck
bun --filter slate-react typecheck
PLAYWRIGHT_BASE_URL=http://localhost:3100 PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/plaintext.test.ts playwright/integration/examples/richtext.test.ts --project=chromium --grep "keyboard undo restores caret after middle-line typing|undoes inserted text|undo restores deleted selected text|history selection precondition"
bun lint:fix

From /Users/zbeyens/git/plate-2:

bun run completion-check

Scorecard

Weighted total: 0.94.

Status: done. The plan is ready for Ralph execution.

Pass-State Ledger

Plan Deltas From Review

• Added a precise package-level red for the user's caret jump symptom.
• Reclassified the simple plaintext browser row as supporting proof, not full closure for udecode/slate#9.
• Chose first-saveable-operation precondition capture as the root fix.
• Rejected browser-only repair and full snapshot history.
• Deferred internal selectionAfter until redo proof requires it.

Open Questions

None for the first implementation slice.

Final Completion Gates

• Live source owners recorded.
• Inline failing repro recorded.
• Existing browser proof recorded.
• Ecosystem strategy synthesis complete.
• Issue accounting complete without broad live GitHub discovery.
• No public API left in maybe language.
• Ralph gates named with cwd.