Slate v2 React / Decorations Slate Issues Ralplan

1. Current Verdict

Status: done after pass 12.

This should be one combined architecture lane, not two loose plans:

• React runtime: provider identity, editor replacement, committed snapshot publishing, selector subscriptions, focus lifecycle, and rerender breadth.
• Decorations / marks / annotations: transient projections, render-time marks, durable anchors, annotation stores, widget stores, source-scoped invalidation, and selection/IME fallout from overlay DOM changes.

Hard take: do not rebuild legacy decorate as the center of the universe. The current v2 source already has the right backbone: selector-first React runtime, runtime-id projection stores, product-noun decoration sources, and annotation stores. The remaining planning work is issue-corpus accounting, external evidence synthesis, proof thresholds, and deciding exactly where the public API should stay Slate-close versus where source/store APIs become the scalable path.

Pass 1 completed the current-state read and initial score. Pass 2 completed bounded ClawSweeper related-issue discovery for the combined React runtime plus decorations / marks / annotations surface. Pass 3 completed the full issue-ledger pass for plan-relevant rows and kept the claim boundary conservative. Pass 4 hardened the intent, non-goals, package boundaries, and decision brief against the pass-3 issue matrix. Pass 5 completed the ecosystem steal/reject/diverge synthesis. Pass 6 completed performance, DX, migration, regression, and simplicity proof pressure. Pass 7 completed the maintainer objection ledger and accepted revisions. Pass 8 completed the high-risk pre-mortem and proof expansion. Pass 9 completed ecosystem maintainer pressure across React, Slate, Plate, slate-yjs, Lexical, ProseMirror, and Tiptap. Pass 10 merged the accepted review deltas into the executable targets, phases, proof gates, and score caps. Pass 11 completed issue-sync accounting without promoting any issue claims and synced the PR reference to the accepted public API and proof wording. Pass 12 closed the planning lane at 0.92 and assigned implementation-only risk to later ralph slices. Completion is done for Slate Ralplan planning. This is not a release or implementation-complete claim.

2. Intent And Boundary

Intent:

• create one execution-grade plan for the React runtime plus decorations / marks / annotations issue surface, not one plan per issue cluster;
• decide the owner boundary for each issue family before implementation starts;
• keep raw Slate unopinionated while still giving serious applications a scalable overlay substrate;
• avoid planning per issue cluster;
• use existing completed React-runtime and decoration plans as evidence, not as current mutable owners;
• keep exact issue closure language tied to proof, not architectural optimism.

Desired outcome:

• one ralph-ready implementation plan with issue classifications, proof routes, and no stale public API claims;
• an API decision map that says which user-facing shapes are simple, advanced, or internal;
• a proof map that separates package tests, browser rows, benchmarks, and raw-device/mobile rows;
• exact fixed issue claims only where current proof can auto-close the original repro;
• performance claims tied to benchmarks and browser/user-path rows, not hook vibes.

In scope:

• .tmp/slate-v2/packages/slate-react provider, selectors, projection stores, decoration sources, annotation stores, widget stores, render leaf/text behavior, and examples/tests that prove them;
• .tmp/slate-v2/packages/slate mark, range, anchor, runtime-id, and commit metadata only where React projection depends on them;
• .tmp/slate-v2/packages/slate-dom only where decorated or annotated DOM shape affects selection, focus, browser range translation, or input timing;
• React runtime issue rows under docs/slate-issues;
• decoration, mark, annotation, and overlay issue rows under docs/slate-issues;
• Plate/slate-yjs migration-backbone pressure only at substrate level.

Non-goals:

• no broad Slate core rewrite inside this lane;
• no product comment system in raw Slate;
• no revival of current-version Plate APIs as raw Slate requirements;
• no raw mobile/IME closure from desktop React tests;
• no exact closure for external Redux/MobX/debugger/HMR reports without current repro proof;
• no legacy decorate compatibility quest that drags the scalable path back into global invalidation;
• no table, clipboard, history, docs, or examples work unless it directly changes the React projection/overlay proof contract.

Decision boundaries:

• slate-react owns React projection, selector fanout, focus lifecycle, external-store integration, decoration sources, annotation/widget stores, and render delivery.
• slate owns committed snapshots, runtime ids, mark/range semantics, anchor identity, dirty metadata, and transaction state.
• slate-dom owns DOM range/selection truth, browser point mapping, focus repair, and input/composition proof when overlay DOM shape affects editing.
• Product layers own comment workflows, suggestions, permissions, collaboration services, and opinionated toolbar/editor UX.
• Broad hooks can stay broad by contract. Hot paths must use selectors, runtime-id subscriptions, or source/annotation stores.
• Exact issue claims require the original issue class to be replayed by the right proof owner: package test, browser row, benchmark, or device lane.

Weakest-boundary pressure test:

• #2465/#2564 could tempt us to redesign marks/inlines as a rich product component system. Do not do that here. This lane may require better mark payload and render projection semantics, but it must not turn raw Slate into a link/comment/mention framework.
• #4993/#4997 could tempt us to expose the entire projection engine as the new public API. Also no. The user-facing path should stay simple first: decorate for basic transient ranges, source stores for high-churn overlays, annotation stores for durable anchors, projection transport for advanced or internal use.

Unresolved user-decision points:

• none for pass 11. The next work is closure scoring and final handoff.

3. Current-State Read

Prior plans to reuse as evidence:

• docs/plans/2026-05-04-slate-v2-clawsweeper-v2-react-runtime-ralplan.md is already done for v2-react-runtime.
• docs/plans/2026-04-28-slate-v2-decoration-annotation-rewrite-review-plan.md is already done for decoration/annotation architecture review.
• docs/plans/2026-04-30-slate-v2-decoration-annotation-api-ralplan.md is already done for annotation/comment API shape.
• This plan is a new combined slate-issues consolidation lane. Do not reopen those done plans as mutable state.

Live Slate v2 source shape:

• <Slate> currently accepts editor, decorationSources, annotationStore, and change callbacks in .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:63-74.
• <Slate> subscribes to editor commits, batches focused state, DOM text sync, change callbacks, and selector dispatch in .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:108-172.
• <Slate> composes decoration sources and the annotation projection store in .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:175-184.
• Provider stack publishes selector, projection, annotation, editor, and focus contexts in .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:216-228.
• useEditorSelector supports equality, runtime id, deferred fanout, and shouldUpdate in .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selector.tsx:68-151.
• Selector fanout dedupes runtime-id listeners and skips stale mounted-node fanout for certain root changes in .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selector.tsx:212-330.
• Projection store has dirtiness, runtimeScope, sourceId, source/runtime subscribers, metrics, and refresh options in .tmp/slate-v2/packages/slate-react/src/projection-store.ts:31-100.
• Projection dirty matching understands selection, text, mark, node, annotation, and external classes in .tmp/slate-v2/packages/slate-react/src/projection-store.ts:206-243.
• Decoration sources are product-noun wrappers over projection stores in .tmp/slate-v2/packages/slate-react/src/decoration-source.ts:111-129.
• Multiple overlay sources are composed through runtime snapshot and runtime-id subscriptions in .tmp/slate-v2/packages/slate-react/src/decoration-source.ts:131-204.
• Annotation stores carry id, anchor, data, projection payload, annotation subscriptions, and projection store output in .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:13-87.
• Annotation refresh can target ids and avoid full fallback when candidates are known in .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:215-267 and .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:332-420.
• Annotation projection tracks changed runtime buckets, annotation subscribers, and metrics in .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:664-742.
• Annotation external refresh accepts ids and treats [] as no-op in .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:761-767.
• Editable text consumes projection slices and passes them into segmented renderLeaf / renderText output in .tmp/slate-v2/packages/slate-react/src/components/editable-text.tsx:324-441.

Focused current verification:

• cwd: .tmp/slate-v2
• command: bun test ./packages/slate-react/test/provider-hooks-contract.tsx ./packages/slate-react/test/projections-and-selection-contract.tsx ./packages/slate-react/test/annotation-store-contract.tsx ./packages/slate-react/test/widget-layer-contract.tsx ./packages/slate-react/test/render-profiler-contract.test.tsx
• result: 40 pass, 0 fail, 200 expect() calls.
• cwd: plate-2
• command: pnpm lint:fix
• result: passed; no fixes applied.
• cwd: plate-2
• command: bun run completion-check -- --file .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• result: expected failure because the active completion file is pending after pass 5.

Initial read result:

• already done in live source: editor replacement/context update proof exists.
• already done in live source: selector hooks receive commit facts and can avoid broad updates.
• already done in live source: decoration sources and projection stores are runtime-id/subscriber based.
• already done in live source: annotation stores have id-targeted refresh and projection metrics.
• already done in plan: combined issue accounting was rerun in pass 3 for current React + decoration slate-issues.
• already done in plan: external editor synthesis was refreshed in pass 5 against current React/Lexical/ProseMirror/Tiptap evidence.
• gap: no final implementation phase list exists for this exact combined lane.

4. Initial Issue Surface

Pass 1 candidate set from the local slate-issues corpus:

Important issue evidence already found:

• docs/slate-issues/benchmark-candidate-map.md:139-165 says #4483 is a dynamic-decoration rerender benchmark, specifically global invalidation pain.
• docs/slate-issues/benchmark-candidate-map.md:361-387 says #5131 is a clean selection-driven subscription-granularity benchmark.
• docs/slate-issues/benchmark-candidate-map.md:390-416 says #4210 is the reusable selection/edit rerender breadth benchmark lane.
• docs/slate-issues/benchmark-candidate-map.md:486-510 says #2051 is the simple typing rerender breadth benchmark lane.
• docs/slate-v2/ledgers/issue-coverage-matrix.md:82-85 already records #3656/#4141 as Improves and #5131/#3430 as Not claimed.
• docs/slate-v2/ledgers/issue-coverage-matrix.md:132-146 already records #4483/#4477/#5987/#4392/#3382/#3352 as Improves.

Live ledger sync status:

• pass 2 discovery complete. No issue claim status changed in this pass. Full live ledger and coverage matrix updates are still owned by pass 3 and pass 11.

4.1 Pass 2 Related Issue Discovery / ClawSweeper

Status: complete.

Archive readiness:

• gitcrawl --version returned 0.2.1.
• gitcrawl doctor --json reported one local ianstormtaylor/slate corpus, 659 open threads, 617 clusters, last_sync_at: 2026-05-04T14:58:11.123944Z, and no GitHub token.
• Decision: use gitcrawl as local archive evidence; do not make fresh GitHub state, duplicate, stale, or closure claims from it.

Commands run:

gitcrawl threads --numbers 5709,4680,4165,5404,5131,3656,4141,4210,2051,3430 --include-closed --json ianstormtaylor/slate
gitcrawl threads --numbers 4483,5987,4993,4997,4392,3382,3352,3383,3309,3162 --include-closed --json ianstormtaylor/slate
gitcrawl threads --numbers 4712,4581,5398,5433,4750,4298,4225,2465,2564,4477,3478,3497,5509 --include-closed --json ianstormtaylor/slate
gitcrawl neighbors ianstormtaylor/slate --number 5709 --limit 5 --json
gitcrawl neighbors ianstormtaylor/slate --number 4483 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 5987 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 3383 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 4210 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 3309 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 5398 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 4750 --limit 12 --json
gitcrawl neighbors ianstormtaylor/slate --number 4477 --limit 12 --json
gitcrawl search ianstormtaylor/slate --query "render marks overlapping decorations" --mode hybrid --limit 20 --json
gitcrawl search ianstormtaylor/slate --query "useSlate selection rerender" --mode hybrid --limit 20 --json
gitcrawl search issues "dynamic decorations renderChildren renderText" -R ianstormtaylor/slate --state open --json number,title,state,url,updatedAt,labels --limit 20

Reviewed issue refs:

Important neighbor evidence:

• #5709 neighbors #4680, #5181, #5211, #3497, and #4323; only #5709 has current exact provider replacement proof in the existing matrix.
• #4483 neighbors #2051, #3382, #6033, #2465, #3656, and #2564; this confirms decoration perf, mark/render semantics, and legacy API topology are one pressure family, not one issue closure.
• #5987 neighbors PR #6033, #4560, #5274, #5433, #5826, and #3354; this makes async decoration/caret stability partly DOM selection and IME-adjacent.
• #3383 neighbors #2465, #2564, #4225, #3354, #4426, #3382, and #3151; the payload-collision issue is data-model/render policy pressure.
• #4210 neighbors #5274, #3656, #4141, #5433, #2051, #4225, and #5131; rerender breadth cannot be separated from selection/render timing.
• #5398 neighbors #5433, #5524, #4466, #3943, #3497, #5181, and #5023; this is composition/input runtime evidence, not a desktop React package-only claim.
• #4750 neighbors #3433, #4225, #4298, #3671, #3383, #4317, and #3568; mark query semantics need dedicated proof.

Fork issue dossier output:

• existing sections refreshed by reference/no-op: #5987, #3478, #3497, #5509, #4581, #3309, #2051, #5404, #3383, #4298, #4225, #4483, #4477, #4392, #3382, #3352.
• new concise sections appended for: #5709, #4680, #4165, #5131, #3656, #4141, #4210, #3430, #3162, #4712, #5398, #5433, #4750, #2465, #2564.

Plan delta:

• The combined lane remains valid.
• No fixed claim is promoted by pass 2.
• The plan must add an explicit pass-3 matrix for #4680/#4165/#4210/#3162/ #4712/#5398/#5433/#4750/#2465/#2564, because several are only matrix-only or dossier-missing today.
• Keep #5131 broad-hook behavior as an intentional non-claim unless pass 6 decides to change the public hook contract. That would be a real API decision, not a benchmark cleanup.
• Keep #5398/#5433/#3162 out of this plan's fixed-claim target; they inform browser proof and runtime boundaries, but exact closure belongs to the Mobile/IME lane.

4.2 Pass 3 Full Issue-Ledger Pass

Status: complete.

Sources scanned:

• docs/slate-issues/open-issues-ledger.md
• docs/slate-issues/gitcrawl-live-open-ledger.md
• docs/slate-issues/gitcrawl-clusters.md
• docs/slate-issues/issue-clusters.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/references/pr-description.md
• docs/slate-v2/decorations-annotations-cluster.md

Read-only extraction commands:

rg -n "#(5709|4680|4165|5404|5131|3656|4141|4210|2051|3430|4483|5987|4993|4997|4392|3382|3352|3383|3309|3162|4712|4581|5398|5433|4750|4298|4225|2465|2564|4477|3478|3497|5509|3354|4076|4317|3671|3568|3715|5274|4560|4001|3777|3634|5537|4961)\\b" docs/slate-issues docs/slate-v2 docs/plans tmp -g "*.md"
gitcrawl threads --numbers 4993,4997 --include-closed --json ianstormtaylor/slate
gitcrawl threads --numbers 4483,5987,3383,3354,2465,2564 --include-closed --json ianstormtaylor/slate
gitcrawl search ianstormtaylor/slate --query "4993 top level decorations Range intersection" --mode hybrid --limit 10 --json
gitcrawl search ianstormtaylor/slate --query "4997 decorations selector subscription cursor jumps" --mode hybrid --limit 10 --json

Corpus boundaries:

• The frozen ledger has 682 issue rows. The live gitcrawl mirror has 630 live-open issues, 29 PRs, 659 open threads, and 617 gitcrawl clusters from the 2026-05-04 refresh.
• open-issues-ledger.md owns full-corpus sync state. issue-coverage-matrix.md owns PR-slice claim accounting.
• The React runtime macro theme has 111 issues. The decorations / marks / annotations surface is 19 explicitly tagged rows plus adjacent selection, IME, and performance fallout.
• Pass 3 classified 44 plan-relevant rows. It did not promote any new exact Fixes #... claim.

Plan-relevant issue matrix:

Matrix-only / future-proof reconciliation:

Issue-ledger effect:

• No live ledger, coverage matrix, or PR reference claim changed in pass 3.
• Pass 11 still owns corpus-sync edits if later passes change claim state.
• The current plan now has enough issue accounting to move to intent/boundary hardening in pass 4.

5. Pass 4 Decision Brief

Principles:

• React is projection over committed Slate snapshots, not editor truth.
• Hot editor paths use selector/runtime-id/subscriber fanout, not broad context invalidation.
• Decorations, annotations, and widgets are separate public concepts even when they share projection plumbing.
• Marks are document/content semantics; projections are render-time overlay semantics.
• Exact issue closure requires replayable tests or benchmarks matching the issue.
• Public Slate APIs should stay boring for simple cases and explicit for high-churn cases.
• Product collaboration workflows are not raw Slate defaults.

Drivers:

• Pass 3 classified 44 plan-relevant rows and found no new exact fix claim.
• The issue corpus says runtime-boundary ownership dominates core-engine ownership: React, DOM, and input timing are the real pain center.
• Current source already has the right substrate: selector fanout, projection stores, decoration sources, annotation stores, and focused proof.
• The remaining risk is public API drift: either overexpose internals or keep legacy decorate too powerful.
• #4993/#4997 prove the failure is not just slow rendering. It is an invalid contract between external state, decoration invalidation, and selection timing.
• React 19.2 helps external-store consumption, but it cannot rescue a broad editor-wide invalidation contract.

Viable options:

Chosen target:

editor commit metadata
  -> React selector/runtime-id fanout
  -> decoration sources by source dirtiness and runtime scope
  -> annotation stores by changed annotation ids and runtime buckets
  -> render leaf/text receives projection slices
  -> benchmarks/browser rows decide exact issue claims

Consequences:

• decorate remains a simple Slate-close entry point, not the recommended high-churn overlay primitive.
• createDecorationSource becomes the scalable path for external or frequently changing transient overlays.
• Annotation stores own durable id-bearing anchors. Raw Slate does not ship a product comment workflow.
• Core mark/range work is allowed only when React projection cannot preserve payload, anchor, or selection semantics without it.
• DOM work is required only when overlay rendering changes browser selection, focus, point mapping, or input/composition behavior.
• Mobile/IME rows stay out of exact closure until the matching proof lane exists.

Follow-up owners:

6. Initial Confidence Score

Weighted total after pass 10: 0.92.

Why not higher:

• bench:react:huge-document-overlays:local was red during planning because the benchmark imported useSlateSelector, passed projectionStore to <Slate>, and created a bare editor. Ralph slice 1 repaired it to current APIs: useEditorSelector, decorationSources, and withReact(createEditor()).
• Browser/native behavior rows are specified but not run in this pass.
• Plate/slate-yjs migration substrate rows are defined but not proven against adapter code.
• Later implementation slices remain open. pass 10, not implementation closure.

Pass-10 score cap verdict:

• The plan can reach >= 0.92 before issue sync because the accepted objections, high-risk gates, and ecosystem demands are now merged into the executable plan rather than parked as commentary.
• This is plan confidence only. It does not mean implementation closure: issue-ledger sync, final handoff, and the later .tmp/slate-v2 implementation gates remain required.

7. Ecosystem Strategy Synthesis

Status: complete after pass 5.

Evidence read:

• React 19.2: docs/research/sources/editor-architecture/react-19-2-external-store-and-background-ui.md
• Lexical: docs/research/sources/editor-architecture/lexical-mark-store-and-decorator-split.md
• ProseMirror: docs/research/sources/editor-architecture/prosemirror-mapped-overlays-and-bookmarks.md
• Tiptap: docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md
• Local Slate v2: docs/research/sources/editor-architecture/slate-v2-local-proof-substrate.md
• Overlay invalidation decision: docs/research/decisions/slate-v2-source-scoped-overlay-invalidation.md
• Learnings: docs/solutions/logic-errors/2026-04-03-slate-react-v2-projection-proof-must-split-range-semantics-from-react-overlay-store.md and docs/solutions/performance-issues/2026-04-11-slate-v2-huge-document-typing-needs-selector-fanout-cuts-before-islands.md
• Live source refresh: .tmp/slate-v2/packages/slate-react/src/projection-store.ts, .tmp/slate-v2/packages/slate-react/src/decoration-source.ts, .tmp/slate-v2/packages/slate-react/src/annotation-store.ts, .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selector.tsx, .tmp/slate-v2/packages/slate-react/test/projections-and-selection-contract.tsx, and .tmp/slate-v2/packages/slate-react/test/annotation-store-contract.tsx.

Strategy:

Non-negotiable conclusion:

• The architecture is directionally right, not complete.
• ProjectionStore should stay advanced/internal transport by default.
• decorate stays the small classic path.
• Decoration sources are the scalable transient overlay path.
• Annotation stores are the durable id-bearing path.
• Widget stores stay separate from text ranges.
• The next serious tranche is source-scoped invalidation and proof, not another React hook wrapper.

7.1 Ecosystem Maintainer Pressure

Status: complete after pass 9.

Pass-9 evidence re-read:

• React 19.2 external-store and background UI research: docs/research/sources/editor-architecture/react-19-2-external-store-and-background-ui.md
• Lexical mark/store/decorator split: docs/research/sources/editor-architecture/lexical-mark-store-and-decorator-split.md
• ProseMirror mapped overlays and bookmarks: docs/research/sources/editor-architecture/prosemirror-mapped-overlays-and-bookmarks.md
• Tiptap extension command React DX: docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md
• local Slate v2 overlay proof substrate: docs/research/sources/editor-architecture/slate-v2-local-proof-substrate.md
• local Plate migration pressure from packages/suggestion, plugin resolver tests, docs/slate-v2/decorations-annotations-cluster.md, and prior Slate-v2 migration plans.

Maintainer pressure table:

Accepted pass-9 revisions:

• Pass 10 must add an ecosystem-proof checklist to the executable phases, not leave the owner table as commentary.
• Plate adapter proof must explicitly use public substrate nouns first. If it needs projection internals as the main API, the plan is not ready.
• slate-yjs proof must include remote edit mapping for bookmarks and annotation projection buckets, with mount state and product comment schema kept local or above raw Slate.
• Lexical and ProseMirror pressure keeps field-best performance claims capped until dirty/source/runtime impact facts and browser rows are green.
• Tiptap pressure requires docs/examples to be discoverable before execution: decorate first, scalable sources second, product examples above raw Slate, projection internals last.

Dropped ecosystem demands:

• Do not adopt Lexical node classes as Slate's public API.
• Do not adopt ProseMirror schemas/viewdesc as Slate's public API.
• Do not adopt Tiptap chain/commands as a second write engine.
• Do not make Plate or slate-yjs current adapter compatibility a raw Slate closure requirement.

Pass-9 verdict:

• Keep the plan and send it to revision.
• The architecture is strong enough to revise, but not ready for done: pass 10 must merge these ecosystem demands into the implementation phases and final handoff before issue sync.

8. Public API Target

Accepted after pass 10:

• keep classic decorate only for simple transient Slate-style ranges;
• keep createDecorationSource for scalable external/high-churn transient overlays;
• keep annotationStore / annotation hooks for durable id-bearing anchors;
• keep widget stores separate from decoration ranges;
• keep ProjectionStore, projection selectors, and projection-store metrics as advanced transport, not the beginner authoring surface;
• default huge-overlay benchmark repair path is useEditorSelector plus decorationSources;
• restore useSlateSelector or direct <Slate projectionStore={...}> only if the implementation phase produces an explicit public API audit, typed alias contract, and docs answer.

Docs/example order:

1. decorate for simple transient ranges.
2. createDecorationSource / decorationSources for high-churn or external transient overlays.
3. annotationStore, annotation hooks, and widget hooks for durable anchors and product-layer UI substrate.
4. Projection internals only on an advanced escape-hatch page.

9. Internal Runtime Target

Accepted after pass 10:

• selectors update from commit facts and runtime-id impact metadata;
• projection sources dirty by source class and runtime scope;
• annotation stores refresh by impacted annotation ids when possible;
• render text consumes projection slices without turning every text node into a broad React subscriber;
• source full refresh remains a safe fallback, not the steady-state perf story;
• source-scoped invalidation is the next implementation tranche: dirty source class, impacted runtime ids, source ids, annotation ids, and benchmark metrics must flow below React before any field-best performance claim.

10. Hooks / Components / Render DX Target

Accepted after pass 10:

• broad: useEditor for editor identity and static-ish access;
• narrow: useEditorSelector, useEditorState, useNodeSelector, useTextSelector, useSlateProjections, annotation/widget hooks;
• render: renderLeaf remains close to Slate terminology, but projection slices must preserve overlapping payloads without flattening metadata into one winner.

Docs should keep useDecorationSelector advanced. Normal app examples should start from decorate, decorationSources, annotation stores, and widget hooks.

11. Plate Migration-Backbone Target

Status: revised after pass 10.

Accepted substrate target:

• Plate can build product annotations, comments, suggestions, toolbars, and decorations on top of decoration/annotation/widget stores without wrapping every core call.
• Plate-specific overlay products do not become raw Slate API.
• Plate should consume raw Slate through: decorationSources, createDecorationSource, useSlateDecorationSource, annotationStore, useSlateAnnotationStore, useSlateAnnotations, useSlateWidgetStore, useSlateWidgets, Bookmark, and commit dirtiness.
• Plate should own comment workflow, permissions, suggestions, sidebars, toolbars, markdown/product extensions, and collaborative service wiring.
• Plate proof later must compile at least one product-style comments/suggestion adapter without importing projection internals as the primary API.
• The adapter proof must use public substrate nouns first: decorationSources, createDecorationSource, useSlateDecorationSource, annotationStore, useSlateAnnotationStore, useSlateAnnotations, useSlateWidgetStore, useSlateWidgets, Bookmark, and commit dirtiness.
• If the adapter needs projection internals as the primary API, the plan is not ready for ralph.

12. slate-yjs Migration-Backbone Target

Status: revised after pass 10.

Accepted substrate target:

• raw Slate exports durable anchors and deterministic commit/runtime metadata;
• collaboration adapters map comment/annotation anchors through their own CRDT or service layer;
• raw Slate does not force comment-only users to mutate the document value.
• EditorCommit already exposes runtime dirtiness and metadata fields in live source: dirtyPaths, dirtyScope, decorationImpactRuntimeIds, nodeImpactRuntimeIds, replaceEpoch, metadata, and operation classes.
• slate-yjs proof later must show remote text/structure edits update bookmarks and annotation projection buckets without forcing raw Slate to own the CRDT comment schema.
• The proof must keep mount state local. Shared CRDT state cannot depend on shell/staged mount state, React component state, or product comment schema in raw Slate.

13. Issue-Ledger Accounting

Status: complete after pass 11.

The issue-ledger classification pass and pass-11 sync are complete for this planning lane. Closure still belongs to pass 12.

Pass 2 owner:

• complete. ClawSweeper ran once for React runtime plus decorations / marks / annotations.
• gitcrawl archive evidence was used first.
• docs/slate-v2/ledgers/fork-issue-dossier.md now has missing concise sections for the pass-2 reviewed issues.

Pass 3 owner:

• complete. The full docs/slate-issues stack was scanned for the combined React runtime plus decorations / marks / annotations surface.
• 44 plan-relevant issue rows were classified in this plan.
• No fixed-issue claim status changed. Public API target language changed in pass 10, so pass 11 must check whether the PR reference needs a public API / proof-reference sync without upgrading any issue to exact Fixes.

Current PR reference status:

• synced after pass 11.
• docs/slate-v2/references/pr-description.md now reflects the accepted API ladder: decorate, decoration sources, annotation/widget stores, and projection internals as advanced runtime surface.
• The PR reference now records the huge-overlay benchmark API drift owner: migrate to useEditorSelector plus decorationSources by default; restore useSlateSelector or direct <Slate projectionStore={...}> only after a public API audit, typed alias contract, and docs answer.
• docs/slate-v2/ledgers/issue-coverage-matrix.md unchanged: no fixed, improved, related, or not-claimed classification changed.
• docs/slate-v2/ledgers/fork-issue-dossier.md unchanged: no new issue was reviewed in pass 11.
• docs/slate-issues/gitcrawl-live-open-ledger.md unchanged: no live cluster rollup changed.
• No issue was upgraded to exact Fixes #....

14. Legacy Regression Proof Matrix

Status: defined after pass 6.

Package proof rows:

Benchmark proof rows:

Native/browser proof rows:

15. Browser Stress / Parity Strategy

Status: defined after pass 6.

Browser strategy:

Command policy:

• iteration: focused package tests plus benchmark scripts above;
• browser closure: bun test:integration-local from .tmp/slate-v2;
• release-quality local closure: bun check:full from .tmp/slate-v2;
• raw mobile/device claims: only bun test:mobile-device-proof:raw on a real device lane, and not in this React/decorations plan.

16. Applicable Implementation-Skill Review Matrix

Pass 6 applicability:

16.1 Pass 6 Proof Pressure Matrix

Performance cohorts:

Repeated-unit budgets:

Memory/DOM tags required for large and stress rows:

• JS heap, DOM node count, mounted text count, shell/group count, listener count, cached projection/index size, dirty runtime-id set size, annotation/comment count, decoration density, custom renderer flags, browser/mobile/IME tag, and rendering mode.

Degradation contract:

• default mode stays DOM-present;
• shell/staged mode is allowed only for large/stress cohorts or explicit opt-in;
• every shell/staged claim must classify browser find, screen-reader traversal, native selection, copy, paste, select-all, IME, mobile touch selection, undo/history, collaboration, and follow-up typing as native, model-backed, materialize-first, unsupported, or opt-in only.

17. High-Risk Deliberate Mode

Triggered: yes.

Reason:

• React runtime subscriptions, render contracts, decorations, annotations, selection/IME fallout, public API shape, and performance claims are all high-risk surfaces.

Status: complete after pass 8.

High-risk trigger:

• This plan changes or validates public React API shape, runtime subscription behavior, overlay rendering contracts, durable annotation anchors, benchmark/release gates, and issue-closure language. A bad call here would be user-visible and expensive to reverse.

Blast radius:

Three-scenario pre-mortem:

Expanded proof plan:

Rollback and remediation answers:

• If source-scoped invalidation regresses, keep full-refresh fallback, expose metrics, and block field-best performance claims until the benchmark turns green again.
• If the benchmark repair demands too much compatibility debt, migrate the benchmark to current useEditorSelector / decorationSources and document the old names as intentionally unsupported unless the audit says otherwise.
• If shell/staged mode breaks native behavior, keep it opt-in only, label the failed affordance as unsupported/materialize-first, and keep DOM-present rendering as default.
• If Plate/slate-yjs proof needs product semantics, leave those semantics above raw Slate and strengthen the substrate rather than importing product workflow into slate-react.
• If browser rows fail, do not soften the gate. Reclassify issue claims to related/improves and keep completion pending.

High-risk verdict:

• Keep the plan, but with hard gates:
  • no implementation closure before the huge-overlay benchmark is repaired;
  • no browser/native claim before focused browser proof;
  • no Mobile/IME exact closure from this lane;
  • no raw Slate product comment workflow;
  • no restored compatibility alias/prop without an explicit API audit;
  • no issue-sync upgrade before pass 11.

18. Hard Cuts And Rejected Alternatives

Initial hard cuts:

• no legacy decorate as the only scalable overlay API;
• no product comment system in raw Slate;
• no broad useEditor as the recommended hot-path subscription;
• no field-best decoration performance claim without source-scoped invalidation and benchmark proof;
• no exact Mobile/IME closure from desktop React package tests.

19. Slate Maintainer Objection Ledger

Status: complete after pass 7.

Evidence refreshed for this pass:

• current <Slate> public props are editor, decorationSources, annotationStore, and change callbacks in .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:63-74;
• current <Slate> composes decoration sources and annotation projection stores in .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:175-184;
• current slate-react exports useEditorSelector, decoration source hooks, annotation hooks, widget hooks, projection hooks, and projection store types in .tmp/slate-v2/packages/slate-react/src/index.ts:82-138;
• current createDecorationSource wraps projection transport behind a product-noun source API in .tmp/slate-v2/packages/slate-react/src/decoration-source.ts:111-129;
• current annotation stores own id, anchor, optional data/projection, projection store, and targeted subscription contracts in .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:13-87;
• the huge-document overlay benchmark is stale: it imports useSlateSelector and passes projectionStore to <Slate> in .tmp/slate-v2/scripts/benchmarks/browser/react/huge-document-overlays.tsx:12-19 and .tmp/slate-v2/scripts/benchmarks/browser/react/huge-document-overlays.tsx:237-239.

Challenge rows:

Accepted revisions:

• Documentation/tutorial order must be decorate first, decoration sources second, annotation/widget stores third, projection internals advanced last.
• Implementation phase 2 must repair the huge-overlay benchmark against the current API before any more benchmark-based claims.
• The huge-overlay benchmark drift is not only useSlateSelector; it also passes stale projectionStore directly to <Slate>.
• Default decision for the red benchmark is to migrate it to useEditorSelector plus decorationSources; restore aliases/props only if a public API audit deliberately chooses compatibility.
• No Mobile/IME closure language is allowed from this lane. Keep negative controls and cross-link to the Mobile/IME plan for raw-device claims.

Dropped choices:

• decorate-only as the scalable overlay strategy;
• projection-store-first public API;
• raw Slate comment/review workflow ownership;
• benchmark-only closure;
• shell/staged rendering as default behavior.

Unresolved decisions:

• none. The useSlateSelector / projectionStore drift has a revise verdict with an implementation audit owner, not an open user decision.

20. Pass Schedule And Pass-State Ledger

21. Plan Deltas From Review

Pass 1 deltas:

• Created a new combined React/decorations slate-issues ralplan.
• Reused prior done plans as evidence, not mutable state.
• Recorded current live source owners and a focused .tmp/slate-v2 test gate.
• Seeded issue families and initial score.
• Kept completion pending.

Pass 2 deltas:

• Ran bounded ClawSweeper related-issue discovery for the combined React runtime plus decorations / marks / annotations surface.
• Recorded gitcrawl archive freshness and no-token limitation.
• Added a pass-2 discovery matrix and neighbor evidence.
• Appended missing fork dossier sections for reviewed issues that had no self-contained section.
• Kept all issue claim statuses conservative; no new Fixes #... claim.
• Raised score from 0.76 to 0.80, still far below closure.

Pass 3 deltas:

• Scanned the full local issue corpus stack and the live gitcrawl overlay for the combined React runtime plus decorations / marks / annotations surface.
• Classified 44 plan-relevant rows as fixed, improves, related, not claimed, or outside exact lane.
• Reconciled the previously matrix-only rows for #4680, #4165, #4210, #3162, #4712, #5398, #5433, #4750, #2465, and #2564.
• Explained #4993/#4997 as PR research refs, not issue rows or claimable live issue refs.
• Preserved the split between corpus sync and PR-slice claim accounting.
• Raised score from 0.80 to 0.83; still below closure because ecosystem, performance thresholds, maintainer objections, high-risk review, and final issue sync remain pending.

Pass 4 deltas:

• Rewrote the intent/boundary record so this lane is explicitly about React runtime projection plus decorations / marks / annotations, not a general Slate core, DOM, Mobile/IME, table, clipboard, history, or docs plan.
• Added a pressure test for #2465/#2564 and #4993/#4997 so the plan does not overcorrect into either product-shaped raw Slate or public projection-engine soup.
• Replaced the initial decision brief with a pass-4 brief covering principles, drivers, rejected options, chosen target, consequences, and next owners.
• Locked the simple/scalable/durable/advanced API split as the current planning posture: decorate, decoration sources, annotation stores, projection transport.
• Raised score from 0.83 to 0.84; still below closure because ecosystem synthesis, benchmark/browser proof thresholds, maintainer objections, high-risk review, and issue sync remain pending.

Pass 5 deltas:

• Read the compiled React 19.2, Lexical, ProseMirror, Tiptap, local Slate v2, and source-scoped invalidation pages.
• Checked relevant learnings for projection/store ownership and selector fanout failure modes.
• Re-read live Slate v2 projection, decoration source, annotation store, selector, projection test, and annotation test owners.
• Converted ecosystem evidence into steal/reject/diverge strategy rows instead of a citation list.
• Confirmed the public posture: simple decorate, scalable decoration sources, durable annotation stores, separate widgets, projection transport advanced/internal.
• Raised score from 0.84 to 0.87; still below closure because pass 6 must define exact performance, DX, migration, regression, and simplicity gates.

Pass 6 deltas:

• Applied Vercel React, performance-oracle, performance, tdd, shadcn, and react-useeffect lenses to the plan instead of leaving them as generic applicability notes.
• Added cohort segmentation, repeated-unit budgets, memory/DOM tags, degradation contracts, and native-behavior proof rows.
• Re-read live exports and confirmed useDecorationSelector, useSlateDecorationSource, annotation hooks, widget hooks, EditorCommit dirtiness, and Slate provider props as the current substrate.
• Ran bun run bench:react:rerender-breadth:local in .tmp/slate-v2; it passed and produced exact current recompute/rerender evidence.
• Ran bun run bench:react:huge-document-overlays:local in .tmp/slate-v2; it failed because the benchmark imports stale useSlateSelector while live slate-react exports useEditorSelector.
• Raised score from 0.87 to 0.88; still below closure because pass 7/8 objections/high-risk remain and the huge-overlay benchmark is red.

Pass 7 deltas:

• Applied steelman-pass to the major public API and proof decisions.
• Re-read live <Slate> props, export surface, decoration source shape, annotation store shape, and the huge-document overlay benchmark.
• Corrected the red benchmark diagnosis: it is stale on both useSlateSelector and direct <Slate projectionStore={...}>.
• Accepted the API tiering with stricter docs order: decorate, decoration sources, annotation/widget stores, projection internals.
• Kept raw Slate annotation ownership to durable anchor/projection substrate, not product comment/review workflow.
• Kept shell/staged rendering only as opt-in degradation with explicit native behavior status.
• Raised score from 0.88 to 0.89; still below closure because high-risk, ecosystem-maintainer, revision, issue-sync, closure, and red benchmark owners remain.

Pass 8 deltas:

• Applied high-risk-deliberate-pass to the public API, browser/runtime, performance, migration/collab, release, and issue-claim surfaces.
• Added blast-radius rows for public API, React runtime, browser behavior, data/anchors, migration consumers, and release proof.
• Added a three-scenario pre-mortem for API confusion, browser reality gaps, and migration/collab substrate weakness.
• Expanded proof gates across unit/package, integration, browser/native, migration/adoption, docs/examples, performance/release, and issue accounting.
• Added rollback/remediation rules for broad recompute fallback, alias/prop drift, shell/staged native failures, product-comment pressure, and failed browser rows.
• Raised score from 0.89 to 0.90; still below closure because ecosystem-maintainer, revision, issue-sync, closure, and red benchmark owners remain.

Pass 9 deltas:

• Re-read the React 19.2, Lexical, ProseMirror, Tiptap, and local Slate v2 ecosystem evidence.
• Scanned local Plate/slate-yjs migration pressure from suggestion/comment docs, plugin resolver tests, decoration/annotation cluster docs, and prior migration plans.
• Added maintainer-pressure rows for React, Slate, Plate, slate-yjs, Lexical, ProseMirror, and Tiptap.
• Accepted revisions that pass 10 must merge into executable phases: Plate public-substrate adapter proof, slate-yjs remote anchor mapping proof, Lexical/ProseMirror performance caps, and Tiptap-style docs discoverability.
• Dropped demands to adopt Lexical node classes, ProseMirror schema/viewdesc, Tiptap chain as a second write engine, or current Plate/slate-yjs adapter compatibility as raw Slate closure.
• Raised score from 0.90 to 0.91; still below closure because revision, issue-sync, closure, and red benchmark owners remain.

Pass 10 deltas:

• Merged accepted pass 7-9 revisions into the plan body instead of leaving them as layered review notes.
• Revised the public API target to lock the authoring ladder: decorate, decoration sources, annotation/widget stores, projection internals.
• Revised the internal runtime target to make source-scoped invalidation the next implementation tranche below React.
• Revised Plate and slate-yjs migration targets with explicit adapter proof: public substrate nouns first, remote anchor mapping, local mount state, and no raw Slate product workflow or CRDT service ownership.
• Revised implementation phases to include benchmark API drift repair, source-scoped invalidation, Plate adapter proof, slate-yjs remote anchor mapping, browser/native proof, docs/example discoverability, and sync.
• Decided the score can reach 0.92 before issue sync because the architecture plan is now executable. Completion remains pending because issue sync and closure are still required.

Pass 11 deltas:

• Checked docs/slate-v2/ledgers/issue-coverage-matrix.md, docs/slate-v2/ledgers/fork-issue-dossier.md, docs/slate-issues/gitcrawl-live-open-ledger.md, and docs/slate-v2/references/pr-description.md.
• Kept all fixed/improved/related/not-claimed issue classifications unchanged.
• Updated only the PR reference because pass 10 changed accepted public API and proof wording.
• Recorded that the red huge-overlay benchmark owner is API drift in the benchmark: useSlateSelector and direct <Slate projectionStore={...}> are not current proof surfaces unless explicitly restored through a public API audit.
• Kept score at 0.92; pass 12 still owns closure and final handoff.

Pass 12 deltas:

• Closed the Slate Ralplan planning lane at score 0.92.
• Reclassified the red huge-overlay benchmark as an implementation/release gate, not a blocker to user review of the plan.
• Kept the hard rule: no implementation or release closure while the huge-overlay benchmark is red.
• Wrote the final handoff below so ralph can execute slices without rerunning architecture discovery.

22. Open Questions And What Would Change The Decision

Open questions:

• Which issues can move from Improves or Related to exact Fixes after current thread/repro reads?
• Which classic decorate examples remain simple enough to keep in docs, and which should move to decoration-source examples?
• Which mark rows require core mark/range work before React projection can honestly preserve payload and selection behavior?
• Implementation audit question: migrate stale benchmarks/examples to useEditorSelector plus decorationSources by default; restore useSlateSelector or direct projectionStore only if public API audit proves those aliases are intentional.
• Which browser rows can be narrowed to focused Playwright greps before the final bun test:integration-local gate?

Decision changers:

• current issue repro proves an exact browser closure already exists;
• external research proves a cleaner model than source-scoped projection stores;
• benchmark proof shows current source-scoped stores are still too broad at realistic scale;
• fixing or intentionally rejecting the useSlateSelector / projectionStore compatibility path changes the huge-overlay benchmark owner;
• live source has drifted from the prior plans.

23. Implementation Phases With Owners

Executable draft after pass 10:

1. Claim boundary phase:
   • keep current issue classifications conservative;
   • no exact Fixes #... without replayable original-repro proof;
   • preserve Mobile/IME exact closure for the Mobile/IME lane.
2. Benchmark API drift repair phase:
   • migrate the stale huge-overlay benchmark to useEditorSelector plus decorationSources;
   • restore useSlateSelector or direct <Slate projectionStore={...}> only after an explicit public API audit, typed alias contract, and docs answer;
   • rerun bun run bench:react:huge-document-overlays:local in .tmp/slate-v2.
3. Source-scoped invalidation phase:
   • push dirty source class, source id, impacted runtime ids, annotation ids, and recompute metrics below React;
   • keep full refresh as fallback, not steady state.
4. React selector/provider identity proof phase:
   • prove provider replacement, focused state, selector fanout, and runtime-id wakeups remain narrow.
5. Decoration source invalidation proof phase:
   • prove decorate remains simple;
   • prove high-churn sources wake only matching runtime/source buckets.
6. Annotation/widget substrate proof phase:
   • prove metadata-only annotation updates wake annotation subscribers only;
   • prove annotation projection changes wake only affected runtime buckets;
   • keep widgets separate from text projection ranges.
7. Render-leaf/mark metadata proof phase:
   • preserve overlapping payloads and mark metadata without flattening into one winner.
8. Browser overlay/selection/IME negative-control proof phase:
   • prove find, selection, copy, paste, select-all, follow-up typing, and mode status for decorated/annotated/shelled content;
   • keep raw mobile/device closure out of this lane.
9. Ecosystem adapter proof phase:
   • Plate-style comments/suggestions must compile through public substrate nouns first;
   • slate-yjs-style remote edits must map bookmarks and annotation projection buckets while mount state stays local.
10. Docs/example discoverability phase:
    • decorate first;
    • scalable sources second;
    • durable annotations/widgets third;
    • product examples above raw Slate;
    • projection internals advanced last.
11. Benchmark threshold and ledger/reference sync phase:
    • rerender breadth and huge-overlay benchmarks green;
    • issue coverage and PR reference synced only after proof ownership is settled.

24. Fast Driver Gates

Planning gates, cwd plate-2:

pnpm lint:fix
bun run completion-check -- --file .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md

Focused Slate v2 behavior gates, cwd .tmp/slate-v2:

bun test ./packages/slate-react/test/provider-hooks-contract.tsx ./packages/slate-react/test/projections-and-selection-contract.tsx ./packages/slate-react/test/annotation-store-contract.tsx ./packages/slate-react/test/widget-layer-contract.tsx ./packages/slate-react/test/render-profiler-contract.test.tsx
bun run bench:react:rerender-breadth:local
bun run bench:react:huge-document-overlays:local

Final Slate v2 closure gate, cwd .tmp/slate-v2:

bun check

Browser rows are specified, not run. The huge-document overlay benchmark is green after Ralph slice 1, but browser/native rows still gate behavior and release claims.

25. Final User-Review Handoff

Planning verdict:

• done for Slate Ralplan review at score 0.92;
• not implementation complete;
• not release ready;
• ready for ralph execution slices.

Accepted public API decisions:

• keep decorate for simple transient Slate ranges;
• use createDecorationSource, decorationSources, and useSlateDecorationSource for high-churn or external overlays;
• use annotation stores and widget stores for durable anchors and UI overlays;
• keep projection stores/selectors/metrics as advanced runtime surfaces;
• migrate stale benchmark/example code to useEditorSelector plus decorationSources by default;
• restore useSlateSelector or direct <Slate projectionStore={...}> only after a public API audit, typed alias contract, and docs answer.

React runtime decisions:

• React is an adapter over committed editor snapshots, not the owner of editor value truth.
• Broad hooks can stay broad by contract.
• Hot paths must use selector subscriptions, runtime-id buckets, decoration sources, annotation stores, or widget stores.
• Source-scoped invalidation is the next runtime tranche below React; full source refresh remains fallback, not steady state.

Decoration / annotation / widget decisions:

• Decoration sources own scalable transient overlays.
• Annotation stores own durable id-bearing anchors and projection buckets.
• Widgets stay separate from text projection ranges.
• Raw Slate owns substrate only. Product comments, suggestions, permissions, review workflows, and collaboration services stay outside raw Slate.

Mark / render-leaf decisions:

• Preserve overlapping payloads and metadata without flattening them into one winner.
• Core mark/range semantics remain the owner when React projection cannot honestly preserve mark behavior alone.

Plate and slate-yjs migration-backbone decisions:

• Plate proof must compile through public substrate nouns first: decorationSources, createDecorationSource, useSlateDecorationSource, annotationStore, annotation hooks, widget hooks, bookmarks, and commit metadata.
• slate-yjs proof must map remote text/structure edits through bookmarks and annotation projection buckets.
• Mount state stays local. Shared CRDT state cannot depend on React component state, staged DOM state, or product comment schema in raw Slate.

Issue accounting:

• no new exact Fixes #... claim from this planning lane;
• no issue classification changed in pass 11;
• PR reference synced to the accepted API/proof wording;
• Mobile/IME exact closure stays in the Mobile/IME lane;
• DOM selection/focus exact closure stays in the DOM bridge lane.

Proof gates for ralph:

• first repair bench:react:huge-document-overlays:local;
• keep bench:react:rerender-breadth:local green;
• run focused slate-react package tests for provider hooks, projections, annotations, widgets, and render profiling;
• add browser/native rows for decorated/annotated/shelled selection, find, copy, paste, select-all, and follow-up typing before claiming browser behavior;
• use bun check in .tmp/slate-v2 as the fast sibling-repo closure gate.

Recommended ralph slice order:

1. Benchmark API drift repair.
2. Source-scoped invalidation below React.
3. Provider/selector/runtime-id proof hardening.
4. Decoration source invalidation proof.
5. Annotation/widget substrate proof.
6. Mark/render-leaf metadata proof.
7. Browser overlay/selection negative-control proof.
8. Plate/slate-yjs adapter proof.
9. Docs/example discoverability.

26. Final Completion Gates

Current gate status:

• total score 0.92, meets the planning score threshold but is not implementation or release closure;
• closure pass complete for planning;
• ClawSweeper related-issue pass complete for the current issue surface;
• issue-ledger pass complete for the active plan;
• intent/boundary and decision brief pass complete;
• ecosystem synthesis complete;
• performance/DX/migration/regression pressure pass complete;
• Ralph slice 1 complete: bench:react:huge-document-overlays:local green in .tmp/slate-v2;
• bun check passed in .tmp/slate-v2 after the benchmark repair;
• maintainer objection pass complete;
• high-risk deliberate pass complete;
• ecosystem-maintainer pass complete;
• revision pass complete;
• issue-sync pass complete;
• final handoff complete.
• Ralph slice 8 complete: Plate/slate-yjs adapter substrate proof is green in .tmp/slate-v2 through public comment examples, commit metadata, deterministic replay, local runtime targets, and bookmark rebasing.
• Ralph slice 9 complete: docs/examples now expose the simple Editable.decorate path, scalable decorationSources, annotation stores, widget stores, and public hook names with static surface-contract proof.

Completion status is done for this Slate Ralplan planning lane.

27. Ralph Execution Ledger

Slice 1: Huge-Overlay Benchmark API Drift

Status: complete.

Files changed:

• .tmp/slate-v2/scripts/benchmarks/browser/react/huge-document-overlays.tsx
• docs/slate-v2/references/pr-description.md
• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Decision:

• migrated the benchmark to current APIs instead of restoring compatibility aliases;
• used useEditorSelector, createDecorationSource, <Slate decorationSources={...}>, and withReact(createEditor());
• kept issue claims unchanged.

Evidence:

• bun run bench:react:huge-document-overlays:local passed in .tmp/slate-v2;
• focused slate-react package tests passed: provider hooks, projections, annotations, widgets, and render profiling;
• bun run bench:react:rerender-breadth:local passed in .tmp/slate-v2;
• bun check passed in .tmp/slate-v2.

Next owner:

• source-scoped invalidation below React.

Slice 2: Source-Scoped Invalidation Below React

Status: complete; already done in live source, verified by focused tests and benchmarks.

Files changed:

• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/packages/slate-react/src/projection-store.ts
  • maps dirtiness classes to editor commit sources;
  • subscribes projection stores through Editor.subscribeSource(...);
  • gates recompute by dirtiness, runtimeScope, and targeted sourceId;
  • exposes metrics for source reads, runtime bucket changes, and source subscriber wakes.
• .tmp/slate-v2/packages/slate-react/src/decoration-source.ts
  • passes decoration source id, dirtiness, and runtimeScope into the projection store.

Decision:

• no implementation patch needed; the plan's target is already present in current .tmp/slate-v2;
• kept PR reference unchanged because this slice changes no public API, issue claim, or proof status beyond already-recorded benchmark/source-scoped rows;
• kept issue claims unchanged.

Evidence:

• bun test ./packages/slate-react/test/projections-and-selection-contract.tsx -t source passed in .tmp/slate-v2;
• bun run bench:react:rerender-breadth:local had already passed with sourceScopedInvalidation showing unrelated source recompute counts at 0;
• bun check passed in .tmp/slate-v2.

Next owner:

• provider/selector runtime-id proof hardening.

Slice 3: Provider/Selector Runtime-Id Proof Hardening

Status: complete; already done in live source, verified by focused contracts.

Files changed:

• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selector.tsx
  • routes selector listeners through global, deferred, or runtime-id buckets;
  • limits runtime fanout to affectedNodeRuntimeIds / nodeImpactRuntimeIds;
  • skips stale mounted runtime-id fanout for root-order-only commits.
• .tmp/slate-v2/packages/slate-react/src/hooks/use-decoration-selector.tsx
  • reads one runtime id and subscribes through store.subscribeRuntimeId(...) when available.

Decision:

• no implementation patch needed; provider replacement, focused state, selector fanout, and runtime-id wakeups are already covered by current tests;
• no public API or PR reference change;
• kept issue claims unchanged.

Evidence:

• bun test ./packages/slate-react/test/provider-hooks-contract.tsx ./packages/slate-react/test/projections-and-selection-contract.tsx passed in .tmp/slate-v2;
• prior full bun check passed in .tmp/slate-v2 after slice 2.

Next owner:

• decoration source invalidation proof.

Slice 4: Decoration Source Invalidation Proof

Status: complete.

Files changed:

• .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/projections-and-selection-contract.tsx
• docs/slate-v2/references/pr-description.md
• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx
  • adds Editable.decorate as the simple transient range API;
  • implements it as a thin createDecorationSource(...) adapter below Editable, composed with any provider-level projection store;
  • keeps generated projection keys internal when simple ranges omit a key.
• .tmp/slate-v2/packages/slate-react/src/decoration-source.ts
  • remains the scalable source-id/runtime-bucket substrate for external or high-churn overlays.

Decision:

• fixed the public-DX mismatch instead of editing the plan to pretend decorate existed;
• did not restore direct <Slate projectionStore={...}> or useSlateSelector;
• kept issue claims unchanged because this is API/proof hardening, not original issue replay.

Evidence:

• bun test ./packages/slate-react/test/projections-and-selection-contract.tsx -t "simple Editable decorate" passed in .tmp/slate-v2;
• bun test ./packages/slate-react/test/projections-and-selection-contract.tsx ./packages/slate-react/test/app-owned-customization.tsx passed in .tmp/slate-v2;
• bun lint:fix passed in .tmp/slate-v2 and fixed formatting;
• bun check passed in .tmp/slate-v2.

Next owner:

• annotation/widget substrate proof.

Slice 5: Annotation/Widget Substrate Proof

Status: complete; already done in live source, verified by focused contracts.

Files changed:

• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/packages/slate-react/src/annotation-store.ts
  • keeps annotation subscribers separate from projection/runtime subscribers;
  • reprojects only candidate annotation ids when editor commit metadata allows;
  • wakes only changed annotation ids and changed runtime buckets.
• .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-annotations.tsx
  • exposes whole-store and single-annotation subscriptions through useSyncExternalStore.
• .tmp/slate-v2/packages/slate-react/src/widget-store.ts
  • owns widget visibility/state independently from text projection ranges.

Decision:

• no implementation patch needed; the annotation/widget substrate is already split correctly in live source;
• no public API, PR reference, or issue-claim change.

Evidence:

• bun test ./packages/slate-react/test/annotation-store-contract.tsx ./packages/slate-react/test/widget-layer-contract.tsx passed in .tmp/slate-v2;
• pnpm lint:fix passed in plate-2 after state sync.

Next owner:

• mark/render-leaf metadata proof.

Slice 6: Mark/Render-Leaf Metadata Proof

Status: complete.

Files changed:

• .tmp/slate-v2/packages/slate-react/test/projections-and-selection-contract.tsx
• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/packages/slate-react/src/components/editable-text.tsx
  • splits text by all projection boundaries;
  • keeps segment.slices as multiplicity-safe projection metadata;
  • passes text marks through leaf / segment.marks without collapsing projection payloads into marks.

Decision:

• added the missing public-path contract for renderLeaf;
• preserved the existing renderSegment contract;
• no public API or issue-claim change.

Evidence:

• bun test ./packages/slate-react/test/projections-and-selection-contract.tsx -t "renderLeaf receives" passed in .tmp/slate-v2;
• bun test ./packages/slate-react/test/projections-and-selection-contract.tsx passed in .tmp/slate-v2;
• bun lint:fix passed in .tmp/slate-v2;
• bun check passed in .tmp/slate-v2.

Next owner:

• browser overlay/selection negative-control proof.

Slice 7: Browser Overlay/Selection Negative-Control Proof

Status: complete.

Files changed:

• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Browser proof covered:

• decorated highlighted text selection, typing, IME, generated mark-click gauntlet, Backspace/Delete caret recovery, copy, collapsed copy/cut, and cut;
• annotation-backed review comments, sidebar state, inline slices, and widget panel sync;
• DOM coverage shell boundaries, native find, model-backed copy/select-all, drag selection across boundary placeholders, hidden model updates, and IME with hidden boundaries.

Decision:

• accepted Chromium-focused browser proof for this slice;
• did not claim raw mobile/device closure; the mobile-only DOM coverage row was intentionally skipped by the test file;
• kept issue claims unchanged.

Rejected tactic:

• running two Playwright webServer jobs in parallel caused one Next build to fail with "Another next build process is already running"; reran the failed shell/coverage row sequentially.

Evidence:

• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun run playwright playwright/integration/examples/highlighted-text.test.ts --project=chromium passed in .tmp/slate-v2: 12 passed;
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun run playwright playwright/integration/examples/review-comments.test.ts --project=chromium passed in .tmp/slate-v2: 1 passed;
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun run playwright playwright/integration/examples/dom-coverage-boundaries.test.ts --project=chromium passed in .tmp/slate-v2: 7 passed, 1 mobile-only skipped.

Next owner:

• Plate/slate-yjs adapter proof.

Slice 8: Plate/slate-yjs Adapter Substrate Proof

Status: complete.

Files changed:

• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx
• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• docs/slate-v2/references/pr-description.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/site/examples/ts/review-comments.tsx
  • builds review comments from Bookmark, useSlateAnnotationStore, useSlateAnnotations, useSlateWidgetStore, and useSlateWidgets;
  • keeps comment workflow in the product example, not raw Slate core.
• .tmp/slate-v2/site/examples/ts/collaborative-comments.tsx
  • models writer document writes and reviewer comment writes as separate channels over public annotation substrate;
  • keeps reviewer document writes at 0.
• .tmp/slate-v2/packages/slate/test/collab-history-runtime-contract.ts
  • proves deterministic remote operation replay, remote metadata, history skip, bookmark rebasing, and local runtime target rebasing/nulling.
• .tmp/slate-v2/packages/slate/test/commit-metadata-contract.ts
  • proves typed collaboration metadata, including Yjs-style origin metadata.
• .tmp/slate-v2/packages/slate/test/migration-backbone-contract.ts
  • proves extension/state/tx backbone without adapter-shaped public namespaces such as api, tf, plate, or yjs.

Decision:

• added a static public-surface contract for product comment examples instead of importing current Plate or slate-yjs adapters into raw Slate;
• kept raw Slate at substrate level: bookmarks, commits, metadata, deterministic operations, public annotation stores, and public widget stores;
• rejected projection internals as the primary product-comments path;
• kept issue claims unchanged.

Evidence:

• bun test ./packages/slate/test/collab-history-runtime-contract.ts ./packages/slate/test/commit-metadata-contract.ts ./packages/slate/test/migration-backbone-contract.ts ./packages/slate-react/test/surface-contract.tsx passed in .tmp/slate-v2: 27 passed;
• bun lint:fix passed in .tmp/slate-v2;
• bun check passed in .tmp/slate-v2: lint, package/site/root typecheck, Bun tests, and Vitest with 202 slate-react tests.

Next owner:

• docs/example discoverability.

Slice 9: Docs/Example Discoverability

Status: complete.

Files changed:

• .tmp/slate-v2/docs/libraries/slate-react/editable.md
• .tmp/slate-v2/docs/libraries/slate-react/hooks.md
• .tmp/slate-v2/docs/libraries/slate-react/slate.md
• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx
• docs/plans/2026-05-08-slate-v2-react-decorations-slate-issues-ralplan.md
• docs/slate-v2/references/pr-description.md
• .tmp/completion-checks/slate-v2-react-decorations-slate-issues-ralplan.md
• active goal state

Live source owner:

• .tmp/slate-v2/docs/libraries/slate-react/editable.md
  • documents Editable.decorate as the simple editor-local decoration path;
  • points shared/high-churn overlays to provider-owned decorationSources.
• .tmp/slate-v2/docs/libraries/slate-react/slate.md
  • uses useSlateDecorationSource(...) for provider-owned decoration sources;
  • names Editable.decorate as the simple callback path.
• .tmp/slate-v2/docs/libraries/slate-react/hooks.md
  • documents useSlateDecorationSource, annotation hooks, and widget hooks.
• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx
  • locks docs and product comments to public substrate nouns and rejects projection internals as the default path.

Decision:

• documented the simple and scalable overlay paths instead of making examples teach projection internals;
• kept useDecorationSelector advanced;
• did not change issue claims.

Evidence:

• bun test ./packages/slate-react/test/surface-contract.tsx passed in .tmp/slate-v2: 14 passed;
• bun lint:fix passed in .tmp/slate-v2;
• bun check passed in .tmp/slate-v2: lint, package/site/root typecheck, Bun tests, and Vitest with 203 slate-react tests.

Next owner:

• none. React runtime/decorations/marks/annotations execution lane is complete.