Slate v2 Plate-fit API hard cuts 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.92, ready for Ralph execution

Verdict

Harsh answer: the last editable-capabilities plan was still too Plate-shaped.

It correctly spotted that public capabilities authoring is bad DX. It then overcorrected by inventing editable.keymap, editable.renderers, and editable.onCommand as a nicer public shape. That is still a plugin framework inside raw Slate.

Slate should hard-cut the Plate-fit layer:

• cut public editableKeyCommands(...);
• cut public editableRenderers(...);
• cut the planned editable.keymap API before it exists;
• cut the planned editable.renderers facet before it lands;
• cut public Editable onCommand / EditableCommand as normal app DX;
• keep Editable onKeyDown, onDOMBeforeInput, onPaste, and render* props as raw Slate React escape hatches;
• keep transforms.*, queries, normalizers, state, and tx as Slate extension substrate;
• keep clipboard.insertData as a DOM/clipboard ingress extension facet, but stop authoring it through string capabilities;
• keep editor.api.* for mounted runtime handles such as DOM, clipboard, and history controls;
• keep capabilities as internal registry machinery only, not public examples or app authoring.

This means the public raw Slate examples should become more Slate-ish, not more Plate-ish:

<Editable
  renderElement={renderElement}
  renderLeaf={renderLeaf}
  onKeyDown={(event, { editor }) => {
    if (isHotkey("mod+b", event)) {
      toggleMark(editor, "bold");
      return true;
    }
  }}
/>

Reusable model behavior still belongs in extension middleware:

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

Clipboard ingress is different from model transforms:

const image = () =>
  defineEditorExtension<CustomEditor>()({
    name: "image",
    elements: [{ type: "image", void: "editable-island" }],
    clipboard: {
      insertData(data, { editor, next }) {
        if (!hasImage(data)) return next();

        editor.update((tx) => {
          tx.nodes.insert(createImage(data));
        });
        return true;
      },
    },
  });

Plate should own the nice product API:

const RichTextPlugin = createPlatePlugin({
  key: 'richText',
  render: { ... },
  shortcuts: { toggleBold: { keys: [[Key.Mod, 'b']] } },
  inputRules: [ ... ],
  pasteRules: [ ... ],
})

Intent And Boundary

Weakest assumption:

• Previous plans treated "feature-owned setup should live together" as enough justification to add Slate extension facets for React renderers and keymaps. That assumption is too broad. It is true for Plate plugins. It is not automatically true for raw Slate.

Intent-boundary pass result:

• Public onCommand is not shrunk into onNativeInputIntent. It is cut from public app DX. If native-format input still needs semantic routing, that stays internal/runtime-owned and must be proven against #3568/#3586; public users keep raw onDOMBeforeInput plus model middleware.
• Editable decorate stays as a raw Slate React render-time callback. Docs can steer persistent/async/perf-sensitive overlays to projection or annotation sources, but cutting decorate would break a classic low-level escape hatch without replacing it with something simpler.
• capabilities becomes internal registry plumbing. Do not document it as an advanced public authoring API. Public extension authors get named package facets such as api, clipboard, transforms, state, and tx.
• No user question is needed. The missing decisions are architecture calls, not product preference questions.

Live Current State

Hard-Cut Matrix

Keep Matrix

Before / After Shapes

Rendering

Current docs/examples:

const paragraph = () =>
  defineEditorExtension({
    name: "paragraph",
    capabilities: editableRenderers({
      elements: { paragraph: ParagraphElement },
    }),
  });

Target raw Slate:

const renderElement = (props: RenderElementProps<CustomElement>) => {
  switch (props.element.type) {
    case "paragraph":
      return <ParagraphElement {...props} />;
  }
};

<Editable renderElement={renderElement} />;

Target Plate:

const ParagraphPlugin = createPlatePlugin({
  key: "paragraph",
  node: { component: ParagraphElement },
});

Hotkeys

Current:

capabilities: {
  ...editableKeyCommands(({ editor, event }) => {
    if (isHotkey('mod+b', event)) {
      toggleMark(editor as CustomEditor, 'bold')
      return true
    }
  }),
}

Target raw Slate:

<Editable
  onKeyDown={(event, { editor }) => {
    if (isHotkey("mod+b", event)) {
      toggleMark(editor, "bold");
      return true;
    }
  }}
/>

Target Plate:

const BoldPlugin = createPlatePlugin({
  key: "bold",
  shortcuts: { toggle: { keys: [[Key.Mod, "b"]] } },
});

Model Behavior

Current good direction:

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

Target: keep it. This is Slate, not Plate.

Clipboard

Current:

capabilities: {
  'clipboard.insertData': ((editor, data) => {
    // paste behavior
  }) satisfies DOMClipboardInsertDataHandler,
}

Target:

defineEditorExtension({
  name: "html-paste",
  clipboard: {
    insertData(data, { editor, next }) {
      if (!data.types.includes("text/html")) return next();
      // paste behavior
      return true;
    },
  },
});

This does not conflict with transforms.*. clipboard.insertData decides how a browser DataTransfer enters the editor. transforms.* defines reusable model mutations after input has been interpreted.

Decision Brief

Principles:

1. Raw Slate exposes primitives and escape hatches, not feature frameworks.
2. React package APIs should be React/runtime-shaped, not Plate plugin-shaped.
3. Model behavior belongs in core extension middleware, not browser event string registries.
4. DOM ingress belongs to slate-dom / slate-react package facets, not generic registry strings.
5. Plate owns product-level packaging: shortcuts, keymaps, components, render registries, input rules, paste rules, toolbar command catalogs.

Top drivers:

1. Prevent raw Slate from becoming a half-Plate plugin framework.
2. Preserve the Slate mental model for users coming from legacy Slate: render props, browser event props, and editor method/transform behavior.
3. Keep the extension substrate strong enough for Plate and slate-yjs without exposing every product convenience in raw Slate.

Viable options:

Consequences:

• Some first-party Slate examples become less "packaged" and more explicit.
• Plate gets the polished plugin API story instead of raw Slate pretending to be a plugin framework.
• The previous editable-capabilities plan needs revision, not execution as-is.
• Native-format input proof must move out of public EditableCommand DX before onCommand is removed. This is a regression guard, not a reason to keep the public command API.
• Persistent or async overlays should prefer projection/annotation sources, but raw decorate stays for simple render-time decoration.
• Any future public registry-like authoring API must be a named package facet. capabilities is not that API.

Rejected boundary:

• Do not ask Plate migration to preserve raw Slate's temporary helper APIs. Plate gets to migrate straight to its own plugin language on top of the Slate substrate.

Pass closure:

• Intent, outcome, scope, non-goals, decision boundaries, and unresolved user decisions are explicit.
• No user question remains.

Ecosystem Strategy Synthesis

Research And Ecosystem Live Refresh Pass

Pass result: complete.

Mode: research-layer maintain plus local source refresh. Existing compiled research was strong enough; no new research page was needed. The research log records this pass.

Live local source evidence:

Research conclusion:

• The final boundary is stronger after live refresh: raw Slate keeps substrate and escape hatches; Plate owns bundled product APIs.
• Tiptap is the strongest evidence for rich plugin packaging, but that is evidence for Plate, not for raw Slate.
• ProseMirror is the strongest evidence that DOM/view props and clipboard hooks are runtime-layer concerns, not model transforms.
• Lexical is the strongest evidence for read/update lifecycle, extension output, and internal command substrate, not public app command DX.

Score after this pass:

Total score: 0.84. Still below closure threshold and still pending.

Issue Ledger Accounting

No new fixed issue claim is accepted by this pass.

Related Issue Discovery Pass

Pass result: complete.

Discovery source: durable ClawSweeper/ledger outputs only. No broad live GitHub discovery was needed because the touched public API surface already has current generated rows, manual sync rows, fork dossier entries, coverage rows, and PR reference text.

Ledger implication:

• docs/slate-v2/ledgers/fork-issue-dossier.md gets a new pass section for this revised #3177 direction.
• docs/slate-issues/gitcrawl-v2-sync-ledger.md, docs/slate-v2/ledgers/issue-coverage-matrix.md, and docs/slate-v2/references/pr-description.md remain pending for the later issue-sync accounting pass.

Broader Issue Ledger Pass

Pass result: complete.

Inputs read:

• docs/slate-issues/gitcrawl-live-open-ledger.md
• docs/slate-issues/gitcrawl-v2-sync-ledger.md
• docs/slate-issues/open-issues-ledger.md
• docs/slate-issues/gitcrawl-clusters.md
• docs/slate-issues/issue-clusters.md
• docs/slate-issues/test-candidate-map.md and targeted range files
• docs/slate-issues/benchmark-candidate-map.md
• docs/slate-issues/package-impact-matrix.md
• docs/slate-issues/requirements-from-issues.md
• docs/slate-v2/ledgers/issue-coverage-matrix.md
• docs/slate-v2/ledgers/fork-issue-dossier.md

Broader issue matrix:

Issue-ledger conclusion:

• No new Fixes or Improves claims.
• The implementation plan must preserve existing clipboard and beforeinput proof while cutting Plate-shaped authoring APIs.
• The later issue-sync pass must update stale wording in the manual ledger, coverage matrix, and PR reference where they still describe raw Slate renderer registries or public onCommand as the accepted final shape.

Issue pass status:

• Related issue discovery is complete.
• Manual issue/reference sync is still pending because the plan reverses #3177 wording from "extension-owned renderers stay target" to "renderer registry belongs in Plate."
• No broad live GitHub discovery is needed; durable ledgers already cover the touched issue rows.

Applicable Implementation Review Matrix

Pressure Passes

Pass result: complete.

Harsh read: the plan gets better when it removes more, not when it renames the same product ideas into nicer facets. Raw Slate should not grow a small Plate. It should expose the substrate Plate needs and leave the ergonomic product API to Plate.

Pressure score after this pass:

Total score: 0.89. Still below closure threshold and still pending.

Regression Proof Matrix

High-Risk Pre-Mortem

Trigger: public API hard cut across Slate React examples/docs/tests.

Pass result: complete.

Blast radius:

Three-scenario pre-mortem:

Expanded proof plan:

Rollback/remediation answer:

• No backward-compat aliases. This is a hard cut.
• If native-format proof fails, keep the internal route and cut only the public prop/types; do not reintroduce public onCommand.
• If editor.api typing fails, revise the typed api authoring layer; do not reopen public string capabilities.
• If examples become unreadable, move product-shaped examples to Plate docs or simplify the raw Slate example; do not add editable.* back.
• If clipboard scope expands beyond input ingress, split a future output facet; do not overload insertData.

High-risk verdict:

• Keep the hard cut.
• Revise the execution plan to put native-format and editor.api type proof before broad docs/example cleanup.
• No implementation edit should claim Plate/slate-yjs migration beyond substrate readiness unless separate proof is added.

High-risk score after this pass:

Total score: 0.92. Closure still pending because revision, issue-sync, and closure-final-gates have not completed.

Maintainer Objection Ledger

Pass result: complete.

Architecture strategist read: the old helper direction created inappropriate intimacy between raw Slate React and product feature packaging. The correct architecture is boring and narrower: React view props for app UI, core extensions for model/runtime behavior, package-owned facets for DOM ingress and mounted handles, Plate plugins for product composition.

Accepted revisions from this pass:

• onCommand is not merely "too product-shaped"; it is the highest regression risk. The implementation phase must preserve internal native-format proof before deleting the public prop/types.
• clipboard.insertData stays only because it is DOM ingress. It must not become the place for output serializers, paste rules, or product policy.
• The plan must teach the authoring split directly: React view props, editor model/runtime extensions, typed mounted APIs, and Plate product plugins.
• Public capabilities can remain as internal registry mechanics only if normal authoring and docs cannot depend on it.

Maintainer score after this pass:

Total score: 0.90. Still below closure threshold and still pending.

Revision Pass

Pass result: complete.

Coherence fixes applied:

• The accepted hard cut no longer uses conditional public-removal language for EditableCommand*.
• Related issue discovery is complete; only manual issue/reference sync remains pending.
• Implementation order now starts with regression locks and type-substrate proof before deleting public APIs.
• clipboard.insertData remains scoped to input ingress; output serialization stays outside this plan.
• The current score is 0.92; earlier score rows are retained as pass history, not current readiness claims.

Simplicity fixes applied:

• No replacement public editable.* namespace.
• No public onNativeInputIntent.
• No backward-compat aliases.
• No slate-yjs/collab claim beyond preserving the operation/state/tx substrate.

Current Ralph execution order:

1. Lock native-format, editor.api, clipboard, and public-surface proof.
2. Split public extension authoring from internal capability registry mechanics.
3. Remove public Plate-shaped APIs and exports.
4. Rewrite examples/docs around raw Slate buckets.
5. Sync issue ledgers and PR reference.
6. Run the Slate v2 verification gates.

Implementation Phases

1. Regression and substrate locks in .tmp/slate-v2:
   • prove native-format/beforeinput behavior before public onCommand removal;
   • prove editor.api.dom, editor.api.clipboard, editor.api.history, and editor.getApi(...) stay typed without public string capabilities;
   • prove clipboard ingress behavior and existing clipboard issue claims stay green.
2. Extension type cleanup:
   • split public authoring from internal capability registry mechanics;
   • hide public capabilities from normal EditorExtension authoring;
   • add typed api authoring for installed handles;
   • add typed clipboard package facet for DOM ingress.
3. Public surface hard cut:
   • remove editableKeyCommands, editableRenderers, capability constants, and public type exports from slate-react;
   • remove public EditableCommand* / onCommand;
   • preserve internal native-format routing only where the beforeinput proof requires it.
4. Examples/docs rewrite:
   • renderers through Editable render* props;
   • hotkeys through Editable onKeyDown;
   • model behavior through transforms.*;
   • paste behavior through clipboard.insertData.
5. Contract rewrite:
   • flip tests currently requiring editableRenderers / editableKeyCommands;
   • add negative type tests for Plate-fit APIs.
6. Ledger/reference sync:
   • revise #3177 rows from "registered renderers target" to "raw render props plus Plate renderer registry target";
   • preserve #4613 clipboard improve claim;
   • keep #5961 not claimed.

Issue Sync Accounting

Pass result: complete.

Synced artifacts:

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

Issue accounting result:

Claim result:

• New fixed claims: 0.
• New improved claims: 0.
• Fixed/improved issue counts remain unchanged.
• PR reference now reflects the final hard-cut direction instead of the older editable-capabilities plan.

Fast Driver Gates

Run from /Users/zbeyens/git/slate-v2:

bun --filter slate-react test:vitest -- surface-contract keyboard-input-strategy-contract generic-react-editor-contract
bun --filter slate-react typecheck
bun --filter slate-dom test
bun --filter slate-dom typecheck
bun --filter slate typecheck
bun typecheck:site
bun check

Planning-state gate from /Users/zbeyens/git/plate-2:

node tooling/scripts/completion-check.mjs

Pass State Ledger

Open Questions

None for this pass.

Resolved:

1. Public <Editable onCommand> / EditableCommand* is fully cut. No public onNativeInputIntent replacement in this plan.
2. Editable decorate remains a raw render-time callback; projection or annotation sources handle persistent/async/perf-sensitive overlays.
3. capabilities is internal registry plumbing, not an advanced public authoring API.

Final Handoff Outline

Final handoff status: complete.

Accepted hard cuts:

• Cut public editableKeyCommands(...).
• Cut public EDITABLE_KEY_COMMAND_CAPABILITY.
• Reject planned public editable.keymap.
• Cut public editableRenderers(...).
• Cut public EDITABLE_RENDERERS_CAPABILITY.
• Reject planned public editable.renderers.
• Cut public <Editable onCommand>.
• Cut public EditableCommand* types.
• Cut public EditorExtension.capabilities / registration-output capabilities as normal authoring and docs/examples API.
• Keep public EditableInputRule* and public extension commands already cut.
• No backward-compatible aliases.

Accepted keeps:

• Keep defineEditorExtension(...) and creation-time extensions: [...].
• Keep transforms.*, queries, normalizers, operationMiddlewares, commitListeners, state, and tx.
• Keep raw Editable renderElement, renderLeaf, renderText, renderVoid, decorate, onKeyDown, onDOMBeforeInput, and onPaste.
• Keep clipboard.insertData as typed DOM/clipboard input ingress only.
• Keep editor.api.dom, editor.api.clipboard, editor.api.history, and editor.getApi(...) as typed mounted runtime handles.
• Keep internal capability registry mechanics only as implementation substrate.

Before/after target:

// Before: raw Slate pretending to be a product plugin framework.
defineEditorExtension({
  name: 'paragraph',
  capabilities: editableRenderers({
    elements: { paragraph: ParagraphElement },
  }),
})

// After: raw Slate React uses render props.
<Editable renderElement={renderElement} />

// Before: raw Slate key registry.
editableKeyCommands(({ editor, event }) => {
  if (isHotkey('mod+b', event)) {
    toggleMark(editor, 'bold')
    return true
  }
})

// After: raw Slate UI hotkeys stay in the React event prop.
<Editable
  onKeyDown={(event, { editor }) => {
    if (isHotkey('mod+b', event)) {
      toggleMark(editor, 'bold')
      return true
    }
  }}
/>

// Keep: reusable model behavior belongs in extension middleware.
defineEditorExtension({
  name: "checklist",
  transforms: {
    deleteBackward({ editor, next }) {
      if (applyChecklistBackspaceStart(editor)) return;
      next();
    },
  },
});

// Keep, but typed and narrow: clipboard input ingress only.
defineEditorExtension({
  name: "html-paste",
  clipboard: {
    insertData(data, { editor, next }) {
      if (!data.types.includes("text/html")) return next();
      return true;
    },
  },
});

Plate boundary:

• Plate owns shortcuts, keymaps, input rules, paste rules, renderer/component registries, toolbars, and product plugin packaging.
• Raw Slate provides the lower-level substrate Plate needs; it does not keep temporary Slate React helper APIs for Plate migration compatibility.

Implementation order for Ralph:

1. Lock native-format/beforeinput proof, editor.api typing, clipboard ingress, and public-surface contracts in .tmp/slate-v2.
2. Split public extension authoring from internal capability registry mechanics.
3. Remove the public Plate-shaped APIs and exports.
4. Rewrite examples/docs around raw Slate buckets.
5. Sync issue ledgers and PR reference.
6. Run the Slate v2 gates listed in Fast Driver Gates.

Issue accounting:

• #3177: related only; no renderer registry fix/improve claim.
• #5961: not claimed; stale DevTools warning remains unreproduced.
• #4613: existing improve claim preserved for typed insertData ingress.
• #4569: existing docs fix claim preserved with typed clipboard wording.
• #5233: existing custom fragment-key fix claim preserved.
• New fixed claims: 0.
• New improved claims: 0.

Final completion gates:

• Total score 0.92; no dimension below 0.85.
• All scheduled pass rows are complete.
• Issue ledger, fork dossier, coverage matrix, and PR reference are synced.
• No unresolved user decision remains.
• No Slate v2 implementation files were edited by Slate Ralplan.
• Slate v2 implementation verification remains assigned to the later Ralph execution because this plan is planning-only.