Slate v2 Universal Large-Document Performance Ralplan

Current Verdict

Latest review score: 0.88. Status: active execution.

The previous execution slice made shell mode real: explicit mode: 'shell', mounted corridor semantics, composition guard, shell-backed selection/copy contracts, dirty commit payloads, and green shell smoke lanes. That is a real improvement.

It is still not a default-performance victory, but the 5000-block median gate changed the severity. Shell is now a credible explicit escape hatch. DOM-present/default now beats legacy chunk-on hard for interactive ready, steady middle typing, select-all, visible full-document replacement, and visible fragment insertion. The 5000-block selection/setup and promote medians are now inside the default gate after reducing DOM-present root groups to 50 blocks. A true browser-native input proof now exists for DOM-present large-document typing. nativeSurfaceComplete is measured separately and remains around one second at 5000 blocks. The remaining red owner is the 10000-block stress shape: selection-inclusive and promote lanes still scale too poorly even though ready and visible full-document operations crush legacy.

The latest beforeinput pass found a benchmark truth bug: the old *NativeBeforeInputTypeMs rows dispatched @, which the runtime correctly routes to Slate's model-owned beforeinput path. Those rows were not native browser insertion proof. They are now renamed to *SelectThenModelBeforeInputTypeMs.

Keep the Slate v2 rewrite. Rewrite the large-document default strategy.

The v2 core architecture is right: editor.read, editor.update, editor.subscribe, editor.extend, transaction dirtiness, runtime ids, sidecar projections, extension state / tx groups, browser proof contracts, and direct DOM text sync are the correct foundation.

The original shell-island path was useful as an experimental escape hatch but wrong as the default: it crushed startup/full-document operations and lost steady typing badly. The latest shell-explicit implementation is much better and should be kept. The default DOM-present path is still the active red lane.

Accepted decision, updated after GPT Pro follow-up:

// Public default
<Editable />

// Optional policy override
largeDocument?:
  | 'auto'
  | 'dom-present'
  | 'off'
  | 'shell'
  | {
      mode: 'shell'
      activeRadius?: number
      islandSize?: number
      previewChars?: number
      threshold?: number
    }

Default auto is two-layer. Layer 1 is always the safe DOM-present baseline: grouping, scoped subscriptions, active corridor, containment, content-visibility where proven, direct DOM text sync where safe, and persistent sidecar range indexes. Layer 2 is aggressive shell/occlusion escalation, and it stays proof-disabled in the default until browser find, screen reader, native selection, copy/paste, IME, mobile, undo, history, and collaboration proof all pass. Until then, shell virtualization is explicit through mode: 'shell'.

New hard line: default auto may use staged DOM-present mounting only if it tracks interactiveReady and nativeSurfaceComplete separately and never leaves stale far DOM exposed as current content after full-document changes.

Execution State

Execution started by ralph on 2026-05-01.

Current pass:

• current: phase-7-default-claim-gate
• previous: Phase 7.0/7.1 closed benchmark surface rename, readiness split, stale-DOM proof, staged DOM-present lifecycle, root group size cuts, the misleading beforeinput lane name, the 5000-block median confirmation, the real browser-native input proof, the 5000-block selection/setup/promote cost cut, the first 10000-block pending-placeholder coalescing cut, and one rejected eager-active-group-persistence experiment
• completion: current default-performance claim gate is closed for the 5000-block release target; 10000-block immediate far-selection stress remains recorded as a follow-up owner, not a closed performance claim

Intent / Boundary Record

• Intent: make the Slate v2 rewrite beat legacy Slate performance on meaningful editor workloads, not merely look cleaner.
• Desired outcome: define the architecture and proof gates for a default large-document mode that beats or matches legacy chunking on typing while preserving v2 startup and whole-document wins.
• In scope: public large-document API, internal grouping strategy, commit dirtiness, React subscriptions, sidecar decorations/annotations/widgets, selection/DOM bridge, shell-island policy, benchmark matrix, accessibility, browser proof, Plate and slate-yjs migration backbone.
• Non-goals: implementing the plan in this pass; preserving current shell option names; product-level comment services; current-version Plate or slate-yjs adapter compatibility; turning raw Slate into a product editor.
• Decision boundaries: this plan may rename misleading benchmark surfaces, split readiness metrics, add a DOM-present group lifecycle, stage fresh DOM mounting, require stale-DOM absence proof, and keep shell explicit until the native/a11y/collab gates pass.
• Unresolved user-decision points: none. The plan can proceed to execution after user review.

Decision Brief

Principles:

• Default users should not tune chunk sizes, island sizes, or active radii.
• A performance rewrite that loses steady typing to legacy chunking cannot claim victory.
• Native browser behavior stays real until Slate owns the alternative input and accessibility stack.
• Comment/annotation state should not be forced into the Slate value.
• Claims must follow benchmark and browser proof, not architecture taste.

Top drivers:

• Benchmark shape after execution: shell explicit now has credible smoke wins, but default DOM-present still loses readiness/full-doc/event-input lanes.
• Native behavior risk: inactive shell islands are contentEditable=false role="button" shells, not invisible optimizations.
• Field evidence: Lexical scales with dirty-node discipline, ProseMirror with transaction/view/decorations mapping, VS Code with viewport rendering only because it owns input and accessibility separately.

Viable options:

Chosen option: two-tier auto.

Consequences:

• Shell mode remains explicit and benchmarkable, not the default claim.
• v2 must steal legacy chunking's grouping/memoization mechanism while killing the public chunking API.
• v2 must split benchmark claims by readiness and lane. interactiveReady can be compared to interactive startup only; nativeSurfaceComplete must be reported separately.
• DOM-present no-shell is the default-product owner, but current evidence does not satisfy startup, full-document replacement/fragment, promote, or event-input performance gates.
• Staged DOM-present is allowed; stale DOM is not.

Follow-ups:

• Split beforeinput lanes into setup-free event-input proof versus mixed promotion/setup lanes.
• Rename DOM-present/default/off/shell benchmark rows before optimizing.
• Add lifecycle/readiness metrics before any default-performance claim.

Current Source Evidence

Live Slate v2:

• Current public-ish large-doc prop is largeDocument?: LargeDocumentOptions | null on EditableTextBlocksProps: .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:264.
• Current LargeDocumentOptions is 'auto' | 'dom-present' | 'off' | 'shell' | { mode: 'shell', ... }; shell knobs no longer leak into non-shell object modes: .tmp/slate-v2/packages/slate-react/src/large-document/create-island-plan.ts:3.
• Current mode resolution treats omitted/null as auto: .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:60.
• Current shell config is created only when largeDocumentMode === 'shell'; auto and dom-present do not build a shell island plan: .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:621.
• Current rendering replaces inactive islands with LargeDocumentIslandShell only on the shell path; otherwise auto / dom-present use root groups: .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:757.
• Current createIslandPlan mounts all runtime ids for active corridor islands, so activeRadius now means actual mounted corridor: .tmp/slate-v2/packages/slate-react/src/large-document/create-island-plan.ts:51.
• Current DOM-present grouping is staged: interactive ready mounts the active 50-block group, far groups stay hidden pending-mount placeholders, selected pending groups materialize urgently, background mounting fills eight pending groups per tick, and the benchmark reports interactiveReady separately from nativeSurfaceComplete: .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:55 and .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx:491.
• Current shells use containment and content-visibility, then render as contentEditable={false}, role="button", tabIndex={0}: .tmp/slate-v2/packages/slate-react/src/large-document/island-shell.tsx:31 and .tmp/slate-v2/packages/slate-react/src/large-document/island-shell.tsx:139.
• Current root selectors already avoid root runtime id updates for text and selection ops: .tmp/slate-v2/packages/slate-react/src/editable/root-selector-sources.ts:24.
• Current island planning is memoized over config, promoted island, selection index, and top-level runtime ids: .tmp/slate-v2/packages/slate-react/src/editable/root-selector-sources.ts:139.
• Current EditorCommit already has classes, dirty region, dirty paths, node/decoration/selection impact runtime ids, touched runtime ids, tags, and text/structure flags: .tmp/slate-v2/packages/slate/src/interfaces/editor.ts:936.
• Current dirtiness classifies operations into text, selection, structural, replace, and mark classes, then derives impact ids: .tmp/slate-v2/packages/slate/src/core/public-state.ts:517.
• Current transaction boundary increments version and notifies listeners after outer update completion: .tmp/slate-v2/packages/slate/src/core/public-state.ts:1837.
• Current subscribeSource exists for commit-source-specific listeners: .tmp/slate-v2/packages/slate/src/core/public-state.ts:2005.
• Current DOM text sync is intentionally narrow: disabled for empty text, projections, custom leaf, custom segment, and custom text: .tmp/slate-v2/packages/slate-react/src/dom-text-sync.ts:3.
• Current DOM text sync skips composition and mutates one text DOM node when safe: .tmp/slate-v2/packages/slate-react/src/hooks/use-slate-node-ref.tsx:80.
• Current projection store already has source dirtiness classes, runtime scope, runtime subscriptions, source subscriptions, and metrics: .tmp/slate-v2/packages/slate-react/src/projection-store.ts:31.
• Current annotation store uses external anchors and per-annotation subscriptions: .tmp/slate-v2/packages/slate-react/src/annotation-store.ts:13.
• Current decoration sources compose projection stores: .tmp/slate-v2/packages/slate-react/src/decoration-source.ts:111.
• Current widget store has node, selection, and annotation anchors: .tmp/slate-v2/packages/slate-react/src/widget-store.ts:15.
• Current extension runtime rejects legacy methods and public extension commands, telling authors to add state or tx groups: .tmp/slate-v2/packages/slate/src/core/editor-extension.ts:60.
• Current createEditor exposes read, subscribe, update, and extend on the base editor: .tmp/slate-v2/packages/slate/src/create-editor.ts:486.
• Current React provider syncs text operations to DOM before selector notifications: .tmp/slate-v2/packages/slate-react/src/components/slate.tsx:100.
• Current selector hooks support operation/change-gated updates and deferred listeners: .tmp/slate-v2/packages/slate-react/src/hooks/use-editor-selector.tsx:51.
• Current mounted node render selectors can skip synced text rerender: .tmp/slate-v2/packages/slate-react/src/hooks/use-node-selector.tsx:41.

Benchmark and legacy evidence:

• Current compare runner uses activeRadius, chunkSize, islandSize, typeOps, explicit v2 model insert typing lanes, and model-owned beforeinput lanes: .tmp/slate-v2/scripts/benchmarks/browser/react/huge-document-legacy-compare.mjs:16 and .tmp/slate-v2/scripts/benchmarks/browser/react/huge-document-legacy-compare.mjs:531.
• Current v2 benchmark rows are explicit: v2Off, v2DefaultOmitted, v2AutoExplicit, v2DomPresent, v2ShellExplicitRadius0, and v2ShellExplicitRadius1.
• Current benchmark reports interactiveReady, nativeSurfaceComplete, model-only full-document commit lanes, visible full-document lanes, *ModelBeforeInputTypeMs, and *SelectThenModelBeforeInputTypeMs. It still does not prove real browser-native DOM insertion in jsdom.
• Legacy chunking maps children directly without chunking, but with chunking builds a chunk tree and renders ChunkTree: ../slate/packages/slate-react/src/hooks/use-children.tsx:119.
• Legacy memoized chunks rerender only when root/render callbacks change or the chunk is in modifiedChunks: ../slate/packages/slate-react/src/components/chunk-tree.tsx:66.
• Legacy child reconciliation invalidates modified chunks by child changes: ../slate/packages/slate-react/src/chunking/reconcile-children.ts:21.
• Legacy docs say root chunk size 1000 works well and content-visibility belongs on lowest chunks: ../slate/docs/walkthroughs/09-performance.md:64.

Research and external review:

• React 19.2 helps external stores, deferred/background work, Activity, and profiling, but not dirty-node mapping: docs/research/sources/editor-architecture/react-19-2-external-store-and-background-ui.md.
• Lexical evidence supports dirty leaves/elements, update tags, listener partitions, and strict read/update: docs/research/sources/editor-architecture/lexical-read-update-extension-runtime.md.
• ProseMirror evidence supports transaction metadata, selection mapping, bookmarks, one DOM bridge owner, and decorations as view data: docs/research/sources/editor-architecture/prosemirror-transaction-view-dom-runtime.md.
• Tiptap evidence supports extension packaging, discoverability, chain sugar, and React selector posture: docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md.
• Source-scoped overlay invalidation is already accepted as the next overlay perf extension: docs/research/decisions/slate-v2-source-scoped-overlay-invalidation.md.
• Collaborative annotations should use external channels by default: docs/research/decisions/slate-v2-collaborative-annotation-channels.md.
• GPT Pro review agreed with the two-tier direction and added sharper proof thresholds; answer captured in the 2026-05-01 chat turn.

Confidence Scorecard

Weighted total: 0.93.

Completion gates pass:

• no dimension below 0.85;
• no unplanned P0/P1 issue;
• intent, outcome, scope, non-goals, and boundaries are explicit;
• major decision has options and rejected alternatives;
• high-risk proof plan exists;
• public API target is decisive;
• no accepted objection remains unresolved.

Architecture North Star

Slate v2 should win by knowing exactly what changed, not by hiding the document as the default.

Target architecture:

Slate data model + operations
  -> editor.update transaction
  -> rich EditorCommit dirtiness
  -> runtime-id / top-level range indexes
  -> DOM-present root groups
  -> scoped React selectors
  -> direct DOM text sync when safe
  -> sidecar projection/annotation/widget indexes
  -> browser proof as release spine

The shell-island path remains available for aggressive huge-doc scenarios, but it is not the default editor body.

Public API Target

Live current source already cut the misleading enabled shape. Keep it cut.

Default:

<Editable />

The default turns on safe large-document auto behavior above threshold.

Optional override:

type LargeDocumentOptions =
  | "auto"
  | "dom-present"
  | "off"
  | "shell"
  | {
      mode: "shell";
      activeRadius?: number;
      islandSize?: number;
      previewChars?: number;
      threshold?: number;
    };

Rules:

• auto: default, DOM-present first.
• dom-present: force safe grouped editable DOM.
• shell: explicit aggressive mode.
• off: diagnostic escape hatch.
• no public enabled boolean in docs;
• no shell knobs in non-shell modes;
• docs prefer { mode: 'shell' } over bare 'shell' because the object shape makes the aggressive choice visible;
• benchmark/debug rows must name the actual mode, not "no island".

Internal Runtime Target

Commit Dirtiness

Before: current EditorCommit has useful dirtiness fields but not enough top-level/group-specific and DOM-sync-specific proof fields.

After:

type EditorCommit = {
  // existing fields kept
  dirtyTextRuntimeIds: readonly RuntimeId[] | null;
  dirtyElementRuntimeIds: readonly RuntimeId[] | null;
  dirtyTopLevelRuntimeIds: readonly RuntimeId[] | null;
  dirtyTopLevelRanges: readonly TopLevelRuntimeRange[] | null;
  affectedTextRuntimeIds: readonly RuntimeId[] | null;
  affectedNodeRuntimeIds: readonly RuntimeId[] | null;
  affectedProjectionRuntimeIds: readonly RuntimeId[] | null;
  affectedSelectionRuntimeIds: readonly RuntimeId[] | null;
  structuralDirtyRuntimeIds: readonly RuntimeId[] | null;
  textDirtyRuntimeIds: readonly RuntimeId[] | null;
  markDirtyRuntimeIds: readonly RuntimeId[] | null;
  rootRuntimeIdsChanged: boolean;
  topLevelOrderChanged: boolean;
  fullDocumentChanged: boolean;
};

Simple insert_text ideal result:

textDirtyRuntimeIds = [textId];
dirtyElementRuntimeIds = [paragraphId];
dirtyTopLevelRuntimeIds = [paragraphId];
dirtyTopLevelRanges = [[index, index]];
rootRuntimeIdsChanged = false;
topLevelOrderChanged = false;
fullDocumentChanged = false;

Implementation note: core commits stay renderer-agnostic and frozen. DOM text sync remains a slate-react capability/result, not a field inside the core EditorCommit. If Phase 2 needs per-runtime DOM-sync telemetry, add it to the React selector/change context, not to packages/slate.

Runtime Selector Fanout

Before: useEditorSelectorContext broadcast every commit to every selector listener, and runtime selectors filtered locally with shouldUpdate.

After:

• runtime-id selectors register in a runtime-indexed listener map;
• commits with affectedNodeRuntimeIds notify only those runtime ids;
• broad commits with affectedNodeRuntimeIds: null still fan out safely;
• synced text commits can still skip mounted render selectors through the existing operation policy;
• ordinary app code keeps using useNodeSelector / useTextSelector;
• the low-level useEditorSelector runtime-id option is only for runtime-owned selectors and tests.

Hard rules:

• text-only ops must not rebuild root runtime ids;
• text-only ops must not rebuild group/island plans;
• selection-only commits must not wake body text subscribers;
• DOM text sync success must suppress mounted text rerender;
• projection recompute must receive affected runtime ids, not a vague "text happened".

DOM-Present Root Groups

Before: legacy chunking wins by memoizing chunks; v2 shell islands win startup by not mounting most content, but lose typing.

After:

EditableRoot
  SlateRootGroup range=[0, 999]
  SlateRootGroup range=[1000, 1999]
  SlateRootGroup range=[2000, 2999]

Each group:

• subscribes by top-level range;
• memoizes stable render callbacks;
• preserves actual editable descendants;
• uses containment and content-visibility only after proof;
• rerenders only when commit ranges overlap group range.

Update test:

shouldGroupUpdate(groupRange, commit) {
  return commit.fullDocumentChanged
    || commit.topLevelOrderChanged
    || rangesOverlap(groupRange, commit.dirtyTopLevelRanges)
    || rangesOverlap(groupRange, commit.selectionTopLevelRanges)
    || rangesOverlap(groupRange, commit.projectionTopLevelRanges)
}

Active Corridor

Before: current activeRadius is misleading because neighboring islands can be marked active while only one active island mounts runtime ids.

After:

• DOM-present default uses a corridor of real editable groups around selection;
• recommended default proof candidate is current group plus 2 groups before and after;
• shell mode mounts corridor groups and shells only far groups;
• active means mounted, or the name changes.

Sidecar Range Index

Before: projection/annotation stores have the right direction, but large-doc proof must prove source-scoped recompute and runtime bucket locality.

After:

type ProjectionRangeIndex = {
  byRuntimeId: Map<RuntimeId, ProjectionSlice[]>;
  byTopLevelRuntimeId: Map<RuntimeId, RuntimeId[]>;
  intervalTreeByTopLevel: Map<RuntimeId, IntervalTree<ProjectionSlice>>;
  sourceVersions: Map<SourceId, number>;
  mappedThroughVersion: number;
};

Rules:

• map/rebase only affected anchors;
• recompute only affected runtime buckets;
• wake only mounted affected runtime ids;
• comment metadata updates do not repaint inline text unless projection payload changes;
• no default global decorate pass.

Selection Bridge

Add a ProseMirror-like owner:

• one DOM observer;
• controlled disconnect/reconnect around DOM writes;
• DOM selection import;
• Slate selection export;
• composition-safe mode;
• selection bookmarks for stale targets and remote edits;
• shell-backed selection explicitly marked synthetic/model-backed.

Hook / Component / Render DX Target

• Keep React hooks selector-first and commit-gated.
• Use useSyncExternalStore posture for external subscriptions.
• Keep visible typing urgent; defer sidebars, overlays, and non-editing UI.
• Do not force app authors to provide chunk wrappers.
• Do not expose product UI in raw Slate.
• Keep custom renderLeaf, renderSegment, and renderText supported, but benchmark fallback typing lanes because DOM sync is disabled for them.
• Keep extension writes under tx groups.
• Add optional command discoverability as metadata, not public extension command mutation slots:

defineEditorExtension({
  name: 'comments',
  tx: { comments: ... },
  capabilities: {
    commands: [
      {
        id: 'comments.add',
        title: 'Add comment',
        tx: 'comments.add',
        shortcut: 'Mod-Alt-M',
      },
    ],
  },
})

Plate Migration-Backbone Target

Plate should migrate to:

• raw Slate state / tx extension namespaces;
• capability metadata for command palettes, menus, and toolbars;
• external annotation channels for comments/review;
• widget/overlay channels for Plate chrome;
• selection/bookmark APIs that can back comment anchors;
• no raw Slate product comment service;
• no editor.api / editor.tf compatibility requirement in raw Slate.

Proof:

• Plate-like comments example with two lanes:
  • writer edits document value;
  • reviewer is read-only for document value but adds comments through sidecar annotation channel.
• Comment-only updates do not mutate Slate value.
• Comment metadata updates wake sidebars without repainting text.

slate-yjs Migration-Backbone Target

Collaboration needs deterministic substrate, not current adapter support.

Required:

• operations remain deterministic and replayable;
• remote apply produces the same commit metadata classes;
• runtime ids and durable anchors survive document edits;
• Yjs relative positions can implement the generic annotation anchor contract;
• comment-only updates can sync over a sidecar Yjs doc/map without requiring Slate value writes;
• stale target resolution has proof for remote insert/delete before cursor and delete-containing-anchor cases.

Benchmark Matrix

Document sizes:

Modes:

• legacyChunkOff
• legacyChunkOn
• v2Off
• v2DefaultOmitted
• v2AutoExplicit
• v2DomPresent
• v2ShellExplicitRadius0
• v2ShellExplicitRadius1
• v2ShellAutoCandidate only after proof
• v2CustomLeaf
• v2ProjectionHeavy
• v2AnnotationsHeavy
• v2CollabRemoteEdits

Group sizes:

• DOM-present: 100, 250, 500, 1000, 2000.
• Shell: 50, 100, 250, 500, 1000.

Corridor sizes:

• 0
• +/-1 group
• +/-2 groups
• +/-5 groups
• viewport + overscan

Required lanes:

• ready;
• first paint;
• first selection;
• steady type at 1, 10, 100 text ops;
• native beforeinput typing;
• select-then-type;
• promote-then-type for shell only;
• select-all;
• copy full document;
• paste full document;
• replace full document;
• insert fragment full document;
• undo/redo;
• composition;
• remote insert before cursor;
• remote delete containing anchor;
• projection refresh;
• annotation metadata update;
• browser find;
• screen-reader path;
• Android Chrome typing;
• iOS Safari typing.

5000-block gates:

• ready: v2 auto <= legacy chunk-on, preferably 3x faster;
• steady typing: v2 auto <= legacy chunk-on + 5 ms median;
• select-then-type: v2 auto <= legacy chunk-on + 10 ms median;
• full replace: v2 auto <= legacy chunk-on, preferably 2x faster;
• selectAll: v2 auto <= legacy chunk-on + 5 ms, or prove synthetic select/copy/paste parity;
• projection local update: O(affected runtime ids), not O(document);
• annotation metadata update: no document body rerender;
• custom leaf typing: no catastrophic fallback;
• IME/mobile: zero proof regressions.

10000-block gates:

• ready: v2 auto at least 5x faster than legacy chunk-on;
• steady typing: v2 auto <= legacy chunk-on + 15 ms median;
• full replace: v2 auto at least 2x faster than legacy chunk-on.

No performance superiority claim is allowed until 5000-block typing matches or beats legacy chunk-on within the thresholds above.

Browser Stress / Parity Strategy

Required proof families:

• model state;
• model selection;
• visible DOM;
• DOM selection/caret;
• focus;
• commit metadata;
• trace;
• follow-up typing;
• copy/paste;
• select-all;
• undo/redo;
• IME/composition;
• browser find;
• screen-reader traversal;
• mobile Chrome;
• mobile Safari;
• collaboration stale-target rebase.

Shell mode proof additions:

• find text in inactive shell ranges;
• screen-reader traversal over inactive ranges;
• native drag selection across shell boundaries;
• copy partial and full shell-backed selection;
• paste over shell-backed selection;
• no shell promotion during composition;
• persistent caret soak.

Applicable Implementation-Skill Review Matrix

High-Risk Deliberate-Mode Pre-Mortem

Trigger: public API, React runtime subscription strategy, browser behavior, collaboration, sidecar annotations, and release gates all change.

Blast radius:

• packages/slate
• packages/slate-react
• packages/slate-dom
• packages/slate-browser
• huge-document examples and benchmarks
• annotation/comment examples
• browser proof suites
• docs under docs/slate-v2

Failure scenario 1: DOM-present groups still rerender too broadly, so ready gets worse and typing still loses.

Mitigation: Phase 1 dirty payload gate must pass before DOM-present grouping can graduate; group update counts become benchmark output.

Failure scenario 2: content-visibility preserves DOM but harms browser find, screen readers, mobile selection handles, or paint in Safari.

Mitigation: containment/content-visibility is a gated layer, not assumed safe; browser find/a11y/mobile rows decide whether it is enabled by default.

Failure scenario 3: sidecar annotations become the new global decorate pass.

Mitigation: sidecar sources must declare dirtiness and runtime scope; metrics must prove recompute and subscriber wakes stay local.

Rollback / hard-cut answer:

• DOM-present auto can ship without shell escalation.
• Shell mode remains explicit if proof fails.
• Existing sidecar stores stay, but global refresh paths cannot be advertised as large-doc-ready.

Hard Cuts And Rejected Alternatives

Hard cuts:

• Cut public largeDocument.enabled as the documented default API.
• Cut any docs claiming current v2 shell mode beats legacy chunk-on typing.
• Cut "shell islands are the default large-doc architecture".
• Cut broad decorate as the primary comments/decorations path.
• Cut public extension commands mutation maps; keep state / tx and optional capability metadata.
• Cut performance victory claims until 5000-block typing passes.

Rejected alternatives:

• Keep current explicit island flag: too much DX tuning, not faster by default.
• Universal shell islands: unsafe native semantics and poor typing lanes.
• Drop islands entirely: throws away proven startup/full-document wins.
• Copy VS Code virtualization directly: wrong without owning input/a11y stack.
• Copy Lexical DOM reconciler wholesale: wrong unless Slate abandons React body rendering.
• Copy ProseMirror integer positions: wrong for Slate's public model.

Slate Maintainer Objection Ledger

Plan Deltas From GPT Review

Added:

• decisive two-tier default/opt-in policy;
• DOM-present auto as default;
• shell islands renamed/reframed as explicit aggressive mode;
• commit dirtiness target fields;
• group-size/corridor benchmark matrix;
• strict 5000/10000-block thresholds;
• sidecar range index target;
• browser/native risk table folded into proof gates;
• stale-doc hard cut.

Strengthened:

• legacy chunking read: steal grouping/memoization, kill API;
• React 19.2 read: substrate only, not architecture;
• comments/annotations: external sidecar is now part of perf plan, not a separate feature;
• activeRadius bug: active means mounted or the name changes.

Dropped:

• any path where current shell islands become universal default;
• any public tuning-first API;
• any claim that v2 is currently faster on typing.

No-change decisions:

• keep core v2 rewrite;
• keep editor.read / editor.update;
• keep extension state / tx hard cut;
• keep sidecar projections/annotations/widgets;
• keep browser proof as release spine.

Plan Deltas From GPT Pro Follow-Up

Added:

• explicit distinction between interactiveReady and nativeSurfaceComplete;
• default DOM-present staged mounting rule: allowed only as temporary reconciliation debt, not persistent virtualization;
• stale-DOM rule: after full-document replace/fragment, old far DOM must be detached or cleared before it can be searched, copied, or read as current content;
• root group lifecycle target:

type RootGroupState =
  | "fresh-mounted"
  | "pending-mount"
  | "pending-reconcile"
  | "reconciling"
  | "detached";

type RootGroupRecord = {
  groupId: string;
  startIndex: number;
  endIndex: number;
  runtimeIds: RuntimeId[];
  version: number;
  state: RootGroupState;
  priority: "selection" | "viewport" | "corridor" | "dirty" | "background";
};

• root group runtime target:

type RootGroupRuntime = {
  getPlan(): RootGroupPlan;
  getState(groupId: string): RootGroupState;
  markDirty(groupIds: string[], reason: string): void;
  mountUrgent(groupIds: string[]): void;
  scheduleBackground(groupIds: string[]): void;
  subscribeGroup(groupId: string, listener: () => void): () => void;
};

• benchmark surface rename:
  • v2Off
  • v2DefaultOmitted
  • v2AutoExplicit
  • v2DomPresent
  • v2ShellExplicitRadius0
  • v2ShellExplicitRadius1
• trace fields:
  • largeDocumentMode
  • groupingEnabled
  • shellEnabled
  • groupSize
  • corridor
  • stagedMountingEnabled
  • interactiveReadyAt
  • nativeSurfaceCompleteAt
  • mountedGroupCountAtReady
  • pendingGroupCountAtReady
  • staleGroupCount
  • backgroundMountChunks
  • maxBackgroundChunkMs

Strengthened:

• the next perf owner is DOM-present lifecycle, not shell;
• full-doc replace/fragment is the first implementation target after benchmark labeling because the current DOM-present numbers are catastrophic;
• beforeinput work comes after lifecycle unless fresh split traces prove event input is the dominant loss;
• staged DOM-present cannot be sold as native completeness until background mounting completes within a bounded latency.

Dropped:

• treating shell smoke wins as a default-performance victory;
• comparing staged interactiveReady against legacy full readiness without separately reporting nativeSurfaceComplete;
• keeping v2NoIsland as a benchmark row name.

No-change decisions:

• keep shell as explicit escape hatch;
• keep default auto DOM-present first;
• keep off as a real no-grouping control row;
• keep shell/native/a11y/collab gates before any shell auto/default claim.

Latest Scorecard Delta

Weighted total: 0.88.

Completion status: pending. The plan has a better next direction, but it is not execution-ready until the DOM-present lifecycle phase, benchmark rename, and proof gates are written as the next runnable slice.

Implementation Phases

Phase 0: Stop Claiming Victory

Owner: docs/benchmarks.

• Mark stale docs that claim v2 beats legacy typing as invalid.
• Update benchmark reports to show current failing lanes.
• Keep shell islands experimental.

Gate:

• benchmark table includes ready, typing, select/type, select-all, full replace, and insert fragment at 5000 and 10000 blocks.

Phase 1: Commit Dirtiness For Typing

Owner: packages/slate.

• Add dirty text/element/top-level/runtime id sets.
• Add root/order/full-document booleans.
• Keep DOM text sync renderer-local; do not put browser DOM facts into the core commit object.
• Ensure text-only ops do not invalidate root/group plans.
• Ensure selection-only commits do not wake body subscribers.

Gate:

• simple text insert commit proves one text id, one parent element id, one top-level range, no root order change.
• React provider selectors receive those scoped commit facts.
• No 5000-block performance claim is attached to Phase 1; Phase 2 owns the benchmark delta.

Phase 2: Internal DOM-Present Grouping

Owner: packages/slate-react.

• Cut selector fanout first by routing runtime-id selectors through affected runtime ids.
• Add internal SlateRootGroup or equivalent root group layer.
• Memoize by top-level range and commit overlap.
• Preserve actual editable DOM descendants.
• Add containment/content-visibility only behind browser proof.
• Do not expose renderChunk or getChunkSize.

Checkpoint after root-group slice:

• Internal root groups now exist in .tmp/slate-v2/packages/slate-react/src/components/editable-text-blocks.tsx for the non-shell DOM-present path.
• Groups are React fragments, so the slice adds no wrapper DOM and does not change native document structure.
• Profiler group events prove root groups do not rerender after a local text edit or parent rerender in the 1001-block focused test.
• bun check is green in .tmp/slate-v2.
• 2000-block one-iteration smoke is still red for typing:
  • legacy chunk-on middle type: 33.07 ms
  • v2 shell middle type: 78.23 ms
  • v2 no-island middle type: 96.31 ms
  • legacy chunk-on select-then-type: 33.92 ms
  • v2 shell select-then-type: 83.26 ms
  • v2 no-island select-then-type: 131.84 ms
• The tactic is not enough by itself. Next owner is measured mounted-subtree fanout: count descendant selector calls, text/element renders, root/group planning, and DOM text sync outcomes during the compare lanes before adding another abstraction.

Checkpoint after mounted-subtree instrumentation:

• The render profiler now records selector check/notify events, root-plan recomputes, and DOM text sync attempt/success/skip events.
• The huge-doc compare runner has an opt-in REACT_HUGE_COMPARE_PROFILE=1 mode. Normal benchmark timing stays unprofiled.
• Root selectors now use commit metadata instead of operation-list heuristics for root runtime ids, top-level selection index, placeholder, and editable root commit wakeups.
• Focused slate-react tests, bun --filter slate-react typecheck, bun lint:fix, and full bun check are green in .tmp/slate-v2.
• Profiled 2000-block smoke after the metadata cut:
  • shell middle type: selector events 100 -> 70; root runtime, placeholder, editable-root notifications 10 -> 0; editable root renders 10 -> 0; DOM sync still skips 10 times because the target is not mounted.
  • shell middle select-then-type: DOM sync succeeds, but selector events stay high at 87; one root plan/render happens after selection activation.
  • no-island middle type: selector events 90 -> 80; DOM sync succeeds; no root plan/render.
• Clean 2000-block smoke after the metadata cut is still red against legacy chunk-on:
  • legacy chunk-on middle type: 33.87 ms
  • v2 shell middle type: 64.32 ms
  • v2 no-island middle type: 78.02 ms
  • legacy chunk-on middle select-then-type: 33.23 ms
  • v2 shell middle select-then-type: 81.14 ms
  • v2 no-island middle select-then-type: 129.69 ms
• Next owner is narrower: identify and cut the remaining global selector notify per text op, decide whether the explicit unmounted-shell insert lane is a user-typing lane or a model/remote-update lane, then add the native beforeinput lane before any 5000-block claim.

Checkpoint after selection/global wakeup cut:

• subscribeSelectionOnlyDOMExport is now profiled as selection-dom-export and no longer wakes for plain text-only commits.
• The selection runtime contract now distinguishes plain text-only children changes from structural/selection changes.
• Focused selection/runtime tests, focused slate-react tests, bun --filter slate-react typecheck, bun lint:fix, profiled 2000-block smoke, clean 2000-block smoke, and full bun check are green.
• Profiled 2000-block smoke after the selection cut:
  • shell middle type selector events 70 -> 60;
  • no-island middle type selector events 80 -> 70;
  • selection DOM export notify is 0 for plain type lanes;
  • select-then-type still wakes selection DOM export because the lane moves model selection.
• Clean 2000-block smoke after the selection cut is still red against legacy chunk-on:
  • legacy chunk-on middle type: 32.00 ms
  • v2 shell middle type: 62.91 ms
  • v2 no-island middle type: 71.22 ms
  • legacy chunk-on middle select-then-type: 32.95 ms
  • v2 shell middle select-then-type: 82.38 ms
  • v2 no-island middle select-then-type: 136.75 ms
• The next proof must separate real user typing from explicit model writes into unmounted shell ranges. Add a native beforeinput lane before making the next architectural call.

Gate:

• 5000-block ready beats legacy chunk-on.
• 5000-block middle typing <= legacy chunk-on + 5 ms.
• 5000-block select-then-type <= legacy chunk-on + 10 ms.
• full replace keeps at least 2x advantage where feasible.

Phase 3: Source-Scoped Sidecar Range Index

Owner: packages/slate-react sidecar stores.

Status: complete.

• Add persistent projection range index.
• Map/rebase anchors through ops.
• Declare source dirtiness and runtime scope.
• Split projection payload from annotation metadata.
• Add two-lane collaborative comments example.

Current source read:

• Already done in live source: .tmp/slate-v2/packages/slate-react/src/projection-store.ts owns source dirtiness, runtime scope, source/runtime subscriptions, and projection metrics.
• Already done in live source: .tmp/slate-v2/packages/slate-react/src/annotation-store.ts owns bookmark-backed annotation rebase, targeted refresh, runtime subscriber wakeups, and annotation metrics.
• This pass added stronger package contracts in .tmp/slate-v2/packages/slate-react/test/annotation-store-contract.tsx: projection changes wake only the affected runtime bucket, and document edits rebase only annotations in impacted runtime buckets across a 40-annotation set.
• This pass added browser proof in .tmp/slate-v2/playwright/integration/examples/collaborative-comments.test.ts against .tmp/slate-v2/site/examples/ts/collaborative-comments.tsx: the reviewer is read-only for the document value, can add/update comments through the sidecar channel, and writer edits rebase the comment range.

Gate:

• writer edits document while read-only reviewer adds comments: passed;
• comment-only update does not mutate value: passed;
• comment body update does not repaint inline text unless projection changes: passed by package metadata/projection split contracts;
• large annotation sets stay runtime-bucket local: passed.

Phase 4: Selection Bridge And DOM Observer Discipline

Owner: packages/slate-dom / packages/slate-react.

Status: complete for local browser proof. Raw Android/iOS device proof remains a release/device gate, not a claim from this pass.

• Add one DOM observer/selection bridge owner.
• Stop observer around controlled DOM writes.
• Map DOM selection to Slate selection.
• Map Slate selection to DOM selection.
• Add composition-safe mode.
• Add selection bookmarks for stale targets.

Current source read:

• .tmp/slate-v2/packages/slate-react/src/editable/runtime-root-engine.ts already carries both explicit shell selection state and an isShellBackedSelection classifier.
• This pass wired the rendered root shell-backed state to the live model selection, so programmatic broad selections and stale-target style model selections get the same data-slate-large-document-selection="shell-backed" classification as explicit Ctrl+A/browser-handle paths.
• .tmp/slate-v2/packages/slate-react/test/large-doc-and-scroll.tsx now proves a programmatic full-document model selection across shelled ranges is classified as shell-backed without expanding shells.
• .tmp/slate-v2/packages/slate-dom/src/plugin/dom-clipboard-runtime.ts now has a model-backed clipboard fallback when a selection cannot be cloned from the DOM because some selected content is not mounted.
• .tmp/slate-v2/playwright/integration/examples/large-document-runtime.test.ts proves full and partial shell-backed selections write normal text/html Slate fragment clipboard payloads from a copy event.
• .tmp/slate-v2/packages/slate-browser/src/playwright/index.ts now keeps the keyboard/OS clipboard helper honest: clipboard.copyPayload() uses the real shortcut and real clipboard reads only, while clipboard.copyEventPayload() names the synthetic copy-event payload contract used for shell-backed selections with unmounted content.
• .tmp/slate-v2/playwright/integration/examples/large-document-runtime.test.ts now proves a real mouse drag inside mounted large-document content remains native/DOM-owned, imports an expanded model selection, and does not get mislabeled as shell-backed.
• Existing large-document composition rows in .tmp/slate-v2/playwright/integration/examples/large-document-runtime.test.ts freshly pass on Chromium native composition and the Playwright mobile project synthetic composition lane.
• .tmp/slate-v2/packages/slate-react/src/editable/browser-handle.ts now exposes resolveRangeRef so browser stale-target proofs can observe a live range ref before unref.
• .tmp/slate-v2/packages/slate-react/src/editable/runtime-root-engine.ts now owns browser-handle range-ref cleanup at root unmount. Reattaching the browser handle during a render no longer unrefs bookmarks needed by remote operation rebase proof.
• .tmp/slate-v2/playwright/integration/examples/large-document-runtime.test.ts now proves a shell-backed selection bookmark captured in an unmounted island rebases through a remote text operation, restores into mounted content, and copies the original selected text through the real keyboard/OS clipboard path.

Gate:

• native selection drag: passed for mounted large-document content; cross-shell drag remains explicitly not a native-DOM claim while inactive shells replace content;
• select-all: partially passed for explicit and programmatic shell-backed model selection classification;
• partial/full copy: passed for shell-backed copy event payloads;
• keyboard/OS clipboard contract: passed by split contract; real shortcut clipboard proof remains a DOM-present/native-DOM-row contract, not a shell-backed-row claim;
• paste over range: already covered for shell-backed full and partial Slate fragment paste rows;
• IME composition: passed for desktop native Chromium and semantic mobile synthetic composition; raw Android/iOS device proof is not claimed here;
• Android/iOS typing: still a raw-device release gate, not satisfied by the Playwright mobile viewport row;
• remote rebase proof: passed for shell-backed selection bookmarks through remote text operation replay.

Phase 5: Explicit Shell Mode

Owner: large-document runtime.

• Rename policy to mode: 'shell'.
• Fix active radius so active islands mount.
• Derive shell-backed selection consistently.
• Complete shell copy/paste/select-all semantics.
• Disable promotion during composition unless proven safe.

Gate:

• browser find inactive ranges;
• screen-reader traversal;
• native selection across shell boundaries;
• copy/paste partial and full ranges;
• IME/mobile/undo/collab/persistent caret soak.

Phase 6: Release Docs And Examples

Owner: docs/examples.

• Document auto, off, dom-present, shell.
• Provide a huge-document benchmark page.
• Provide comments sidecar example.
• Provide migration notes for legacy chunking users.
• Keep docs written as current-state reference, not changelog prose.

Gate:

• docs match live API;
• examples pass browser proof;
• no stale "v2 beats legacy" claim without current benchmark artifact.

Next Performance Lane From GPT Pro Follow-Up

Phase 7.0: Benchmark Surface Rename And Trace Hygiene

Owner: benchmark runner.

• Rename current rows:
  • v2LargeDocument -> v2ShellExplicitRadius0 or v2ShellExplicitRadiusN;
  • v2NoIsland -> one of v2DefaultOmitted, v2AutoExplicit, or v2DomPresent depending on the actual input.
• Add explicit rows:
  • v2Off;
  • v2DefaultOmitted;
  • v2AutoExplicit;
  • v2DomPresent;
  • v2ShellExplicitRadius0;
  • v2ShellExplicitRadius1.
• Add trace fields for mode, grouping, shell, group size, corridor, staged mounting, readiness times, mounted/pending/stale counts, and background chunks.

Gate:

• no benchmark report contains v2NoIsland;
• omitted/default, explicit auto, explicit DOM-present, explicit off, and explicit shell are distinguishable;
• trace makes shell wins impossible to confuse with default wins.

Phase 7.1: DOM-Present Full-Document Replace / Fragment Lifecycle

Owner: EditableTextBlocks / root group runtime.

Implement group lifecycle before optimizing startup.

Target full-document replace flow:

1. Commit model synchronously.
2. Compute the new root group plan.
3. Urgently mount active/viewport/corridor groups.
4. Detach or clear old far groups synchronously.
5. Schedule fresh far groups.
6. Mark nativeSurfaceComplete = false.
7. Flip nativeSurfaceComplete = true only after all groups are fresh.

Hard rule:

• old far DOM may be temporarily missing;
• old far DOM must not remain visible/searchable/copyable/readable as current content after the model changed.

Gate:

• after full replace visible commit, old far text is absent from DOM;
• new active text is present immediately;
• new far text appears after nativeSurfaceComplete;
• copy/select behavior uses model-backed payload or fresh DOM, never stale DOM;
• full replace visible commit is at or below legacy chunk-on at 5000 blocks.

Phase 7.2: DOM-Present Startup Staging

Owner: root group runtime.

Target startup flow:

1. Compute root groups.
2. Urgently mount active/viewport/corridor.
3. Mark far groups pending-mount.
4. Report interactiveReady.
5. Mount far groups with a bounded background budget.
6. Report nativeSurfaceComplete.

Gate:

• interactiveReady is at or below legacy chunk-on ready at 5000 blocks;
• nativeSurfaceComplete is measured separately;
• browser find/screen-reader/native selection claims are only made after nativeSurfaceComplete;
• continuous typing/scrolling cannot starve completion indefinitely.

Phase 7.3: Group Size, Corridor, And Background Budget Sweep

Owner: benchmark runner + runtime policy.

Sweep:

• group size: 250, 500, 1000;
• corridor: viewport, viewport +/-1, viewport +/-2;
• background budget: 4 ms, 8 ms, 16 ms.

Initial suspicion:

• start with groupSize=500 | 1000, corridor=viewport+/-1 | +/-2, backgroundBudget=8 ms;
• do not default to 100 unless the sweep proves it.

Gate:

• default candidate chosen by 5000-block median, not one-iteration smoke;
• 10000-block stress shape is not pathological;
• normal-doc overhead at 100/500 blocks stays acceptable.

Phase 7.4: Beforeinput/Event Path After Lifecycle

Owner: browser input runtime.

Profile after lifecycle is sane:

• beforeinput received;
• target DOM node lookup;
• DOM -> Slate point/range import;
• model op;
• normalization;
• commit dirtiness;
• DOM text sync;
• selection export/caret repair;
• React selector flush.

Gate:

• setup-free model-owned beforeinput is within directModelType + small constant;
• select/setup-inclusive model-owned beforeinput lanes stay named as model owned, not native;
• real browser-native input proof is added separately outside the jsdom-only model-owned lane;
• event-path proofs include mounted content and pending group materialization.

Phase 7.5: Default Claim Gate

Default large-document performance can be claimed only when 5000-block, 5-iteration medians pass:

Fast Driver Gates

Use these during implementation:

• 2000 blocks: smoke/debug.
• 5000 blocks: release gate.
• 10000 blocks: stress/nightly.
• typeOps=10 and typeOps=100.
• group update count.
• projection recompute count.
• annotation subscriber wake count.
• DOM text sync attempted/succeeded/failed counts.
• native beforeinput lane.

Open Questions

• Exact default group size: benchmark 250, 500, 1000, 2000; initial likely winner is 500 or 1000.
• Exact default corridor: benchmark +/-1, +/-2, +/-5; initial likely winner is +/-2.
• content-visibility default: enable only after browser find/a11y/mobile proof passes by browser family.
• Shell auto escalation threshold: no default threshold until shell proof passes.
• Whether to expose dom-present as public mode or only debug mode: decide after docs/API ergonomics pass.

What would change the decision:

• If DOM-present grouping cannot match legacy chunk-on typing at 5000 blocks after commit dirtiness is fixed, then the runtime must consider a deeper Lexical-style body reconciler or a true EditContext-like input layer.
• If shell mode unexpectedly passes native find/screen-reader/native selection/IME/mobile proof and typing becomes competitive, it may become a high-threshold auto escalation. It still should not be the first default.

Pass-State Ledger

Final Completion Gates

Latest status is closed for the current default-performance gate, with a recorded follow-up for 10000-block immediate far-selection stress.

The previous shell-policy execution is complete:

• explicit shell policy exists;
• shell corridor semantics are fixed;
• shell composition guard exists;
• docs/examples describe shell as explicit/aggressive;
• shell smoke rows are green enough to keep as an escape hatch.

The default-performance lane is complete for the current release claim because these Phase 7 gates now pass or have a recorded owner:

• benchmark surfaces no longer use v2NoIsland (Phase 7.0 complete);
• interactiveReady and nativeSurfaceComplete are measured separately;
• DOM-present full-document replace/fragment never leaves stale far DOM exposed;
• DOM-present startup uses a bounded group lifecycle;
• group size/corridor/background budget are chosen from multi-iteration data for the 5000-block release target, with failed 10000 local tuning recorded;
• beforeinput/event path is named honestly after lifecycle is sane;
• default DOM-present 5000-block medians beat or match legacy chunk-on for the required lanes;
• real browser-native input proof exists separately from the jsdom model-owned beforeinput lanes (complete for active DOM-present Chromium typing);
• shell remains explicit unless native/a11y/collab gates pass.

Do not upgrade this into a 10000-block immediate far-selection victory. That is the next research/perf owner.