@voithos-labs/aragonite 0.10.1

package/dist/action-contracts.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Every action interface a block component invokes upward through Svelte context, plus
+ * the commit vocabulary those calls are expressed in.
+ */
+import type { CstNode, TableAlignment } from './core/nodes';
+import type { NodeView } from './core/node-views';
+import type { StructuralChange } from './tree-operations/structural-change';
+import type { TrackedPosition } from './tree-operations/node-ops';
+import type { SharingState } from './tree-operations/sharing';
+import type { BlockComponent, FocusPosition } from './block-component';
+import type { ScopedOpDescriptor } from './schema/operations';
+import type { DocPath } from './selection/path-math';
+/**
+ * Caret-restore coordinate stored with a commit's undo snapshot: `path` is the `DocPath`
+ * dialect and must resolve in the pre-mutation tree; `'skip'` joins the caller's
+ * already-pushed entry. Minted by the scope factories (`block-edit-scope.ts`) or the
+ * `path-math` helpers, never composed at a call site.
+ */
+export type CommitSnapshotArg = {
+    path: DocPath;
+    offset: number;
+} | 'skip';
+/**
+ * Who owns the undo entry: `'own'` (the default) pushes one, `'join'` means the caller
+ * already pushed the entry covering this composite operation and this must not add one.
+ */
+export type UndoEntryMode = 'own' | 'join';
+/**
+ * Opt-in for structural commits that can legitimately no-op. The ceremony then discards
+ * the pre-captured snapshot: no undo entry, no edit event, no publish (`afterTick` still
+ * runs — caret placement is a view concern). NOT for content/metadata commits, whose
+ * `noop` StructuralChange means "structure held, bytes changed" and MUST still publish.
+ */
+export type DiscardIfNoop = boolean;
+/**
+ * Post-tick view callback — where a commit lands its caret. Awaited, so a landing that
+ * must first reveal an off-window target (VR-12) is expressible here; the reveal is
+ * bounded (VR-5), so awaiting cannot hang. Returning nothing opts out of the wait.
+ */
+export type CommitAfterTick = () => void | Promise<void>;
+export interface BlockEditActions {
+    splitBlock(blockIndex: number, offset: number): void | Promise<void>;
+    /**
+     * Focus the block after `blockIndex` in this scope, minting an empty paragraph when
+     * it is the last child. An off-window next block leaves the caret put, key consumed.
+     */
+    descendToBody(blockIndex: number): void | Promise<void>;
+    /**
+     * @internal Mint a paragraph carrying `text` at a BOUNDARY of this scope, caret after
+     * the text. `boundaryIndex === children.length` appends. The between-blocks caret's
+     * insertion door (`selection/gap-caret.ts`).
+     */
+    insertParagraph(boundaryIndex: number, text: string): void | Promise<void>;
+    mergeWithPrevious(blockIndex: number): void | Promise<void>;
+    mergeWithNext(blockIndex: number): void | Promise<void>;
+    deleteBlock(blockIndex: number): void | Promise<void>;
+    /**
+     * `preEditOffset` is the undo snapshot's cursor anchor; `postEditFocusOffset` is where
+     * the caret lands when a kind change remounts the block (typing `# ` on a paragraph),
+     * defaulting to `preEditOffset`.
+     */
+    updateBlockContent(blockIndex: number, text: string, preEditOffset?: number, postEditFocusOffset?: number): void | Promise<void>;
+    /**
+     * Where a caret at `offset` lands once this scope has committed `text` — the image of
+     * a container's `bodyWrite` rewrite, so a surface whose committed bytes differ from
+     * its DOM seats the caret on the bytes. Identity when the scope rewrites nothing.
+     */
+    mapCommittedOffset?(text: string, offset: number): number;
+    /**
+     * Mutate block metadata without touching raw — for state expressed as metadata (task
+     * checkboxes), NOT raw-driven metadata like heading level (use updateBlockContent).
+     * The patch is shallow-merged; an empty patch is a no-op.
+     */
+    updateBlockMetadata(blockIndex: number, metadata: Record<string, unknown>, options?: {
+        undoEntry?: UndoEntryMode;
+        afterTick?: CommitAfterTick;
+    }): void | Promise<void>;
+    /**
+     * Replace the block at `blockIndex` with zero or more new blocks.
+     * `replacement.length === 0` is equivalent to deleteBlock. `focus.path` addresses a caret
+     * landing inside the replacement's own structure; `snapshotOffset` is where the caret was,
+     * for the undo entry, and defaults to where it lands.
+     */
+    replaceBlock(blockIndex: number, replacement: CstNode[], focus?: {
+        replacementIndex: number;
+        offset: number;
+        path?: number[];
+    }, options?: {
+        undoEntry?: UndoEntryMode;
+        snapshotOffset?: number;
+    }): void | Promise<void>;
+}
+export interface MoveFocusOptions {
+    /**
+     * When false, a move past the true document end no-ops instead of appending a trailing
+     * paragraph; only the root append is suppressed, sibling moves and upward delegation
+     * are unaffected. Defaults to true (Enter/split rely on the append).
+     */
+    append?: boolean;
+    /** @internal Set by a move that LEAVES a gap caret, so the boundary it just left
+     *  cannot re-capture it. */
+    skipGapStop?: boolean;
+}
+export interface FocusActions {
+    moveFocus(blockIndex: number, position: FocusPosition, options?: MoveFocusOptions): void | Promise<void>;
+    /** Mount an off-window top-level block before placing a caret in it; see EditorActionsDeps.revealPath. */
+    revealPath(path: number[]): Promise<BlockComponent | null>;
+    /**
+     * @internal Park the caret at an eligible between-blocks boundary, reporting whether it
+     * did. Required, not optional: a dropped forward makes every gap arrival below it
+     * silently vanish.
+     */
+    tryGapStop(parentPath: number[], boundaryIndex: number): boolean;
+}
+export interface HistoryActions {
+    requestUndo(): void | Promise<void>;
+    requestRedo(): void | Promise<void>;
+}
+/**
+ * Owned mutation view handed to a container/multi-scope commit's `mutate`: `node` is the
+ * unshared copy already spliced into the live tree. Never write through references
+ * captured before the commit — they may be stale snapshot-shared originals.
+ */
+export interface ContainerScope {
+    node: CstNode;
+    children: CstNode[];
+    sharing: SharingState;
+}
+export interface MultiScopeTarget {
+    /** Scope identity — a view suffices; the ceremony unshares the spine and mints the owned mutation view. */
+    node: NodeView;
+    /** The `BlockListState` shape the ceremony writes: ids by assignment, refs only in
+     *  place — the array identity is the scope's, so a replacement strands its teardowns. */
+    state: {
+        innerBlockIds: string[];
+        readonly innerBlockRefs: (BlockComponent | undefined)[];
+    };
+    /** Doc-absolute path of `node`; the commit primitive unshares its spine. */
+    path: number[];
+}
+export interface CommitMultiScopeArgs<S extends readonly MultiScopeTarget[] = readonly MultiScopeTarget[]> {
+    /** `scopes[0]` is the outermost — inner raws must be current before outer rebuilds. */
+    scopes: S;
+    snapshot: CommitSnapshotArg;
+    /** One view in, one StructuralChange out per scope, same order — tuple-checked for literal scope arrays. */
+    mutate: (scopeViews: {
+        [K in keyof S]: ContainerScope;
+    }) => {
+        readonly [K in keyof S]: StructuralChange;
+    };
+    op?: ScopedOpDescriptor;
+    afterTick?: CommitAfterTick;
+    discardIfNoop?: DiscardIfNoop;
+    /**
+     * Caret positions the scopes' settles carry through their folds, parallel to `scopes` —
+     * a fold re-tiles the bytes under a landing chosen before the settle ran. Written in
+     * place, so `afterTick` reads the settled seat back off the object it passed in.
+     */
+    trackCaret?: readonly (TrackedPosition | undefined)[];
+}
+export interface CommitStructuralArgs {
+    snapshot: CommitSnapshotArg;
+    mutate: (children: CstNode[]) => StructuralChange;
+    op?: ScopedOpDescriptor;
+    afterTick?: CommitAfterTick;
+    /** Leaf(ves) for the dev invariant check when `mutate` returns `noop` (in-place kind change). */
+    touchedNodes?: CstNode[];
+    discardIfNoop?: DiscardIfNoop;
+}
+export interface CommitContainerStructuralArgs {
+    /** Scope identity — a view suffices; the ceremony unshares the spine and mints the owned mutation view. */
+    containerNode: NodeView;
+    /** Doc-absolute path of `containerNode` — the spine the primitive unshares + rebuilds. */
+    path: number[];
+    state: {
+        innerBlockIds: string[];
+        readonly innerBlockRefs: (BlockComponent | undefined)[];
+    };
+    snapshot: CommitSnapshotArg;
+    mutate: (scope: ContainerScope) => StructuralChange;
+    op?: ScopedOpDescriptor;
+    afterTick?: CommitAfterTick;
+    discardIfNoop?: DiscardIfNoop;
+}
+/**
+ * Selection-free commit surface, so the selection layer can depend on it without
+ * dragging in `EditorSelection`/`UndoEntry`. `UndoController` (editor-actions/deps)
+ * extends it with the two selection-typed members.
+ */
+export interface CommitController {
+    /** Editor's sharing epoch state, exposed for out-of-ceremony copy-path-on-write. */
+    sharing: SharingState;
+    pushUndoSnapshot(blockIndex: number, offset: number): void;
+    /** Snapshot whose no-caret fallback seeds a deep leaf path (e.g. a match nested in a list item). */
+    pushUndoSnapshotPath(path: number[], offset: number): void;
+    /** Debounced typing snapshot; `leafPath` is the edited leaf's doc-absolute path. */
+    pushUndoSnapshotDebounced(leafPath: number[], offset: number, batchKey?: string | number): void;
+    /** Start the batch's pause window, once the keystroke's own edit has settled. Paired with
+     *  every `pushUndoSnapshotDebounced`, or the batch never ends by pause. */
+    armUndoPause(): void;
+    commitStructural(args: CommitStructuralArgs): Promise<void>;
+    commitContainerStructural(args: CommitContainerStructuralArgs): Promise<void>;
+    commitMultiScope<const S extends readonly MultiScopeTarget[]>(args: CommitMultiScopeArgs<S>): Promise<void>;
+    /**
+     * Expose the document root as a MultiScopeTarget so commitMultiScope
+     * callers can include doc-level splices alongside container scopes
+     * (e.g., a cross-block delete whose LCA is the document root).
+     */
+    getDocScope(): MultiScopeTarget;
+    /** Flush the pending keystroke batch — emit its `input` event and clear the
+     *  debounce timer — before a history swap, so the batch's bytes aren't lost. */
+    flushDebouncedCheckpoint(): void;
+    /** Run a command's byte write as its own undo entry. A command is not typing, so the
+     *  keystroke batch breaks on BOTH sides: one Ctrl+Z takes the command and nothing else. */
+    isolateUndoEntry(write: () => void): void;
+}
+export interface ContainerEditActions {
+    /**
+     * Push a debounced undo snapshot for routine text input. `leafPath` is the edited
+     * leaf's doc-absolute path; `batchKey` (its stable block id) breaks the batch on
+     * focus moves between sibling leaves.
+     */
+    pushDebouncedCheckpoint(leafPath: number[], offset: number, batchKey?: string | number): void;
+    /** The checkpoint's other half: open the pause window once the keystroke's edit has settled. */
+    armDebouncedPause(): void;
+    /**
+     * Publish a raw change made outside the commit primitive, forwarded unchanged through
+     * nested containers. Raw rebuilds are NOT part of the nudge — out-of-ceremony writers
+     * rebuild via `withUnsharedSpine`, which operates on owned copies.
+     */
+    nudgeReactivity(): void;
+    /**
+     * Copy-path-on-write wrapper for out-of-ceremony writes (routine typing): unshares the
+     * spine doc-root → `absPath`, calls `write` with the owned chain (outermost first) and the
+     * epoch to own anything OFF that spine, then rebuilds innermost-first. The caller still pushes
+     * its own checkpoint and nudges. True means the rebuild re-derived a container's kind (typing
+     * out a `> [!TIP]` marker), remounting the edited leaf — the caller re-places the caret.
+     * `write` returns the change its own settle made, so the wrapper can publish it.
+     */
+    withUnsharedSpine(absPath: number[], write: (chain: CstNode[], sharing: SharingState) => StructuralChange | void): boolean;
+    /**
+     * Preferred entry for structural container mutations: spine unshare, snapshot,
+     * publish, edit event, post-tick. `mutate` receives the OWNED container with its
+     * working children attached — mutate through it, never through captures.
+     */
+    commitContainer(args: CommitContainerStructuralArgs): Promise<void>;
+}
+export interface ListContext {
+    insertItemAfter(itemIndex: number, newItem?: CstNode): Promise<void>;
+    exitListAtItem(itemIndex: number): Promise<void>;
+    indentItem(itemIndex: number): Promise<void>;
+    unindentItem(itemIndex: number): Promise<void>;
+    /**
+     * Split the item mid-content: first half stays, second half moves into a
+     * new sibling item. Emits exactly one undo snapshot and one edit event.
+     */
+    splitItemAtOffset(itemIndex: number, innerIndex: number, offset: number): Promise<void>;
+    /** Promote a nested list item to the parent list level. Called on the PARENT list's context.
+     *  `nestedListNode` is scope identity (a live-tree reference) — a view; writes go through the ceremony. */
+    promoteNestedItem(parentItemIndex: number, nestedListNode: NodeView, nestedItemIndex: number): Promise<void>;
+    /** Returns this list's index in its enclosing list (for nested-list promotion). */
+    getContainingItemIndex(): number;
+}
+export type CellPosition = 'start' | 'end' | number;
+export interface TableContext {
+    focusCell(rowIdx: number, colIdx: number, position: CellPosition): void;
+    getStickyColumn(): number | null;
+    setStickyColumn(colIdx: number): void;
+    resetStickyColumn(): void;
+    exitUpward(stickyX: number): void;
+    exitDownward(stickyX: number): void;
+    notifyCellFocused(rowIdx: number, colIdx: number): void;
+    notifyCellBlurred(): void;
+    insertRowAbove(rowIdx: number): Promise<void>;
+    insertRowBelow(rowIdx: number): Promise<void>;
+    insertColumnLeft(colIdx: number): Promise<void>;
+    insertColumnRight(colIdx: number): Promise<void>;
+    deleteRow(rowIdx: number): Promise<void>;
+    deleteColumn(colIdx: number): Promise<void>;
+    /** Move a body row up/down among body rows. The header row is fixed (no-op on it). */
+    moveRowUp(rowIdx: number): Promise<void>;
+    moveRowDown(rowIdx: number): Promise<void>;
+    /** Move a body row to an arbitrary target index (drag reorder); no-op if from === to. */
+    reorderRowTo(from: number, to: number): Promise<void>;
+    /** Move a column to an arbitrary target index (drag reorder); no-op if from === to. */
+    reorderColumnTo(from: number, to: number): Promise<void>;
+    /** Move a column left/right; no-op at the first/last column boundary. */
+    moveColumnLeft(colIdx: number): Promise<void>;
+    moveColumnRight(colIdx: number): Promise<void>;
+    cycleAlignment(colIdx: number): Promise<void>;
+    /** Set a column's alignment directly — distinct from the cycle step. */
+    setColumnAlignment(colIdx: number, alignment: TableAlignment): Promise<void>;
+}
+/**
+ * The TableContext mutations addressed by ONE axis index, the vocabulary the affordance
+ * menu and the cell's table commands both dispatch through. Derived from the contract
+ * rather than listed beside it, so a member with any other signature cannot be named.
+ */
+export type TableAxisAction = {
+    [K in keyof TableContext]: TableContext[K] extends (index: number) => Promise<void> ? K : never;
+}[keyof TableContext];

package/dist/action-contracts.js

@@ -0,0 +1,5 @@
+/**
+ * Every action interface a block component invokes upward through Svelte context, plus
+ * the commit vocabulary those calls are expressed in.
+ */
+export {};

package/dist/active-editor.d.ts

@@ -0,0 +1,16 @@
+export declare function registerEditor(root: HTMLElement): void;
+export declare function unregisterEditor(root: HTMLElement): void;
+export declare function markEditorInteracted(root: HTMLElement): void;
+/** True when a body-level chord routes to `root`. */
+export declare function claimsBodyChord(root: HTMLElement): boolean;
+/**
+ * True when `active` is a text-entry surface outside every mounted editor. The reserved
+ * chords (Ctrl+F / Ctrl+H) yield to it, so an editor never hijacks a consumer's own field.
+ */
+export declare function isForeignTextEntry(active: Element | null): boolean;
+/** True when `el` takes text input — the surfaces a programmatic focus move must yield to. */
+export declare function isTextEntrySurface(el: Element | null): boolean;
+/** Release the claim if this editor holds it, so a torn-down instance never keeps it. */
+export declare function releaseInteractedEditor(root: HTMLElement): void;
+/** Test-only: clear both the claim and the mounted set between cases. */
+export declare function __resetActiveEditorForTests(): void;

package/dist/active-editor.js

@@ -0,0 +1,67 @@
+/**
+ * Which editor a document-level chord routes to when no block holds native focus. The
+ * keydown listener sees every editor's keystrokes on the page, so the claimant is the
+ * last-interacted editor while that claim is live, else the sole mounted one. Two mounted
+ * editors with no live claim resolve to neither — guessing drives the wrong instance.
+ * Module-level by design: cross-instance coordination is the point.
+ */
+const mountedEditors = new Set();
+let lastInteracted = null;
+export function registerEditor(root) {
+    mountedEditors.add(root);
+}
+export function unregisterEditor(root) {
+    mountedEditors.delete(root);
+}
+export function markEditorInteracted(root) {
+    lastInteracted = root;
+}
+/** True when a body-level chord routes to `root`. */
+export function claimsBodyChord(root) {
+    if (lastInteracted === root)
+        return true;
+    const hasLiveClaim = lastInteracted !== null && mountedEditors.has(lastInteracted);
+    return !hasLiveClaim && mountedEditors.size === 1 && mountedEditors.has(root);
+}
+// Text-like <input> types the reserved chords yield to. Non-text types are deliberately
+// absent: they don't consume Ctrl+F, so a sole editor keeps claiming while one has focus.
+const TEXT_ENTRY_INPUT_TYPES = new Set([
+    'text',
+    'search',
+    'url',
+    'email',
+    'tel',
+    'password',
+    'number'
+]);
+/**
+ * True when `active` is a text-entry surface outside every mounted editor. The reserved
+ * chords (Ctrl+F / Ctrl+H) yield to it, so an editor never hijacks a consumer's own field.
+ */
+export function isForeignTextEntry(active) {
+    if (!isTextEntrySurface(active))
+        return false;
+    for (const root of mountedEditors) {
+        if (root.contains(active))
+            return false;
+    }
+    return true;
+}
+/** True when `el` takes text input — the surfaces a programmatic focus move must yield to. */
+export function isTextEntrySurface(el) {
+    if (el instanceof HTMLTextAreaElement)
+        return true;
+    if (el instanceof HTMLInputElement)
+        return TEXT_ENTRY_INPUT_TYPES.has(el.type);
+    return el?.matches('[contenteditable]:not([contenteditable="false"])') ?? false;
+}
+/** Release the claim if this editor holds it, so a torn-down instance never keeps it. */
+export function releaseInteractedEditor(root) {
+    if (lastInteracted === root)
+        lastInteracted = null;
+}
+/** Test-only: clear both the claim and the mounted set between cases. */
+export function __resetActiveEditorForTests() {
+    lastInteracted = null;
+    mountedEditors.clear();
+}

package/dist/ambient/ambient-cursor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Ambient-aware cursor I/O for prose contenteditable surfaces: raw ↔ DOM offset
+ * translation that respects the leading ambient marker span a container block contributes
+ * to its first prose child. Zero-ambient surfaces are first-class consumers —
+ * `getAmbientLength: () => 0` reduces this to plain widget-aware translation.
+ */
+import { type RawOffset } from '../cursor/coordinate-spaces';
+export interface AmbientCursorDeps {
+    getEl: () => HTMLElement | null | undefined;
+    getAmbientLength: () => number;
+    /**
+     * Logical caret position (raw units) when the live DOM range is gone or trapped — the
+     * "user clicked here" intent that survives Chromium dropping element-level carets
+     * across event-loop yields. Null when no snap intent is active.
+     */
+    getSnapTarget?: () => number | null;
+}
+export interface AmbientCursorIO {
+    /** Raw offset of the collapsed caret, or null if no selection inside `el`. */
+    getRaw(): RawOffset | null;
+    /** Move the caret to the given raw offset. Offsets at/before the ambient
+     * boundary land just after the marker span. */
+    setRaw(offset: RawOffset): void;
+    /** Raw offsets of the anchor/focus endpoints of the current selection, or null. */
+    getRawSelection(): {
+        start: RawOffset;
+        end: RawOffset;
+    } | null;
+    /** Raw offsets of an arbitrary range inside this surface — an InputEvent's target range, which
+     *  a word delete reports at a COLLAPSED caret and the selection therefore cannot answer. */
+    rawRangeOf(range: AbstractRange): {
+        start: RawOffset;
+        end: RawOffset;
+    } | null;
+    /** Ensure the caret sits outside the ambient marker region. No-op when `el`
+     * isn't the active element or the caret is already out. */
+    clampOutOfAmbient(): void;
+    /** Park the caret immediately after the ambient span — used as the raw-0 landing. */
+    setToAmbientBoundary(): void;
+}
+export declare function createAmbientCursorIO(deps: AmbientCursorDeps): AmbientCursorIO;

package/dist/ambient/ambient-cursor.js

@@ -0,0 +1,120 @@
+/**
+ * Ambient-aware cursor I/O for prose contenteditable surfaces: raw ↔ DOM offset
+ * translation that respects the leading ambient marker span a container block contributes
+ * to its first prose child. Zero-ambient surfaces are first-class consumers —
+ * `getAmbientLength: () => 0` reduces this to plain widget-aware translation.
+ */
+import { asRawOffset, toClampedRawOffset, toDomTextOffset } from '../cursor/coordinate-spaces';
+import { domTextOffsetAtNode, findDomTextOffsetTarget } from '../cursor/widget-offset';
+import { ambientSpanOf, placeCaretAfterAmbientSpan } from './ambient-dom';
+export function createAmbientCursorIO(deps) {
+    function snapTargetRaw() {
+        const target = deps.getSnapTarget?.() ?? null;
+        return target === null ? null : asRawOffset(target);
+    }
+    function readLiveRange() {
+        const el = deps.getEl();
+        if (!el || document.activeElement !== el)
+            return { state: 'inactive' };
+        const sel = window.getSelection();
+        if (!sel || sel.rangeCount === 0)
+            return { state: 'dropped' };
+        const ambient = ambientSpanOf(el);
+        return {
+            state: 'live',
+            el,
+            range: sel.getRangeAt(0),
+            collapsed: sel.isCollapsed,
+            inAmbient: (node) => ambient !== null && ambient.contains(node)
+        };
+    }
+    function getRaw() {
+        const live = readLiveRange();
+        if (live.state === 'inactive')
+            return null;
+        // Dropped (Chromium loses element-level carets past atomic widgets) or rebounded
+        // into a contenteditable=false island: the snap target carries the user's intent.
+        if (live.state === 'dropped')
+            return snapTargetRaw();
+        if (live.inAmbient(live.range.startContainer))
+            return snapTargetRaw();
+        const content = domTextOffsetAtNode(live.el, live.range.startContainer, live.range.startOffset);
+        return toClampedRawOffset(content, deps.getAmbientLength());
+    }
+    function setToAmbientBoundary() {
+        const el = deps.getEl();
+        if (el)
+            placeCaretAfterAmbientSpan(el);
+    }
+    function setRaw(offset) {
+        const el = deps.getEl();
+        if (!el)
+            return;
+        const ambientLength = deps.getAmbientLength();
+        // Walking to position ambientLength lands inside the marker island, where Chromium
+        // bounces the caret out in front of the span. Use a sibling boundary instead.
+        if (ambientLength > 0 && offset <= 0) {
+            setToAmbientBoundary();
+            return;
+        }
+        const target = toDomTextOffset(offset, ambientLength);
+        const pos = findDomTextOffsetTarget(el, target);
+        if (!pos)
+            return;
+        // The walker's last-text-node fallback can land inside the marker text, where the
+        // contenteditable="false" island traps the caret.
+        const ambient = ambientSpanOf(el);
+        if (ambient && ambient.contains(pos.node)) {
+            setToAmbientBoundary();
+            return;
+        }
+        const range = document.createRange();
+        try {
+            range.setStart(pos.node, pos.offset);
+        }
+        catch {
+            return;
+        }
+        range.collapse(true);
+        const sel = window.getSelection();
+        sel?.removeAllRanges();
+        sel?.addRange(range);
+    }
+    function clampOutOfAmbient() {
+        // Liveness before the ambient read, as every other method here does it: the length is an
+        // owner-bound derived at the call site, and a surface unmounted mid-dispatch is a dead owner.
+        const live = readLiveRange();
+        if (live.state !== 'live' || !live.collapsed)
+            return;
+        const ambientLength = deps.getAmbientLength();
+        if (ambientLength === 0)
+            return;
+        const content = domTextOffsetAtNode(live.el, live.range.startContainer, live.range.startOffset);
+        if (content >= ambientLength)
+            return;
+        setToAmbientBoundary();
+    }
+    function getRawSelection() {
+        const live = readLiveRange();
+        if (live.state !== 'live' || live.collapsed)
+            return null;
+        // No snap-target fallback here, unlike `getRaw`: a single caret intent cannot stand
+        // in for one end of a pair, and the clamp below already maps the marker interior to
+        // raw 0 — the right boundary for a drag that began inside the marker.
+        return rawEndpointsOf(live.el, live.range, deps.getAmbientLength());
+    }
+    function rawRangeOf(range) {
+        const el = deps.getEl();
+        if (!el || !el.contains(range.startContainer) || !el.contains(range.endContainer))
+            return null;
+        return rawEndpointsOf(el, range, deps.getAmbientLength());
+    }
+    return { getRaw, setRaw, getRawSelection, rawRangeOf, clampOutOfAmbient, setToAmbientBoundary };
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+function rawEndpointsOf(el, range, ambientLength) {
+    return {
+        start: toClampedRawOffset(domTextOffsetAtNode(el, range.startContainer, range.startOffset), ambientLength),
+        end: toClampedRawOffset(domTextOffsetAtNode(el, range.endContainer, range.endOffset), ambientLength)
+    };
+}

package/dist/ambient/ambient-dom.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DOM construction and lookup for the ambient marker span — the read-only
+ * prefix container blocks contribute to their first prose child's textContent.
+ */
+import type { AmbientPrefix } from '../block-component';
+export declare function buildAmbientSpan(prefix: AmbientPrefix): HTMLSpanElement;
+export declare function ambientSpanOf(blockEl: ParentNode): HTMLElement | null;
+export declare function ambientLengthOf(blockEl: HTMLElement): number;
+export declare function placeCaretAfterAmbientSpan(blockEl: HTMLElement): boolean;

package/dist/ambient/ambient-dom.js

@@ -0,0 +1,102 @@
+/**
+ * DOM construction and lookup for the ambient marker span — the read-only
+ * prefix container blocks contribute to their first prose child's textContent.
+ */
+import { domDescendants } from '../cursor/dom-walk';
+import { isAtomicInlineWidget, isHiddenMarkerText } from '../cursor/widget-offset';
+import { devWarn } from '../dev-warn';
+export function buildAmbientSpan(prefix) {
+    const normalized = typeof prefix === 'string' ? { text: prefix } : prefix;
+    const outer = document.createElement('span');
+    outer.className = 'md-marker';
+    outer.setAttribute('contenteditable', 'false');
+    const ranges = normalized.interactive ?? [];
+    let cursor = 0;
+    for (const range of ranges) {
+        if (range.start < 0 || range.end > normalized.text.length || range.start >= range.end) {
+            devWarn('ambient-span', 'interactive range out of bounds or empty', {
+                range,
+                textLength: normalized.text.length
+            });
+            continue;
+        }
+        if (range.start > cursor) {
+            outer.appendChild(document.createTextNode(normalized.text.slice(cursor, range.start)));
+        }
+        const inner = document.createElement('span');
+        inner.className = range.className;
+        if (range.role)
+            inner.setAttribute('role', range.role);
+        if (range.ariaChecked !== undefined) {
+            inner.setAttribute('aria-checked', String(range.ariaChecked));
+        }
+        inner.textContent = normalized.text.slice(range.start, range.end);
+        inner.addEventListener('click', range.onClick);
+        outer.appendChild(inner);
+        cursor = range.end;
+    }
+    if (cursor < normalized.text.length) {
+        outer.appendChild(document.createTextNode(normalized.text.slice(cursor)));
+    }
+    return outer;
+}
+export function ambientSpanOf(blockEl) {
+    const first = blockEl.firstChild;
+    if (!first || first.nodeType !== Node.ELEMENT_NODE)
+        return null;
+    const span = first;
+    if (!span.classList.contains('md-marker'))
+        return null;
+    if (span.getAttribute('contenteditable') !== 'false')
+        return null;
+    return span;
+}
+export function ambientLengthOf(blockEl) {
+    return ambientSpanOf(blockEl)?.textContent?.length ?? 0;
+}
+export function placeCaretAfterAmbientSpan(blockEl) {
+    const span = ambientSpanOf(blockEl);
+    if (!span)
+        return false;
+    const range = document.createRange();
+    // Prefer the first text node after the span so visual-line geometry returns real rects;
+    // setStartAfter yields a collapsed range with no textbox in empty-item state. A hidden
+    // marker run next to the span is not that text node — it paints nothing, and descending
+    // into it would seat raw 0 inside unpainted bytes.
+    const textAfter = firstTextNodeAfter(span);
+    if (textAfter && !isHiddenMarkerText(textAfter, blockEl)) {
+        range.setStart(textAfter, 0);
+    }
+    else {
+        range.setStartAfter(span);
+    }
+    range.collapse(true);
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+    return true;
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+function firstTextNodeAfter(node) {
+    let sibling = node.nextSibling;
+    while (sibling) {
+        // An atomic widget stands for raw bytes, so text past it is not raw 0.
+        if (isAtomicInlineWidget(sibling))
+            return null;
+        const text = firstTextDescendant(sibling);
+        if (text)
+            return text;
+        sibling = sibling.nextSibling;
+    }
+    return null;
+}
+// Unfiltered on the way down, unlike the measurable-text search it resembles
+// (`cursor/visual-lines.ts`): the caller judges hidden marker text once, at the top.
+function firstTextDescendant(node) {
+    for (const current of domDescendants(node)) {
+        if (current.nodeType === Node.TEXT_NODE && (current.textContent?.length ?? 0) > 0) {
+            return current;
+        }
+    }
+    return null;
+}

package/dist/assert.d.ts

@@ -0,0 +1,6 @@
+export interface InvariantViolation {
+    code: string;
+    message: string;
+    detail?: unknown;
+}
+export declare function assertInvariant(tag: string, check: () => InvariantViolation | null): void;