Slate v2 read access DX ralplan

Date: 2026-05-18 Status: done Owner: Slate Ralplan planning only Completion id: 019e1fc0-dba0-7de1-9236-b484a144cda6 Current pass: closure-final-gates Score: 0.90, ready for Ralph handoff

Verdict

Harsh answer: I do not like the current example shape.

This is too much ceremony for a Slate author:

const selection = editor.read((state) => state.selection.get());

But the fix should not be editor.state.selection.get(). That is the wrong steal from ProseMirror. ProseMirror commands receive an immutable state argument; they do not read mutable editor root state. Lexical also does not teach editor.state.selection; it teaches contextual reads and $getSelection inside read, update, or command listener scope.

Best initial target:

deleteBackward({ editor, state, next, unit }) {
  const selection = state.selection.get()

  if (selection && RangeApi.isCollapsed(selection)) {
    const cell = state.nodes.find({
      match: (n) => NodeApi.isElement(n) && n.type === 'table-cell',
    })

    if (cell) {
      const start = state.points.start(cell[1])

      if (PointApi.equals(selection.anchor, start)) {
        return
      }
    }
  }

  return next({ unit })
}

Keep editor.read((state) => ...) as the canonical outer read boundary. Add state to transform middleware context first. Do not widen this to every lifecycle context in the same slice.

Intent And Boundary

Current Live State

Decision Brief

Principles:

1. The read boundary must stay explicit.
2. Transform middleware should feel like old Slate method override DX, not like a React render callback.
3. Do not extend the editor root with live state namespaces.
4. Do not add helper piles just to hide the API.
5. Extension state groups must remain typed and composable.

Top drivers:

1. Examples are public API pedagogy.
2. Model behavior now lives in transforms.*, so the transform authoring path must be pleasant.
3. ProseMirror/Lexical both prove contextual state access is normal; neither justifies editor.state.

Options:

API Target

Current:

deleteBackward({ editor, next, unit }) {
  const selection = editor.read((state) => state.selection.get())
  const cell = editor.read((state) => state.nodes.find({ match }))
  const start = editor.read((state) => state.points.start(cellPath))
}

Target:

deleteBackward({ editor, state, next, unit }) {
  const selection = state.selection.get()
  const cell = state.nodes.find({ match })
  const start = cell ? state.points.start(cell[1]) : null
}

Middleware context target:

export type EditorTransformMiddlewareContext<
  TEditor extends BaseEditor<any>,
  TArgs extends object,
> = TArgs & {
  editor: TEditor;
  state: EditorStateView<ValueOf<TEditor>, ExtensionsOf<TEditor>>;
  next: EditorTransformNext<TArgs>;
};

Exact generic spelling needs live-source design in Ralph; the law is that state is the installed read view for that editor and extension set.

Ecosystem Strategy Synthesis

Research Ecosystem Refresh Pass

Status: complete.

Research-wiki mode: maintain. The existing editor-architecture research lane is already the right evidence layer for this question, so this pass refreshed the compiled decision pages and live local sources instead of opening a new full corpus ingest.

Compiled pages checked:

• docs/research/sources/editor-architecture/read-update-runtime-corpus-ledger.md
• docs/research/sources/editor-architecture/lexical-read-update-extension-runtime.md
• docs/research/sources/editor-architecture/prosemirror-transaction-view-dom-runtime.md
• docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md
• docs/research/decisions/slate-v2-read-update-runtime-architecture.md
• docs/research/decisions/slate-v2-state-tx-public-api-and-extension-namespaces.md
• docs/research/decisions/slate-v2-perfect-plan-should-steal-read-update-transaction-discipline-and-extension-dx.md

Live-source refresh:

• Slate v2 already names the read callback value state and types it as EditorStateView.
• Slate v2 transform middleware currently passes { editor, next, ...args }; adding state is a small context expansion, not a new root API.
• Slate v2 query middleware also passes { editor, next, ...args }, but the intent pass still keeps query middleware out of scope because query recursion semantics need separate review.
• ProseMirror commands use state as the command-context read object and mutation goes through dispatch(state.tr...).
• Tiptap command props use state plus tr, editor, commands, chain, and view; this supports state as a contextual command name but is too product-shaped for raw Slate core.
• Lexical proves active read/update/command context legality, not state naming. Its $getSelection() style remains a reject for Slate.

Naming challenge:

Research verdict:

• state is still the best name.
• The docs must call it a contextual read view, not a snapshot.
• Transform middleware only is still the right first scope.
• Do not add editor.state, editor.getSelection(), or editor.read.* in this plan.

Rejected Shortcuts

• editor.state.selection.get(): too attractive, too dangerous. It looks like ProseMirror but without ProseMirror's immutable EditorState object.
• editor.selection.get(): worse; it revives root editor field/method sprawl.
• Editor.getSelection(editor): not the teaching path for this rewrite.
• One scoped editor.read(...) block per transform: acceptable as a local migration fallback, but not the target DX. It still forces object packing and callback ceremony in the exact lifecycle that should already own context.
• Local helpers like isAtStartOfTableCell(editor): good only when reused; bad as the default example style because they hide the real API.
• editor.read.selection.get(): maybe useful later, but not first. It is less clearly Slate-ish than passing state into the context that already owns the transform lifecycle.

Testing And Proof Target

Ralph implementation should add/update:

• packages/slate/test/extension-methods-contract.ts: transform middleware context receives typed state; state.selection.get() and extension state groups are available.
• negative type tests: state is read-only inside transform middleware.
• packages/slate-react/test/surface-contract.tsx: examples teach contextual state in transform middleware, not root editor.state.
• examples:
  • site/examples/ts/tables.tsx
  • site/examples/ts/markdown-shortcuts.tsx
  • site/examples/ts/richtext.tsx
• docs:
  • docs/concepts/08-plugins.md
  • docs/libraries/slate-react/editable.md
  • docs/walkthroughs/05-executing-commands.md

Fast gates from /Users/zbeyens/git/slate-v2:

• bun test ./packages/slate/test/extension-methods-contract.ts
• bun --filter slate-react test:vitest -- surface-contract
• bun --filter slate typecheck
• bun --filter slate-react typecheck
• bun typecheck:site
• bun check

Related Issue Discovery Pass

Status: complete.

ClawSweeper mode: applied through durable local ledgers only. No broad live GitHub search was needed because this is an API/example authoring refinement inside already-reviewed extension/read surfaces.

Search terms and ledgers read:

• editor.read, state.selection, state.nodes, extension composition, transform middleware, #3802, #3557, #3177, #5961, #5080.
• docs/slate-issues/gitcrawl-live-open-ledger.md
• docs/slate-issues/gitcrawl-v2-sync-ledger.md
• docs/slate-v2/ledgers/fork-issue-dossier.md
• docs/slate-v2/ledgers/issue-coverage-matrix.md
• docs/slate-v2/references/pr-description.md

Issue matrix:

Claim result:

• New fixed claims: 0.
• New improved claims: 0.
• Related classifications changed: 0.
• Fork issue dossier updates: none; existing #3802, #3557, #3177, #5961, and query-DX sections already cover this pressure.
• PR description updates: none; accepted API shape should change only after later implementation or final API-sync pass.

Full Issue Ledger Pass

Status: complete.

Full local issue-doc scan:

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

Additional rows surfaced by the full scan:

No additional fixed or improved issue claims are justified. The full ledger scan reinforces the earlier boundary: contextual middleware state is API-DX substrate work under the already-classified extension/plugin pressure, not a closure claim for plugin registries, keypress hooks, DOM selection, or input runtime issues.

Issue sync result:

• docs/slate-issues/gitcrawl-v2-sync-ledger.md: unchanged; candidate rows already classify #3222, #4089, and #4181.
• docs/slate-v2/ledgers/issue-coverage-matrix.md: unchanged; matrix-only non-claim row already includes #3222 and #4089, while #4181 stays triage-closed in the sync ledger.
• docs/slate-v2/ledgers/fork-issue-dossier.md: unchanged; Plate-fit broader pass already reviewed #3222, #3802, #3557, and #4089.
• docs/slate-v2/references/pr-description.md: unchanged; no accepted API shape or proof status changes until implementation.

Intent Boundary And Decision Brief Pass

Status: complete.

Evidence refreshed:

• /Users/zbeyens/git/slate-v2/site/examples/ts/tables.tsx:112
• /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:789
• /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:928
• /Users/zbeyens/git/slate-v2/packages/slate/src/core/editor-extension.ts:390
• /Users/zbeyens/git/slate-v2/packages/slate/src/core/query-middleware.ts:146
• /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1531

Pressure-test result:

The weak assumption was that state means an immutable ProseMirror-style EditorState. That is not true in current Slate v2. EditorStateView is a contextual read-view API whose methods read current editor state. That is fine for middleware DX, but the docs and tests must not call it a frozen snapshot.

Important implementation boundary:

• Do not wrap transform middleware handlers in editor.read(...). Transform handlers must still be allowed to call next() and therefore enter writes.
• Implementation needs an internal contextual state-view provider for transform middleware, likely the same view shape used by editor.read, without turning transform middleware execution into a read-only scope.
• The read contract becomes: app/outer code uses editor.read((state) => ...); transform middleware uses context.state as the sanctioned contextual read handle.

Viable options after pressure:

Resolved boundary:

• Contextual state applies to transform middleware first.
• Query middleware, clipboard middleware, operation middleware, commit listeners, and normalizers stay unchanged in this plan.
• If a later pass finds repeated read ceremony in another lifecycle context, it gets its own evidence row and context-specific rules.

Consequences:

• Examples become shorter without local helper piles.
• state in middleware must be documented as a read view, not as an immutable snapshot.
• Tests must cover typing and runtime context shape for transforms.
• Implementation must avoid stale-state confusion around next(): examples should read before deciding whether to delegate; code that needs post-next state should call a fresh read after delegation in a separately reviewed pattern.

Remaining ambiguity:

• None that requires a user decision before the next pass. Maintainer/steelman can still challenge the public context expansion and teaching cost.

Maintainer Steelman Pass

Status: complete.

Accepted revisions from this pass:

• Add the one-scoped-read-block alternative to the decision matrix and reject it explicitly as the final DX.
• Strengthen proof requirements around stale reads after next().
• Keep state as the name, but require docs/JSDoc to call it a contextual read view.

Closure Final Gates

Status: complete.

Pass-State Ledger

Scorecard

Total: 0.90. Status is done.

Open Questions

• No user decision is needed before Ralph.
• Deferred follow-up: only consider editor.read.* one-shot helpers after a broader call-site audit proves repeated ceremony outside transform middleware.

Ralph Implementation Phases

1. Add typed state to transform middleware context.
2. Update table/markdown/richtext examples to use contextual state.
3. Update docs to teach contextual state in middleware and editor.read for general outer reads.
4. Add type/runtime contracts.
5. Run the fast gates from /Users/zbeyens/git/slate-v2.

Final Handoff Draft

• Cut: editor.state.selection.get() as root API.
• Add: state on transform middleware context.
• Keep: editor.read((state) => ...) as the canonical general read boundary.
• Defer: one-shot editor.read.* helpers until after call-site audit.
• Keep: inline example logic unless reused; no local helper pile.