Slate v2 Unified Extension Composition Ralplan

Status: done Runtime id: 019e1fc0-dba0-7de1-9236-b484a144cda6 Completion file: active goal state Current pass: complete Next pass: none

Ralph Revision - Default React History And Disabled Extension Types

Decision:

• createReactEditor() and useSlateEditor() install React and history by default.
• Raw createEditor() stays unopinionated; headless history still requires extensions: [history()].
• Every extension may set enabled: false.
• Extension resolution is latest same-name wins. A disabled same-name extension is a tombstone: it removes the previous runtime install and removes that extension output from editor types.
• There is no replaces API. Future duplicate strictness is a separate option, not part of this slice.
• React context uses a React-only context value. It must not require history, because history({ enabled: false }) is valid.

Implementation evidence:

• EditorResolvedInstalledExtensions resolves extension tuples right-to-left, drops disabled extensions, and excludes replaced same-name types.
• Installed state/tx/api type mapping distributes over extension unions and empty extension slots contribute never, not absorbing unknown.
• extendEditor cleans existing same-name extension records before installing the latest resolved extension set.
• history() accepts { enabled?: boolean } and exposes typed state/tx slots plus editor.api.history controls.
• React creation prepends react() and history(), then appends user extensions so user extensions can override or tombstone defaults.
• React examples use useSlateEditor({ extensions: [custom()] }) or no extensions field for default history.

Fresh verification from /Users/zbeyens/git/slate-v2:

• bun install: passed, lockfile saved with no dependency changes.
• bun x tsc --project packages/slate/test/tsconfig.generic-types.json --noEmit: passed.
• bun x tsc --project packages/slate-history/test/tsconfig.generic-types.json --noEmit: passed.
• bun x tsc --project packages/slate-react/test/tsconfig.generic-types.json --noEmit: passed.
• bun test ./packages/slate/test/extension-methods-contract.ts: 14 passed.
• bun --filter slate typecheck: passed.
• bun --filter slate-history typecheck: passed.
• bun --filter slate-react typecheck: passed.
• bun typecheck:site: passed.
• bun lint:fix: passed, fixed 4 files.
• bun check: passed; existing React hook warning remains in packages/slate-react/src/components/slate.tsx.

Implementation Closure Evidence

Final implementation state:

• Core supports createEditor({ extensions }), installed state / tx / editor.api inference, and token-based editor.getApi(extensionToken).
• slate-history exports history() and routes stack reads through state.history, undo/redo through tx.history, and ambient controls through editor.api.history.
• slate-dom exports dom() and installs sibling editor.api.dom and editor.api.clipboard handles.
• slate-react exports react(), createReactEditor(), ReactEditorInstance, and useSlateEditor({ extensions }).
• First-party examples and docs teach lower camel-case extension factories, editor.api.* handles, and clipboard.insertData handler keys.

Final verification from /Users/zbeyens/git/slate-v2:

• bun --filter slate-dom typecheck: passed.
• bun --filter slate-react typecheck: passed.
• bun typecheck:site: passed.
• bun lint:fix: passed, no fixes applied.
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/check-lists.test.ts playwright/integration/examples/editable-voids.test.ts playwright/integration/examples/markdown-shortcuts.test.ts playwright/integration/examples/inlines.test.ts --project=chromium: 38 passed.
• bun check: passed; it reports one existing eslint warning in packages/slate-react/src/components/slate.tsx and 0 errors.

Final stale-surface grep:

• Old public names remain only in negative type/runtime tests.
• Root editor.dom remains only inside internal DOM/React installers and internal DOM coverage implementation.

Current Verdict

Hard take: the user is right. withHistory(withReact(createEditor())), useSlateEditor({ withEditor }), and custom withX(editor) { editor.extend(...) } are transitional, not the final Slate v2 DX.

The best target is one public extension story:

• authors pass extension factories/values at editor creation
• built-in packages export extension factories, not with* mutators
• examples define lowercase extension factories by default, not wrapper functions
• editor.extend stays as an internal installer or test escape hatch, not the taught app-author API
• the editor root stays small; replayable extension typing flows into state and tx, not into root editor properties
• non-replayable DOM/React APIs become installed extension handles accessed through editor.api.dom / editor.api.react, not DOMEditor, ReactEditor, editor.dom, state.dom, or tx.dom
• generic code that has an extension token may use editor.getApi(extensionToken), not string registry lookup
• typed extension output is inferred from the extension list, not from T & HistoryEditor<ValueOf<T>>
• public editor-bound helper namespaces are cut with Editor; only pure document/value helpers keep *Api names such as NodeApi, PathApi, and RangeApi

This is a breaking change. Good. Carrying both wrapper composition and extension registration would make Slate v2 look like a half-migration.

Intent And Boundary

Original Live Current State

Before And After Shape

Current shape:

const editor = useSlateEditor<CustomValue, CustomEditor>({
  withEditor: (editor) => withEditableVoids(withHistory(editor)),
  initialValue,
});

const withEditableVoids = (editor: CustomEditor) => {
  editor.extend({
    name: "editable-voids",
    elements: [{ type: "editable-void", void: "editable-island" }],
  });

  return editor;
};

Target shape:

const editableVoid = () =>
  defineEditorExtension({
    name: "editable-voids",
    elements: [{ type: "editable-void", void: "editable-island" }],
  });

const editor = useSlateEditor({
  initialValue,
  extensions: [editableVoid()],
});

Current history shape:

const editor = withHistory(withReact(createEditor<CustomValue>()));

editor.undo();
editor.redo();
HistoryEditor.withoutSaving(editor, () => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

Target history shape:

const editor = createReactEditor({
  initialValue,
});

editor.update((tx) => {
  tx.history.undo();
});

editor.update((tx) => {
  tx.history.redo();
});

editor.api.history.withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

Target custom behavior shape:

const checklist = () =>
  defineEditorExtension({
    name: "checklist",
    transforms: {
      deleteBackward({ editor, next }) {
        if (applyChecklistBackspaceStart(editor)) return;

        next();
      },
    },
  });

const editor = useSlateEditor({
  initialValue,
  extensions: [checklist()],
});

No withChecklists. No withEditableVoids. No withEditor. No as CustomEditor just to recover a wrapper intersection.

Naming convention:

• Extension factories are lower camel-case singular nouns by default: history(), dom(), editableVoid(), checklist(), mention(), table().
• Use plural names only when the concept is naturally a collection or action family, such as shortcuts() or normalizers().
• Static extension values use PascalCase plus Extension only when they are values, not functions: EditableVoidExtension.
• Do not export PascalCase callables such as History().
• Do not suffix callables as HistoryExtension(). That reads like a class or constant but behaves like a factory.
• Plate's NamePlugin convention belongs to Plate's product plugin layer. Raw Slate uses extension factories/values, not plugins.

Decision Brief

Principles:

1. One extension mechanism beats nostalgic wrapper composition.
2. Raw Slate uses extensions, not Plate plugins.
3. Replayable extension output is grouped and typed on state/tx; mounted environment capability output is exposed on typed editor.api handles.
4. Runtime ordering must be deterministic before React/provider mount.
5. Old method-override power stays covered through extension middleware, not monkeypatching.

Top drivers:

1. Current code already has a real extension registry and middleware substrate.
2. History/DOM/React still bypass that substrate with wrapper mutation.
3. Plate and slate-yjs need a typed migration backbone, not compatibility with today's wrapper names.

Viable options:

Chosen option:

const editor = createEditor({
  initialValue,
  extensions: [history(), myExtension()],
});

React helper:

const editor = useSlateEditor({
  initialValue,
  extensions: [myExtension()],
});

useSlateEditor creates a React-capable editor through the same extension pipeline. A non-hook createReactEditor({ extensions }) can exist for tests and non-hook React setup. It is a creation helper, not a second extension model. The returned editor may carry a phantom installed-extension generic for read, update, and extensions inference. Its public root shape stays small: read, subscribe, update, api, and typed getApi.

Public API Target

Core

type CreateEditorOptions<
  V extends Value = Value,
  TExtensions extends readonly EditorExtensionInput[] = [],
> = {
  extensions?: TExtensions;
  initialSelection?: Selection;
  initialValue?: V;
};

declare function createEditor<
  V extends Value = Value,
  const TExtensions extends readonly EditorExtensionInput[] = [],
>(options?: CreateEditorOptions<V, TExtensions>): Editor<V, TExtensions>;

Editor<V, TExtensions> should carry installed extension type information for read, update, and extensions, without adding extension-owned public root properties such as editor.history or editor.dom. Replayable extension groups and installed extension handles are inferred from the tuple:

const extensions = [history(), react(), checklist()] as const;
const editor = createEditor({ initialValue, extensions });

editor.read((state) => state.history.canUndo());
editor.read((state) => state.history.redos());
editor.update((tx) => tx.checklist.toggle());
editor.update((tx) => tx.history.undo());

editor.api.dom.resolvePath(element);
editor.api.clipboard.insertData(data);

Built-in Packages

Cut these public exports:

• withHistory
• withDOM
• withReact

Add extension factories:

• history() from slate-history
• dom(options?) from slate-dom
• react(options?) from slate-react

Factory naming rule:

• Built-in factories stay lower camel-case: history(), dom(), react().
• Custom factories should follow the same singular shape: editableVoid(), checklist(), mention(), table().
• Plural factory names are reserved for naturally plural domains such as shortcuts() or normalizers().
• Static extension values may use PascalCase plus Extension: EditableVoidExtension.
• Do not use History() or HistoryExtension() for factory exports.
• Do not copy Plate's NamePlugin suffix into raw Slate. Plate plugins are a product-layer concept; raw Slate extensions are the substrate.

react() depends on or installs DOM capability through the extension dependency system. It must not call withDOM because that preserves the old mental model inside the new one.

React

Cut withEditor from useSlateEditor.

const editor = useSlateEditor({
  initialValue,
  extensions: [editableVoid()],
});

The hook installs React capability through the same creation path. If direct construction is needed:

const editor = createReactEditor({
  initialValue,
  extensions: [editableVoid()],
});

Typed API Access

Direct app code should prefer the installed handle:

editor.api.history.withoutSaving(() => {
  editor.update((tx) => tx.nodes.set({ type: "paragraph" }));
});

Generic code that has an extension token can use getApi:

editor.getApi(history).withoutSaving(() => {
  editor.update((tx) => tx.nodes.set({ type: "paragraph" }));
});

editor.getApi(dom).focus();

The token is the branded extension factory or static extension value, not a string and not a freshly created extension instance:

editor.getApi("history"); // type error
editor.getApi(history()); // type error
editor.getApi(history).undo(); // type error; use tx.history.undo()
editor.getApi(history).redos(); // type error; use state.history.redos()

History

History becomes state and tx extension groups:

editor.read((state) => state.history.canUndo());
editor.read((state) => state.history.canRedo());
editor.read((state) => state.history.undos());
editor.read((state) => state.history.redos());

editor.update((tx) => {
  tx.history.undo();
});

editor.update((tx) => {
  tx.history.redo();
});

Do not keep public editor.undo, editor.redo, editor.writeHistory, editor.history root fields, or HistoryEditor.* helpers. Extension runtime state owns the stacks; state.history exposes readonly stack/read helpers, tx.history exposes write actions such as undo/redo, and editor.api.history exposes editor-bound history controls.

History control for update grouping should use update metadata first:

editor.update(fn, { metadata: { history: { mode: "push" } } });
editor.update(fn, { metadata: { history: { mode: "merge" } } });
editor.update(fn, { metadata: { history: { mode: "skip" } } });

Do not duplicate stack reads or undo/redo on editor.api.history in the first pass. Stack reads stay on state.history; undo/redo stay on tx.history.

Editor-bound helpers that are not pure data APIs live on the installed extension handle:

editor.api.history.withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

editor.api.history.withoutMerging(() => {
  editor.update((tx) => {
    tx.text.insert("x");
  });
});

DOM

Do not keep public editor.dom. It is the same root-growth mistake as editor.history, and putting it under state.dom / tx.dom is worse because DOM methods depend on mounted browser state, WeakMaps, native selection, Window, and DataTransfer.

Current shape:

editor.dom.focus();
editor.dom.resolvePath(element);
editor.dom.clipboard.insertData(data);

Target shape:

editor.api.dom.focus();
editor.api.dom.resolvePath(element);
editor.api.dom.resolveRangeRect(range);
editor.api.clipboard.insertData(data);

The architecture move is to formalize extension capabilities:

• state groups are coherent, replayable reads over Slate editor/model state
• tx groups are coherent, replayable writes/actions over Slate editor/model state
• capabilities are installed runtime handles for mounted or external systems

const editor = useSlateEditor({
  initialValue,
});

editor.api.dom.resolvePath(element);
editor.api.dom.focus();
editor.api.clipboard.insertData(data);

dom() can register multiple public runtime handles. It installs the dom handle for DOM projection/focus APIs and the clipboard handle for DataTransfer / clipboard APIs. Public API keys are capability names, not package names. The public surfaces are the typed installed handles at editor.api.dom and editor.api.clipboard. They can assert that the capability exists, but they must not be intersection types that add dom or clipboard to the editor root.

editor.api.clipboard.insertData(data) may parse DataTransfer and then open an internal editor.update to apply Slate operations. The public API still does not pass DataTransfer through tx, because the browser object is not a replayable transaction input. Do not expose editor.api.dom.clipboard.insertData(data); nesting clipboard under DOM is package-shaped, not capability-shaped.

React follows the same rule. react() may expose a typed editor.api.react handle for React-bound runtime helpers, but ReactEditor must not be public app DX and must not be a root editor intersection type that adds DOM or React fields.

Internal Runtime Target

• Keep defineEditorExtension.
• Keep dependency, peer dependency, and conflict checks.
• Keep elements, transforms, queries, normalizers, operationMiddlewares, commitListeners, state, tx, and typed extension handles backed by internal capabilities.
• Install extensions during createEditor before the editor reaches React provider code.
• Remove extend from the public BaseEditor author type, or mark it explicitly internal and stop exporting it as the normal app API.
• Keep a private extendEditor(editor, extension) installer for core package implementation and focused tests.
• Do not use extension editor groups for public app APIs. If the runtime keeps an editor-group escape hatch, treat it as internal and do not use it for history/DOM/React public DX.
• Formalize capability access behind editor.api.<name> handles. Direct app code uses those handles. Generic extension-aware code may call editor.getApi(extensionToken) where the token is a branded factory/value. Raw string lookup such as getEditorCapability(editor, name) stays internal, and app code should not call DOMEditor.*.
• Do not expose editor.plugins. Raw Slate may expose read-only extension metadata later, but the normal API is typed state/tx groups plus editor.api, not registry inspection.

The existing ExtensionRegistry already has the right raw ingredients: capabilities, commands, commit listeners, element specs, editor groups, operation middlewares, query middlewares, state groups, and tx groups (/Users/zbeyens/git/slate-v2/packages/slate/src/core/extension-registry.ts:31). Pass 7 narrows the public target again: mounted DOM/React target is exposed through typed installed extension handles, not public DOMEditor / ReactEditor namespaces, even though the live registry can currently install editor groups.

Type Target

Current bad shape:

export const withHistory = <T extends Editor<any>>(
  editor: T
): T & HistoryEditor<ValueOf<T>>

Target shape:

const extensions = [history(), editableVoid()] as const;

const editor = createEditor({
  initialValue,
  extensions,
});

Inference should give:

• ValueOf<typeof editor> = CustomValue
• state.history.* exists inside editor.read because history() is installed
• tx.history.* exists inside editor.update because history() is installed
• tx.<customGroup> exists only when the custom extension declares it
• editor.api.history.withoutSaving exists because history() is installed
• editor.getApi(history).withoutSaving exists because history() is installed and history is a typed extension token
• editor.api.dom.* exists because dom() or react() is installed
• editor.getApi(dom).* exists because dom() or react() is installed and dom is a typed extension token
• editor.api.clipboard.* exists because dom() or a future dedicated clipboard installer provides that capability
• editor.getApi(clipboard).* exists because the clipboard API token is installed by dom() or a future dedicated clipboard installer
• no editor.history.* root namespace is installed for normal app code
• no editor.dom.* root namespace is installed for normal app code
• no local CustomEditor = ReactEditor & HistoryEditor & ... glue for normal examples
• no string editor.getApi('history') public typing
• no fresh-instance editor.getApi(history()) public typing
• no nested editor.api.dom.clipboard.* public typing
• no duplicated editor.getApi(history).undo() or editor.getApi(history).redos() public typing

Negative type tests must be explicit, not implied:

const plainEditor = createEditor({ initialValue });

// @ts-expect-error history is not installed
plainEditor.api.history.withoutSaving(() => {});

// @ts-expect-error history is not installed
plainEditor.getApi(history);

const historyEditor = createEditor({
  initialValue,
  extensions: [history()],
});

historyEditor.api.history.withoutSaving(() => {});
historyEditor.getApi(history).withoutSaving(() => {});

// @ts-expect-error string lookup is not public API
historyEditor.getApi("history");

// @ts-expect-error fresh extension instances are not lookup tokens
historyEditor.getApi(history());

// @ts-expect-error undo is replayable transaction API
historyEditor.api.history.undo();

// @ts-expect-error undo is replayable transaction API
historyEditor.getApi(history).undo();

// @ts-expect-error dom is not installed
historyEditor.api.dom.focus();

// @ts-expect-error dom is not installed
historyEditor.getApi(dom);

// @ts-expect-error clipboard is not installed
historyEditor.api.clipboard.insertData(data);

const domEditor = createEditor({
  initialValue,
  extensions: [dom()],
});

domEditor.api.dom.focus();
domEditor.api.clipboard.insertData(data);

// @ts-expect-error clipboard is top-level capability API
domEditor.api.dom.clipboard.insertData(data);

This should be closer to Plate's TSlateEditor<V, P> generic idea, but with raw Slate names:

• extensions, not plugins
• state / tx, not api / tf
• extension groups, not product plugin config

Ecosystem Strategy Synthesis

Research Ecosystem Refresh - Pass 5

Trigger:

The user challenged the DOM boundary again: if read and update are only for replayable editor/model APIs, then editor.dom cannot simply move there. This pass tested whether that means another architecture move is needed.

Verdict:

Yes, the plan needs a named architecture concept, but not a new app-author API. The concept is first-class extension capabilities. The public shape stays:

const editor = useSlateEditor({
  extensions: [history(), react()],
  initialValue,
});

editor.read((state) => state.history.redos());

editor.update((tx) => {
  tx.history.undo();
});

editor.api.dom.focus();
editor.api.dom.resolvePath(element);

No editor.dom. No state.dom. No tx.dom.

Ecosystem findings:

Architecture update:

• extensions install three kinds of output: replayable state groups, replayable tx groups, and mounted/external capabilities.
• state groups are coherent model reads.
• tx groups are coherent model writes/actions.
• capabilities are runtime handles that may touch DOM, React, Window, selection, DataTransfer, Yjs docs, or other external systems.
• typed editor.api.<name> handles are the installed runtime/control surface.
• typed editor.getApi(extensionToken) is the generic escape hatch for extension-aware code; string/raw capability getters stay internal.

Pass verdict:

The plan is stronger, not broader. The needed architecture move is to name and type capabilities as extension output, then expose them through typed installed extension handles. Copying DOM into read / update would be a category error. Copying Tiptap's root facade would be product-layer creep. The current target remains the best Slate-ish DX: creation-time extensions, replayable state / tx, and editor.api handles for mounted runtime APIs.

Plate Migration Backbone

Plate should be able to map Plate plugins to raw Slate extensions:

createPlateEditor({
  plugins: [TablePlugin, HistoryPlugin],
});

internally becomes:

createEditor({
  extensions: [
    history(),
    tableSchemaExtension(),
    tableTransformExtension(),
    tableRenderExtension(),
  ],
});

Plate keeps product config, options stores, components, toolbars, and rich rule families. Slate supplies the unopinionated extension substrate.

Conflict is allowed: Plate can migrate to this instead of forcing Slate to keep with* wrappers for Plate's comfort.

slate-yjs Migration Backbone

Current slate-yjs evidence is old Slate wrapper mutation:

• YjsEditor extends editor with sharedRoot, connect, disconnect, applyRemoteEvents, storeLocalChange, and flushLocalChanges.
• withYjs casts T & YjsEditor, assigns fields, and patches apply / onChange.

Target:

• yjs({ sharedRoot, localOrigin, positionStorageOrigin }) extension
• runtime state owns sharedRoot, connection state, local change buffer, and origins
• operation middleware captures local operations
• commit listeners flush local changes
• remote Yjs events enter through editor.update(..., { metadata: { collab: { origin: 'remote', saveToHistory: false } } })
• history uses commit metadata, not wrapper ordering

No claim that current slate-yjs can migrate without adapter work.

Regression Proof Matrix

Performance DX Migration Regression Pressure - Pass 6

Trigger:

The chosen architecture is attractive enough to be dangerous. Pass 6 tests whether it stays good when judged as a hot editor runtime, a TypeScript API, a migration, and a regression surface.

Live evidence used:

• createEditor currently accepts only initialSelection and initialValue, and wires read / update through runtime closures in /Users/zbeyens/git/slate-v2/packages/slate/src/create-editor.ts:498 and /Users/zbeyens/git/slate-v2/packages/slate/src/create-editor.ts:527.
• BaseEditor still exposes public extend, while CreateEditorOptions has no extensions field in /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:501 and /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:988.
• Extension outputs already include capabilities, state, transforms, and tx in /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:1273.
• Transform middleware has a no-handler fast path before command dispatch in /Users/zbeyens/git/slate-v2/packages/slate/src/core/transform-middleware.ts:117.
• Query middleware has a no-handler fast path before recursive middleware dispatch in /Users/zbeyens/git/slate-v2/packages/slate/src/core/query-middleware.ts:136.
• stateGroups and txGroups are materialized onto each read/update view in /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1370 and /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1484.
• Operation middleware currently snapshots the registry Set into an array for every operation in /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1737.
• Commit listener notification already delays snapshot materialization until a listener needs it in /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:2571.
• useSlateEditor still wraps withReact(createEditor(...)) and then calls withEditor in /Users/zbeyens/git/slate-v2/packages/slate-react/src/hooks/use-slate-editor.ts:25.
• Existing benchmark owners cover core transaction/query/ref/node-transform, history memory, collaboration readiness, React rerender breadth, and huge document compare in /Users/zbeyens/git/slate-v2/package.json:11 and /Users/zbeyens/git/slate-v2/scripts/benchmarks/README.md:110.
• Current tests still prove the old wrapper surface in several places, while extension contracts already cover state/tx groups and transform/query middleware. The live grep showed current withHistory, withDOM, withReact, and withEditor usages in history, DOM, React, and examples.

Pressure verdict:

The architecture survives, but only with explicit performance rules. The absolute-best shape does not change back to wrappers, and it does not expose editor.dom. The implementation plan must add hard runtime guardrails:

DX verdict:

The best call-site still looks like this:

const editor = useSlateEditor({
  initialValue,
  extensions: [checklist()],
});

Do not require:

const extensions = [checklist()] as const;

for normal inline usage. The public overload should use a const generic so the array literal infers as a tuple. Reusable arrays may still use as const or satisfies, but primary examples should not teach that as mandatory.

History should stay:

editor.read((state) => state.history.redos());

editor.update((tx) => {
  tx.history.undo();
});

History.undo(editor) is rejected for the public API for the same reason Editor.* is rejected: it is an editor-bound helper namespace. Do not duplicate undo/redo on editor.api.history in the first pass. Outside update, call editor.update((tx) => tx.history.undo()); inside update, use tx.history.undo().

DOM/React should move to installed extension handles:

editor.api.dom.focus();
editor.api.dom.resolvePath(element);
editor.api.clipboard.insertData(data);

Generic extension-aware code can use typed token access:

editor.getApi(history).withoutSaving(() => {
  editor.update((tx) => tx.history.undo());
});

No public string capability accessor. If package internals need raw capability lookup, keep it internal and typed.

Regression gates to add before Ralph claims success:

# cwd: /Users/zbeyens/git/slate-v2
bun test ./packages/slate/test/public-surface-contract.ts
bun test ./packages/slate/test/generic-extension-namespace-contract.ts
bun test ./packages/slate/test/extension-methods-contract.ts
bun test ./packages/slate/test/query-extension-contract.ts
bun test ./packages/slate/test/normalization-contract.ts
bun --filter slate-history test
bun --filter slate-dom test
bun --filter slate-react test:vitest -- generic-react-editor-contract surface-contract with-react-contract
bun --filter slate typecheck
bun --filter slate-history typecheck
bun --filter slate-dom typecheck
bun --filter slate-react typecheck
bun run bench:core:transaction:local
bun run bench:core:query-ref-observation:local
bun run bench:core:node-transforms:local
bun run bench:core:history-retained-memory:local
bun run bench:core:collab-readiness:local
bun run bench:react:rerender-breadth:local
REACT_HUGE_COMPARE_BLOCKS=5000 REACT_HUGE_COMPARE_ITERATIONS=5 REACT_HUGE_COMPARE_TYPE_OPS=10 bun run bench:react:huge-document:legacy-compare:local
PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/check-lists.test.ts playwright/integration/examples/editable-voids.test.ts playwright/integration/examples/markdown-shortcuts.test.ts playwright/integration/examples/inlines.test.ts --project=chromium
bun check

Additional contracts to add during Ralph:

Pass 6 decision:

Keep the architecture. Add performance guardrails and proof gates before code:

• no-handler transform/query paths must stay direct
• operation middleware needs an empty-path allocation fix
• state/tx group factories must stay cheap, with benchmark proof
• React must install once at creation, never per render
• TypeScript must infer inline extension arrays without teaching casts
• migration is hard-cut, not compatibility mode
• benchmark and browser proof are mandatory before ralph can call the implementation complete

Slate Maintainer Objection Ledger - Pass 7

Trigger:

The user caught the remaining half-cut: if public Editor.* is gone because editor-bound helpers should not live in static namespaces, then HistoryEditor.withoutSaving, DOMEditor.focus, and ReactEditor.* have the same smell. Keeping them would leave authors guessing which APIs live on editor, state, tx, editor.api, or a package namespace.

Evidence used:

• live HistoryEditor extends Editor with root history, undo, redo, and writeHistory in /Users/zbeyens/git/slate-v2/packages/slate-history/src/history-editor.ts:18.
• live HistoryEditor.withoutSaving, withMerging, withoutMerging, and withNewBatch are editor-bound helper methods in /Users/zbeyens/git/slate-v2/packages/slate-history/src/history-editor.ts:88.
• live withHistory calls HistoryEditor.withoutSaving while mutating the editor root in /Users/zbeyens/git/slate-v2/packages/slate-history/src/with-history.ts:25 and /Users/zbeyens/git/slate-v2/packages/slate-history/src/with-history.ts:42.
• live withDOM still assigns e.dom = createDOMEditorCapability(e) in /Users/zbeyens/git/slate-v2/packages/slate-dom/src/plugin/with-dom.ts:67.
• live DOMEditor is a public editor-bound helper namespace in /Users/zbeyens/git/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:603.
• live ReactEditor aliases DOMEditor in /Users/zbeyens/git/slate-v2/packages/slate-react/src/plugin/react-editor.ts:1.
• live core already has an extension registry with capabilities, stateGroups, txGroups, and editorGroups in /Users/zbeyens/git/slate-v2/packages/slate/src/core/extension-registry.ts:31.

API namespace law:

• Keep pure data/value helper namespaces: NodeApi, ElementApi, TextApi, PathApi, PointApi, RangeApi, OperationApi.
• Cut public editor-bound static namespaces: Editor, HistoryEditor, DOMEditor, ReactEditor, and future YjsEditor.
• If an API needs a mounted editor instance, it belongs either inside editor.read, inside editor.update, or under an installed handle at editor.api.<name>.
• Internal package implementation can keep private helper objects, but public docs, examples, and exports should not teach editor-bound static namespaces.

Revised public shape:

const editor = useSlateEditor({
  initialValue,
  extensions: [history(), react(), checklist()],
});

editor.read((state) => state.history.canUndo());

editor.update((tx) => {
  tx.history.undo();
});

editor.api.history.withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

editor.api.dom.focus();
editor.api.dom.resolvePath(element);
editor.api.clipboard.insertData(data);

editor.getApi(history).withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

Steelman ledger:

Accepted revisions from pass 7:

• Public editor-bound helper namespaces are cut: no public HistoryEditor, DOMEditor, ReactEditor, or future YjsEditor.
• editor.api becomes the stable typed installed-extension handle map.
• editor.getApi(extensionToken) becomes the stable typed generic accessor for extension-aware code.
• history() exposes replayable state.history and tx.history, plus editor-bound helpers such as editor.api.history.withoutSaving.
• dom() / react() expose mounted runtime handles such as editor.api.dom.focus() and editor.api.dom.resolvePath(...).
• dom() may expose multiple capability handles, including top-level editor.api.clipboard; do not nest clipboard under editor.api.dom.
• Pure data/value namespaces keep *Api naming.
• Public surface tests must assert the hard cut for HistoryEditor, DOMEditor, and ReactEditor, not only with* wrappers.

Pass 7 decision:

Revise the plan. The earlier package-helper target was not the absolute-best DX. It was a compromise. The stronger architecture has one public location for editor-bound extension APIs: editor.api.<name>. That gives Slate users a simple mental model:

• plain data helpers: NodeApi, PathApi, RangeApi
• editor core: editor.read, editor.update, editor.subscribe
• installed editor-bound APIs: editor.api.history, editor.api.dom, editor.api.react
• generic installed API access: editor.getApi(history), editor.getApi(dom), editor.getApi(clipboard), editor.getApi(EditableVoidExtension)
• replayable extension read/write code: state.history, tx.history

Confidence Score - Pass 7

Weighted score: 0.91.

The score improves, but it still cannot close. High-risk pre-mortem, ecosystem maintainer pass, revision, issue/reference sync, and final gates are still pending.

High-Risk Deliberate Pass - Pass 8

Trigger:

This plan hard-cuts public editor wrappers and editor-bound helper namespaces while adding one stable typed editor.api handle map. That touches public API, package boundaries, React/DOM runtime behavior, history semantics, examples, type inference, performance gates, and third-party migration.

Blast radius:

Three-scenario pre-mortem:

Expanded proof plan:

Rollback and remediation answer:

No compatibility aliases. If implementation finds editor.api is too broad, narrow it; do not fall back to public HistoryEditor / DOMEditor / ReactEditor. If installed-handle typing fails, fix the extension tuple and phantom-type design before migrating examples. If DOM mounted state is not stable enough, split the internal mount lifecycle, but keep the public handle shape. If performance data regresses, fix no-handler and group materialization costs before shipping the public API.

Accepted refinements from pass 8:

• editor.api is a sealed, read-only installed-handle map, not a second plugin registry.
• Do not duplicate replayable history APIs on editor.api.history in the first pass. Reads stay in state.history; undo/redo stay in tx.history.
• editor.api.history is for ambient history controls such as withoutSaving, withMerging, withoutMerging, and withNewBatch.
• DOM/React handles may expose mounted runtime APIs because those APIs are not replayable model reads or transaction writes.
• Public-surface gates must fail on static editor-bound namespaces and wrapper exports, not only on root editor fields.

Pass 8 verdict:

Keep the plan with the refinements above. The scary part is real: without a hard rule, editor.api can turn into root growth with better branding. The rule is simple enough to ship:

• state for replayable reads
• tx for replayable writes/actions
• editor.api for installed runtime/control handles
• *Api only for pure data/value helpers

Confidence Score - Pass 8

Weighted score: 0.91.

The score does not close the lane. Ecosystem maintainer pass, revision, issue/reference sync, and final gates are still pending.

Ecosystem Maintainer Pass - Pass 9

Trigger:

Pass 8 made editor.api the public installed-handle map. This pass asks whether Lexical, ProseMirror, Tiptap, Plate, or slate-yjs prove that shape is wrong, too broad, or missing an architectural boundary.

Fresh evidence used:

• Lexical extension types define unique names, conflicts, dependencies, peer dependencies, config merge, lifecycle, and output typing in /Users/zbeyens/git/lexical/packages/lexical/src/extension-core/types.ts:164.
• Lexical React requires a stable extension argument and builds the editor from React provider, React extension config, and user extension in /Users/zbeyens/git/lexical/packages/lexical-react/src/LexicalExtensionComposer.tsx:36 and /Users/zbeyens/git/lexical/packages/lexical-react/src/LexicalExtensionComposer.tsx:89.
• ProseMirror EditorState is persistent, plugin-owned, and transaction-applied in /Users/zbeyens/git/prosemirror-state/src/state.ts:83.
• ProseMirror plugins can define state fields and view objects in /Users/zbeyens/git/prosemirror-state/src/plugin.ts:7.
• ProseMirror EditorView owns DOM, focus, input, DOM observer, doc view, and plugin views in /Users/zbeyens/git/prosemirror-view/src/index.ts:27.
• Tiptap Editor owns options.extensions, root commands, chain/can, storage, mounted view, and lifecycle callbacks in /Users/zbeyens/git/tiptap/packages/core/src/Editor.ts:85.
• Tiptap ExtensionManager collects commands from extensions with editor, options, storage, and schema type context in /Users/zbeyens/git/tiptap/packages/core/src/ExtensionManager.ts:27.
• Plate maps plugin generics into keyed plugins, api, tf, and transforms in /Users/zbeyens/git/plate/packages/core/src/lib/editor/SlateEditor.ts:186 and creates TSlateEditor<V, InferPlugins<P[]>> in /Users/zbeyens/git/plate/packages/core/src/lib/editor/withSlate.ts:215.
• slate-yjs currently mutates root collaboration fields and exposes YjsEditor helpers in /Users/zbeyens/git/slate-yjs/packages/core/src/plugins/withYjs.ts:29 and /Users/zbeyens/git/slate-yjs/packages/core/src/plugins/withYjs.ts:156.

Ecosystem verdict table:

Architecture result:

Keep the pass-8 model unchanged, with one clarification:

• editor.api.<name> is Slate's installed-output handle map.
• It is not Tiptap storage, Plate plugins, or a public capability registry.
• Handles are allowed only for installed runtime/control APIs that cannot live as replayable state or tx groups.
• Extension lifecycle, dependency, conflict, and cleanup rules should be closer to Lexical than to wrapper mutation.
• DOM/React handle lifecycle should steal ProseMirror's view discipline: mounted state must be owned, updated, and destroyed explicitly.
• Collaboration should steal ProseMirror/Lexical transaction discipline, not slate-yjs root mutation.

Rejected ecosystem alternatives:

Pass 9 verdict:

Keep the plan. The external systems sharpen the boundaries but do not beat the pass-8 shape. The best Slate v2 architecture remains:

• creation-time extensions
• state for replayable reads
• tx for replayable writes/actions
• editor.api for installed runtime/control handles
• *Api only for pure data/value helpers
• Plate owns product plugin facade APIs

Confidence Score - Pass 9

Weighted score: 0.92.

The score still cannot close. Revision, issue/reference sync, and final gates remain.

Revision Pass - Pass 10

Trigger:

Passes 7, 8, and 9 changed the target from package helper namespaces to a sealed installed-handle map. This pass reconciles the older wording so Ralph does not implement a hybrid API by accident.

Consistency review result:

Final target API law:

const editor = useSlateEditor({
  initialValue,
  extensions: [history(), react(), checklist()],
});

editor.read((state) => state.history.redos());

editor.update((tx) => {
  tx.history.undo();
});

editor.api.history.withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

editor.getApi(history).withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

editor.api.dom.focus();
editor.api.dom.resolvePath(element);

Do not add:

editor.history;
editor.dom;
HistoryEditor.withoutSaving(editor, fn);
DOMEditor.focus(editor);
ReactEditor.focus(editor);
editor.api.history.undo();
editor.api.history.redos();

Final rule table:

Revision decisions:

• No new architecture change.
• No new issue claim.
• No ledger write in this pass; pass 11 owns issue/reference sync.
• Before pass 11, the PR reference still teaches the old withEditor rationale and wrapper-composition framing.
• The final Ralph handoff must implement public-surface tests before removing code so stale exports fail loudly.

Confidence Score - Pass 10

Weighted score: 0.93.

The score still cannot close. Issue/reference sync and final gates remain.

Issue Reference Sync Pass - Pass 11

Trigger:

Pass 10 settled the final API law, but the maintainer-facing PR reference and related issue rows still contained accepted wording for withEditor, withDOM / withReact options, editor.dom, and DOMEditor.findPath.

Read set:

• docs/slate-v2/references/pr-description.md
• docs/slate-v2/ledgers/issue-coverage-matrix.md
• docs/slate-issues/gitcrawl-v2-sync-ledger.md
• docs/slate-v2/ledgers/fork-issue-dossier.md

Sync result:

Claim policy:

• New fixed issue claims: 0.
• New improved issue claims: 0.
• Existing fixed/improved rows stay unchanged. This pass only aligns reference wording and related-row proof targets with the accepted architecture.

Not changed:

• Historical current-state evidence and rejected examples in this plan still name withHistory, withEditor, HistoryEditor, DOMEditor, ReactEditor, editor.dom, and editor.extend where those names are evidence of the current problem or explicit rejected API.
• Existing issue rows that quote upstream issue titles or legacy reports keep enough legacy wording to remain searchable, but their v2 proof target is no longer a public helper namespace.

Open:

• Closure score and final gates remain pending. Pass 11 cannot set top-level done; one activation may complete only this scheduled pass.

Confidence Score - Pass 11

Weighted score: 0.94.

The score still cannot close. The closure score and final gates are a separate pass.

Closure Score And Final Gates - Pass 12

Eligibility:

• Rows 1 through 11 were already recorded as complete before this closure activation started.
• Pass 11 left top-level status pending and named closure-score-and-final-gates as the next pass.

Closure checks:

Final closure score:

Weighted score: 0.94.

Closure verdict:

Done for Slate Ralplan planning. This plan is ready for a later Ralph execution handoff. It does not claim implementation is done.

Post-Closure API Naming Refinement - 2026-05-17

User decision:

Use editor.api.<name> for installed runtime/control handles instead of editor.extensions.<name>.

Accepted refinement:

editor.read((state) => state.history.redos());

editor.update((tx) => {
  tx.history.undo();
});

editor.api.history.withoutSaving(() => {
  editor.update((tx) => {
    tx.nodes.set({ type: "paragraph" });
  });
});

editor.api.dom.focus();
editor.api.dom.findPath(element);

Hard rule:

• editor.api.history.undo() is rejected.
• editor.api.history.redos() is rejected.
• Replayable reads stay in editor.read.
• Replayable writes/actions stay in editor.update.
• editor.api is only for installed runtime/control APIs and ambient wrappers around future updates.

Why:

editor.api.history.withoutSaving is better author DX than editor.extensions.history.withoutSaving, but duplicating undo / redo in both editor.api and tx would recreate the same "where does this method live?" problem this plan is cutting. The final rule is:

• state = reads
• tx = mutations
• editor.api = installed runtime/control handles

Plate boundary:

Raw Slate using editor.api does not mean copying Plate's product plugin facade. Plate owns product plugins, product APIs, transforms, option stores, components, and rule families. Raw Slate editor.api is narrower: installed runtime/control handles inferred from the extensions list.

Issue Ledger Accounting - Pass 1

No fixed or improved issue claim is made in this pass.

Initial related pressure from ledgers:

Pass 2 ran bounded related-issue discovery from existing ledgers first. It did not broad-search GitHub.

Related Issue Discovery - Pass 2

Read set:

• generated live open rows in docs/slate-issues/gitcrawl-live-open-ledger.md
• manual current classifications in docs/slate-issues/gitcrawl-v2-sync-ledger.md
• fixed/related claims in docs/slate-v2/ledgers/issue-coverage-matrix.md
• fork issue notes in docs/slate-v2/ledgers/fork-issue-dossier.md
• stale accepted API text in docs/slate-v2/references/pr-description.md
• issue theme and package pressure in docs/slate-issues/issue-clusters.md, docs/slate-issues/package-impact-matrix.md, and docs/slate-issues/requirements-from-issues.md

Discovery verdict:

No new fixed or improved issue claim belongs to this pass. The unified extension architecture is related pressure plus a must-preserve constraint for existing proofs. The next pass should do the full row-by-row issue-ledger accounting and update ledgers only where a classification, claim, proof owner, or stale accepted-API reference actually changes.

Ledger write decision:

• No gitcrawl-v2-sync-ledger.md classification changes in pass 2.
• No fork-issue-dossier.md section needed in pass 2 because no issue claim was promoted, demoted, or newly reviewed as an exact issue.
• issue-coverage-matrix.md should be updated in the issue-ledger pass only if the final plan changes proof owners or claim wording.
• docs/slate-v2/references/pr-description.md is stale: it still presents useSlateEditor({ initialValue, withEditor }) and says withEditor mirrors withReact / withHistory. Reference sync must invalidate that text after this plan's final architecture is accepted.

Issue-Ledger Pass - Pass 3

Pass result:

The ledger now has an explicit accounting path for unified extension composition. This pass still makes no fixed issue claim and no improved issue claim. It does update the current manual sync and coverage ledgers where the planning owner changed.

Changed ledger artifacts:

• docs/slate-issues/gitcrawl-v2-sync-ledger.md
• docs/slate-v2/ledgers/issue-coverage-matrix.md
• docs/slate-v2/ledgers/fork-issue-dossier.md

Unchanged in this pass:

• docs/slate-issues/gitcrawl-live-open-ledger.md because it is generated live input only.
• docs/slate-issues/open-issues-ledger.md because current manual sync is owned by gitcrawl-v2-sync-ledger.md.
• docs/slate-v2/references/pr-description.md because reference narrative sync is pass 11 and the architecture plan is still under review.

Reference-sync decision:

docs/slate-v2/references/pr-description.md still contained obsolete withEditor / wrapper-composition accepted shape during pass 3. Do not edit it in pass 3. Pass 11 rewrites it after the intervening review passes keep the API target.

Intent Boundary And Decision Brief Challenge - Pass 4

Trigger:

The user challenged the previous target: editor.history.undo() contradicts the principle that extensions should not extend the editor root type. The same challenge applies to migrating editor.history.redos; history needs state extension coverage, not only methods. The follow-up DOM challenge tightened the boundary again: editor.read and editor.update are for coherent editor/model work, not mounted browser APIs.

Evidence used:

• live editor root currently exposes read, subscribe, update, and public extend in /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:501.
• live extension substrate already supports state, tx, and editor groups in /Users/zbeyens/git/slate-v2/packages/slate/src/interfaces/editor.ts:1205.
• live public-state code materializes extension stateGroups onto read views and txGroups onto update transactions in /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1371 and /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1485.
• live editor-group registration mutates the editor root in /Users/zbeyens/git/slate-v2/packages/slate/src/core/extension-registry.ts:327.
• live history wrapper currently mutates root fields history, undo, redo, and writeHistory in /Users/zbeyens/git/slate-v2/packages/slate-history/src/with-history.ts:25.
• live DOM wrapper currently mutates root field dom in /Users/zbeyens/git/slate-v2/packages/slate-dom/src/plugin/with-dom.ts:55.
• live DOM package already has a helper namespace and capability factory in /Users/zbeyens/git/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:603 and /Users/zbeyens/git/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts:1726.
• live extension registry already has a capabilities map and registerCapability in /Users/zbeyens/git/slate-v2/packages/slate/src/core/extension-registry.ts:32 and /Users/zbeyens/git/slate-v2/packages/slate/src/core/extension-registry.ts:169.
• live public-state update transaction has replay guardrails in /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:130 and /Users/zbeyens/git/slate-v2/packages/slate/src/core/public-state.ts:1433.

Pressure test:

The weak assumption was that editor.history.undo() is acceptable because it is namespaced. It is not. It still extends the editor root. If the architecture principle is "the editor root stays stable and small", then root namespaces are only a softer version of the same problem. A second weak assumption was that DOM can simply move to state.dom / tx.dom. It cannot. DOM projection and focus depend on mounted browser state, so those APIs need capabilities, not replayable state/transaction groups.

Revised intent/boundary record:

Decision changes:

Updated API shape:

const editor = useSlateEditor({
  extensions: [history(), react(), editableVoid()],
  initialValue,
});

editor.read((state) => state.history.canUndo());
editor.read((state) => state.history.redos());

editor.update((tx) => {
  tx.history.undo();
});

editor.api.dom.resolvePath(element);
editor.api.dom.focus();
editor.getApi(history).withoutSaving(() => {
  editor.update((tx) => tx.text.insert("x"));
});

No HistoryEditor.*, DOMEditor.*, or ReactEditor.* public app DX. If it is editor-bound, it belongs to the installed extension handle.

Pass verdict:

The architecture is stronger after this correction. Creation-time extensions stays the best public model, but the earlier editor.history.* target was a leak from the old wrapper mental model. The absolute-best shape is now:

• root editor: stable core methods only
• extension install: creation-time extensions
• replayable extension reads: state.<group>
• replayable extension writes/actions: tx.<group>
• mounted/environment capabilities: editor.api.<name> installed handles
• generic runtime/control access: editor.getApi(extensionToken)
• editor-bound helpers: installed handles, no public static helper namespaces
• naming: lowercase extension factories

Remaining ambiguity:

None that needs a user question. The later ecosystem pass can still challenge factory capitalization or whether the typed getApi accessor is too much surface, but pass 7 sets the default to lowercase factories plus installed extension handles.

Applicable Review Lenses

Maintainer Objection Seed Ledger

Implementation Phases For Ralph

1. Add extensions to createEditor and install through the existing internal extension registry before state is exposed.
2. Add typed extension-list inference for replayable state/tx groups and installed editor.api handles plus editor.getApi(extensionToken).
3. Convert withHistory to history() extension, moving stack reads to state.history, undo/redo writes to tx.history, and ambient history controls to editor.api.history.
4. Convert withDOM to dom() extension that registers editor.api.dom.
5. Convert withReact to react() extension and add createReactEditor; expose React-bound runtime helpers through editor.api.react.
6. Replace useSlateEditor({ withEditor }) with useSlateEditor({ extensions }).
7. Migrate examples from wrapper functions to lower camel-case extension factories/values.
8. Update public exports and public-surface tests, including hard removal of HistoryEditor, DOMEditor, and ReactEditor from app-facing exports.
9. Update docs and PR reference to current API only, no migration-story wording.
10. Run focused package tests, browser rows, typecheck, lint, and bun check from .tmp/slate-v2.

Fast Driver Gates

Planning-only gates:

# cwd: /Users/zbeyens/git/plate-2
pnpm lint:fix

Implementation gates for Ralph:

# cwd: /Users/zbeyens/git/slate-v2
bun test ./packages/slate/test/public-surface-contract.ts
bun test ./packages/slate/test/generic-extension-namespace-contract.ts
bun test ./packages/slate/test/extension-methods-contract.ts
bun test ./packages/slate/test/query-extension-contract.ts
bun test ./packages/slate/test/normalization-contract.ts
bun --filter slate-history test
bun --filter slate-dom test
bun --filter slate-react test:vitest -- provider-hooks-contract generic-react-editor-contract surface-contract with-react-contract
bun --filter slate typecheck
bun --filter slate-history typecheck
bun --filter slate-dom typecheck
bun --filter slate-react typecheck
bun lint:fix
PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/check-lists.test.ts playwright/integration/examples/editable-voids.test.ts playwright/integration/examples/markdown-shortcuts.test.ts playwright/integration/examples/inlines.test.ts --project=chromium
bun check

Confidence Score - Pass 1

Weighted score: 0.85.

Score is intentionally below closure threshold. The direction is strong, but issue discovery, objection, high-risk, performance, revision, reference sync, and closure passes are still pending.

Confidence Score - Pass 5

Weighted score: 0.87.

Score improves because the ecosystem evidence is now current and concrete. It still cannot close because performance, objection, high-risk, revision, reference sync, and final gates are pending.

Confidence Score - Pass 6

Weighted score: 0.89.

The score improves, but it still cannot close. Maintainer objections, high-risk pre-mortem, final ecosystem pass, revision, reference sync, and final gates are still pending.

Pass-State Ledger

Plan Deltas From Review

• Created this plan for the with* versus editor.extend architecture review.
• Rejected the current wrapper-composition story as final DX.
• Chose creation-time extensions as the single public extension model.
• Chose extension-list type inference over T & HistoryEditor<ValueOf<T>>.
• Kept Plate boundary: raw Slate uses extensions and state / tx; Plate keeps plugins and product APIs.
• Recorded that docs/slate-v2/references/pr-description.md had stale withEditor rationale; pass 11 revised it.
• Added ledger ownership for unified extension composition through #3802 and updated #3177 / #3557 related rows without promoting any issue claim.
• Pass 4 removed editor.history.* from the target and put history reads under state.history and history actions under tx.history.
• Pass 4 rejected editor.state.redos, editor.dom, state.dom, and tx.dom.
• Pass 4 added the capability lane: dom() / react() install mounted capabilities.
• Pass 5 validated the capability lane against Lexical, ProseMirror, Tiptap, Plate, slate-yjs, and live Slate DOM/React helpers.
• Pass 5 kept history(), dom(), and react() as the best common-call-site names despite Lexical's PascalCase extension constants.
• Pass 5 rejects string/raw capability access, but the post-closure refinement accepts typed editor.getApi(extensionToken) for generic code.
• Pass 6 kept the architecture under performance pressure but added mandatory guardrails: preserve transform/query no-handler fast paths, add operation middleware empty-path allocation fix, benchmark extension overhead, keep React creation stable, and hard-cut wrapper exports with type/browser proof.
• Pass 7 hard-cut public HistoryEditor, DOMEditor, and ReactEditor with Editor; only pure data/value helper namespaces keep *Api names.
• Pass 7 added editor.api.<name> as the stable installed-handle map for editor-bound extension APIs such as editor.api.history.withoutSaving and editor.api.dom.focus.
• Pass 7 added editor.getApi(extensionToken) as the Plate-like typed accessor for generic code while keeping direct app code on editor.api.<name>.
• Pass 8 kept editor.api but sealed it as installed runtime/control handles only. Replayable history reads stay in state.history; undo/redo stay in tx.history; editor.api.history is limited to ambient controls such as withoutSaving, withMerging, withoutMerging, and withNewBatch in the first pass.
• Pass 9 re-checked Lexical, ProseMirror, Tiptap, Plate, and slate-yjs against the pass-8 target and kept the model. The pass rejected a separate public view object, Tiptap root commands/storage, Plate plugin API copy, public YjsEditor, and PascalCase built-in factories.
• Pass 10 consolidated the target into one final API law: pure data helpers use *Api; replayable reads use state; replayable writes/actions use tx; installed runtime/control APIs use editor.api; product facade APIs stay in Plate.
• Pass 10 clarified that editor.api.history does not duplicate undo/redo or stack reads in the first pass.
• Pass 11 synced PR and issue-reference wording to the final API law, including useSlateEditor({ extensions }), editor.api.dom, and no public editor-bound helper namespaces. No issue claim changed.
• Pass 12 verified closure gates and moved the planning lane to done without claiming implementation completion.
• Post-closure naming refinement made factory-first examples the primary DX: built-ins and custom factories use lower camel-case; NameExtension is only for static extension values; Plate's NamePlugin suffix stays in Plate.
• Post-closure type refinement requires negative tests for uninstalled typed APIs, string getApi, fresh-instance getApi, duplicated history APIs, and examples falling back to CustomEditor intersections.

Open Questions That Can Still Change Details

• Exact factory names are closed for the plan: built-ins stay history(), dom(), and react(); custom factories follow lower camel-case such as editableVoid(), checklist(), mention(), and table(). Plural names are reserved for naturally plural domains such as shortcuts() or normalizers(). PascalCase NameExtension is reserved for static extension values.
• Whether createReactEditor is necessary beside useSlateEditor. This pass includes it because tests and non-hook setup need a direct constructor.
• Whether raw Slate should expose read-only installed-extension metadata. This pass says no public registry until a concrete author use exists.
• Public string/raw capability access is rejected for the plan. Typed editor.api.<name> handles are the direct public surface, and editor.getApi(extensionToken) is the generic public accessor.

Done Handoff

Status: complete for Slate Ralplan planning.

Implementation status: not started by this skill. A later Ralph pass should execute the plan in .tmp/slate-v2.

Ralph Execution Start - 2026-05-17

Status: pending for implementation.

Ralph generated the scoped continuation prompt at active goal state and moved the scoped completion state back to pending for execution.

Current pass:

• current_pass: tdd-pass
• current_pass_status: in_progress
• current_pass_owner: .tmp/slate-v2/packages/slate
• current_pass_scope: creation-time extension installation and typed installed API contracts

Initial tracer evidence:

• Live .tmp/slate-v2 still exposes withHistory, HistoryEditor, withDOM, withReact, useSlateEditor({ withEditor }), public editor.extend, and wrapper-based tests/examples.
• Existing useful test owners include .tmp/slate-v2/packages/slate/test/generic-extension-namespace-contract.ts, .tmp/slate-v2/packages/slate/test/extension-methods-contract.ts, .tmp/slate-v2/packages/slate/test/tsconfig.generic-types.json, .tmp/slate-v2/packages/slate-history/test/generic-history-contract.ts, and .tmp/slate-v2/packages/slate-react/test/generic-react-editor-contract.tsx.

First red target:

• Add .tmp/slate-v2/packages/slate/test/generic-extension-install-contract.ts.
• Add that file to .tmp/slate-v2/packages/slate/test/tsconfig.generic-types.json.
• Run bun --filter slate typecheck from .tmp/slate-v2.
• Expected red: createEditor({ extensions }), editor.api, and editor.getApi(...) are not implemented yet.

Red result:

• Added .tmp/slate-v2/packages/slate/test/generic-extension-install-contract.ts.
• Added it to .tmp/slate-v2/packages/slate/test/tsconfig.generic-types.json.
• Ran bun --filter slate typecheck from .tmp/slate-v2.
• Failure is expected and points at the right owner:
  • CreateEditorOptions does not accept extensions.
  • Editor<CustomValue> does not expose api.
  • uninstalled state / tx negative tests are unused because current declaration-merged groups still leak without installed-extension inference.

Green result:

• Implemented createEditor({ extensions }) in .tmp/slate-v2/packages/slate.
• Added installed-extension inference for editor.read, editor.update, editor.api, and editor.getApi(extensionToken).
• Added runtime token identity for editor.getApi(extensionToken) so a fresh extension object with the same name/capability is rejected.
• Added a curried typed-authoring form, defineEditorExtension<Editor<CustomValue>>()({...}), for value-specific extension definitions without erasing literal installed group keys.

Ralph React Extension Slice - 2026-05-17

Status: complete for the focused React package slice; implementation remains pending for examples/docs/browser/final gates.

Red result:

• Replaced .tmp/slate-v2/packages/slate-react/test/generic-react-editor-contract.tsx with the hard-cut target: react(), createReactEditor(), useSlateEditor({ extensions }), editor.api.react, editor.api.dom, editor.api.clipboard, and negative tests for public ReactEditor, public withReact, and withEditor.
• Ran bun x tsc --project packages/slate-react/test/tsconfig.generic-types.json --noEmit from .tmp/slate-v2.
• Failure was expected: slate-react exported no react() or createReactEditor(), stale withReact imports still existed, and useSlateEditor still accepted withEditor.

Green result:

• Implemented react() as the creation-time Slate React extension.
• Added createReactEditor({ extensions }) and rewired useSlateEditor({ extensions }) through it.
• Cut public root exports for withReact and ReactEditor.
• Exposed installed runtime handles through editor.api.react, editor.api.dom, and editor.api.clipboard.
• Replaced runtime editor.dom / editor.dom.clipboard calls in slate-react with editor.api.dom / editor.api.clipboard.
• Updated editor.getApi(extensionToken) so multi-capability extensions return the capability whose key matches the extension name.
• Migrated focused React provider/surface tests from wrapper construction to createReactEditor().

Verification:

• bun --filter slate-react typecheck: passed.
• bun --filter slate typecheck: passed.
• bun --filter slate-dom typecheck: passed.
• bun --filter slate-react test:vitest -- provider-hooks-contract surface-contract: 45 pass, 0 fail.
• bun test ./packages/slate-react/test/with-react-contract.tsx: 1 pass, 0 fail.
• bun lint:fix: passed and fixed 10 files; the focused type/test gates were rerun after lint and stayed green.

Next owner:

• Migrate first-party examples and docs from withEditor, local with* wrappers, public ReactEditor types, and editor.dom to extension factories plus installed editor.api.* handles.
• Updated the focused generic extension contracts to install extensions at editor creation time instead of relying on dynamic editor.extend typing.
• Updated the public editor method contract to include the planned getApi accessor.

Green verification:

• bun --filter slate typecheck from .tmp/slate-v2: passed.
• bun test ./packages/slate/test/public-surface-contract.ts ./packages/slate/test/generic-extension-namespace-contract.ts ./packages/slate/test/extension-methods-contract.ts ./packages/slate/test/query-extension-contract.ts ./packages/slate/test/normalization-contract.ts from .tmp/slate-v2: 390 pass, 0 fail.
• bun lint:fix from .tmp/slate-v2: passed.
• Reran bun --filter slate typecheck from .tmp/slate-v2 after lint: passed.
• Reran the focused core contract tests after lint: 390 pass, 0 fail.

History slice result:

• Replaced the history generic type contract with the final API shape: history(), state.history, tx.history, editor.api.history, and editor.getApi(HistoryExtension).
• Implemented .tmp/slate-v2/packages/slate-history/src/history-extension.ts.
• Exported history() from slate-history.
• Removed stale withHistory and HistoryEditor source files from .tmp/slate-v2/packages/slate-history/src.
• Migrated focused history tests away from editor-root history fields and root undo/redo methods.
• Updated core installed-group extraction so declared state/tx groups resolve with the installed editor value type, keeping history() generic-free at call sites.

History verification:

• bun x tsc --project packages/slate-history/test/tsconfig.generic-types.json --noEmit from .tmp/slate-v2: failed red, then passed after implementation.
• bun --filter slate-history typecheck from .tmp/slate-v2: passed.
• bun test ./packages/slate-history/test/history-contract.ts ./packages/slate-history/test/integrity-contract.ts ./packages/slate-history/test/index.spec.ts from .tmp/slate-v2: 50 pass, 1 skip, 0 fail.
• bun --filter slate typecheck from .tmp/slate-v2: passed after core type-helper changes.
• bun lint:fix from .tmp/slate-v2: passed.
• Reran focused history type/runtime gates after lint: passed.
• rg -n "withHistory|HistoryEditor" packages/slate-history/src packages/slate-history/test/generic-history-contract.ts packages/slate-history/test/history-contract.ts packages/slate-history/test/integrity-contract.ts packages/slate-history/test/index.spec.ts from .tmp/slate-v2: no matches.

DOM slice result:

• Added a DOM generic type contract for dom(), editor.api.dom, and editor.api.clipboard.
• Implemented dom() in .tmp/slate-v2/packages/slate-dom.
• Removed withDOM from the public slate-dom root.
• Split clipboard into a sibling capability, not editor.api.dom.clipboard.
• Migrated focused DOM/clipboard tests to createEditor({ extensions: [dom()] }) and editor.api.dom / editor.api.clipboard.
• Renamed the internal bridge installer to installDOM; withDOM is no longer present in slate-dom source except the public-surface negative assertion.

DOM verification:

• bun x tsc --project packages/slate-dom/test/tsconfig.generic-types.json --noEmit from .tmp/slate-v2: failed red, then passed after implementation.
• bun --filter slate-dom typecheck from .tmp/slate-v2: passed.
• bun --filter slate typecheck from .tmp/slate-v2: passed after DOM changes.
• bun test from .tmp/slate-v2/packages/slate-dom: 71 pass, 0 fail.
• bun lint:fix from .tmp/slate-v2: passed.
• Reran focused DOM type/runtime gates after lint and internal rename: passed.

Next implementation owner:

• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts
• .tmp/slate-v2/packages/slate/src/create-editor.ts
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts
• .tmp/slate-v2/packages/slate/src/core/extension-registry.ts

Final target:

• creation-time extensions
• built-ins as history(), dom(), and react()
• custom factories as lower camel-case, with NameExtension reserved for static extension values
• replayable reads under state
• replayable writes/actions under tx
• installed runtime/control handles under editor.api
• generic installed API access through editor.getApi(extensionToken), not strings or freshly created extension instances
• no public with* wrappers, withEditor, author-facing editor.extend, HistoryEditor, DOMEditor, ReactEditor, or future editor-bound *Editor app DX
• pure data/value helper namespaces keep *Api

Required Ralph proof:

• public-surface contract fails on stale wrappers and editor-bound helper namespaces
• type contracts prove extension-list inference and installed-handle typing
• negative type contracts cover missing editor.api.*, missing editor.getApi(extensionToken), editor.getApi('history'), editor.getApi(history()), editor.api.history.undo, editor.getApi(history).undo, and fallback CustomEditor intersections
• history contracts prove state.history, tx.history, and editor.api.history control helpers
• DOM/React contracts prove installed handles and lifecycle cleanup
• examples/docs teach extension values, not wrapper functions
• browser rows cover touched React/DOM examples
• benchmarks cover zero/one/many extension overhead and no-handler fast paths
• broad .tmp/slate-v2 gate runs before any implementation release claim