Slate v2 example memoization hard-cut ralplan

Date: 2026-05-14 Status: done Score: 0.92 Owner: Slate Ralplan planning only Execution owner: ralph in .tmp/slate-v2

Verdict

The keydown plan was too narrow.

Correction: the first version of this plan was wrongly marked ready. It had a good current-state inventory, but it had not completed the Slate Ralplan pass schedule. The pass ledger below is now closed and the Done Handoff is ready for user review.

There are three real library-level memoization leaks:

1. Rendering docs still teach useCallback for renderElement, renderLeaf, renderText, and renderSegment.
2. Editing behavior examples still use callback props and memoized rule arrays because Slate React lacks complete command/key/paste/rule ownership.
3. Option-object APIs still make examples memoize objects to avoid identity churn. Projection-store examples are a lower-priority smell, not a release blocker.

Do not turn this into "delete every useCallback". That would be stupid. Internal runtime callbacks, subscriptions, UI demo handlers, and overlay state can keep memoization when identity is a real implementation detail.

Scope

Inventory source:

• .tmp/slate-v2/site/examples/ts
• .tmp/slate-v2/docs
• .tmp/slate-v2/packages/slate-react/test/input-router-contract.test.tsx

Implementation edits are out of scope for this pass.

Hard Cuts And Conditional Cleanups

1. Render props should not teach useCallback

Current examples/docs:

• docs/concepts/09-rendering.md
• docs/walkthroughs/03-defining-custom-elements.md
• docs/walkthroughs/04-applying-custom-formatting.md
• docs/walkthroughs/05-executing-commands.md
• docs/walkthroughs/09-performance.md

Current problem:

• docs say render functions should be top-level or useCallback
• Editable passes render props through memoized block/text components
• EditableTextBlock compares renderer prop identity, so inline renderers can rerender too much
• the docs therefore teach React ceremony as normal Slate onboarding

Target:

• keep renderElement, renderLeaf, renderText, and renderSegment as raw escape-hatch props
• add a Slate React renderer capability consumed by Editable
• teach component/renderer registration as the default path

Candidate shape:

editor.extend(
  editableRenderers({
    elements: {
      code: CodeElement,
      paragraph: ParagraphElement,
    },
    leaves: {
      bold: BoldLeaf,
    },
  }),
);

This belongs in slate-react, not core slate. Core EditorElementSpec should stay non-React.

Docs target:

• no useCallback in beginner render docs
• performance docs say stable top-level components/spec registration first
• raw render props stay advanced/custom

2. Editing behavior should move to command/rule capabilities

Current examples:

• site/examples/ts/tables.tsx
• site/examples/ts/code-highlighting.tsx
• site/examples/ts/markdown-shortcuts.tsx
• site/examples/ts/inlines.tsx
• site/examples/ts/iframe.tsx
• site/examples/ts/richtext.tsx
• site/examples/ts/images.tsx

Current problem:

• tables.tsx uses useCallback<EditableKeyDownHandler>
• code-highlighting.tsx uses useCallback for keydown behavior
• markdown-shortcuts.tsx uses useMemo for inputRules, useCallback for Android onDOMBeforeInput, and useCallback for Enter/Backspace
• inlines.tsx uses useMemo for inputRules, plus raw keydown/paste handlers
• iframe.tsx and richtext.tsx still teach raw hotkey parsing
• images.tsx still teaches raw select-all key parsing

Target:

• make onCommand keydown-complete, not format-only
• add key-command capability for custom hotkeys
• keep editableInputRules(...) as extension capability, not example-local memoized arrays
• add command-aware rules for Enter/Backspace/Delete
• route paste customization through insert-data or paste rules
• move Android pending diff flushing into the runtime

This supersedes the narrower keydown-only plan: docs/plans/2026-05-14-slate-v2-keydown-command-coverage-ralplan.md.

3. Rendering strategy option objects should be value-normalized

Current example:

• site/examples/ts/rendering-strategy-runtime.tsx

Current problem:

• the example memoizes a renderingStrategy object before passing it to Editable
• EditableTextBlocks already normalizes strategy internals, but some memo dependencies still preserve option object identity

Target:

• Editable/EditableTextBlocks should normalize rendering strategy options by primitive fields
• examples should be able to inline:

<Editable
  renderingStrategy={{
    estimatedBlockSize,
    overscan,
    threshold: 1,
    type: "virtualized",
  }}
/>

No user memo required.

4. Annotation/widget projection hooks are optional

Current examples:

• site/examples/ts/review-comments.tsx
• site/examples/ts/collaborative-comments.tsx
• site/examples/ts/persistent-annotation-anchors.tsx

Current problem:

• examples memoize annotation and widget arrays before passing them into useSlateAnnotationStore and useSlateWidgetStore
• the hooks already keep latest cells internally, but array identity still drives refresh effects

Conditional target:

• add projector-friendly overloads to Slate React projection hooks, not a comment-specific API
• keep app-specific mapping in user code, but move memoization mechanics into the hook
• do not make this a release blocker; land it only if the overload is tiny, generic, metadata-safe, and clearer than a shared example helper

Candidate shape:

const annotationStore = useSlateAnnotationStore(editor, {
  deps: [comments],
  project: () => comments.map(toAnnotation),
});

const widgetStore = useSlateWidgetStore(editor, {
  annotationStore,
  deps: [comments],
  project: () => comments.map(toWidget),
});

This is lower priority than renderer, command/rule routing, and rendering strategy normalization. It is a real smell, but not strong enough to block the execution handoff.

5. One-shot initial value docs should not use useMemo

Current docs:

• docs/walkthroughs/06-saving-to-a-database.md

Current problem:

• docs use useMemo(..., []) to read localStorage-backed initial content
• this is the wrong React teaching shape for one-shot initialization

Target:

• use plain lazy useState in docs unless a tiny, already-safe core overload falls out of implementation
• do not teach useMemo as constructor storage

Do not add core lazy initialValue just to clean one walkthrough. If CreateEditorOptions stays value-only, the docs use lazy useState.

Weak Cuts / Do Not Push Into Slate React

Full Inventory

Execution Order

1. Renderer capability and docs rewrite.
2. Command/key/input/paste behavior cuts.
3. Rendering strategy option normalization.
4. Optional projection overload only if it stays tiny and generic.
5. Docs-first lazy initialization cleanup.
6. Opportunistic safe URL/helper cleanup and trivial callback simplification.

Do not start with safe URL cleanup. It is the easiest work and the least important architecture issue.

Current-State Read And Initial Score

This pass re-grounded the plan in current Slate v2 source and docs:

• .tmp/slate-v2/site/examples/ts: searched for all useCallback and useMemo examples.
• .tmp/slate-v2/docs: searched for all docs that teach useCallback or useMemo.
• .tmp/slate-v2/packages/slate-react/test/input-router-contract.test.tsx: read test-only memoization.
• .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-editor.ts: read current editor construction API.
• .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-annotation-store.tsx and .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-widget-store.tsx: read projection-store identity behavior.
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts: read current non-React EditorElementSpec.
• .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx: read renderer and rendering-strategy prop identity pressure.

Initial score is intentionally below the completion threshold:

Weighted score: 0.55.

Completion threshold remains >= 0.92 with no dimension below 0.85.

Slate Ralplan Pass-State Ledger

Passes 1 through 12 are complete. The plan is ready for user review and later ralph execution.

Verification Plan

From .tmp/slate-v2:

• focused slate-react unit tests for renderer capability and key command routing
• focused example tests for tables, inlines, markdown shortcuts, code highlighting, and rendering strategy runtime; add annotation/widget example proof only if the optional projection overload lands
• docs grep proving beginner docs no longer teach useCallback/useMemo as required Slate ceremony
• bun --filter slate-react typecheck
• bun lint:fix
• bun --filter slate-react test
• bun check

From plate-2 after planning/doc artifact edits:

• pnpm lint:fix
• bun run completion-check

Related Issue Discovery

Status: complete for discovery. Exact issue accounting is complete in the Issue-Ledger Pass below.

ClawSweeper mode: applied as a ledger/cache-first discovery pass. No broad live GitHub issue list/search was run, because the generated live ledger, manual v2 sync ledger, coverage matrix, fork dossier, benchmark map, and test-candidate maps already expose the touched surfaces.

Read evidence:

• 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
• docs/slate-issues/test-candidate-map/*
• 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
• docs/slate-v2/references/pr-description.md

Candidate issue set for pass 3:

No fork dossier, coverage matrix, manual sync ledger, or PR reference rows were changed in pass 2. Pass 3 completed exact claim classification and found no claim-ledger update was justified by a planning-only pass.

Issue-Ledger Pass

Status: complete.

Verdict: this pass changes planning confidence only. It does not add or promote any fixed issue claim, because the current work is a planning pass and did not add fresh Slate v2 source, test, browser, benchmark, or docs proof.

Issue accounting:

Claim changes from this pass:

• New Fixes claims: 0.
• New Improves promotions: 0.
• Fixed/improved demotions: 0.
• Manual sync ledger changes: 0.
• Coverage matrix changes: 0.
• PR reference changes: 0.
• Fork dossier additions: 0.

Why no ledger files changed: every candidate already has a current cached row or is only plan-local pressure. A planning-only pass must not rewrite public issue claims unless it changes exact claim text, proof routes, or closure status.

Next issue gate: pass 11 must re-run sync accounting after the architecture decision, proof plan, and revision passes. If later execution changes renderer, command, paste, projection, or initialization proof, that later pass owns the manual sync, coverage matrix, fork dossier, and PR reference updates.

Intent And Decision Boundary Pass

Status: complete.

Live source refresh for this pass:

• .tmp/slate-v2/docs/walkthroughs/09-performance.md:44 still tells users to stabilize renderElement, renderLeaf, renderText, and renderSegment with top-level functions or useCallback.
• .tmp/slate-v2/docs/concepts/09-rendering.md:17 and .tmp/slate-v2/docs/concepts/09-rendering.md:45 still teach useCallback-wrapped render functions.
• .tmp/slate-v2/packages/slate-react/src/components/editable.tsx:87 exposes inputRules, renderingStrategy, onDOMBeforeInput, onCommand, onKeyDown, and scrollSelectionIntoView as raw Editable props.
• .tmp/slate-v2/packages/slate-react/src/components/editable.tsx:216 defines EditableCommandHandler; .tmp/slate-v2/packages/slate-react/src/components/editable.tsx:227 defines the raw onDOMBeforeInput escape hatch with command context.
• .tmp/slate-v2/packages/slate-react/src/editable/runtime-root-engine.ts:144 still rebuilds effective input rules from the inputRules prop identity.
• .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:501 still accepts raw renderElement; the render callback remains a hot path.
• .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-annotation-store.tsx:15 and .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-widget-store.tsx:17 still take projected arrays directly and refresh when array identity changes.
• .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-editor.ts:23 constructs the editor lazily, but .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:619 still types CreateEditorOptions.initialValue as a value, while extension runtime state at .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:869 already permits lazy initializers.
• .tmp/slate-v2/site/examples/ts/tables.tsx:105, .tmp/slate-v2/site/examples/ts/markdown-shortcuts.tsx:87, and .tmp/slate-v2/site/examples/ts/rendering-strategy-runtime.tsx:508 remain representative example-local memoization sites.

Intent:

• Remove React memoization as required Slate ceremony where the memo exists only because Slate React lacks a semantic owner.
• Keep Slate unopinionated. The answer is not "turn raw Slate into Plate".
• Keep raw escape hatches for advanced apps, but stop making escape hatches the happy path in docs/examples.
• Make performance behavior an API contract that can be tested, not a documentation warning that users must remember.

Outcome for a later ralph execution:

• Beginner rendering docs and examples no longer teach useCallback as the normal way to render elements, leaves, text, or projected segments.
• Common editing examples no longer need user-owned memoized onKeyDown, onDOMBeforeInput, or inputRules arrays for first-party behavior.
• Rendering strategy examples can pass option objects inline without defeating internal memoization.
• Annotation/widget examples may stop memoizing derived arrays by hand if a tiny generic projector overload survives implementation review.
• One-shot initial value docs use lazy useState, not useMemo.

In scope:

• slate-react renderer registration/capability for default element, leaf, text, and segment rendering.
• slate-react command/key/input/paste/rule ownership for common editing behavior that examples currently express as memoized callbacks.
• Internal value-normalization for renderingStrategy option objects.
• Optional projector overloads for useSlateAnnotationStore and useSlateWidgetStore, only if the overload is tiny, generic, and safer than a shared helper.
• Docs and examples that currently teach memoization as Slate setup work.
• Focused tests and grep checks proving current docs/examples no longer require this ceremony.

Non-goals:

• Do not remove raw renderElement, renderLeaf, renderText, renderSegment, onKeyDown, or onDOMBeforeInput.
• Do not put React component registration in raw slate core.
• Do not put URL sanitization, embed policy, mention popup behavior, debug UI, or benchmark controls into Slate React.
• Do not make virtualization production-ready in this lane.
• Do not assume React Compiler as a dependency or a correctness requirement.
• Do not implement Plate's plugin authoring model inside raw Slate.
• Do not claim any new fixed issue until implementation and proof exist.

Decision boundaries:

User decision points:

• No user decision is needed before pass 5.
• If the later revision pass finds two equally clean public names for renderer registration, ask then. Do not stop this pass for naming bikeshedding.
• Lazy initialValue in core is not a user-decision point for this plan. Use lazy useState in docs unless implementation independently proves a tiny safe overload.

Decision Brief

Principles:

• Semantic APIs beat handler memoization.
• Raw escape hatches stay available, but they are not onboarding material.
• Raw Slate core remains React-free.
• Slate React owns generic React runtime behavior; Plate owns product policy.
• React Compiler can make examples nicer, but Slate's public API must not rely on it.
• Every issue-facing claim needs implementation proof before the ledger changes.

Decision drivers:

• Performance: avoid prop-identity churn in hot render and input paths.
• DX: examples should read like editor code, not React memoization exercises.
• Migration: Plate and slate-yjs need generic substrate primitives, not one-off example callbacks.
• Testability: command, renderer, projection, and strategy behavior must be covered by package tests or example tests.
• Adoption: breaking changes must keep raw prop escape hatches.

Viable options:

Chosen direction:

1. Add a Slate React renderer capability/registration API. renderElement, renderLeaf, renderText, and renderSegment stay as raw props for advanced customization.
2. Make onCommand and extension-owned input/key/paste rules complete enough that examples stop parsing keys and native input events for common behavior.
3. Normalize renderingStrategy option objects by primitive fields inside the runtime, so inline objects do not create avoidable churn.
4. Keep annotation/widget projector overloads optional. Land only if the API is tiny, generic, metadata-safe, and clearly better than a shared helper.
5. Rewrite one-shot initial value docs to lazy useState; do not add core lazy initialValue for this walkthrough alone.

Rejected implementation shapes:

• A global React renderer registry in raw slate: wrong owner.
• A Plate-style plugin object as the default raw Slate authoring model: too opinionated.
• A single memoizeEverything docs section: preserves the bad API signal.
• A broad useStableCallback helper: treats the symptom, not the owner.
• A hard removal of onKeyDown or onDOMBeforeInput: hostile to advanced apps and browser escape hatches.

Consequences:

• slate-react gets a slightly larger public surface, but it buys back cleaner examples and lower hot-path identity pressure.
• The later proof pass must include rerender and handler-staleness tests. A pretty API without runtime proof is not enough.
• Docs must distinguish "recommended semantic API" from "escape hatch". Mixing those again is how this problem came back.
• Issue ledgers stay unchanged until execution produces fresh proof.

Pass 4 score update:

Weighted score: 0.68.

Research And Ecosystem Strategy Pass

Status: complete.

Research mode: maintain. The compiled editor-architecture lane already covers the relevant comparison set, so this pass did not create new research pages. It did append the research log and recorded the gap report here. The remaining gaps are execution-proof gaps, not missing source-family gaps.

Compiled evidence read:

• docs/research/index.md and docs/research/log.md.
• docs/research/sources/editor-architecture/lexical-read-update-extension-runtime.md.
• docs/research/sources/editor-architecture/prosemirror-transaction-view-dom-runtime.md.
• docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md.
• docs/research/sources/editor-architecture/react-19-2-external-store-and-background-ui.md.
• docs/research/decisions/slate-v2-state-tx-public-api-and-extension-namespaces.md.
• docs/research/decisions/editor-node-dx-should-use-runtime-owned-shells-and-spec-first-renderers.md.
• docs/research/systems/editor-node-text-mark-dx-landscape.md.
• docs/research/decisions/plugin-input-rules-guide-should-lead-with-runtime-first-then-feature-owners-then-api-reference.md.
• docs/analysis/editor-architecture-candidates.md.

Local source evidence read:

• Lexical: ../lexical/packages/lexical/src/LexicalEditor.ts.
• ProseMirror: ../raw/prosemirror/packages/state/src/transaction.ts, ../prosemirror-view/src/index.ts, ../prosemirror-view/src/selection.ts, and ../prosemirror-view/src/input.ts.
• Tiptap: ../tiptap/packages/core/src/ExtensionManager.ts, ../tiptap/packages/core/src/CommandManager.ts, ../tiptap/packages/react/src/useEditorState.ts, and ../tiptap/packages/react/src/useEditor.ts.
• Plate: ../plate/packages/core/src/react/editor/PlateEditor.ts, ../plate/packages/core/src/react/editor/withPlate.ts, and ../plate/packages/autoformat/src/plugin.ts.
• slate-yjs: ../slate-yjs/packages/core/src/plugins/withYjs.ts, ../slate-yjs/packages/core/src/utils/position.ts, ../slate-yjs/packages/core/src/plugins/withYHistory.ts, and remote cursor React hooks.

Ecosystem synthesis:

Cross-system decisions from this pass:

1. Renderer capability should be spec-first, not a thin helper around renderElement. The target is closer to defineElement({ render }) plus runtime-owned shells than to "memoize this callback".
2. onCommand is the right generic public name for edit intent at the Editable boundary. Extension APIs may expose feature commands, but raw Slate should not lead with a Tiptap-style command catalog.
3. Input rules should move out of example-local useMemo arrays, but they should stay feature-owned. A generic rules engine is useful; a new central product policy bucket is not.
4. Rendering strategy normalization is still valid, but it is a smaller runtime hygiene fix than renderer and command ownership.
5. Projection hook projector overloads are plausible because they match React external-store and slate-yjs selector evidence, but later passes downgrade them to optional. They should land only if generic, tiny, and metadata-safe.
6. Lazy initial value is docs-first. A core overload is not required for this plan and must not weaken operation replay, collaboration initialization, or fixed issue claims around editor replacement and provider value ownership.

Research gap report:

Pass 5 score update:

Weighted score: 0.75.

Pressure Pass

Status: complete.

Applied review lenses:

Live source pressure evidence:

• EditableDOMRootProps still exposes inputRules, renderingStrategy, onDOMBeforeInput, onCommand, and onKeyDown as raw props in .tmp/slate-v2/packages/slate-react/src/components/editable.tsx.
• Rendering strategy metrics already include cohort, degradation mode, DOM node count, mounted counts, shell counts, and nativeSurfaceComplete in .tmp/slate-v2/packages/slate-react/src/components/editable.tsx.
• EditableTextBlocks still accepts raw renderElement, renderLeaf, renderText, renderSegment, and renderVoid props in .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx.
• runtime-root-engine.ts still memoizes effective input rules by inputRules prop identity.
• useSlateAnnotationStore and useSlateWidgetStore still refresh when the projected array identity changes.
• useSlateEditor is already lazy as a hook, but public CreateEditorOptions.initialValue is still value-only.
• Existing tests already cover annotation locality, render profiling, rendering strategy metrics/degradation, large DOM-present group stability, and virtualized native-surface flags, but not the specific "user can stop memoizing examples" contract.

Keep / Downgrade / Cut

Performance

• applicability: applied.
• Vercel rules used:
  • rerender-dependencies: strategy configs and effects should depend on primitive fields, not option-object identity.
  • rerender-lazy-state-init: one-shot localStorage reads belong in lazy initialization, not useMemo(..., []).
  • rerender-defer-reads: event handlers should not subscribe/render just to read state later.
  • advanced-event-handler-refs: long-lived native listeners need latest callbacks without reattachment.
  • client-event-listeners: repeated editor blocks should not carry repeated global/native listener work.
  • js-length-check-first, js-set-map-lookups, and js-early-exit: hot projection and rule paths need cheap guards before scans.
• extra performance rules used:
  • cohort segmentation
  • repeated-unit budget
  • event-delegation budget
  • interaction INP matrix
  • memory/DOM tagging
  • degradation contract
  • editor native behavior proof
  • React 19 runtime proof
• repeated units:
  • top-level block renderer
  • text/leaf renderer
  • input event/rule dispatch
  • annotation/widget projection bucket
  • rendering strategy group/segment
• cohorts:
  • normal: 0-500 blocks, low decorations, DOM-present
  • medium: 500-2000 blocks, DOM-present with strict repeated-unit budgets
  • large: 2000-10000 blocks, staged rendering and DOM metrics required
  • stress: 10000-50000 blocks, explicit degradation rows required
  • pathological: 50000+ blocks or custom renderers plus dense annotations, collaboration, IME/mobile, or broad selection
• budgets:
  • no per-block effects from renderer registration
  • no per-block event handler growth from command/rule APIs
  • typing/selecting must not allocate or scan proportional to full document
  • projection refresh must be scoped by affected runtime ids or explicit external ids
  • rendering strategy metrics must keep DOM node, mounted group, shell, and boundary counts visible
• React/runtime primitives:
  • useSyncExternalStore-style selectors remain correct for projected UI
  • React transitions/deferred work can help sidebars and overlays only
  • React 19 Activity is not a hidden editable-content primitive
  • React Compiler is not accepted as a library correctness contract
• interaction metrics required:
  • type
  • select
  • select then type
  • select-all
  • copy
  • paste
  • backspace/enter shortcut
  • click far group then type
  • materialize staged/shell/virtualized group
  • remote/projection update
• trace/CWV proof:
  • page load/Core Web Vitals are out of scope for this plan
  • React Performance Tracks matter only when component breadth is suspicious
  • lab proxies are event-to-update and event-to-paint by interaction/cohort
• memory tags:
  • JS heap
  • DOM node count
  • mounted group count
  • shell/virtualized boundary count
  • event listener count
  • projected annotation/widget count
  • dirty runtime id set size
• degradation contract:
  • DOM-present/staged is the production path
  • shell and virtualized remain named degraded modes
  • every degraded mode must classify browser find, screen-reader traversal, native selection, copy, paste, select-all, IME, mobile touch selection, undo/history, collaboration, and follow-up typing
• dashboard/RUM gap:
  • no production RUM required for this docs/example API cleanup lane
  • if performance claims are marketed later, tag interaction name, cohort, rendering strategy, document size, DOM nodes, annotations, browser, mobile, IME, and release version

DX And API Pressure

Unopinionated Core Pressure

Raw slate must not absorb:

• React renderers.
• URL trust policy.
• mention popup behavior.
• table product navigation.
• toolbar/shortcut packages.
• Plate-style api / tf naming.
• React projection stores.

Raw slate may own:

• value initialization if the function-valued initializer is a pure construction-time value API.
• transaction/commit metadata that Slate React, Plate, and slate-yjs can all consume.
• extension namespace substrate through state / tx.

Slate React may own:

• renderer component registration.
• native input/keyboard command classification.
• generic feature-owned input/paste/key rules.
• projection-store hook mechanics.
• rendering strategy normalization and metrics.

Migration Pressure

Regression Proof Matrix

TDD Execution Shape

Execution should use vertical slices:

1. Renderer registration test, implementation, docs rewrite.
2. Command/rule routing test, implementation, examples rewrite.
3. Rendering strategy inline-object test, implementation, example rewrite.
4. Projection overload test only if the API survives implementation review.
5. Lazy initial value docs grep, with core test only if core API changes.

Do not write all tests first. That would lock the wrong API too early.

Simplicity Review

Core purpose: stop teaching React memoization as Slate setup work when the runtime can own the identity or behavior.

Simplification decisions:

• Keep renderer capability and command/rule routing because they remove real repeated ceremony across docs/examples.
• Keep rendering strategy normalization because it is small and internal.
• Downgrade projection overloads because they may create public API weight for three examples.
• Cut core lazy initialValue unless implementation is tiny; lazy docs are enough for the current problem.
• Cut safe URL and UI overlay callbacks from this architecture lane.

Plan delta from pass 6:

• Execution order changes to:
  1. renderer capability and render docs
  2. command/rule routing and editing examples
  3. rendering strategy normalization
  4. conditional projection overload
  5. docs-first lazy initialization
• Projection overload is no longer a required closure item.
• Core lazy initialValue is no longer required for closure.
• Performance proof now requires cohorts, repeated-unit budgets, interaction rows, memory/DOM tags, and native behavior classification for degraded modes.

Pass 6 score update:

Weighted score: 0.82.

Slate Maintainer Objection Ledger

Status: complete.

This pass asks the uncomfortable question first: would a serious Slate maintainer reject this as a slow drift from unopinionated primitives into a framework? Some objections are real. The plan survives only where the answer is stronger than "cleaner examples".

Rejected after objection review:

• "Remove every example useCallback / useMemo": too broad and wrong.
• "Make raw Slate core own React renderers": wrong owner.
• "Ship a central product input-rule registry": Plate/plugin territory.
• "Use React Compiler as the answer": not a library contract.
• "Claim old issues from architecture cleanup alone": overclaiming.

Pass 7 score update:

Weighted score: 0.86.

High-Risk Deliberate Pass

Status: complete.

High-risk trigger: this plan changes public Slate React API guidance, render contracts, command/rule routing, browser-native input behavior, docs/examples, and migration substrate expectations. It is additive on paper, but it touches the exact places where editor regressions are expensive: typing, selection, IME, paste, undo, rendering breadth, and downstream plugin authors.

Live API refresh used for this pass:

• EditableDOMRootProps still exposes inputRules, renderingStrategy, onDOMBeforeInput, onCommand, and onKeyDown in .tmp/slate-v2/packages/slate-react/src/components/editable.tsx.
• EditableTextBlocks still forwards renderElement, renderLeaf, renderText, renderSegment, and renderVoid, and memo comparison still includes renderer identity in .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx.
• runtime-root-engine.ts still derives effective input rules from inputRules prop identity and owns Android/native input routing.
• useSlateAnnotationStore and useSlateWidgetStore still refresh from array identity.
• CreateEditorOptions.initialValue is still value-only while Editor also has lazy initializer typing elsewhere.

Blast Radius

Three-Scenario Pre-Mortem

High-Risk Rows

Expanded Proof Plan

Rollback And Remediation

• Renderer registration rollback: keep raw render docs and remove the new docs recommendation before cutting raw props. Raw props are the recovery path.
• Command/rule rollback: keep onKeyDown and onDOMBeforeInput documented and tested; do not migrate an example if the semantic route cannot express it.
• Rendering strategy rollback: revert to internal identity memo only if primitive normalization distorts metrics.
• Projection rollback: do not land the overload unless it is tiny and generic.
• Lazy initialization rollback: docs use lazy useState; core public API stays value-only unless the implementation is proven boring.
• Issue rollback: no claims move before pass 11, so bad planning cannot create public issue debt.

Pass 8 decision: keep the plan, but split optional projection and drop required core lazy initialization. The release-quality target is now:

1. Renderer registration and render docs.
2. Command/rule routing and editing examples.
3. Rendering strategy primitive normalization.
4. Optional projection only after tiny generic proof.
5. Docs-first lazy initialization.

Pass 8 score update:

Weighted score: 0.88.

Ecosystem Maintainer Pass

Status: complete.

This pass treats the plan as if Plate, slate-yjs, legacy Slate, and the major editor ecosystems had to live with it. Verdict: keep the plan, but the execution handoff must be stricter about feature ownership and metadata. The dangerous version of this plan is "nice examples with a big new Slate React API." The acceptable version is "small Slate React primitives that make Plate and collaboration easier without absorbing their policy."

Ecosystem evidence refreshed:

• Plate current source exposes plugin-owned api, tf, plugin lists, handler, render, decorate, and input-rule metadata in ../plate/packages/core/src/react/editor/PlateEditor.ts and ../plate/packages/core/src/react/editor/withPlate.ts.
• Plate autoformat is now explicitly inert/deprecated and says new behavior belongs in feature-owned inputRules in ../plate/packages/autoformat/src/plugin.ts.
• slate-yjs current source depends on local/remote origins, operation batching, stored relative positions, and history selection snapshots in ../slate-yjs/packages/core/src/plugins/withYjs.ts, ../slate-yjs/packages/core/src/utils/position.ts, and ../slate-yjs/packages/core/src/plugins/withYHistory.ts.
• Slate v2 current source already exposes editor.read, editor.update, extension state/tx, commands, commit listeners, metadata, operations, bookmarks, and selection impact metadata in .tmp/slate-v2/packages/slate/src/interfaces/editor.ts.
• Lexical confirms command listeners, dirty node tracking, root/decorator/update listeners, and read/update lifecycle are worth stealing structurally.
• ProseMirror confirms transactions should own document changes, selection, stored marks, metadata, paste/input tags, scroll intent, and the DOM selection bridge.
• Tiptap confirms extension-owned commands, keyboard shortcuts, input rules, paste rules, and React selector posture are good DX, but its chain-first command surface is not the raw Slate target.
• React 19.2 compiled evidence keeps useSyncExternalStore and background UI as projection/overlay tools, not editor-core invalidation.

Maintainer Lenses

Plan Deltas From Ecosystem Review

Accepted deltas:

• Add a hard constraint that command/rule execution preserves update metadata, origins, operation batching, and selection/history snapshots.
• Strengthen the Plate migration target: Slate React provides primitives Plate can consume; it does not mimic Plate api/tf or ship Plate product policy.
• Strengthen the docs target: raw handlers/render props are valid reference APIs, not deprecated paths.
• Keep optional projection split out of release blockers because slate-yjs cares about durable anchors and source dirtiness, not a comment-example overload.
• Require browser-native proof to remain a closure blocker, even though the API direction is now ecosystem-consistent.

Rejected deltas:

• Do not move rich Markdown, table, URL, mention, toolbar, or paste policy into raw Slate React.
• Do not make editor.commands or chain-style Tiptap APIs the public raw Slate shape.
• Do not make renderer registration a replacement for raw render props.
• Do not make React Compiler, useCallback, or useMemo part of the public correctness story.
• Do not claim slate-yjs readiness from React projection improvements.

Ecosystem Closure Matrix

Pass 9 score update:

Weighted score: 0.90.

Revision Pass

Status: complete.

This pass folded the accepted deltas from passes 6 through 9 back into the front of the plan so the handoff does not lie by omission. The earlier draft still made projection and lazy initialValue sound more central than the later review allowed. That is fixed.

Coherence review:

Scope review:

Final execution handoff shape for ralph:

1. Renderer registration and render docs.
2. Command/rule routing and editing examples, preserving command/update metadata, origins, operation batching, selection/history snapshots, and raw handler fallback.
3. Rendering strategy primitive normalization.
4. Docs-first lazy initialization with lazy useState.
5. Optional projection overload only if implementation proves it is tiny, generic, metadata-safe, and better than a shared helper.
6. Opportunistic safe URL/helper and trivial callback cleanup only after the architecture rows.

Pass 10 score update:

Weighted score: 0.91.

Completion

This planning lane is complete. The old keydown-only plan is now a subset of this broader memoization hard-cut plan.

Issue Sync Accounting Pass

Status: complete.

Read evidence:

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

Issue sync result:

Claim changes:

• New Fixes claims: 0.
• New Improves promotions: 0.
• Fixed/improved demotions: 0.
• Manual sync ledger changes: 0.
• Coverage matrix changes: 0.
• Fork dossier changes: 0.
• PR reference changes: 0.

pr-description unchanged: this pass changes the execution plan and proof expectations only. It changes no exact fixed issue claim, accepted public API shape in the PR reference, proof status, release gate, example row, or maintainer-facing PR narrative.

Closure Score And Final Gates

Status: complete.

Final score:

Weighted score: 0.92.

Final gate audit:

• pass schedule: complete
• pass-state ledger: complete
• issue sync accounting: complete with no claim changes
• PR reference sync: unchanged with reason recorded
• objection ledger: accepted or downgraded into plan deltas
• high-risk deliberate mode: complete
• ecosystem maintainer pass: complete
• final execution handoff: complete
• final user-review handoff: complete
• Slate v2 verification claim: no implementation behavior claim is made from this planning pass; execution proof is assigned to ralph

Done Handoff

Slate Ralplan is ready for user review: docs/plans/2026-05-14-slate-v2-example-memoization-hard-cut-ralplan.md

Decisions:

• Public API: add Slate React renderer registration/capability for element, leaf, text, and segment rendering; raw render props remain public escape hatches.
• Public API: keep renderElement, renderLeaf, renderText, and renderSegment; stop teaching user useCallback as the beginner fix for renderer identity.
• Public API: keep onCommand as the clean semantic command boundary; do not rename to onEditableCommand.
• Public API: do not add a raw Slate command catalog or Tiptap-style chain API.
• Editing behavior: move table, markdown, format, paste, Enter, Backspace, and Delete example behavior toward command/rule capabilities where Slate React owns routing mechanics.
• Editing behavior: keep raw onKeyDown, onDOMBeforeInput, and paste handlers as supported advanced escape hatches, with fallback tests.
• Editing behavior: runtime owns Android pending diff flushing if the command and rule path touches that behavior.
• Input rules: keep rule machinery primitive and feature-owned; Plate/plugin packages own rich markdown, table, link, mention, toolbar, and product rule families.
• React/runtime: normalize renderingStrategy option objects by primitive fields so examples can inline equivalent objects without identity churn.
• React/runtime: remove memoization from public examples only where Slate React owns identity; keep real app UI, overlay, benchmark, and test-harness memoization where it is an implementation detail.
• Projection: split/defer projector overloads; land only if the overload is tiny, generic, metadata-safe, avoids broad reprojection, and beats a shared helper.
• Projection: do not claim projection improvements imply slate-yjs readiness; React projections remain local runtime facts.
• Initialization docs: replace one-shot useMemo(..., []) localStorage reads with lazy useState.
• Initialization API: do not add core lazy initialValue just to clean one walkthrough; only accept it if implementation proves it is tiny and already safe.
• Docs: beginner rendering docs should teach renderer registration or top-level stable components first; raw render props stay documented as valid control surfaces.
• Docs: performance docs should describe library-owned identity and proof gates, not push callback stabilization as normal user ceremony.
• Weak cuts: URL sanitization helpers in embeds, paste-html, and inlines stay app/example utilities, not Slate core or Slate React API.
• Weak cuts: mentions popup keydown, iframe blur, debug buttons, and huge-doc controls remain app/demo UI state, not library-owned architecture.
• Plate migration: expose primitive renderer/rule/command shapes that Plate can package, without copying current Plate editor.api / editor.tf naming into raw Slate.
• slate-yjs migration: preserve update metadata, origins, operation batching, durable anchors, and selection/history snapshots through command/rule work.
• Browser proof: require native input, IME-sensitive beforeinput, Android pending diff if touched, paste, select-all/copy, and staged/virtualized degraded-mode classification before implementation closure.
• Performance proof: require repeated-unit budgets for unchanged block, text, leaf, event listener count, rule dispatch cost, strategy metric stability, and projection refresh count if projection lands.
• TDD proof: first red tests should cover renderer registration/raw escape hatch, command latest-handler/fallback semantics, input-rule order/fallback, rendering-strategy primitive normalization, and docs grep.
• Issue accounting: no new Fixes or Improves claims from this planning pass.
• Issue accounting: keep #5181, #4317, #5961, #5928, #5994, #5987, #4483, #3382, #3352, #3656, #4141, #2051, #790, #2465, #6016, #4268, and #2560 at their current related/improves/non-claim statuses until execution proof changes them.
• Issue accounting: keep existing fixed claims #6013, #5605, #5709, and #4569 unchanged; this plan must not broaden them.
• Hard cut: do not start with safe URL cleanup; it is easiest and least important.
• Hard cut: do not delete every useCallback / useMemo; only cut the ones caused by missing Slate React ownership.
• Hard cut: do not put product behavior in raw Slate React to make examples prettier.
• Execution order: renderer registration and render docs first.
• Execution order: command/rule routing and editing examples second.
• Execution order: rendering strategy primitive normalization third.
• Execution order: docs-first lazy initialization fourth.
• Execution order: optional projection fifth, only if it earns its API weight.
• Execution order: opportunistic helper/trivial callback cleanup last.

Ralph Execution Ledger

Status: done Runtime state: active goal state Continuation prompt: active goal state

Activation:

• 2026-05-14: User invoked $ralph for the full plan.
• Thread goal set around the desired Slate v2 end state.
• Completion state reopened from planning done to Ralph execution pending.

Execution slices:

• ralph-execution-slice-1-renderer-registration-and-docs: complete. Added editableRenderers(...), consumed registered renderers in Editable, and moved beginner docs away from useCallback renderer guidance.
• ralph-execution-slice-2-command-rule-routing: complete. Added editableKeyCommands(...), made onCommand keydown-complete, and moved strong command/rule examples off memoized callback props.
• ralph-execution-slice-3-rendering-strategy-normalization: complete. Normalized rendering-strategy option objects by primitive fields and removed the example renderingStrategy memo.
• ralph-execution-slice-4-lazy-initial-value-docs: complete. Replaced localStorage one-shot useMemo docs with lazy useState.
• ralph-execution-slice-5-optional-projection-overload-review: complete. Added generic projector overloads to annotation/widget hooks and removed projection-array useMemo from comment examples.
• ralph-execution-slice-6-opportunistic-weak-cut-cleanup: complete. Moved iframe, images, and richtext hotkeys to registered key commands; left URL parsing, popup keys, cursor movement, and demo controls app-owned.
• ralph-execution-slice-7-reference-and-issue-accounting-sync: complete. Synced PR reference and issue ledgers without adding fixed/improved claims.
• ralph-execution-slice-8-final-verification: complete. Added the missing core bookmark replace_children fix/regression needed by the projection overload, then ran package, typecheck, lint, and scoped browser proof.

Closeout:

• completion-closeout
• Owner: .tmp/slate-v2 package, site, lint, browser, and plate-2 checkpoint gates.
• Result: scoped checkpoint set to done after all in-scope implementation, reference sync, compound note, and verification gates closed.

Final verification:

• Green: cd /Users/zbeyens/git/slate-v2/packages/slate && bun test ./test/bookmark-contract.ts ./test/collab-canonical-reconcile-contract.ts ./test/collab-bookmark-position-contract.ts (18 passed).
• Green: cd /Users/zbeyens/git/slate-v2/packages/slate-react && bun test:vitest test/annotation-store-contract.test.tsx test/widget-layer-contract.test.tsx test/surface-contract.test.tsx test/keyboard-input-strategy-contract.test.ts (46 passed).
• Green: cd /Users/zbeyens/git/slate-v2 && bun --filter slate typecheck.
• Green: cd /Users/zbeyens/git/slate-v2 && bun --filter slate-react typecheck.
• Green: cd /Users/zbeyens/git/slate-v2 && bun typecheck:site.
• Green: cd /Users/zbeyens/git/slate-v2 && bun typecheck:root.
• Green: cd /Users/zbeyens/git/slate-v2 && bun lint:fix.
• Green: cd /Users/zbeyens/git/slate-v2 && PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun run playwright playwright/integration/examples/persistent-annotation-anchors.test.ts --project=chromium (1 passed).
• Green: cd /Users/zbeyens/git/slate-v2 && PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun run playwright playwright/integration/examples/code-highlighting.test.ts playwright/integration/examples/markdown-shortcuts.test.ts playwright/integration/examples/inlines.test.ts playwright/integration/examples/tables.test.ts playwright/integration/examples/iframe.test.ts playwright/integration/examples/images.test.ts playwright/integration/examples/collaborative-comments.test.ts playwright/integration/examples/review-comments.test.ts playwright/integration/examples/persistent-annotation-anchors.test.ts --project=chromium (56 passed).
• Green: cd /Users/zbeyens/git/slate-v2 && PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun run playwright playwright/integration/examples/rendering-strategy-runtime.test.ts playwright/integration/examples/richtext.test.ts --project=chromium -g "keeps DOM-owned text sync explicit and opt-out safe|proves DOM-present rendering-strategy input can use real browser-native typing|renders the full TanStack-backed experimental virtualized example with bounded DOM|exposes TanStack-backed experimental virtualized controls and warning|applies mark hotkeys to inserted rich text and clears active marks|applies block, alignment, and clear-formatting hotkeys|records core command metadata for keydown movement|records kernel policies for browser command and repair traces|records a soft break command for Shift\\+Enter" (9 passed).
• Residual out-of-scope: the broader browser sweep over the same files produced 168 passed, 3 skipped, and 5 failed; rerun narrowed this to 4 deterministic IME/native composition rows, while the native word-delete row passed on rerun. Those failures are not renderer registration, key-command routing, rendering-strategy option identity, projection, or bookmark-anchor proof.