Slate V2 Normalizer Extension DX Ralplan

Status: done

Runtime id: 019e362b-c486-7372-84c1-1c04fef96ff6

Completion file: active goal state

Continuation file: active goal state

Current pass: editor-node-normalizer-split, complete

Next pass: none

Ralph Execution Grounding

Task statement: implement the accepted follow-up in .tmp/slate-v2: split extension normalization into normalizers.editor for editor-root/value repair and normalizers.node for non-root node repair, keep scoped normalizer tx, migrate forced-layout off WeakSet + commitListeners, and prove type/runtime, benchmark, browser, and broad gates.

Desired outcome: Slate v2 has one Slate-close extension authoring path for normalization, with root/value repair separated from node-entry repair, no public arbitrary normalizer ids, and first-party examples teaching normalization instead of post-commit repair.

Known facts:

• packages/slate/src/interfaces/editor.ts exposes typed normalizers.editor and normalizers.node lanes.
• packages/slate/src/core/editor-extension.ts registers those lanes with extension-local internal ids.
• packages/slate/src/core/normalize-node.ts runs extension normalizers before fallback with next(...).
• site/examples/ts/forced-layout.tsx now uses normalizers.editor instead of a module WeakSet, register, and commitListeners.
• bench:core:normalization:compare:local already compares current v2 against legacy ../slate and writes tmp/slate-normalization-compare-benchmark.json.

Constraints:

• Do not add top-level extension.normalizeNode.
• Do not keep public arbitrary normalizer map keys.
• Do not expose full EditorUpdateTransaction in normalizer context.
• Do not claim new Fixes or Improves without exact proof.
• Keep Plate APIs and current slate-yjs adapters untouched.

Likely touchpoints:

• .tmp/slate-v2/packages/slate/src/interfaces/editor.ts
• .tmp/slate-v2/packages/slate/src/core/editor-extension.ts
• .tmp/slate-v2/packages/slate/src/core/normalize-node.ts
• .tmp/slate-v2/packages/slate/test/normalization-contract.ts
• .tmp/slate-v2/packages/slate/test/public-surface-contract.ts
• .tmp/slate-v2/scripts/benchmarks/core/compare/normalization.mjs
• .tmp/slate-v2/site/examples/ts/forced-layout.tsx

Execution state: active under Ralph as of 2026-05-17. Completion state is active goal state and stays pending until implementation, proofs, reference docs, and closeout pass accounting are complete.

Current Verdict

The current forced-layout example is bad DX. The module-level WeakSet<CustomEditor> plus commitListeners repair loop teaches the wrong model for document constraints. It looks like an app-level afterthought when the feature is actually normalization policy.

The best target preserves the legacy Slate normalizeNode mental model without reviving method monkeypatching, with* wrappers, or a second vocabulary beside transforms and queries. The public authoring surface is:

• first-class extension.normalizers.node(...) for node normalization
• no top-level extension.normalizeNode
• no arbitrary public normalizer id map
• tx exposed in normalizer context so examples write through the current transaction, not nested editor.update(...)
• no global WeakSet, no post-commit repair listener, no wrapper composition
• extension-local internal registration keys, so two extensions can both define normalizers.node without overwriting each other

This is a public DX/API refinement, not a new schema DSL.

Intent Boundary

Intent-boundary pass status: complete.

Evidence used:

• Live forced-layout source shows the public example currently teaches a module-level reentry guard and commit-listener repair loop.
• Live Slate v2 core already has typed ordered extension normalizers with next(...), fallback delegation, cleanup, and fixpoint scheduling.
• The related issue pass found no fixed-issue claim that would require asking the user to choose between DX and closure.

Accepted boundaries:

• The target may use extension.normalizers.node as the authoring surface.
• The target may add tx to normalizer context.
• The target may register typed normalizer lanes by extension name plus lane through an internal id helper.
• The target may rewrite first-party examples and public-surface contracts.
• The target may break current internal extension shape if it improves Slate authoring and preserves normalizer capability.

Rejected boundaries:

• No legacy method override teaching path.
• No with* wrapper composition.
• No Plate-like required-root schema DSL in raw Slate.
• No generic empty-text factory unless a later pass proves it separately.
• No preflight schema-veto hook in this plan.
• No issue auto-close claim without exact package/browser proof.

Weakest-answer pressure test:

The only risky part is tx in normalizer context. Without tx, public examples either use nested editor.update(...), import internal transforms, or mutate through a second API shape. That is exactly how the current bad example happened. The plan therefore keeps tx, but requires Ralph to prove it does not create unsafe recursion and that writes stay in the active transaction.

User question: none. The repo facts and the user's stated preference are enough: the desired shape is closest to Slate normalization, named consistently as normalizers.node, not closest to the current commitListeners repair loop.

Source-Backed Current State

Live diff note: git -C /Users/zbeyens/git/slate-v2 diff -- site/examples/ts/forced-layout.tsx returned empty output. The bad DX is in the live file, not an uncommitted local diff in that sibling checkout.

Decision Brief

Principles:

• Slate users should recognize normalization immediately.
• Public examples must not teach hidden global guards for core engine policy.
• The extension model stays the single composition path.
• Public writes go through transaction APIs, not old Transforms globals.
• Normalizer lifecycle slots follow the same plural-bucket grammar as transforms and queries.

Top drivers:

• The example is first-party teaching material.
• Legacy Slate developers expect the normalization mental model, but the public shape should be consistent with transforms and queries.
• Current engine already has typed ordered normalizer middleware.
• Commit listeners are for observing commits, not enforcing document shape.
• Normalizer registration must be collision-safe across extensions.

Viable options:

Chosen target:

export type EditorNormalizerTransaction<V extends Value = Value> = Pick<
  EditorUpdateTransaction<V>,
  "break" | "fragment" | "marks" | "nodes" | "selection" | "text"
> & {
  value: Pick<EditorUpdateTransaction<V>["value"], "get">;
};

export type EditorNormalizerContext<TEditor extends BaseEditor<any> = Editor> =
  EditorNormalizerArgs<ValueOf<TEditor>> & {
    editor: TEditor;
    next: EditorNormalizerNext<EditorNormalizerArgs<ValueOf<TEditor>>>;
    tx: EditorNormalizerTransaction<ValueOf<TEditor>>;
  };

export type EditorNormalizerMiddlewareMap<
  TEditor extends BaseEditor<any> = Editor,
> = {
  node?: EditorNormalizer<TEditor>;
};

export type EditorExtension<TEditor extends BaseEditor<any> = Editor> = {
  name: string;
  normalizers?: EditorNormalizerMiddlewareMap<TEditor>;
  // other existing slots stay
};

Registration rule:

if (slots.normalizers?.node) {
  cleanups.push(
    registerNormalizer(
      editor,
      getExtensionSlotId(extension.name, "normalizers.node"),
      slots.normalizers.node,
    ),
  );
}

Consequence: extensions get one obvious public node-normalizer hook that matches the existing plural-bucket style. Arbitrary normalizer ids disappear from the public API. The internal id format is not documented.

Before And After

Current forced-layout shape:

const ENFORCING_LAYOUT = new WeakSet<CustomEditor>();

const enforceLayout = (editor: CustomEditor) => {
  if (ENFORCING_LAYOUT.has(editor)) return;

  const children = editor.read((state) => state.value.get());
  // plan repairs...

  ENFORCING_LAYOUT.add(editor);
  try {
    editor.update((tx) => {
      // insert title, insert paragraph, set types
    });
  } finally {
    ENFORCING_LAYOUT.delete(editor);
  }
};

const forcedLayout = () =>
  defineEditorExtension<CustomEditor>()({
    name: "forced-layout",
    register({ editor }) {
      enforceLayout(editor);

      return {
        commitListeners: [() => enforceLayout(editor)],
      };
    },
  });

Target teaching shape:

const forcedLayout = () =>
  defineEditorExtension<CustomEditor>()({
    name: "forced-layout",
    normalizers: {
      node({ entry, next, tx }) {
        const [node, path] = entry;

        if (!NodeApi.isEditor(node) || path.length !== 0) {
          next();
          return;
        }

        const children = tx.value.get();
        const first = children[0];
        const second = children[1];
        const firstText = first ? NodeApi.string(first) : "";

        if (children.length <= 1 && firstText === "") {
          tx.nodes.insert(createTitle(), { at: [0], select: true });
          return;
        }

        if (children.length < 2) {
          tx.nodes.insert(createParagraph(), { at: [1] });
          return;
        }

        if (NodeApi.isElement(first) && first.type !== "title") {
          tx.nodes.set(setType("title"), { at: [0] });
          return;
        }

        if (NodeApi.isElement(second) && second.type !== "paragraph") {
          tx.nodes.set(setType("paragraph"), { at: [1] });
          return;
        }

        next();
      },
    },
  });

The important rule: one repair per normalizer invocation, then return. The normalization loop reruns until fixpoint. That removes the need for the WeakSet.

First-party usage should call the feature factory by feature name:

const editor = useSlateEditor({
  extensions: [forcedLayout()],
});

Public API Target

• Replace public normalizers?: EditorNormalizerMap<TEditor> with normalizers?: EditorNormalizerMiddlewareMap<TEditor>.
• Add normalizers.node?: EditorNormalizer<TEditor> as the node-normalizer lifecycle slot.
• Add normalizer-scoped tx to EditorNormalizerContext.
• Keep next(overrides?) exactly once.
• Register normalizers.node by extension name plus typed lane through an internal helper, not a documented string format.
• Preserve extension latest-wins behavior at the extension name level.
• Teach normalizers.node as the normal node-normalizer authoring path.
• Do not expose arbitrary public normalizer ids such as root, title, paragraph, or layout.
• Do not expose recursive or bulk transaction controls on normalizer tx: tx.normalize, tx.withoutNormalizing, tx.operations.replay, and tx.value.replace stay unavailable in normalizers.
• Do not expose top-level extension.normalizeNode.
• Do not expose old Editor.normalizeNode as the public authoring path.
• Do not add withForcedLayout, withNormalizers, or wrapper composition.

Internal Runtime Target

• normalizers.node registers into the existing normalizer pipeline.
• The registration id is generated internally from extension name plus normalizers.node.
• tx is a restricted facade over the active update view used by the normalization pass, not a nested editor.update(...).
• Normalizer writes stay inside the current transaction and participate in the existing dirty-path/fixpoint loop.
• Full update APIs that can recurse, replay arbitrary ops, or replace the whole value stay out of normalizer context.
• Existing tests for ordered normalizers, fallback override, cleanup, and double next() stay green.

React And Example Target

• forced-layout.tsx should import no reentry guard.
• It should not use register(...) or commitListeners for layout repair.
• It should not call editor.update(...) from normalizer code.
• It should keep the visible render behavior: one title and one paragraph.
• Public-surface tests should stop classifying forced-layout as a primitive write exception unless the contract explicitly permits tx writes inside normalizers.node.

Migration Backbone

Plate pressure:

• Plate can map plugin-owned structural policy to normalizers.node without wrapper composition.
• Plate still owns opinionated schema presets. Raw Slate only supplies the generic normalization hook.

slate-yjs pressure:

• Normalizer repairs remain normal operations inside the transaction pipeline, which keeps history/collab metadata ownership outside the example.
• The plan does not claim remote convergence changes. It only requires that normalizer-generated operations stay within existing operation replay proof.

Issue Ledger Accounting

No fixed issue claim in this pass.

Related issue discovery pass status: complete.

ClawSweeper mode: archive-first local ledger discovery. No broad live GitHub search was run. The pass read the generated live ledger, v2 sync ledger, test candidate maps, coverage matrix, fork dossier, and PR reference rows for normalizer/normalizeNode candidates.

Discovery result:

• No issue should be newly claimed as fixed by this plan alone.
• #4641 is the only direct implementation-pressure row for the Ralph slice.
• #4701 and #3275 are API/DX pressure, not closure claims.
• #2039 is related debugging pressure but not solved by forced-layout DX.
• #3950 and #5811 are already accounted through prior normalization fixpoint work and should not be reopened by this example/API cleanup.

Reviewed issue surfaces:

Issue sync status:

• docs/slate-issues/gitcrawl-live-open-ledger.md read for current live rows.
• docs/slate-issues/gitcrawl-v2-sync-ledger.md read for current manual classifications.
• docs/slate-issues/open-issues-ledger.md read for normalization/API cluster rows.
• docs/slate-issues/gitcrawl-clusters.md and docs/slate-issues/issue-clusters.md read for cluster-level normalization pressure.
• docs/slate-issues/test-candidate-map/ read for candidate proof rows.
• docs/slate-issues/benchmark-candidate-map.md read for performance normalization pressure.
• docs/slate-issues/package-impact-matrix.md and docs/slate-issues/requirements-from-issues.md read for package ownership and requirements pressure.
• docs/slate-v2/ledgers/issue-coverage-matrix.md read for existing #3950 and #5811 claims.
• docs/slate-v2/ledgers/fork-issue-dossier.md read for existing #3950 and #5811 long-form sections.
• No manual ledger rows changed in this pass; pass 11 remains the formal issue sync accounting owner if the accepted implementation changes claim text.

Full issue-ledger pass status: complete.

Wider corpus classifications:

PR reference status: unchanged in this pass. The accepted API shape is planned, not implemented, and no fixed issue claim changed.

Regression Proof Matrix

Browser Stress And Parity Strategy

Focused browser row:

PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/forced-layout.test.ts --project=chromium

Run from cwd:

/Users/zbeyens/git/slate-v2

No broader browser matrix is required for the plan itself. If Ralph touches the normalizer engine, the implementation closeout should also run the package normalization tests and the broad bun check gate from .tmp/slate-v2.

Performance Review And Legacy Normalizer Benchmark

Performance applicability: applied.

Why this is not optional: changing the extension normalizer shape can make normalization look cleaner while quietly adding middleware dispatch, transaction facade, or id lookup overhead. That would be a bad trade.

Vercel micro-rules used:

• js-early-exit: normalizers must exit fast for non-root entries.
• js-set-map-lookups: internal lane lookup must stay keyed, not scan-based.
• js-cache-property-access: hot-path normalizer dispatch should avoid repeated deep reads where a local binding is enough.

Performance rules used:

• cohort segmentation
• repeated-unit budget
• interaction INP matrix as lab-proxy discipline
• memory and DOM tagging

Repeated unit:

• dirty node entry visited by normalization
• extension node-normalizer dispatch
• transaction-facade write during one repair

Cohorts:

Benchmark owner:

• Reuse scripts/benchmarks/core/compare/normalization.mjs.
• Extend that file if needed; do not create a new benchmark file unless this lane cannot express the decision.
• Keep artifact output at tmp/slate-normalization-compare-benchmark.json.

Required legacy-compare command, cwd /Users/zbeyens/git/slate-v2:

bun run bench:core:normalization:compare:local

Required medium cohort command, cwd /Users/zbeyens/git/slate-v2:

NORMALIZATION_BENCH_ITERATIONS=7 NORMALIZATION_BENCH_EXPLICIT_BLOCKS=1000 NORMALIZATION_BENCH_INSERT_BLOCKS=2000 NORMALIZATION_BENCH_INSERT_OPS=200 bun run bench:core:normalization:compare:local

Custom normalizer lane requirement:

• Add or extend a compare lane that measures legacy editor.normalizeNode = (entry) => { ...; normalizeNode(entry) } against v2 normalizers.node({ entry, next, tx }).
• Include a no-op pass-through normalizer lane to measure dispatch overhead.
• Include a forced-layout one-repair lane to measure the real planned example.
• Keep the benchmark cross-repo: current v2 against ../slate legacy.

Acceptance budget:

Memory and DOM tags:

• No DOM tag is expected for the core normalization compare.
• Record heap delta if the compare harness exposes it.
• For the forced-layout browser proof, record visible h2/p counts and confirm no post-commit repair loop is mounted.

Plan delta:

• The implementation is not Ralph-complete until the legacy normalizer compare artifact is produced and summarized.
• If the existing v2 baseline already loses one diagnostic lane to legacy, do not hide it. Record it, prove this change did not worsen it, and open a separate performance follow-up if needed.

Implementation Review Matrix

Pressure Pass Results

Pressure-passes status: complete.

Hard pressure verdict:

• tx is still the right target, but only if Ralph proves it is the active update view created during normalization. A fake tx or nested update is a regression dressed as DX.
• normalizeNode and arbitrary normalizer maps are rejected as public authoring paths. Docs and examples should use normalizers.node.
• forcedLayout() is better than layout() because examples teach naming conventions. Generic names look small but age badly.
• The plan still must not claim slate-yjs convergence. It only gives slate-yjs a sane future migration backbone.

Maintainer Objection Ledger

Steelman Challenge Ledger

Steelman pass status: complete.

High-Risk Deliberate Pass

High-risk pass status: complete.

Trigger: this changes public extension API, normalizer runtime behavior, example teaching surface, and migration backbone expectations for plugin and collaboration authors.

Blast radius:

Pre-mortem:

Expanded proof plan:

Rollback / hard-cut answer:

• Keep the hard cut away from WeakSet + commitListeners; it teaches the wrong runtime owner.
• If normalizer-scoped tx cannot be implemented safely, fall back to normalizers.node({ editor, entry, next }) and do not ship nested update examples.
• If typed normalizer-lane registration creates runtime churn, keep the internal helper but document only normalizers.node.

High-risk verdict: keep with the scoped-tx revision and proof gates above.

Ecosystem Maintainer Pass

Ecosystem maintainer pass status: complete.

Trigger: this proposal changes extension authoring, normalizer registration, normalization writes, example behavior, and the migration backbone for plugin and collaboration authors.

Affected extension points:

• EditorExtension.normalizers.node
• EditorExtensionRegistrationOutput
• EditorNormalizerContext
• internal normalizer registration ids
• normalization transaction closeout

Plugin migration-backbone surface:

• Raw Slate stays extensions: [forcedLayout()].
• Plate can map a product plugin's structural policy to a Slate extension normalizer.
• Plate keeps plugins, typed plugin options, editor.api, editor.tf, and getApi(...) as product-layer APIs.
• No Plate adapter, Plate API rename, or Plate registry change is required by this planning slice.

Collab contract affected:

• Normalizer-generated repairs must be regular transaction operations.
• Repairs must not be produced by nested editor.update(...).
• Repairs must not use tx.operations.replay or tx.value.replace.
• Metadata and selection behavior must stay attached to the outer update.
• Current slate-yjs wrappers are pressure evidence only; this plan does not claim current adapter closure.

Ecosystem verdict: keep. The plan is stronger with the scoped tx, internal id helper, and explicit no-adapter-support claim. The main closure blocker is runtime proof that normalizer writes stay in the outer transaction.

Ecosystem Strategy Synthesis

Research/ecosystem live-source refresh pass status: complete.

Evidence used:

• docs/research/sources/editor-architecture/read-update-runtime-corpus-ledger.md marks Lexical, ProseMirror, and Tiptap as evidenced, with no raw or compile gap for this scoped question.
• docs/research/sources/editor-architecture/lexical-read-update-extension-runtime.md supports read/update lifecycle, update tags, dirty scheduling, and extension dependency ideas.
• docs/research/sources/editor-architecture/prosemirror-transaction-view-dom-runtime.md supports transaction ownership, selection mapping/bookmarks, centralized DOM bridge ownership, and decorations as view data.
• docs/research/sources/editor-architecture/tiptap-extension-command-react-dx.md supports extension packaging, command discoverability, selector posture, and optional chain sugar.
• docs/research/decisions/slate-v2-state-tx-public-api-and-extension-namespaces.md is the current authority for state / tx public naming and extension namespaces.
• Live Slate v2 source confirms EditorNormalizerContext currently has { editor, next }, extension inputs expose normalizers, registration uses raw normalizer ids, and forced-layout currently uses WeakSet plus commitListeners.
• Live Plate source confirms product-layer plugin inference and editor.api belong to Plate pressure, not raw Slate core naming.
• Live slate-yjs source confirms current wrapper pressure around withYjs, withYHistory, Editor.withoutNormalizing, editor.apply, and editor.normalizeNode.

No research wiki page changed in this pass. Maintain mode found accepted compiled pages that already answer this scoped API question; the stale artifact was this plan's synthesis, not the research layer.

Hard Cuts

• Cut ENFORCING_LAYOUT.
• Cut commitListeners from forced-layout.
• Cut register({ editor }) for initial layout repair.
• Cut nested editor.update(...) from public normalizer example code.
• Cut global normalizer ids that let same-key map entries overwrite across extensions.
• Cut top-level extension.normalizeNode.
• Cut arbitrary public normalizer map keys.
• Keep commitListeners as a separate extension slot for observers.
• Keep normalizers.node as the public node-normalizer lane.

Implementation Phases

1. Core type/API phase, owner Ralph:

   • Add normalizers.node to EditorExtension and registration output.
   • Remove public arbitrary normalizer map keys.
   • Add normalizer-scoped tx to EditorNormalizerContext.
   • Register the typed node-normalizer lane by extension name through an internal helper.
   • Add type/runtime tests.

2. Example phase, owner Ralph:

   • Rewrite forced-layout.tsx to normalizers.node({ entry, tx, next }).
   • Remove ENFORCING_LAYOUT, enforceLayout, register, and commitListeners.
   • Keep visible title/paragraph behavior unchanged.

3. Public-surface phase, owner Ralph:

   • Update public-surface-contract.ts classification.
   • Add grep/contract coverage for no forced-layout guard or commit-listener repair.

4. Verification phase, owner Ralph:

   • Run focused package tests.
   • Run legacy normalizer compare benchmark.
   • Run forced-layout Playwright row.
   • Run package typecheck and broad gate named by implementation impact.

Fast Driver Gates

Planning artifact check, cwd /Users/zbeyens/git/plate-2:

node tooling/scripts/completion-check.mjs

Expected while this plan is pending: fail with the scoped completion file named. That is correct until closure/final-gates pass.

Implementation gates, cwd /Users/zbeyens/git/slate-v2:

bun test ./packages/slate/test/normalization-contract.ts

bun test ./packages/slate/test/public-surface-contract.ts

bun run bench:core:normalization:compare:local

NORMALIZATION_BENCH_ITERATIONS=7 NORMALIZATION_BENCH_EXPLICIT_BLOCKS=1000 NORMALIZATION_BENCH_INSERT_BLOCKS=2000 NORMALIZATION_BENCH_INSERT_OPS=200 bun run bench:core:normalization:compare:local

PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/forced-layout.test.ts --project=chromium

bun check

Ralph Execution Results - 2026-05-17

Implemented in /Users/zbeyens/git/slate-v2:

• EditorExtension.normalizers.editor and EditorExtension.normalizers.node replaced arbitrary public normalizer map keys.
• defineEditorExtension(...) now rejects extra top-level extension keys, so direct normalizeNode and commands slots fail at the helper boundary.
• Normalizer context now exposes scoped tx with core repair APIs and value.get().
• Extension normalizer registration uses extension-local internal ids like name:normalizers.editor and name:normalizers.node.
• forced-layout now uses normalizers.editor({ next, tx }) and no longer uses WeakSet, startup register repair, commitListeners, or nested editor.update(...).
• The normalization compare benchmark includes v2 normalizers.node for no-op dispatch and v2 normalizers.editor for forced-layout repair versus legacy editor.normalizeNode override lanes.

Proof completed before closeout:

• bun test ./packages/slate/test/normalization-contract.ts passed.
• bun test ./packages/slate/test/normalization-contract.ts ./packages/slate/test/public-surface-contract.ts passed.
• bun --filter slate typecheck passed.
• bun typecheck:site passed.
• bun typecheck:root passed.
• bun lint:fix passed and fixed formatting/imports needed by the current Slate v2 checkout.
• bun run bench:core:normalization:compare:local passed with v2 faster than legacy on explicit normalization and no-op normalizer dispatch; forced-layout repair measured 0.03ms per repair versus legacy 0.02ms, delta +0.01ms, inside the accepted absolute budget.
• NORMALIZATION_BENCH_ITERATIONS=7 NORMALIZATION_BENCH_EXPLICIT_BLOCKS=1000 NORMALIZATION_BENCH_INSERT_BLOCKS=2000 NORMALIZATION_BENCH_INSERT_OPS=200 bun run bench:core:normalization:compare:local passed; medium cohort kept v2 faster than legacy on explicit normalization and no-op normalizer dispatch, while forced-layout repair stayed within the accepted absolute budget at delta +0.01ms.
• PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_WORKERS=1 bun x playwright test playwright/integration/examples/forced-layout.test.ts --project=chromium passed both forced-layout browser rows.
• bun check passed. It still prints the existing React Hooks dependency warning in packages/slate-react/src/components/slate.tsx.

Known diagnostic still outside this slice:

• The normalization compare benchmark still shows current v2 slower than legacy on insertTextReadAfterEachMs; that lane existed before this API slice and is not caused by the normalizer lane split.

Editor/Node Normalizer Split - 2026-05-17

Follow-up decision: split root/editor normalization from ordinary node normalization.

Chosen API:

defineEditorExtension({
  name: "forced-layout",
  normalizers: {
    editor({ next, tx }) {
      // root value/layout repair
      next();
    },
    node({ entry, next, tx }) {
      // non-root node repair
      next();
    },
  },
});

Rules:

• normalizers.editor owns editor-root/value-level repair.
• normalizers.node does not receive the editor root.
• Do not add element or text lanes in this slice.
• Keep scoped normalizer tx.
• Migrate forced-layout to normalizers.editor.
• Preserve existing cleanup, ordering, double-next, and benchmark proof.

Execution result:

• Added EditorRootNormalizer* types and normalizers.editor.
• Renamed node-entry normalizer types to EditorNodeNormalizer*.
• Routed only the editor root ([]) through normalizers.editor.
• Routed only non-root entries through normalizers.node.
• Kept scoped normalizer tx on both lanes.
• Migrated forced-layout to normalizers.editor({ next, tx }).
• Updated public-surface and generic type tests so normalizers.editor has no entry, while normalizers.node never receives the editor root.

Pass Schedule And Ledger

Current Score

Score note: this is plan-confidence, not implementation proof. The plan is Ralph-ready; source/runtime/browser proof remains in the Ralph execution gates.

Plan Deltas From Review

• Rejected the current WeakSet + commitListeners shape.
• Strengthened the target beyond normalizers: { rootLayout } by replacing arbitrary public ids with the typed normalizers.node lane.
• Added normalizer-scoped tx so the public example uses transaction APIs.
• Added extension-local typed-lane registration keys through an internal helper to prevent collisions.
• Renamed the teaching factory from layout() to forcedLayout().
• Rejected top-level normalizeNode sugar to avoid two public spellings for one lifecycle slot.
• Revised tx from full EditorUpdateTransaction to a normalizer-scoped transaction facade.
• Made normalizer id namespacing internal instead of a documented string format.
• Added high-risk pre-mortem and proof gates for transaction scope, normalizer ordering/cleanup, browser behavior, and history/collab metadata.
• Added a performance review requiring bench:core:normalization:compare:local against legacy ../slate, a medium cohort, and custom normalizer lanes for no-op dispatch and forced-layout repair.
• Added ecosystem maintainer answers for Plate/plugin migration and slate-yjs/collab determinism.
• Confirmed raw Slate should not copy Plate plugin APIs.
• Confirmed this plan makes no current slate-yjs adapter support promise.
• Revision pass kept the architecture unchanged and narrowed the handoff to the exact core/example/test slice.
• Added issue coverage matrix planning sync for the normalizer extension DX plan.
• Kept PR reference unchanged because there is no implemented proof and no new fixed or improved claim.
• Closed the Slate Ralplan lane after verifying all scheduled passes.
• Cut arbitrary public normalizer map keys.
• Kept commitListeners only for observation, not structural repair.

Revision Pass

Revision pass status: complete.

The pass re-read the accepted decisions after the maintainer, high-risk, and ecosystem passes. No reversal is needed.

Final architecture target:

• extensions: [forcedLayout()] is the single authoring route.
• defineEditorExtension({ normalizers: { node(...) {} } }) is the normal node-normalizer path.
• Arbitrary public normalizer map keys are cut.
• tx stays in the normalizer context, but only as a normalizer-scoped facade.
• Normalizer writes must join the outer normalization transaction.
• Normalizer id generation is internal; docs teach typed lifecycle lanes only.
• commitListeners remain valid for observation, not structural repair.
• Plate APIs and slate-yjs adapters stay untouched in this slice.

Rejected during revision:

• No withForcedLayout(...).
• No top-level extension.normalizeNode.
• No editor.normalizeNode = ... teaching route.
• No arbitrary public normalizer id map.
• No schema DSL for required root blocks.
• No full EditorUpdateTransaction in normalizer context.
• No nested editor.update(...) inside normalizers.
• No current slate-yjs adapter support claim.

Handoff wording revision:

Before this pass, the handoff could be misread as "add enough API to make the example prettier." That is too weak. The actual handoff is: move structural repair into the normalization pipeline while preserving Slate's extension composition model and keeping transaction/collab behavior observable.

Revision verdict: keep. The remaining work is accounting, not architecture debate.

Issue Sync Accounting

Issue sync accounting status: complete.

Source files re-read:

• docs/slate-issues/gitcrawl-live-open-ledger.md
• docs/slate-issues/gitcrawl-v2-sync-ledger.md
• docs/slate-issues/open-issues-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/ledgers/fork-issue-dossier.md
• docs/slate-v2/references/pr-description.md
• issue dossiers for #4641, #4701, #3275, #2039, #3950, and #5811

Accounting result:

• Added Normalizer Extension DX Planning Sync - 2026-05-17 to docs/slate-v2/ledgers/issue-coverage-matrix.md.
• No fixed issue claim added.
• No improved issue claim added.
• docs/slate-v2/references/pr-description.md stays unchanged.
• docs/slate-issues/gitcrawl-v2-sync-ledger.md stays unchanged because the accepted plan preserves the existing manual classifications.
• docs/slate-v2/ledgers/fork-issue-dossier.md stays unchanged because the current long-form sections already cover #3950, #5811, #2643, #2195, #2405, #2355, and #3430, while #4641, #4701, #3275, and #2039 remain planning-pressure rows until implementation proof exists.

Formal issue matrix:

ClawSweeper verdict: applied, ledger-first. No broad live GitHub search was needed. The active plan has precise related/no-claim accounting and the PR reference does not need a change.

Closure Final Gates

Closure final-gates status: complete.

Gate results:

Final handoff status: complete.

Open Questions

None blocking the chosen direction.

What could change the decision:

• If current normalizer transaction internals cannot expose tx without unsafe recursion, fall back to normalizers.node({ editor, entry, next }) plus a documented narrow repair path. That would be worse DX and should need proof before accepting.
• If closure finds a missing final gate or stale handoff claim, fix that before Ralph.

Final Handoff

Ralph-ready handoff:

Public API:

• Build extension.normalizers.node.
• Remove arbitrary public normalizer map keys.
• Add normalizer-scoped tx to normalizer context.
• Register typed normalizer lanes by extension name through an internal helper.
• Keep commitListeners for observation only.

Runtime:

• Keep normalizer writes in the outer normalization transaction.
• Do not expose full EditorUpdateTransaction in normalizer context.
• Do not expose tx.normalize, tx.withoutNormalizing, tx.operations.replay, or tx.value.replace.
• Require no nested editor.update(...) inside normalizers.

Example:

• Use forcedLayout() for the example extension factory.
• Rewrite forced-layout to the target snippet.
• Remove ENFORCING_LAYOUT, post-commit repair, and startup repair scheduling.

Proof:

• Add positive and negative type tests for extension inference and scoped tx.
• Add negative type tests rejecting top-level normalizeNode and arbitrary normalizer keys.
• Add runtime tests for typed-lane registration, two-extension collisions, order/latest-wins, cleanup, double-next, and no nested update.
• Add legacy normalizer benchmark proof: bench:core:normalization:compare:local, the medium cohort command, and a custom normalizer lane comparing legacy editor.normalizeNode override to v2 normalizers.node.
• Add public-surface proof that forced-layout no longer teaches WeakSet, commit-listener repair, or legacy editor.normalizeNode = ....
• Add focused forced-layout browser proof.

Boundaries:

• Do not edit Plate APIs or current slate-yjs adapters for this slice.
• Do not add a schema DSL, path-only normalization, wrapper composition, top-level extension.normalizeNode, arbitrary public normalizer ids, or a generic empty-text factory in this slice.
• Do not claim current slate-yjs adapter support.

Issue accounting:

• New Fixes: none.
• New Improves: none.
• Related/planning pressure: #4641, #4701, #3275, #2039.
• Existing preserved claims: Fixes #3950, Improves #5811.
• Existing non-claims/related rows preserved: #3465, #2643, #2405, #2195, #2355, #3430.

Completion Gates

Status is done because:

• every scheduled Slate Ralplan pass is complete
• issue accounting is synced conservatively
• final handoff is complete
• next pass is none
• implementation proof is explicitly delegated to a later ralph execution