Slate v2 Render Path Prop Performance Ralplan

Date: 2026-05-12

Status: done

Owner: slate-ralplan

Completion: active goal state

Current Verdict

No, the current render path prop is not the absolute-best architecture.

This plan is ready for execution. The current implementation is not done; the planning decision is done.

The runtime architecture is right: mounted nodes are keyed by stable runtime ids, root-order commits can update root runtime-id lists without notifying every mounted node, and current live reads can resolve a runtime id back to the latest path.

The public render contract is the weak point. RenderElementProps currently exposes eager path and index, and renderVoid exposes eager path. A Path is a moving tree address. If a block is inserted before mounted siblings, Slate has only two choices when eager path is public:

• re-render every shifted mounted sibling so app props, context, weak maps, and DOM path metadata stay fresh;
• skip those renders and risk stale path props / handlers / metadata.

Neither is the best Slate v2 shape.

Accepted target: hard-cut eager path and index from public render props. Keep Slate-close DX through lazy current-path APIs:

• event-time ReactEditor.findPath(editor, element) / equivalent must resolve by runtime id first, not by stale weak-map indexes;
• add an opt-in useElementPath() only for render-time path-dependent UI;
• keep runtime-owned DOM path metadata as debug/fallback, not the public render contract;
• prove leading insert before mounted blocks does not fan out React renders and still resolves current paths correctly.

Intent Boundary

Live Source Evidence

Verification run from /Users/zbeyens/git/slate-v2:

bun test ./packages/slate-react/test/provider-hooks-contract.tsx -t "Editable root-order commits do not fan out to every mounted runtime node"

Result: pass.

bun test ./packages/slate-react/test/surface-contract.tsx -t "useElementSelected remains stable when the selected element path shifts after structural edits"

Result: pass.

Decision Brief

Principles:

• Path is a current address, not stable identity.
• Runtime identity should own mounted-node continuity.
• Default render props must be cheap and hard to misuse.
• Slate-close DX should remain available through event-time helpers.
• Correctness cannot depend on full-sibling rerenders after structural inserts.

Top drivers:

• Leading insert before many mounted siblings shifts every following path.
• React render fanout is the exact performance class v2 is trying to eliminate.
• App renderers commonly close over props in callbacks, so stale eager path is a real correctness footgun.

Options:

Chosen option:

Hard-cut eager path and index from RenderElementProps, and hard-cut eager path from RenderVoidProps. Add lazy current-path APIs only where needed.

Consequences:

• renderElement becomes closer to legacy Slate: attributes, children, element, plus v2-specific isInline / slots if kept.
• Examples that mutate the current node must resolve path inside the event handler, not close over render-time path.
• Path-dependent display can opt into useElementPath(), and only those nodes rerender on path shifts.

Public API Target

Target render element props:

type RenderElementProps<TElement extends Element = Element> = {
  attributes: RenderElementAttributes;
  children: ReactNode;
  element: TElement;
  isInline: boolean;
  slots: EditableElementSlots;
};

Target render void props:

type RenderVoidProps<TElement extends Element = Element> = {
  element: TElement;
};

Target path APIs:

const path = ReactEditor.findPath(editor, element);
const path = useElementPath();

Rules:

• ReactEditor.findPath(editor, element) is the event-time/default API.
• useElementPath() is opt-in render-time UI state and may rerender when the current path changes.
• Do not expose runtime id as normal app DX unless a lower-level unstable hook is needed for internal tests.
• Do not keep index; it is just path.at(-1) with the same invalidation problem.

Internal Runtime Target

Implementation target for later ralph:

1. Add runtime-id tracking for mounted Slate nodes, for example an internal NODE_TO_RUNTIME_ID weak map populated by the node ref / render binding.
2. Make DOMEditor.findPath(editor, node) prefer:
   • runtime id from the node weak map;
   • Editor.getPathByRuntimeId(editor, runtimeId);
   • existing NODE_TO_PARENT / NODE_TO_INDEX fallback only when runtime id is unavailable.
3. Keep NodeRuntimeIdContext as the internal identity context.
4. Replace ElementPathContext public reliance with lazy path resolution.
5. Make DOM-to-Slate point/range conversion runtime-id-first where the DOM node exposes data-slate-runtime-id; data-slate-path remains fallback/debug.
6. Do not notify all runtime-node subscribers merely to refresh public path props.

Hook / Component DX Target

Keep:

• useElement() for current element access.
• useElementSelected() but make its no-arg mode resolve from runtime id or runtime-id-backed findPath, not stale context path.
• ReactEditor.findPath(editor, element) as the Slate-close path read.

Add or revise:

• useElementPath(): Path | null for opt-in render-time path display or path-derived UI.
• docs/examples rule: resolve path inside event handlers before mutating.

Cut:

• RenderElementProps.path
• RenderElementProps.index
• RenderVoidProps.path
• public teaching that spreads data-slate-path as if it is app state

Ecosystem Strategy Synthesis

Issue Ledger Accounting

ClawSweeper related-issue pass: skipped for this pass because cached issue ledgers already cover the rerender-breadth and path-stability surface, and this planning pass makes no new fixed issue claim.

Live ledger rows read from docs/slate-issues/gitcrawl-live-open-ledger.md:

• #3656 leaf rerender pressure.
• #4141 nested ancestor rerender pressure.
• #4210 general rerender prevention.
• #3748 wrap/unwrap parent rerender pressure.
• #2051 leaf-level rerender pressure.

Manual v2 sync ledger status:

• unchanged; existing rows remain Improves, Related, cluster-synced, or Not claimed according to current proof.

Issue matrix:

PR reference sync:

• pr-description unchanged: no fixed issue claim, public PR body, release gate, or accepted API line is changed by this planning-only pass yet.

Regression Proof Matrix

Applicable Implementation Skill Review Matrix

High-Risk Deliberate Mode

Triggered because this changes public render API and browser/path runtime.

Pre-mortem:

1. Apps lose convenient path and overuse useElementPath(), recreating broad path-shift rerenders.
2. Runtime-id-first findPath misses a mounted node and falls back to stale weak maps.
3. Browser tests using [data-slate-path] pass in simple cases but fail after structural shifts.

Proof plan:

• public-surface contract fails if RenderElementProps or RenderVoidProps still expose eager path / index;
• React contract counts render events and selector notifications for leading insert before mounted siblings;
• DOM bridge contract proves findPath returns the shifted current path after a skipped-rerender root-order commit;
• Playwright/browser contract proves click/type on shifted DOM resolves current model path;
• examples compile after migration to event-time path resolution.

Rollback / hard-cut answer:

The hard cut is worth it before publish because keeping eager path either forces exactly the sibling-wide render fanout v2 is designed to avoid or leaves stale public props. A compat alias would preserve the footgun.

Slate Maintainer Objection Ledger

Implementation Phases For Ralph

Phase 1: Red Contracts

Files:

• .tmp/slate-v2/packages/slate-react/test/provider-hooks-contract.tsx
• .tmp/slate-v2/packages/slate-react/test/rendered-dom-shape-contract.tsx
• .tmp/slate-v2/packages/slate-dom/test/bridge.ts
• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx

Add tests:

1. leading insert before 1000 mounted blocks does not notify every runtime-node selector and does not rerender every shifted sibling;
2. event handler on a shifted custom element resolves current path after a leading insert;
3. DOMEditor.findPath returns current path after root-order shift without requiring shifted-node React rerender;
4. public type surface rejects RenderElementProps.path, RenderElementProps.index, and RenderVoidProps.path.

Phase 2: Runtime-Id-First Path Resolver

Files:

• .tmp/slate-v2/packages/slate-dom/src/utils/weak-maps.ts
• .tmp/slate-v2/packages/slate-dom/src/plugin/dom-editor.ts
• .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-node-ref.tsx
• .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx

Implement:

• internal node-to-runtime-id mapping;
• DOMEditor.findPath runtime-id-first;
• DOM-to-model conversion runtime-id-first where possible;
• keep weak-map fallback.

Phase 3: Public Render Prop Hard Cut

Files:

• .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx
• .tmp/slate-v2/packages/slate-react/src/index.ts
• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx
• .tmp/slate-v2/packages/slate/test/public-surface-contract.ts

Implement:

• remove path / index from EditableRenderElementProps;
• remove path from EditableRenderVoidProps;
• remove ElementPathContext from public path freshness duties or keep it internal-only until replaced;
• add useElementPath() if render-time path display needs a public hook.

Phase 4: Example Migration

Files to inspect first:

• .tmp/slate-v2/site/examples/ts/check-lists.tsx
• .tmp/slate-v2/site/examples/ts/images.tsx
• .tmp/slate-v2/site/examples/ts/embeds.tsx
• .tmp/slate-v2/site/examples/ts/inlines.tsx
• any RenderElementPropsFor<...> custom example types.

Migration rule:

• do not close over path from render props;
• resolve current path inside event handlers with ReactEditor.findPath.

Phase 5: Browser / Benchmark Proof

Commands:

cd /Users/zbeyens/git/slate-v2
bun test ./packages/slate-react/test/provider-hooks-contract.tsx
bun test ./packages/slate-react/test/surface-contract.tsx
bun test ./packages/slate-react/test/rendered-dom-shape-contract.tsx
bun test ./packages/slate-dom/test/bridge.ts
bun run bench:react:rerender-breadth:local

Add a focused browser row if any DOM-to-model path changes affect examples:

cd /Users/zbeyens/git/slate-v2
bun playwright test playwright/integration/examples/check-lists.test.ts --project=chromium

Closure Pass

Closure reviewed the first pass and changed the status from pending to done because the remaining gaps are implementation gates owned by ralph, not missing planning decisions.

The Ralph execution pass is complete. The current v2 implementation no longer exposes eager render path / index props.

Scorecard

Weighted total: 0.93.

Planning status: done. Implementation status: done.

Pass-State Ledger

Ralph Execution Gates

• Red contracts exist for leading insert before shifted mounted siblings.
• Public type surface no longer exposes eager render path / index.
• editor.dom.findPath is runtime-id-first and current after skipped-rerender structural shifts.
• Examples no longer close over render-time path.
• Focused tests and rerender breadth benchmark pass from .tmp/slate-v2.
• Browser rows for touched example behavior pass; the unrelated check-list Backspace row remains a separate failure.

Final Completion Gates

• Planning artifacts have a current verdict, intent boundary, decision brief, rejected alternatives, source-backed current state, issue accounting, regression matrix, implementation phases, and ralph gates.
• Completion file can be done because no further Slate Ralplan decision is missing and the Ralph execution gates passed.