Slate v2 Node Query API Ralplan

Date: 2026-05-14

1. Current Verdict

Status: done.

No, the current example shape is not absolute best:

const [link] = editor.read((state) =>
  Array.from(
    state.nodes.match({
      match: (n) => NodeApi.isElement(n) && n.type === "link",
    }),
  ),
);

The underlying v2 traversal is still lazy and generator-based, but this call site throws that away by materializing all matches to read one entry. It also has avoidable API stutter: state.nodes.match({ match: ... }).

Draft target:

const link = editor.read((state) =>
  state.nodes.find({
    match: (n) => NodeApi.isElement(n) && n.type === "link",
  }),
);

const isActive = editor.read((state) =>
  state.nodes.some({
    match: (n) => NodeApi.isElement(n) && n.type === "link",
  }),
);

for (const [node, path] of state.nodes.entries({ at, match })) {
  // lazy all-match traversal
}

Current score: 0.94.

Current-state read, issue-ledger cache validation, source/research grounding, alias policy, API objection pass, DX-extension audit, benchmark acceptance rows, and closure score are complete. The plan is ready for user review and a later Ralph execution.

Follow-up note, 2026-05-14: the broader generator-materialization review in docs/plans/2026-05-14-slate-v2-generator-materialization-api-ralplan.md supersedes only this plan's earlier blanket rejection of state.nodes.toArray. entries / find / some stay accepted; the new plan reopens a narrow allocation-explicit materializer for read-boundary array returns.

2. Intent And Boundary

Intent: keep Slate v2's query API as fast as legacy Slate for first-match and iterator consumers while keeping the accepted editor.read / editor.update lifecycle boundary.

Desired outcome:

• First-match active checks do not call Array.from.
• Boolean active checks do not call Array.from.
• All-match consumers still get lazy traversal.
• Public names are less weird than nodes.match({ match }).
• Slate v2 keeps the state/tx API shape instead of restoring static Editor.nodes(editor, ...) as the normal public route.

In scope:

• .tmp/slate-v2/packages/slate/src/core/public-state.ts
• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts
• .tmp/slate-v2/packages/slate/src/editor/nodes.ts
• current examples that use state.nodes.match for first-match checks
• focused query-contract tests and a small query benchmark
• issue-ledger accounting for the Editor.nodes / query API cluster

Non-goals:

• no React render/runtime rewrite;
• no raw tree model rewrite;
• no ProseMirror integer-position model;
• no Lexical node-map/type-index migration unless benchmarks prove repeated global type queries are hot;
• no current-version Plate or slate-yjs adapter compatibility promise.

Decision boundaries:

• Slate Ralplan may decide public API target shape and proof gates.
• Ralph owns implementation edits in .tmp/slate-v2.
• Hard cut state.nodes.match to state.nodes.entries by default. The local built dist contains the draft API, but the package changelog has no public v2/state-query release note; treat this as pre-release until a release owner proves otherwise. If the draft API already shipped outside this repo, keep a deprecated match alias to entries for one cycle only and remove it before stable v2.

Unresolved user-decision points: none for the current pass. The remaining work is technical proof and score hardening.

3. Decision Brief

Principles:

• Keep reads explicit through editor.read.
• Keep traversal lazy by default.
• Do not make common first-match checks allocate arrays.
• Keep Slate terminology close to NodeEntry, match, mode, voids, and pass.
• Prefer a small generic query surface over plugin/product helpers in core.
• Add generic boolean helpers only when they mirror Slate's existing match-filter semantics without requiring a second candidate predicate.

Top drivers:

• Current v2 query owner is a generator: .tmp/slate-v2/packages/slate/src/editor/nodes.ts:6.
• Raw node traversal is also a generator: .tmp/slate-v2/packages/slate/src/interfaces/node.ts:677.
• Public read state exposes state.nodes.match: .tmp/slate-v2/packages/slate/src/core/public-state.ts:960.
• Examples materialize first-match checks: .tmp/slate-v2/site/examples/ts/inlines.tsx:180 and .tmp/slate-v2/site/examples/ts/richtext.tsx:411.
• Legacy Slate let first-match destructuring consume only the first generator yield: ../slate/packages/slate/src/editor/nodes.ts:6.

Viable options:

Chosen option: rename lazy all-match read API to state.nodes.entries, add state.nodes.find, and add state.nodes.some. Keep match as the predicate option name.

Consequences:

• Existing v2 examples/tests using state.nodes.match need a mechanical rename.
• First-match examples become both shorter and more honest about traversal cost.
• find and some must be implemented by consuming the existing generator only until the result is known.

Follow-ups:

• Add a small first/last/no-match benchmark in Ralph or extend the existing query-ref benchmark.
• Add a visit-count contract test.

4. Confidence Scorecard

Total: 0.94.

Completion threshold is met. The plan is ready for user review.

5. Source-Backed Architecture North Star

Slate v2 should remain:

• read/update lifecycle first;
• lazy traversal by default;
• explicit all-match iteration for structural code;
• first-match helpers for common active checks;
• unopinionated core primitives, not product/plugin shortcuts.

6. Ecosystem Strategy Synthesis

7. Public API Target

Target:

type EditorStateNodesApi = {
  entries: <T extends Node>(
    options?: EditorNodesOptions<T>,
  ) => Generator<NodeEntry<T>, void, undefined>;
  find: <T extends Node>(
    options?: EditorNodesOptions<T>,
  ) => NodeEntry<T> | undefined;
  some: <T extends Node>(options?: EditorNodesOptions<T>) => boolean;
};

Keep existing direct accessors like above, children, first(at), get, levels, next, previous, and void. Do not overload first for query matching because it already means first node at a location.

Hard cut:

• Cut state.nodes.match by default. The local dist artifact contains the draft API, but .tmp/slate-v2/packages/slate/CHANGELOG.md has no v2/state-query release entry. Treat this as pre-release local build state.
• If a release owner confirms that state.nodes.match already shipped outside this repo, keep a deprecated alias to entries for one cycle only, with examples and docs moved to entries, find, and some.

7.1 Public DX Candidate Audit

Accepted now: no additional public node-query method beyond entries, find, and some.

Rejected or deferred:

8. Internal Runtime Target

• entries delegates to the existing getNodes(editor, options) generator.
• find uses for (const entry of getNodes(...)) return entry.
• some uses for (const _ of getNodes(...)) return true.
• No Array.from inside the helpers.
• No global type index in this slice.

9. Hook / Component / Render DX Target

• Toolbar active checks use state.nodes.some(...).
• Uniform selection checks can use some with a negative match or a Plate-level helper; raw Slate should not add an ambiguous every yet.
• Callers that need the actual node use state.nodes.find(...).
• Structural transforms and DOM bridge code use for...of state.nodes.entries.
• Examples should not teach Array.from(...)[0].

10. Plate Migration-Backbone Target

Plate can build product helpers on top of find, some, and entries without wrapping every core call or restoring static Editor.nodes. The target is a small substrate, not Plate's current public API.

11. Slate-Yjs Migration-Backbone Target

No direct collab data-model change. Deterministic lazy query order remains important for plugin and normalization decisions, but this plan makes no serialized operation or remote-apply claim.

12. Issue-Ledger Accounting

ClawSweeper / cache status: reuse existing query-surface cache. Do not run broad live GitHub discovery.

PR description status: unchanged. This plan changes no fixed issue claims, accepted release-gate claims, or maintainer-facing PR narrative yet; the existing #5080 fixed line remains correct and #5684/#5028/#3885 stay related or not claimed.

13. Legacy Regression Proof Matrix

14. Browser Stress / Parity Strategy

No browser behavior changes are planned. Browser proof is not required unless Ralph touches slate-react, slate-dom DOM bridge behavior, or examples with interactive selection assertions.

15. Applicable Implementation-Skill Review Matrix

16. High-Risk Deliberate Mode

Triggered because this changes public API.

Pre-mortem:

1. Alias policy confusion leaves both match and entries in examples forever.
2. find / some accidentally call Array.from internally and only improve DX.
3. Rename breaks extension state groups or tx groups because both spread state.nodes into transaction nodes.

Proof plan:

• Public-surface type test for entries, find, and some.
• Query-contract sequence parity for entries.
• Visit-count early-exit test for find and some.
• Reverse / pass / voids regression tests through renamed API.
• Example grep banning Array.from(state.nodes.entries(...))[0] style.

Rollback / hard-cut answer: hard cut match to entries by default. If the release owner proves match already shipped, keep match as a deprecated alias for one cycle and still add find / some. Do not drop the early-exit helpers.

17. Hard Cuts And Rejected Alternatives

• Cut example first-match Array.from patterns.
• Cut match as the all-match method name if pre-release.
• Reject static Editor.nodes as normal v2 public API.
• Reject callback-only ProseMirror traversal.
• Reject global type indexes without benchmark proof.
• Reject product-style query helpers in raw Slate core.
• Defer count and type indexes until benchmarks prove a real hot path.

18. Slate Maintainer Objection Ledger

19. Pass Schedule And Pass-State Ledger

20. Plan Deltas From Review

Added:

• Draft hard-cut target from state.nodes.match to state.nodes.entries.
• Draft find and some helpers.
• DX candidate audit for extra helpers from Lexical, ProseMirror, and Tiptap.
• Research decision comparing legacy Slate, ProseMirror, Lexical, and Tiptap.
• Focused .tmp/slate-v2 verification row for current query contract.

Dropped:

• Restoring static Editor.nodes as normal v2 public route.
• Copying ProseMirror callback traversal.
• Treating Lexical array returns as a Slate core query model.
• Copying Tiptap selector and product helper APIs into raw Slate.
• Adding every before Slate has a clean candidate/assertion split.

Strengthened:

• Example cleanup must remove first-match Array.from.
• Benchmark/test gates must prove early exit.

21. Open Questions And What Would Change The Decision

• Hard cut state.nodes.match by default. Use a deprecated alias for one cycle only if a release owner proves the draft API already shipped outside this repo.
• If benchmarks show repeated global type queries dominate, plan a separate optional index lane. Do not mix that into this API cleanup.
• If real call sites need count-without-materialization, plan a separate state.nodes.count lane with limit semantics and benchmark proof.
• If source audit finds many all-match consumers where entries reads worse, keep match as the all-match method and still add find / some.

22. Implementation Phases With Owners

Ralph phase 1:

• Add public API tests for entries, find, and some.
• Add early-exit visit-count tests.
• Add parity tests proving entries matches current match ordering, including reverse, pass, voids, and modes.

Ralph phase 2:

• Implement helpers in core/public-state.ts and types in interfaces/editor.ts.
• Rename examples and package callers.
• Decide and implement alias policy.

Ralph phase 3:

• Add or run focused benchmark for first/last/no-match query cases.
• Run release gates.
• Sync issue/docs ledgers if docs/examples change.

23. Fast Driver Gates

Planning-only gate:

# cwd: /Users/zbeyens/git/plate-2
bun run completion-check

Slate v2 gates:

# cwd: /Users/zbeyens/git/slate-v2
bun test ./packages/slate/test/query-contract.ts
bun --filter slate typecheck
rg -n "Array\\.from\\(\\s*state\\.nodes\\.(match|entries)|Array\\.from\\(\\s*tx\\.nodes\\.(match|entries)" packages site/examples/ts

Benchmark gate draft:

# cwd: /Users/zbeyens/git/slate-v2
bun ./scripts/benchmarks/core/current/query-ref-observation.mjs

Acceptance thresholds for Ralph's focused query helper benchmark:

• first-match-at-start: find and some must visit no more than the matched prefix plus ancestors needed by current traversal;
• first-match-at-end / no-match: no worse than current entries traversal by more than 5 percent median across five warm samples;
• first-match-at-start: find and some must be at least 10x faster than Array.from(entries(...))[0] on a 10k-block document, or the benchmark must explain why traversal setup dominates and still prove early-exit visit count;
• no helper may allocate an all-match array internally.

The current pass ran:

# cwd: /Users/zbeyens/git/slate-v2
bun test ./packages/slate/test/query-contract.ts
# result: 79 pass, 0 fail

# cwd: /Users/zbeyens/git/slate-v2
bun --filter slate typecheck
# result: pass

# cwd: /Users/zbeyens/git/slate-v2
bun ./scripts/benchmarks/core/current/query-ref-observation.mjs
# result: pass; nodesReadAfterWriteMs mean 20.28ms, delta +5.72ms

# cwd: /Users/zbeyens/git/slate-v2
rg -n "Array\\.from\\(\\s*state\\.nodes\\.(match|entries)|Array\\.from\\(\\s*tx\\.nodes\\.(match|entries)|state\\.nodes\\.match\\(|tx\\.nodes\\.match\\(" packages site/examples/ts
# result: existing `state.nodes.match` callers found in examples, slate-dom,
# and query-contract; these are Ralph rename/cleanup targets.

# cwd: /Users/zbeyens/git/plate-2
bun run completion-check
# result before closeout: expected failure while Slate Ralplan was pending.

24. Final User-Review Handoff Outline

Ready handoff:

• Public API: state.nodes.match -> state.nodes.entries; add find; add some; alias policy.
• Runtime: generator retained; find/some early-exit.
• DX: examples stop using Array.from for first match.
• Tests: public-surface, query parity, early-exit, reverse/pass/void regression.
• Issues: no new Fixes claim; #3885 stays not claimed unless a docs route is explicitly added.
• Hard cuts: no static Editor.nodes restoration.

25. Final Completion Gates

Passed:

• score is 0.94 and no dimension is below 0.85;
• issue-ledger pass is complete and PR reference status is recorded as unchanged;
• alias policy is decided: hard cut by default, one-cycle alias only if release owner proves external shipment;
• benchmark/test acceptance rows are concrete;
• objection ledger rows are accepted;
• continuation file can be removed after marking completion done.

26. Ralph Execution Result

Status: complete.

Execution date: 2026-05-14.

Implemented in .tmp/slate-v2:

• Added state.nodes.entries(options) as the lazy all-match query API.
• Added state.nodes.find(options) and state.nodes.some(options) as early-exit helpers.
• Cut the public state.nodes.match(options) draft API from the state/tx node surface.
• Updated first-party examples and DOM internals away from Array.from( state.nodes.match(...)) first-match patterns.
• Extended query-ref-observation.mjs with first-match array, find, some, last-match, and no-match lanes.

Proof:

# cwd: .tmp/slate-v2
bun test ./packages/slate/test/query-contract.ts
# result: 80 pass, 0 fail

bun --filter slate typecheck
# result: pass

bun --filter slate-dom typecheck
# result: pass

bun typecheck:site
# result: pass

bun check
# result: pass; includes lint, package/site/root typecheck, Bun tests, and
# slate-react Vitest suite

bun ./scripts/benchmarks/core/current/query-ref-observation.mjs
# result: pass; default 200-block run recorded firstMatchArrayMs mean 23.20ms,
# firstMatchFindMs mean 0.45ms, firstMatchSomeMs mean 0.28ms

DRIFT_BENCH_BLOCKS=10000 DRIFT_BENCH_QUERY_OPS=20 \
DRIFT_BENCH_WRITE_OPS=5 DRIFT_BENCH_REFS=5 DRIFT_BENCH_ITERATIONS=3 \
bun ./scripts/benchmarks/core/current/query-ref-observation.mjs
# result: pass; 10k-block run recorded firstMatchArrayMs mean 190.70ms,
# firstMatchFindMs mean 0.23ms, firstMatchSomeMs mean 0.11ms,
# lastMatchFindMs mean 135.88ms, noMatchFindMs mean 123.50ms

rg -n "Array\\.from\\(\\s*state\\.nodes\\.(match|entries)|Array\\.from\\(\\s*tx\\.nodes\\.(match|entries)|state\\.nodes\\.match\\(|tx\\.nodes\\.match\\(" packages site/examples/ts scripts
# result: no matches

Reference docs:

• docs/slate-v2/references/pr-description.md now names state.nodes.entries, state.nodes.find, and state.nodes.some as the current public query shape.
• #5080 ledger wording now uses state.nodes.entries({ reverse: true }).
• No new fixed issue claim was added.

Residual risk:

• .tmp/slate-v2 had unrelated dirty example/runtime files before this execution (site/examples/ts/embeds.tsx, site/examples/ts/images.tsx, site/examples/ts/paste-html.tsx, site/examples/ts/rendering-strategy-runtime.tsx, and related example registry/test files). They were not reverted or claimed as part of this slice.