Slate v2 Extension Context State/Tx Coverage Ralplan

Date: 2026-05-18 Status: done Completion id: 019e1fc0-dba0-7de1-9236-b484a144cda6 Current pass: ralph-implementation-closeout Current pass status: complete Score: 0.97 implemented

Verdict

Yes: extension.queries should receive state.

No: transform middleware should not receive state as its primary context. deleteBackward, deleteForward, insertBreak, insertText, and the rest of transforms are update lifecycle hooks. The target shape is transforms.*({ tx, next, ...args }), where tx already includes read methods plus write methods.

The catch: current source does not yet guarantee that every transform middleware call runs inside an update transaction. That must be fixed before exposing tx in transform middleware. Adding state there would make the API easier to implement today and worse forever.

Intent

Define the context object for every Slate v2 extension callback so users stop guessing whether they should call editor.read, editor.update, editor.api, or a lifecycle object.

Outcome

• Read lifecycle callbacks get state.
• Update lifecycle callbacks get tx.
• Post-commit callbacks get commit and snapshot.
• Registration and long-lived extension APIs get editor.
• Operation middleware stays low-level and does not get tx.
• No long-lived editor.state root shortcut. It looks nice, but it creates stale-read pressure.

Non-Goals

• No Slate v2 implementation edits in this Ralplan pass.
• No Plate compatibility layer.
• No public compatibility aliases for old Editor.*, DOMEditor.*, or HistoryEditor.* helper namespaces.
• No migration notes in public docs; this plan is implementation guidance.

Current Source Evidence

• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:466 defines EditorCoreStateView read groups.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:484 defines EditorCoreUpdateTransaction as read groups plus write groups.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:505 exposes editor.api, editor.getApi, editor.read, editor.update, editor.extend.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:789 has transform middleware context as { editor, next, ...args }.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:928 has query middleware context as { editor, next, ...args }.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:1210 already gives normalizers a restricted tx.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:1252 has extension state, tx, and editor group factories.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:1304 has clipboard context as { editor, next }.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:1325 has register context as { editor, name, options, runtimeState, signal }.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:1338 lists extension slots: api, clipboard, commitListeners, editor, elements, normalizers, operationMiddlewares, queries, state, transforms, tx.
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:971 builds the read state view and routes read methods through query middleware.
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:1384 builds tx by spreading state and adding write methods.
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:1500 builds the restricted normalizer transaction.
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:1531 implements editor.read((state) => ...).
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:1553 rejects editor.update inside query middleware.
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:1757 routes operations through operation middleware with { editor, operation }.
• .tmp/slate-v2/packages/slate/src/core/public-state.ts:2594 notifies commit listeners with commit and snapshot.
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts:156 rejects legacy methods and commands extension slots.
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts:373 registers transform middleware and passes only { editor, next, ...args }.
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts:423 registers clipboard insertData and passes only { editor, next }.
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts:451 passes normalizer contexts through with tx.
• .tmp/slate-v2/packages/slate/src/core/query-middleware.ts:121 executes query middleware and passes only { editor, next, ...args }.
• .tmp/slate-v2/packages/slate/src/core/command-registry.ts:69 only creates an implicit update when called with implicitUpdate.
• .tmp/slate-v2/packages/slate/src/core/transform-middleware.ts:136 calls executeCommand without implicitUpdate.
• .tmp/slate-v2/site/examples/ts/check-lists.tsx:89 shows current transform middleware repeatedly calling editor.read and then editor.update.
• .tmp/slate-v2/site/examples/ts/tables.tsx:115 shows the same repeated read pattern in delete middleware.
• .tmp/slate-v2/site/examples/ts/images.tsx:96 shows clipboard insertData(data, { editor, next }) with async FileReader.
• .tmp/slate-v2/packages/slate/test/query-extension-contract.ts:527 proves query middleware cannot mutate through editor.update.
• .tmp/slate-v2/packages/slate/test/generic-extension-namespace-contract.ts:254 already has negative type tests for invalid transform and normalizer surfaces.
• .tmp/slate-v2/packages/slate/test/extension-methods-contract.ts:742 covers same-name/latest extension and enabled: false tombstones.

Lifecycle Coverage Map

Before / After Shapes

Query Middleware

Current:

queries: {
  text: {
    string({ at, next, options }) {
      return `${next({ at, options })}!`
    },
  },
}

Target:

queries: {
  text: {
    string({ at, next, options, state }) {
      const selection = state.selection.get()

      if (!selection) {
        return next({ at, options })
      }

      return `${next({ at, options })}!`
    },
  },
}

Rule: use next for the query being intercepted. Use state for adjacent reads. Do not make state.text.string(...) magically bypass the same middleware; that hides recursion instead of teaching the middleware model.

Transform Middleware

Current checklist example:

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

  if (selection && RangeApi.isCollapsed(selection)) {
    const match = editor.read((state) =>
      state.nodes.find({
        match: (n) => NodeApi.isElement(n) && n.type === 'check-list-item',
      })
    )

    if (match) {
      const [, path] = match
      const start = editor.read((state) => state.points.start(path))

      if (PointApi.equals(selection.anchor, start)) {
        editor.update((tx) => {
          tx.nodes.set({ type: 'paragraph' })
          tx.selection.set(start)
        })
        return
      }
    }
  }

  next()
}

Target:

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

  if (selection && RangeApi.isCollapsed(selection)) {
    const match = tx.nodes.find({
      match: (n) => NodeApi.isElement(n) && n.type === 'check-list-item',
    })

    if (match) {
      const [, path] = match
      const start = tx.points.start(path)

      if (PointApi.equals(selection.anchor, start)) {
        tx.nodes.set(
          { type: 'paragraph' } satisfies Partial<SlateElement>,
          {
            match: (n) => NodeApi.isElement(n) && n.type === 'check-list-item',
          }
        )
        tx.selection.set(start)
        return
      }
    }
  }

  next({ unit })
}

Implementation gate: this target is only valid if transform middleware execution is wrapped in the same transaction as the default transform. Current executeTransformMiddleware calls executeCommand without implicitUpdate, so this is not just a type edit.

Clipboard Middleware

Current:

clipboard: {
  insertData(data, { editor, next }) {
    // parse DataTransfer
    editor.update((tx) => {
      tx.fragment.insert(fragment)
    })
    return true
  },
}

Target:

clipboard: {
  insertData(data, { editor, next, state }) {
    const selection = state.selection.get()

    if (!selection) {
      return next()
    }

    editor.update((tx) => {
      tx.fragment.insert(fragment)
    })
    return true
  },
}

No tx here. Clipboard handlers sit on a DOM/DataTransfer boundary and may cross async FileReader or upload boundaries. Holding a transaction open across that is a bug magnet.

Normalizers

Current and target:

normalizers: {
  node({ entry, next, tx }) {
    const value = tx.value.get()
    tx.nodes.insert({ type: 'paragraph', children: [{ text: '' }] })
    next()
  },
}

Keep the restricted normalizer tx. Existing negative type tests already reject tx.normalize, tx.withoutNormalizing, tx.operations.replay, and whole-value replacement.

Decision Brief

Principles:

• Lifecycle object first. state means read. tx means update. editor means long-lived runtime handle.
• No duplicate readable spellings for the same thing when one is enough.
• Do not add root editor.state. It is too easy to treat as always-current mutable state.
• Do not expose tx outside synchronous update lifecycle.
• Do not let Plate-shaped plugin sugar leak into raw Slate.

Viable options:

1. editor only everywhere.
   • Rejected. It keeps examples verbose and hides lifecycle legality.
2. state everywhere plus explicit editor.update.
   • Rejected. It is wrong for transform middleware because transforms are write hooks.
3. tx everywhere.
   • Rejected. It is wrong for query and clipboard lifecycle.
4. Lifecycle-specific context.
   • Accepted. It matches the existing state/tx split and keeps async boundaries honest.

Ecosystem Evidence

Lexical:

• Source summary: docs/research/sources/editor-architecture/lexical-read-update-extension-runtime.md.
• Mechanism: commands and transforms run inside update context; reads and writes have synchronous legality boundaries.
• Slate target: editor.read, editor.update, state in read callbacks, tx in update callbacks.
• Reject: Lexical class nodes, $ helpers, and command-first app API.
• Verdict: agree on lifecycle discipline, diverge on public style.

Tiptap:

• Source summary: docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md.
• Mechanism: extension packaging and command catalog make features discoverable.
• Slate target: keep extension packaging and editor.api, but make editor.update the write lifecycle.
• Reject: making commands the default mutation API.
• Verdict: partial.

Issue corpus:

• docs/slate-issues/issue-intelligence-master-plan.md says the corpus justifies replacing the execution/runtime model, not the JSON model.
• Older batches keep reinforcing plugin/render composition, paste, focus, history, delete, and input-runtime pressure.
• This plan does not claim any issue fixed.

ProseMirror:

• Source summary: docs/research/sources/editor-architecture/prosemirror-transaction-view-dom-runtime.md.
• Mechanism: commands receive current state; transactions own document, selection, marks, metadata, and mapping.
• Slate target: query middleware receives state; transform middleware receives update-local tx; operation middleware stays closer to operation dispatch than app command DX.
• Reject: ProseMirror plugin complexity, integer positions, and command-first public mutation style.
• Verdict: agree on transaction ownership and command-state context, diverge on public extension shape.

Issue Accounting

No global issue ledger changes are required. The related rows are already classified in docs/slate-issues/gitcrawl-v2-sync-ledger.md, docs/slate-v2/ledgers/issue-coverage-matrix.md, and docs/slate-v2/ledgers/fork-issue-dossier.md. This plan changes API target shape; it does not prove an issue reproduction.

Type Test Requirements

Add or revise negative type tests in the execution plan:

• Query middleware context exposes state and does not expose tx.
• Query middleware can call next once and cannot mutate with editor.update.
• Query generator cleanup still cannot mutate.
• Transform middleware context exposes tx; examples should not call editor.read for routine reads.
• Transform middleware tx includes read groups and write groups.
• Transform middleware does not expose a separate state duplicate.
• Clipboard context exposes state and does not expose tx.
• Normalizer context keeps restricted tx; no whole-value replace, no recursive normalize, no replay.
• Operation middleware context does not expose tx.
• Disabled extensions are erased from installed extension types.
• Latest same-name extension wins; no replaces field.
• editor.getApi(extension) returns the typed API for installed extensions and rejects non-installed extensions.

Exact files:

• .tmp/slate-v2/packages/slate/test/extension-methods-contract.ts: transform middleware tx context, transaction routing, no double next, same-name/latest and enabled: false.
• .tmp/slate-v2/packages/slate/test/query-extension-contract.ts: query middleware state context, recursion policy, mutation rejection, generator cleanup rejection.
• .tmp/slate-v2/packages/slate/test/generic-extension-namespace-contract.ts: declaration merging, disabled extension type erasure, getApi(extension) typing, negative context assertions.
• .tmp/slate-v2/packages/slate/test/generic-extension-install-contract.ts: installed extension inference and tombstone behavior.
• .tmp/slate-v2/packages/slate/test/normalization-contract.ts: restricted normalizer tx stays restricted.
• .tmp/slate-v2/packages/slate-dom/test/clipboard-boundary.ts and .tmp/slate-v2/packages/slate/test/clipboard-contract.ts: clipboard state read plus fresh update writes, no async tx.

Example Update Requirements

Update examples after implementation:

• site/examples/ts/check-lists.tsx: inline transform logic should use tx.selection.get, tx.nodes.find, tx.points.start, tx.nodes.set, tx.selection.set.
• site/examples/ts/tables.tsx: delete/backspace/enter boundary logic should live in deleteBackward, deleteForward, and insertBreak transform middleware, not keydown event branches.
• site/examples/ts/images.tsx: clipboard should use state.selection.get for read checks and editor.update for sync writes; async FileReader writes must start a fresh editor.update.
• Public examples should prefer extension callbacks over renderElement / renderLeaf props when the extension owns rendering. Raw <Editable renderElement> remains acceptable only as a low-level escape hatch example.

Open Risks

• Transform middleware cannot get tx until the dispatch path is guaranteed to run inside an update transaction. Current executeTransformMiddleware does not force implicitUpdate.
• Query middleware with full state can recursively call the same query through state. The model should be documented and tested: next is the continuation for the current query.
• Clipboard state is a snapshot-time read. Async callbacks must use a fresh editor.read or editor.update.
• Keeping editor in every context is useful for editor.api, but examples must not teach root editor mutation as the normal path.

Maintainer Objection Ledger

High-Risk Deliberate Mode

Trigger: public API and extension substrate change.

Pre-mortem:

• Transform middleware exposes tx but is not actually update-local, causing nested updates or stale reads.
• Query middleware state causes accidental same-query recursion and confusing stack overflows.
• Clipboard examples accidentally hold transaction objects across async file reads.

Proof matrix:

Rollback/hard-cut answer:

• No compatibility aliases. If implementation proves tx transform middleware cannot be made coherent, drop tx from transforms and keep { editor, next } temporarily; do not ship a fake state compromise.

Implementation Phases

1. Transform dispatch: make transform middleware execute inside the active update transaction and pass tx.
2. Query context: pass state to query middleware and test recursion/mutation rules.
3. Clipboard context: pass state, keep writes through editor.update, and update async examples.
4. Type surface: add negative type tests for context availability, disabled extensions, latest-name wins, and getApi.
5. Examples: rewrite checklists, tables, images, and forced-layout with inline lifecycle logic.
6. Hard-cut guard: keep old methods, commands, public capabilities, and Editor/DOMEditor/HistoryEditor helper alternatives out of public docs/examples.

Verification Gates

Planning artifact:

node tooling/scripts/completion-check.mjs

Implementation gates for a later ralph run:

cd .tmp/slate-v2 && bun test ./packages/slate/test/extension-methods-contract.ts ./packages/slate/test/query-extension-contract.ts ./packages/slate/test/generic-extension-namespace-contract.ts ./packages/slate/test/generic-extension-install-contract.ts ./packages/slate/test/normalization-contract.ts
cd .tmp/slate-v2 && bun test ./packages/slate/test/clipboard-contract.ts ./packages/slate-dom/test/clipboard-boundary.ts
cd .tmp/slate-v2 && bun --filter slate typecheck
cd .tmp/slate-v2 && bun --filter slate-dom typecheck

Pass State Ledger

Final Score

Overall: 0.93 ready.

Final Handoff

Ready for ralph execution when the user asks to build.

• queries: revise to { state, editor, next, ...args }; next remains the current-query continuation.
• transforms: revise to { tx, editor, next, ...args }; first implementation step must make transform middleware transaction-local.
• normalizers: keep restricted tx.
• clipboard: revise to { state, editor, next }; no tx.
• operationMiddlewares: keep { editor, operation }, next.
• commitListeners: keep (commit, snapshot).
• register: keep { editor, name, options, runtimeState, signal }.
• api: keep editor.api and editor.getApi(extension).
• state root shortcut: cut.
• Editor / DOMEditor / HistoryEditor public alternatives: cut from the target public path.
• Issue accounting: no new fixed issue claims; all related rows are classified.

Ralph Execution Grounding

Task statement: implement the accepted extension lifecycle context API in .tmp/slate-v2.

Desired outcome:

• Query middleware receives state.
• Transform middleware receives transaction-local tx.
• Clipboard middleware receives state and never receives tx.
• Normalizer restricted tx stays intact.
• Public alternatives remain cut.
• Examples and typed tests prove the new shape.

Known facts:

• tx is built from state plus write groups in .tmp/slate-v2/packages/slate/src/core/public-state.ts.
• Current transform middleware is registered in .tmp/slate-v2/packages/slate/src/core/editor-extension.ts and dispatched through .tmp/slate-v2/packages/slate/src/core/transform-middleware.ts.
• Current command execution only starts an implicit update when executeCommand(..., { implicitUpdate: true }) is used.
• Current query middleware already rejects editor.update from query execution.
• Current clipboard examples may cross async FileReader boundaries.

Constraints:

• Use vertical TDD slices.
• Keep example logic inline when used once.
• Prefer TypeScript inference, satisfies, and type guards over casts.
• Do not add compatibility aliases.
• Do not rerun related-issue discovery unless the issue surface or claim set changes.

Likely touchpoints:

• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts
• .tmp/slate-v2/packages/slate/src/core/transform-middleware.ts
• .tmp/slate-v2/packages/slate/src/core/query-middleware.ts
• .tmp/slate-v2/packages/slate/src/core/command-registry.ts
• .tmp/slate-v2/packages/slate/test/extension-methods-contract.ts
• .tmp/slate-v2/packages/slate/test/query-extension-contract.ts
• .tmp/slate-v2/packages/slate/test/generic-extension-namespace-contract.ts
• .tmp/slate-v2/site/examples/ts/check-lists.tsx
• .tmp/slate-v2/site/examples/ts/tables.tsx
• .tmp/slate-v2/site/examples/ts/images.tsx

Ralph Execution Ledger