Slate v2 editable capabilities DX ralplan

Date: 2026-05-17 Status: done Owner: Slate Ralplan planning only Execution owner: ralph in .tmp/slate-v2 Completion id: 019e1fc0-dba0-7de1-9236-b484a144cda6 Score: 0.93, closed for Ralph execution

Verdict

capabilities comes from the core extension registry. It was introduced as a generic runtime bucket for extension-provided mounted handles/providers, and it also feeds typed editor.api.* installed handles.

That architecture is valid internally. It is not acceptable as first-party app authoring DX.

Hard answer:

• Keep internal capabilities as the substrate.
• Remove editableKeyCommands(...) as public example/documentation DX.
• Do not remove extension-owned keyboard behavior.
• Do not regress back to raw <Editable onKeyDown> for reusable editor behavior.
• Replace public capability-spread authoring with typed package facets on the same defineEditorExtension(...) object.
• Tighten generic installed handles toward public api authoring and internal provider storage. Public examples should not write capabilities.

The bad part is not only editableKeyCommands. The public shape:

capabilities: {
  ...editableRenderers(...),
  ...editableKeyCommands(...),
  'clipboard.insertData': handler,
}

is registry plumbing exposed as product syntax. That is why the example needs:

const iframeEditor = editor as unknown as CustomEditor;

That cast is the DX failure in one line.

Current source

Why the current API happened

The previous architecture direction correctly separated:

• replayable model reads/writes: editor.read((state) => ...) and editor.update((tx) => ...)
• mounted/browser/runtime handles: editor.api.<name>
• extension installation: extensions: [...]

The unified extension plan already says mounted DOM/React APIs belong to installed capabilities rather than state / tx or editor root namespaces (docs/plans/2026-05-16-slate-v2-unified-extension-composition-ralplan.md:515-545).

The implementation took that correct substrate and exposed it too directly in examples. Public examples should teach editor features, not registry records.

Absolute-best target

Keep one extension declaration. Do not make app authors choose between defineEditorExtension, defineEditableExtension, raw <Editable> props, and capability helper spreads.

Target first-party authoring shape:

const iframe = () =>
  defineEditorExtension<CustomEditor>()({
    name: "iframe",
    editable: {
      renderers: {
        elements: {
          paragraph: ParagraphElement,
        },
        leaves: {
          bold: BoldLeaf,
          code: CodeLeaf,
          italic: ItalicLeaf,
          underline: UnderlineLeaf,
        },
      },
      keymap: {
        "mod+b": { kind: "toggle-mark", mark: "bold" },
        "mod+i": { kind: "toggle-mark", mark: "italic" },
        "mod+u": { kind: "toggle-mark", mark: "underline" },
        "mod+`": { kind: "toggle-mark", mark: "code" },
      },
      onCommand(command, { editor }) {
        if (command.kind !== "toggle-mark") return;

        toggleMark(editor, command.mark);
        return true;
      },
    },
  });

Target image-style shape:

const image = () =>
  defineEditorExtension<CustomEditor>()({
    name: "image",
    elements: [{ type: "image", void: "editable-island" }],
    editable: {
      keymap: {
        "mod+a": { kind: "select-all" },
      },
      renderers: {
        elements: {
          paragraph: Paragraph,
        },
        voids: {
          image: ({ element }) => <Image element={element} />,
        },
      },
    },
    clipboard: {
      insertData(data, { editor, next }) {
        const text = data.getData("text/plain");
        const imageFiles = Array.from(data.files ?? []).filter((file) =>
          file.type.startsWith("image/"),
        );

        if (imageFiles.length === 0 && !isImageUrl(text)) {
          return next();
        }

        editor.update((tx) => {
          // app-specific insert logic
        });

        return true;
      },
    },
  });

Raw escape hatch remains available, but it stops being the first-party feature path:

<Editable
  onKeyDown={(event, { editor }) => {
    // UI-only or truly custom browser behavior.
  }}
/>

Public architecture change

Replace public generic capability authoring with typed extension facets.

Core type target:

export interface EditorExtensionFacets<
  TEditor extends BaseEditor<any> = Editor,
> {}

export type EditorExtension<
  TEditor extends BaseEditor<any> = Editor,
  TOptions = unknown,
> = EditorExtensionCore<TEditor, TOptions> & EditorExtensionFacets<TEditor>;

slate-react augments the extension facets:

declare module "slate" {
  interface EditorExtensionFacets<TEditor extends BaseEditor<any>> {
    editable?: EditableExtensionFacet<TEditor>;
  }
}

slate-dom augments the extension facets:

declare module "slate" {
  interface EditorExtensionFacets<TEditor extends BaseEditor<any>> {
    clipboard?: ClipboardExtensionFacet<TEditor>;
  }
}

The runtime may still compile these facets into internal capabilities. That is an implementation detail. Public authoring should not mention capability names or spread helpers.

Generic installed handles need the same cleanup. If an extension intentionally exposes editor.api.<name>, the public authoring word should be api, not capabilities:

const dom = () =>
  defineEditorExtension({
    name: "dom",
    api: {
      clipboard: (context) => createClipboardApi(context),
      dom: (context) => createDomApi(context),
    },
  });

Internal ordered provider lists may still use the registry machinery, but they should not be the normal public app syntax. In other words:

• public reusable feature authoring: editable, clipboard, elements, transforms, state, tx
• public installed runtime handles: api, read as editor.api.<name>
• internal ordered provider storage: private registry, currently implemented by capabilities
• escape hatch for package authors: register(context) may return private provider output, but examples/docs should not teach raw string capability keys

Keyboard behavior target

Use three layers, in this order:

1. editable.keymap: hotkey-to-semantic-command mapping for reusable editor behavior.
2. editable.onCommand: semantic behavior execution for commands that raw Slate cannot default safely, such as custom marks or custom blocks.
3. editable.onKeyDown: last-resort extension escape hatch for browser/UI quirks that cannot be represented as an editable command.

This preserves the good intent from the current implementation: feature-owned behavior should live with the extension, not in scattered <Editable onKeyDown> props.

It also removes the bad part: event-callback registry helpers with weak editor typing.

Rejected alternatives

Maintainer Objection Pass

Pass status: complete.

Maintainer verdict:

The best shape survives, with one tightening: do not leave capabilities as the normal public word. The final target is:

defineEditorExtension<CustomEditor>()({
  name: "image",
  elements: [{ type: "image", void: "editable-island" }],
  editable: {
    keymap: {
      "mod+a": { kind: "select-all" },
    },
    renderers: {
      voids: {
        image: ImageElement,
      },
    },
  },
  clipboard: {
    insertData(data, { editor, next }) {
      // feature-owned paste behavior
    },
  },
});

Not:

defineEditorExtension({
  capabilities: {
    ...editableKeyCommands(...),
    ...editableRenderers(...),
    'clipboard.insertData': handler,
  },
})

And not:

<Editable onKeyDown={featureBehavior} />

unless the behavior is app-local UI or a real browser escape hatch.

Public surface cuts for Ralph

Hard cut these from first-party docs/examples:

• capabilities: { ...editableKeyCommands(...) }
• capabilities: editableRenderers(...)
• public import of EDITABLE_KEY_COMMAND_CAPABILITY
• public import of EDITABLE_RENDERERS_CAPABILITY
• public docs that teach capability key strings
• example casts from ReactEditor to CustomEditor

Do not necessarily delete the internal capability constants in the same first commit. The implementation can keep private registry names while the public surface moves to editable / clipboard facets.

Type contract

Ralph must add negative type proof:

• editable.onCommand receives the typed CustomEditor, not plain ReactEditor.
• editable.onKeyDown receives the typed CustomEditor, if used.
• editable.renderers.elements.paragraph receives only the paragraph element variant.
• invalid keymap mark keys fail for custom text types.
• invalid keymap block types fail for known custom element types when the command is block-specific.
• enabled: false extensions do not contribute editor.api or facet-derived types.
• raw capability string lookup remains non-public.

The key example test should assert the positive shape too:

defineEditorExtension<CustomEditor>()({
  name: "typed-hotkeys",
  editable: {
    keymap: {
      "mod+b": { kind: "toggle-mark", mark: "bold" },
    },
    onCommand(command, { editor }) {
      const custom: CustomEditor = editor;

      if (command.kind === "toggle-mark") {
        toggleMark(custom, command.mark);
        return true;
      }
    },
  },
});

Example rewrite target

Rewrite first-party examples away from public capability helpers:

Issue accounting

No fixed issue claim yet.

Related issue/accounting pass is complete:

• #3177 render/plugin composition: related. This plan strengthens the same feature-owned composition direction, but no fixed/improved claim until source, examples, type contracts, and docs land.
• #5961 onKeyDown render warning: not claimed. This is a stale repro row; do not claim runtime repair without a current failing route.
• #4613 clipboard customization: related only if the clipboard facet is executed. No claim in this planning pass.

Research position

External-editor mechanism to steal:

• ProseMirror: plugin props are aggregated internally; users do not write registry key strings.
• Lexical: keyboard behavior routes through commands rather than app-owned raw DOM event parsing for model behavior.
• Tiptap: feature authors define extension methods like keyboard shortcuts, commands, node views, and paste/input rules together.

Slate v2 should steal the mechanism, not the whole product API:

• keep raw Slate lower-level than Tiptap
• keep core slate React-free
• keep Editable raw props as escape hatches
• make feature-owned behavior live on the extension object
• hide registry storage from public examples

Related Issue And Research Sync Pass

Pass status: complete.

No fixed issue claim is added by this planning pass.

Issue sync:

Research sync:

Ledger sync performed:

• Added a fork issue dossier section for this plan.
• Added #5961 to the issue coverage matrix as related/not claimed.
• Updated #3177 evidence to include this plan.
• Updated PR reference wording so editableKeyCommands(...) / editableRenderers(...) are no longer described as the accepted final public DX; extension-owned behavior remains accepted, public capability helper spreads do not.

Verification plan

Planning-only current pass did not edit .tmp/slate-v2.

Ralph execution gates:

1. Source/type contract:
   • update EditorExtension typing for package facets
   • add slate-react and slate-dom facet type augmentation
   • type-level negative tests for typed editor inference, invalid marks, and disabled extensions
2. Runtime:
   • facet registration compiles to existing internal capability registry or a split private provider registry
   • preserve extension ordering and latest-extension-wins behavior
   • preserve direct <Editable> prop override/escape-hatch behavior
3. Public surface:
   • remove editableKeyCommands from public docs/examples
   • remove editableRenderers from public docs/examples if the facet replaces it
   • stop exporting public capability constants from slate-react
   • remove capabilities from first-party app/example authoring
   • add public api authoring for installed runtime handles if generic handle authoring must remain public
4. Example proof:
   • iframe.tsx, richtext.tsx, images.tsx, code-highlighting.tsx
   • no as unknown as CustomEditor casts for key/render authoring
   • no first-party editable.onKeyDown unless the example records why command modeling cannot express it
5. Commands:
   • cd .tmp/slate-v2 && bun --filter slate-react test:vitest -- surface-contract keyboard-input-strategy-contract generic-react-editor-contract
   • cd .tmp/slate-v2 && bun --filter slate-react typecheck
   • cd .tmp/slate-v2 && bun --filter slate-dom test
   • cd .tmp/slate-v2 && bun check

Closure Final Gates

Pass status: complete.

Closure assertions:

• Current-state read and verdict is complete.
• Related issue/research sync is complete.
• Maintainer objection pass is complete.
• No pass row remains pending with a runnable planning move.
• No .tmp/slate-v2 implementation, test, example, package, build, or config file was edited by this Slate Ralplan.
• No new fixed/improved issue claim was added.
• #3177 stays related/planning-reviewed.
• #5961 stays not claimed.
• #4613 existing improve claim is preserved but not broadened.
• Ralph execution has concrete target shapes and verification commands.

Final handoff status: complete.

Ralph execution summary:

1. Replace first-party public authoring that writes capabilities with typed package facets such as editable and clipboard.
2. Keep internal provider/registry storage private or advanced; do not teach raw capability strings in examples/docs.
3. Add public api authoring for installed runtime handles if generic handle authoring remains public, read through editor.api.<name>.
4. Remove editableKeyCommands(...) / editableRenderers(...) from public examples/docs once facets replace them.
5. Prefer editable.keymap plus editable.onCommand; use editable.onKeyDown only as a justified last-resort escape hatch.
6. Preserve extension ordering, latest-extension-wins, disabled-extension type exclusion, and existing clipboard behavior claims.
7. Add negative type tests for typed editor inference, invalid mark/block keys, disabled extension output exclusion, and no public raw capability lookup.

Pass state