Your first edit

Every change follows the same path:

Intent → Plan → Transaction → Apply → Normalize → Commit

1. Intent

An intent is a typed declarative description of an edit. The shipped intent vocabulary covers text insertion and deletion, inline marks and links, selection updates, block retagging and alignment, list wrapping/unwrapping, structural fragment insertion, paragraph breaks, paste, and the narrow media/list-marker actions the runtime can earn from browser evidence.

const intent = { kind: "typeText", text: "a" } as const;

Intents carry no DOM state and no mutation. Any dispatcher (substrate, test, command handler) uses the same shape.

2. Plan

A planner turns an intent into an ordered sequence of PlanOps. It reads the current document and selection, asks the resolved planner rules what is supported, and does not mutate state.

3. Transaction

A transaction is the lower-level bundle produced from the plan. It carries ordered Steps, a TransactionId, an optional selection, and TransactionMeta. Its durable JSON form is what persistence and replay use.

4. Apply

Applying a transaction returns a new document and a Mapping from old to new positions. Each step can produce its own inverse on demand via step.invert(docBefore). The committed EditorState is the single source of truth.

5. Normalize

After apply, the normalizer fixes structural invariants: empty text-flow blocks that need a caret anchor, adjacent formatting runs that should merge, and schema-level fallout such as invalid children or marks. Normalization is pure, idempotent, and runs deterministic passes until the document reaches a fixed point.

6. Commit

Commit broadcasts the new state to subscribers. The DOM runtime re-renders from the committed state.

Observing the pipeline

Trace events are emitted through a Tracer constructed via createTracer(sink, sessionId?). Sinks like MemoryTraceSink or a custom TraceSink capture TraceIntentReceived, TracePlanCompiled, TraceTransactionApplied, TraceNormalized, and TraceHistory events.

See Tracing for the channel list.