Slate v2 Api Helper Namespace Rename Ralplan

Date: 2026-05-13

Status: done

Owner: slate-ralplan

Completion: active goal state

Current Verdict

Yes: hard rename the public value helper namespaces from merged type/value names to *Api names.

Accepted target:

import {
  ElementApi,
  NodeApi,
  PathApi,
  PointApi,
  RangeApi,
  TextApi,
  type Element,
  type Node,
  type Path,
  type Point,
  type Range,
  type Text,
} from "slate";

NodeApi.string(node);
ElementApi.isElement(node);
PathApi.next(path);
RangeApi.edges(range);

Do not rename model types just to dodge DOM globals. type Node, type Element, type Text, type Path, type Point, type Range, and operation/ref/location types stay as the Slate data model vocabulary.

Do not add public compatibility aliases like export const Node = NodeApi. That would keep the global-shadowing footgun and autocomplete noise alive.

Do not resurrect a public EditorApi value. The root Editor value is already cut by the live public-surface contract, and editor reads/writes belong to editor.read((state) => ...) and editor.update((tx) => ...).

Closure verdict: ready for Ralph execution.

Intent Boundary

Pressure test:

• If the only reason were "Plate does it", this would be weak.
• The stronger reason is that Slate v2 is a browser-facing library and the current Node / Element / Text / Range value imports shadow DOM names while also relying on TypeScript declaration merging. That is needless friction for humans and agents.

Live Source Evidence

Issue Ledger Accounting

ClawSweeper status: completed for Ralph execution. The bounded sweep stayed on cached local ledgers and the exact #5400 dossier; no broad GitHub issue list refresh was needed.

Ledger evidence:

• docs/slate-issues/gitcrawl-live-open-ledger.md:225 lists current open issue #5400.
• docs/slate-issues/open-issues-dossiers/5402-5250.md:67-77 says the repro is a Slate Node import shadowing the browser Node global.
• docs/slate-issues/gitcrawl-v2-sync-ledger.md:227 now marks #5400 as fixes-claimed after source proof.

PR reference status: updated under Core Editor API Reset with the accepted helper namespace shape and issue #5400 claim text.

Decision Brief

Principles:

1. Model types keep Slate vocabulary.
2. Runtime/helper value imports must not shadow browser globals by default.
3. No public alias that keeps a removed name alive.
4. No editor-state static namespace revival.
5. Migration must be codemodable and contract-proven.

Top drivers:

• DOM globals: Node, Element, Text, and Range are real browser names.
• Agent and human DX: merged type/value names are harder to reason about.
• Plate migration: Plate already proved the *Api suffix reads well in a rich editor ecosystem.

Viable options:

Chosen consequence:

• NodeApi.string(node) is slightly more verbose than Node.string(node), but the name says "helper object", not "document node" or "DOM Node".
• Existing Slate snippets need a codemod: s/\b(Node|Element|Text|Path|Point|Range|Operation|Location|Span|PathRef|PointRef|RangeRef|Scrubber)\./$1Api./ plus import rewrites.

Public API Target

Rename every public merged type/value helper object to *Api.

Primary public helper values:

Closure decisions for previously open names:

• Scrubber uses ScrubberApi, not top-level function pairs. It is a mutable global config helper, but the API-family rule is still clearer than keeping a merged type/value name.
• Location and Span stay public if their source modules remain public, and their helper values become LocationApi and SpanApi.
• PathRef, PointRef, and RangeRef helper values become PathRefApi, PointRefApi, and RangeRefApi.

Hard cuts:

• No public Node, Element, Text, Path, Point, Range, Operation, Location, Span, PathRef, PointRef, RangeRef, or Scrubber value exports.
• No temporary alias exports.
• Internal source may use local aliases while migrating a file, but final public root and public docs must use *Api.

Internal Runtime Target

• Rename implementation constants at their source modules, not only at the root barrel.
• Update internal references to use NodeApi, ElementApi, etc. when they import helper values.
• Keep internal-only Editor static table under slate/internal until the existing Editor hard-cut plan finishes its own migration.
• Avoid changing behavior. This is a naming/API contract pass only.

Hook / Render DX Target

• Public examples that touch DOM should no longer need aliases like Node as SlateNode for helper calls.
• Type imports remain explicit:

import { NodeApi, type Node } from "slate";

• Docs should explain that *Api names are helper namespaces and bare type names are the document model.

Plate And Slate-Yjs Migration Backbone

Plate:

• Plate already uses NodeApi / ElementApi / PathApi.
• This rename reduces adapter noise for Plate migration instead of forcing Plate to translate raw Slate helper names back into its established public shape.

slate-yjs / collaboration:

• No operation shape, path shape, selection shape, runtime id, snapshot, commit, or replay behavior changes.
• Operation helper value becomes OperationApi, but the Operation type and serialized operation records stay unchanged.
• Collaboration proof should be import/type surface only, not behavioral.

Ecosystem Strategy Synthesis

Regression Proof Matrix

Applicable Review Matrix

High-Risk Deliberate Mode

Trigger: public package API rename across root imports.

Blast radius:

• .tmp/slate-v2/packages/slate/src/interfaces/**
• .tmp/slate-v2/packages/slate/test/**
• .tmp/slate-v2/packages/slate-react/** and slate-history imports that read helper values
• .tmp/slate-v2/docs/**, .tmp/slate-v2/site/**
• changeset and PR reference

Pre-mortem:

1. Half-migration leaves both Node and NodeApi import spellings alive.
2. Docs update but tests/examples still compile through stale old value exports.
3. Type/value rename accidentally touches serialized operation or node shapes.

Expanded proof plan:

• Unit: helper API behavior contracts for node, element, text, path, point, range, operation, location, refs, and scrubber.
• Public surface: root export contract requires *Api and rejects old value exports.
• Type: public type-only imports still compile.
• Integration: slate-react and slate-history package typechecks.
• Docs/example: docs and site typecheck with *Api imports.
• Migration: codemod or migration note in changeset.

Rollback/hard-cut answer:

• This should be a hard cut, not a dual export. If a downstream package cannot migrate in one slice, keep temporary local aliases inside that package only, not public root aliases.

Slate Maintainer Objection Ledger

Scorecard

Weighted total: 0.928.

Status: done. The plan is ready for user review and later Ralph execution.

Pass-State Ledger

Implementation Phases For Ralph

1. Start with a red public-surface contract:
   • require NodeApi, ElementApi, TextApi, PathApi, PointApi, RangeApi, OperationApi, LocationApi, SpanApi, PathRefApi, PointRefApi, RangeRefApi, and ScrubberApi;
   • reject old value exports.
2. Rename source constants and internal imports by family.
3. Update package tests that import helper values.
4. Update docs, examples, and site code.
5. Add or update the changeset with migration guidance.
6. Update issue #5400 in docs/slate-issues/gitcrawl-v2-sync-ledger.md, docs/slate-v2/ledgers/issue-coverage-matrix.md, and docs/slate-v2/references/pr-description.md only after proof passes.
7. Verify from /Users/zbeyens/git/slate-v2:

bun --filter slate test:vitest -- public-surface-contract
bun --filter slate test:vitest -- interfaces-contract
bun --filter slate typecheck
bun --filter slate-react typecheck
bun --filter slate-history typecheck
bun x tsc --project site/tsconfig.json --noEmit
bun lint:fix
bun check

Plan Deltas From Review

• Added accepted target: public helper value objects get *Api names.
• Revised prior research: pure data helpers stay public, but bare helper value names do not.
• Kept model types unchanged.
• Rejected public aliases.
• Rejected public EditorApi value.
• Added #5400 as planned issue claim after implementation proof.
• Closed the open questions: Scrubber, Location, Span, and refs all use *Api helper values when public.
• Updated docs/slate-issues/gitcrawl-v2-sync-ledger.md for #5400 from not-claimed to planned-fix.
• Updated docs/slate-v2/references/pr-description.md open debt with the accepted helper namespace cut.

Open Questions

None.

Final Completion Gates

• Closure pass completed.
• Exact rename set is final, with no maybe.
• Issue #5400 proof route and ledger wording are final.
• PR reference owner is final.
• Public-surface, typecheck, docs/example, and downstream smoke gates are named.
• Plan score is 0.928.