Slate v2 Docs Legacy-Style Review Plan

Date: 2026-04-28 Status: done Active pass: Pass 7 complete Score: 0.92

Current Verdict

The current .tmp/slate-v2/docs tree is close to legacy Slate's writing style because large parts are copied from ../slate/docs. That is not enough. Some pages feel right and quietly teach APIs the live source rejects.

The best direction is a source-backed legacy-style rewrite:

• Keep legacy Slate's information architecture: Introduction, Walkthroughs, Concepts, API, Libraries.
• Keep the calm walkthrough voice: problem first, code second, API reference last.
• Replace stale legacy API claims with current Slate v2 contracts from live source and tests.
• Treat docs/general/changelog.md and old migration prose as historical, never the front door.
• Make docs prove the core bargain: Slate stays unopinionated, React stays a projection layer, and app authors get Slate-like render APIs without void/spacer footguns.

Current strongest pages:

Current highest-risk pages:

Pass 2 Docs / Source Inventory

Pass 2 scanned all 61 public markdown docs under .tmp/slate-v2/docs and matched the risky rows against live source, tests, and compiled research. The stale docs are clustered enough that the rewrite should be owner-based, not page-by-page whack-a-mole.

Research state after Pass 2:

• Compiled architecture research is current enough for this pass. docs/research/decisions/slate-v2-state-tx-public-api-and-extension-namespaces.md:100-136 already records the live source gap: state/tx exists and is tested, but docs/examples still teach primitive editor writes.
• React 19.2 evidence is already refreshed as of 2026-04-28 in docs/research/sources/editor-architecture/react-19-2-external-store-and-background-ui.md:88-102.
• Node/render DX research already accepts runtime-owned shells and warns that primitive editor.* writes are not the public example shape in docs/research/decisions/editor-node-dx-should-use-runtime-owned-shells-and-spec-first-renderers.md:126-133.
• No new research page was needed in Pass 2. The gap is now execution-grade docs inventory, not missing research.

Pass 3 Pressure Findings

Pass 3 pressure-tested the Pass 2 inventory against the north star. The result is blunt: this cannot be fixed by making individual pages nicer. The docs need an owner-order rewrite, because the stale claims cross-cut install, core lifecycle, React rendering, collaboration, and proof.

Exact rewrite order after Pass 3:

1. Front door: Introduction.md, Summary.md, install docs, bundled-source docs, and changelog/migration placement.
2. Core lifecycle: Editor, Commands, Transforms, Plugins, Normalizing, and custom-formatting walkthroughs as one read / update / state / tx rewrite.
3. React rendering: Slate, Editable, hooks, elements, voids, decorations, annotations, and performance docs as one runtime-projection rewrite.
4. Collaboration substrate: replace the slate-yjs cookbook with adapter-author backbone docs.
5. Proof gates: stale-term grep, source ledger, extracted snippet checks, and browser contract map.

Pass 4 Maintainer Objection Pass

Pass 4 challenged the Pass 3 rewrite order as a skeptical Slate maintainer. The pressure did not reverse the hard cuts, but it did narrow two decisions:

• Bundled-source docs should be decided from package artifacts, not deleted by assumption.
• Collaboration docs should become a substrate guide, not disappear from the walkthrough/concepts path entirely.

Pass 5 Ecosystem Maintainer Pass

Pass 5 checked the plan against Plate and slate-yjs migration pressure. The right docs line is still: raw Slate documents migration substrate, not current adapter support.

Ecosystem wording to use in the docs:

• "Slate exposes the substrate an adapter can target."
• "Plate can build typed product APIs above state and tx; raw Slate keeps the smaller names."
• "A collaboration adapter imports and exports operations through commits, tags, snapshots, and applyOperations."
• "Runtime ids, selected UI, void shells, and DOM anchors are local projection details."

Ecosystem wording to avoid:

• "Plate compatible" without a specific substrate contract.
• "Works with slate-yjs" until a current adapter and browser proof exist.
• editor.api, editor.tf, withYjs, or product command chains as first-path raw Slate docs.

Pass 6 Revision Pass

Pass 6 resolves the previously open decisions into execution text. No public API surface stays in maybe-language.

Final execution order:

1. Front door and navigation. Rewrite Introduction.md, Summary.md, install docs, bundled-source placement, and changelog placement.
2. Core lifecycle docs. Rewrite Editor, Commands, Transforms, Plugins, Normalizing, and custom-formatting walkthroughs around read, update, state, tx, specs, operations, and commits.
3. React projection docs. Rewrite Slate, Editable, hooks, elements, voids, decorations, annotations, and performance around provider-owned projection and target-scoped subscriptions.
4. Collaboration substrate docs. Rewrite collaboration as adapter-author substrate: commits, tags, snapshots, operation replay, adapter-owned awareness, and local-only runtime ids.
5. Proof gates. Add stale-term grep, source ledger, extracted snippet checks, and browser contract map.

Pass 7 Closure Audit

Pass 7 closes the review gate. This marks the plan ready for a later execution lane; it does not claim the docs are already rewritten.

Confidence Scorecard

Weighted score: 0.92.

Completion is done for the review lane. The plan is ready for a later execution lane.

Source-Backed Architecture North Star

Docs should teach Slate v2 as a small unopinionated editor runtime with a React projection package, not as a React component library that happens to store editor state.

The docs voice should stay close to legacy Slate:

• Start from the user problem.
• Show the smallest working example.
• Explain the mental model after the reader sees it.
• Move exact types and overloads to API pages.
• Avoid product-framework vocabulary that belongs in Plate.

The docs content must stop copying legacy implementation contracts when Slate v2 has made a hard cut.

Public API Target

Public docs should teach these as the normal paths:

const [editor] = useState(() => withReact(createEditor<CustomValue>()))

<Slate editor={editor} initialValue={initialValue} onChange={setValue}>
  <Editable renderElement={renderElement} renderVoid={renderVoid} />
</Slate>

editor.read((state) => {
  return state.selection.get();
});

editor.update((tx) => {
  tx.nodes.set({ type: "heading" });
  tx.marks.toggle("bold");
});

const renderVoid = ({ element, target }: RenderVoidProps<ImageElement>) => {
  return <Image src={element.url} selected={useElementSelected(target)} />;
};

Docs should not teach these as normal authoring paths:

• direct editor.children, editor.selection, editor.operations, or editor.marks
• extension methods(editor)
• app-owned void spacer children
• renderElement as the normal void renderer
• current-version Plate or slate-yjs adapter promises
• broad selection/focus hooks inside every rendered node

Internal Runtime Target

Public docs should explain the runtime at the right level:

• React subscribes to committed editor facts.
• Selection, DOM repair, IME, void shells, decoration projection, and large-document islands are runtime-owned.
• App renderers render content, not editor DOM contracts.
• Advanced source/projection APIs are documented after the normal decorationSources and annotationStores path.

Docs should not expose internal module names or root engine wiring as the author mental model.

Hook, Component, And Render DX Target

Keep legacy Slate's normal element shape:

function Paragraph({ attributes, children }: RenderElementProps) {
  return <p {...attributes}>{children}</p>;
}

Split voids into content-only rendering:

function Image({ element, target }: RenderVoidProps<ImageElement>) {
  const selected = useElementSelected(target);

  return ;
}

Document hook choice by render cost:

The docs should say the rule plainly: content renderers subscribe to the narrowest runtime target they actually draw.

Plate Migration-Backbone Target

Raw Slate docs should not become Plate docs.

The docs should give Plate a migration backbone by documenting:

• editor.extend(...) for named extension installation
• state groups for read helpers
• tx groups for transaction helpers
• elements specs for schema behavior
• commands, commitListeners, operationMiddlewares, and normalizers as substrate hooks
• no editor.api, editor.tf, editor.plate, or product-layer namespaces in raw Slate

Plate can map product APIs onto this substrate later:

Evidence: source registers extension slots for commands, capabilities, elements, normalizers, commitListeners, operationMiddlewares, state, and tx in .tmp/slate-v2/packages/slate/src/core/editor-extension.ts:138-186.

slate-yjs Migration-Backbone Target

Raw Slate docs should not promise that current slate-yjs public APIs already work.

They should document the substrate a collab adapter can target:

• deterministic operation replay through editor.applyOperations(...)
• commit metadata through Editor.getLastCommit(...)
• Editor.subscribe(...) for snapshots and commits
• runtime ids kept local to the editor projection
• editor.update(..., { tag }) for local and remote commit classification
• adapter-owned CRDT positions and awareness state outside Slate operation payloads

Evidence: .tmp/slate-v2/packages/slate/test/migration-backbone-contract.ts:135-195 proves tagged local edits, remote import, operation replay, and runtime ids staying out of operation payloads.

Legacy Regression Proof Matrix

Browser Stress And Parity Strategy

Docs should not rely on demos as proof. Each browser-sensitive doc example should link to a named contract family:

• text input and deletion
• mark toggles
• block transforms
• inline void navigation
• block void navigation
• editable void islands
• table cell navigation
• hover toolbar selection
• search decoration focus retention
• paste and drag/drop
• IME and Android input
• large-document island selection

Fast CI can run a small deterministic subset. Full generated replay belongs in test:stress or release-quality check:full, not default doc iteration.

Hard Cuts And Rejected Alternatives

Slate Maintainer Objection Ledger

Pass Schedule And Pass-State Ledger

Plan Deltas From Review

Added:

• Docs-specific Slate review lane.
• Current docs ranking by source accuracy and legacy style.
• P0 contradiction: extension methods(editor) docs conflict with live source.
• Public docs target for read, update, state, tx, renderVoid, and narrow hooks.
• Collaboration docs correction: migration backbone, not current adapter support.
• Pass 2 stale-doc inventory across extension API, write lifecycle, bundled source, collaboration, React runtime docs, projection ownership, void shell DX, and historical changelog/migration docs.
• Decision not to update research in Pass 2 because the compiled layer already contains the needed 2026-04-28 state/tx, React 19.2, and node-DX decisions.
• Pass 3 pressure findings across React performance, Slate-close DX, unopinionated core boundaries, migration backbone, regression proof, research evidence, and simplicity.
• Exact owner-order rewrite: front door, core lifecycle, React rendering, collaboration substrate, proof gates.
• Pass 4 maintainer objections and accepted/revised responses for owner-order rewrite, tx write lifecycle, void rendering, projection ownership, bundled-source docs, collaboration substrate, and browser proof mapping.
• Pass 5 ecosystem pass with Plate and slate-yjs source evidence, substrate mapping, and wording rules that avoid adapter promises.
• Pass 6 final execution decisions for tx first-path docs, bundled-source nav/artifact policy, collaboration substrate placement, projection ownership, void rendering, and proof gates.
• Pass 7 closure audit and final score.

Dropped:

• The assumption that copied legacy docs are "close enough".
• The idea that current docs are mostly up to date because several snippets mention editor.update.
• Page-by-page cleanup as the execution strategy. The contradictions are owner-clustered, so page-local patching is the wrong shape.
• Keeping broken bundled-source paths for script-tag users.
• Raw Slate adopting Plate api / tf / command-chain naming.
• Raw Slate promising current withYjs compatibility.
• Keeping previously open decision rows as plan debt.

Strengthened:

• Void docs must stay content-only and source-backed.
• Performance docs need hook choice guidance tied to runtime target subscriptions.
• Editable docs need ownership cleanup instead of source-link escape hatches.
• Raw Slate docs should stay Slate-close and unopinionated; Plate/spec-factory-first examples belong above raw Slate, not inside the core docs front path.
• Primitive editor writes can be mentioned only as API/reference bridge material where source supports them inside editor.update; walkthroughs should teach tx.
• Collaboration docs must describe operations, commits, tags, snapshots, runtime-local targets, and adapter-owned awareness/position state.
• Bundled-source docs are not a normal walkthrough unless supported ESM CDN artifacts are explicitly documented from current package output.

Open Questions And What Would Change The Decision

Implementation Phases With Owners

1. Docs/source inventory

   • Owner: docs reviewer.
   • Output: stale-claim inventory for every public doc page.

2. Front-door rewrite

   • Owner: docs author.
   • Output: Introduction.md, Summary.md, and walkthroughs/01-installing-slate.md updated to current source-backed legacy style.

3. Core API concepts rewrite

   • Owner: core API docs author.
   • Output: Editor, Commands, Plugins, Transforms, Normalizing pages aligned with editor.read, editor.update, state, tx, specs, and operation replay.

4. React runtime docs rewrite

   • Owner: slate-react docs author.
   • Output: Slate, Editable, hooks, rendering, voids, decorations, annotations, and performance docs aligned with current source.

5. Collaboration and ecosystem substrate docs

   • Owner: collaboration docs author.
   • Output: migration-backbone explanation with no current-version adapter promise.

6. Proof wiring

   • Owner: test/docs owner.
   • Output: snippet checks, stale-term grep, source line ledger, and slate-browser contract map.

Fast Driver Gates

Use these during docs work:

rg -n "methods\\(|editor\\.children|editor\\.selection|editor\\.operations|editor\\.marks|xx-using|dist/slate|under construction|Editor.addMark\\(|Editor.removeMark\\(|editor\\.insertNodes\\(" /Users/zbeyens/git/slate-v2/docs

rg -n "renderVoid|useElementSelected|decorationSources|annotationStores|state:|tx:|applyOperations|onCommit" /Users/zbeyens/git/slate-v2/packages /Users/zbeyens/git/slate-v2/docs

Run package/docs typechecks only after actual docs/examples/snippet files change.

Final Completion Gates

This review lane can be marked done only when:

• score is at least 0.92
• no dimension is below 0.85
• all public docs contradictions are inventoried or fixed in the plan
• every breaking/paradigm docs change has an accepted objection row
• collaboration docs say migration backbone, not current adapter support
• every major docs page has current source/test evidence
• browser-sensitive examples map to replayable proof rows
• pass schedule is complete
• active goal state says done