@voithos-labs/aragonite 0.10.1

package/dist/reactivity/state-registry.d.ts

@@ -0,0 +1,10 @@
+/** Resolve a container node (by identity; views accepted) to its BlockListState.
+ *  WeakMap, so entries collect when the node becomes unreachable. */
+import type { NodeView } from '../core/node-views';
+import type { BlockListState } from './block-list-state.svelte';
+/** Overwrites any existing entry — the new state becomes authoritative on re-mount. */
+export declare function registerBlockListState(node: NodeView, state: BlockListState): void;
+export declare function getStateForNode(node: NodeView): BlockListState | undefined;
+/** Strict variant, for a caller holding a live-tree node whose container must be mounted.
+ *  `getStateForNode` stays for the ancestor walks where absence is a valid signal. */
+export declare function expectStateForNode(node: NodeView): BlockListState;

package/dist/reactivity/state-registry.js

@@ -0,0 +1,44 @@
+/** Resolve a container node (by identity; views accepted) to its BlockListState.
+ *  WeakMap, so entries collect when the node becomes unreachable. */
+import { DEV } from 'esm-env';
+import { tick } from 'svelte';
+import { devWarn } from '../dev-warn';
+const stateRegistry = new WeakMap();
+/** Overwrites any existing entry — the new state becomes authoritative on re-mount. */
+export function registerBlockListState(node, state) {
+    const existing = stateRegistry.get(node);
+    stateRegistry.set(node, state);
+    if (DEV && existing && existing !== state) {
+        void reportContestedClaim(node, existing, state);
+    }
+}
+/**
+ * A dev signal, not a guarantee. Svelte creates a structural remount's new mount before
+ * tearing the old one down, so a claim contested INSIDE a flush says nothing about
+ * ownership; re-ask once it settles, when a loser still holding child refs means either a
+ * second live owner or a teardown whose clear never reached the live slots.
+ */
+async function reportContestedClaim(node, loser, winner) {
+    await tick();
+    if (stateRegistry.get(node) !== winner)
+        return;
+    if (loser.innerBlockRefs.every((ref) => ref === undefined))
+        return;
+    devWarn('state-registry', `two live components claim the same ${node.kind} — the loser's child refs are orphaned. ` +
+        `Either both mounts render this node, or the loser's teardown emptied slots the ` +
+        `scope no longer reads.`);
+}
+export function getStateForNode(node) {
+    return stateRegistry.get(node);
+}
+/** Strict variant, for a caller holding a live-tree node whose container must be mounted.
+ *  `getStateForNode` stays for the ancestor walks where absence is a valid signal. */
+export function expectStateForNode(node) {
+    const state = stateRegistry.get(node);
+    if (!state) {
+        throw new Error(`[state-registry] no BlockListState registered for ${node.kind} — ` +
+            `caller assumed a mounted container. If this path can visit non-container ` +
+            `nodes, use getStateForNode and guard on undefined.`);
+    }
+    return state;
+}

package/dist/reactivity/use-container-windowing.svelte.d.ts

@@ -0,0 +1,35 @@
+import { type BlockElLookup } from '../editor-keys';
+import type { NodeView } from '../core/node-views';
+import type { RevealTarget } from '../cursor/reveal-anchor';
+import { type ListWindowing, type RevealAnchorPlacement } from './list-windowing.svelte';
+export interface ContainerWindowingOpts {
+    /** This container's index in its PARENT scope, for the upward subtotal report. A getter, so
+     *  reorders report under the current slot. Ignored at the root (no parent sink). */
+    getIndex: () => number;
+    /** This scope's path; the leaf-channel depth is its length. `[]` at the root. */
+    getParentPath: () => number[];
+    getChildren: () => readonly NodeView[];
+    getChildIds: () => string[];
+    /** The content-origin element that scrolls WITH this scope's children. Never the viewport. */
+    getListEl: () => HTMLElement | null;
+    /** The element the PARENT measures for this scope's height. Omit at the root. */
+    getOwnEl?: () => HTMLElement | null;
+    /** True when this scope's DIRECT children are `BlockHost`s → shadow the leaf channel.
+     *  False for direct-`{#each}` scopes (list / table). */
+    provideLeafChannel: boolean;
+    /** Collapse clamp; see `ListWindowingDeps.isCollapsed`. */
+    isCollapsed?: () => boolean;
+}
+/**
+ * Resolve the reveal target into the ROOT scope's coordinates. The model addresses
+ * top-level children only, so a nested target contributes its ancestor's index plus the
+ * measured drop down to itself — without which the pin re-asserts the CONTAINER's top and
+ * pushes an already-resolved nested target back out of view.
+ */
+export declare function placementOf(target: RevealTarget | null, blockEl: BlockElLookup): RevealAnchorPlacement | null;
+/**
+ * One windowing wiring unit per BlockList-bearing or direct-each container scope: reads
+ * the windowing contexts, builds `createListWindowing` with the shared constants, and
+ * provides the subtotal sink plus the leaf channel. Call synchronously during component init.
+ */
+export declare function useContainerWindowing(opts: ContainerWindowingOpts): ListWindowing;

package/dist/reactivity/use-container-windowing.svelte.js

@@ -0,0 +1,95 @@
+import { getContext, setContext } from 'svelte';
+import { EDITOR_DOC_KEY, EDITOR_SERVICES_KEY, PARENT_SCOPE_SINK_KEY, RECORD_BLOCK_HEIGHT_KEY } from '../editor-keys';
+import { createListWindowing } from './list-windowing.svelte';
+/**
+ * Resolve the reveal target into the ROOT scope's coordinates. The model addresses
+ * top-level children only, so a nested target contributes its ancestor's index plus the
+ * measured drop down to itself — without which the pin re-asserts the CONTAINER's top and
+ * pushes an already-resolved nested target back out of view.
+ */
+export function placementOf(target, blockEl) {
+    if (!target || target.path.length === 0)
+        return null;
+    const shallow = { index: target.path[0], block: target.block, innerOffset: 0, height: null };
+    if (target.path.length === 1)
+        return shallow;
+    const ancestorEl = blockEl([shallow.index]);
+    const targetEl = blockEl(target.path);
+    // The ancestor's top is a DIFFERENT block, honest only while the ancestor itself is
+    // windowed out and the model's offset is all that is known. A MOUNTED ancestor missing its
+    // target means the reader scrolled past it inside the container: decline, never teleport.
+    if (!ancestorEl)
+        return shallow;
+    if (!targetEl)
+        return null;
+    const targetRect = targetEl.getBoundingClientRect();
+    return {
+        index: shallow.index,
+        block: target.block,
+        innerOffset: targetRect.top - ancestorEl.getBoundingClientRect().top,
+        height: targetRect.height
+    };
+}
+/**
+ * One windowing wiring unit per BlockList-bearing or direct-each container scope: reads
+ * the windowing contexts, builds `createListWindowing` with the shared constants, and
+ * provides the subtotal sink plus the leaf channel. Call synchronously during component init.
+ */
+export function useContainerWindowing(opts) {
+    const { heightOracle: oracle, scrollport: getPort, correctsScroll, focusedPath: getFocusPath, widthVersion: getWidthVersion, viewportHeightVersion: getViewportHeightVersion, blockElLookup } = getContext(EDITOR_DOC_KEY);
+    const parentSink = getContext(PARENT_SCOPE_SINK_KEY);
+    const revealAnchor = getContext(EDITOR_SERVICES_KEY)?.revealAnchor;
+    // Single-claimant: nested scopes keep top-of-viewport anchoring, or their deltas would
+    // fight over one scrollTop.
+    const claimsRevealAnchor = opts.getParentPath().length === 0;
+    const windowing = createListWindowing({
+        oracle,
+        getChildren: opts.getChildren,
+        getChildIds: opts.getChildIds,
+        getListEl: opts.getListEl,
+        getOwnEl: opts.getOwnEl,
+        getPort: () => getPort?.() ?? null,
+        correctsScroll: () => correctsScroll?.() ?? true,
+        getFocusPath: () => getFocusPath?.() ?? null,
+        getRevealAnchorTarget: claimsRevealAnchor
+            ? () => placementOf(revealAnchor?.get() ?? null, blockElLookup)
+            : undefined,
+        getWidthVersion: () => getWidthVersion?.() ?? 0,
+        getViewportHeightVersion: () => getViewportHeightVersion?.() ?? 0,
+        getParentPath: opts.getParentPath,
+        reportSelfHeight: parentSink
+            ? (h) => parentSink.setChildSubtotal(opts.getIndex(), h)
+            : undefined,
+        isCollapsed: opts.isCollapsed,
+        // A fling can outrun the deferred window recompute and briefly paint an empty spacer
+        // (VR-8). 6 widens the band without breaching the mounted-set ceiling (the < 60 flat
+        // e2e bound guards that); a skeleton background covers the residual one-frame gap.
+        overscan: 6,
+        pinExtensionCap: 100,
+        activateAbovePx: 4000,
+        deactivateBelowPx: 3000
+    });
+    if (opts.provideLeafChannel) {
+        // Only a DIRECT child measures into this model; a deeper host belongs to its own
+        // scope's channel, so register is a no-op here.
+        setContext(RECORD_BLOCK_HEIGHT_KEY, {
+            register(path, index, id, readHeight) {
+                const depth = opts.getParentPath().length;
+                if (path.length !== depth + 1)
+                    return () => { };
+                return windowing.registerChild(id, {
+                    readHeight,
+                    applyHeight: (h) => windowing.recordMeasuredChild(index, id, h)
+                });
+            },
+            measureNow: windowing.measureChildNow,
+            measureOnResize: windowing.measureChildOnResize
+        });
+    }
+    setContext(PARENT_SCOPE_SINK_KEY, {
+        setChildSubtotal: windowing.setChildSubtotal,
+        registerRow: (id, readHeight, applyHeight) => windowing.registerChild(id, { readHeight, applyHeight }),
+        measureRowNow: windowing.measureChildNow
+    });
+    return windowing;
+}

package/dist/reactivity/window-slice.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one home for the windowed-slice bounds. A consumer renders `children.slice(start,
+ * end)` and MUST key/index each rendered child by its ABSOLUTE index `start + localIndex`,
+ * never the local loop index — leaking the local index corrupts paths and structural ops
+ * invisibly (`docs/design/virtual-rendering.md`).
+ */
+import type { WindowResult } from './block-window.svelte';
+export declare function sliceWindow(childCount: number, win: WindowResult | undefined): {
+    start: number;
+    end: number;
+};

package/dist/reactivity/window-slice.js

@@ -0,0 +1,9 @@
+export function sliceWindow(childCount, win) {
+    if (!win?.active)
+        return { start: 0, end: childCount };
+    // A window derived from a prior, longer children array can arrive one reactive tick
+    // before the slice re-derives against the new length.
+    const start = Math.min(win.start, childCount);
+    const end = Math.min(win.end, childCount);
+    return { start, end: Math.max(start, end) };
+}

package/dist/scan-index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The bounded decline for a recognizer whose grammar has no early-stop byte: candidate
+ * positions are collected once per block and each consultation is a binary search, so a
+ * trigger-dense paragraph costs one scan instead of one per trigger. The index memoizes
+ * per raw, bounded (cap 2) rather than weak-keyed because a string cannot key a WeakMap.
+ */
+/**
+ * `collect` scans one block's raw left to right into ascending positions; the returned
+ * lookup answers the first collected position at or after `from`, or -1 when none remains.
+ */
+export declare function createScanIndex(collect: (raw: string) => Int32Array): (raw: string, from: number) => number;

package/dist/scan-index.js

@@ -0,0 +1,27 @@
+/**
+ * The bounded decline for a recognizer whose grammar has no early-stop byte: candidate
+ * positions are collected once per block and each consultation is a binary search, so a
+ * trigger-dense paragraph costs one scan instead of one per trigger. The index memoizes
+ * per raw, bounded (cap 2) rather than weak-keyed because a string cannot key a WeakMap.
+ */
+import { createBoundedMemo } from './bounded-memo';
+/**
+ * `collect` scans one block's raw left to right into ascending positions; the returned
+ * lookup answers the first collected position at or after `from`, or -1 when none remains.
+ */
+export function createScanIndex(collect) {
+    const positionIndex = createBoundedMemo({ cap: 2 });
+    return (raw, from) => {
+        const positions = positionIndex(raw, () => collect(raw));
+        let lo = 0;
+        let hi = positions.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (positions[mid] < from)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo < positions.length ? positions[lo] : -1;
+    };
+}

package/dist/schema/block-commands.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The `(kind, id) → handler` block-command registry and every dispatch seam over it. A chord
+ * (leaf or container bubble), the `runCommand` door and its admissibility read all resolve the
+ * same tiers here, so the rules that hold regardless of invocation live at one seam.
+ * Register-once, throw-on-duplicate (casebook.md "Registries are code, not state"). Here, not
+ * `./commands`: `commands → block-commands → command-id` cycles.
+ */
+import type { AnyBlockKind } from '../core/nodes';
+import type { NodeView } from '../core/node-views';
+import { type AnyCommandId, type PluginCommandId } from './command-id';
+import { type GlobalCommandContext } from './commands';
+import type { KeybindingOverrideMap } from './keybinding-overrides';
+import { type EditorContext } from './plugin-install';
+export interface BlockCommandContext {
+    /** Read context — a bytes-readonly view; metadata edits go through `updateMetadata`. */
+    node: NodeView;
+    arg: unknown;
+    updateMetadata(patch: Record<string, unknown>): void;
+    /**
+     * The mounted component's view-state hooks, which a render-primary plugin casts to its own
+     * hooks type. `undefined` when no component is mounted, and a handler must decline
+     * gracefully then; the platform never learns the shape (`unknown` by design).
+     */
+    hooks?: unknown;
+    /** The dispatching instance's per-plugin EditorContext (document/events/options reads).
+     *  Undefined when the target surface has no instance wiring. */
+    editor?: EditorContext;
+}
+export type BlockCommandHandler = (ctx: BlockCommandContext) => boolean;
+/**
+ * Register-once check precedes the mint, so a duplicate `(kind, name)` reports as
+ * "register-once" rather than as an already-minted collision. The name-validating mint runs
+ * inside `apply` before the map write, so an invalid name never leaves an orphaned handler.
+ */
+export declare function registerBlockCommand(kind: AnyBlockKind, name: string, handler: BlockCommandHandler): PluginCommandId;
+export declare function getBlockCommand(kind: AnyBlockKind, id: AnyCommandId): BlockCommandHandler | undefined;
+export declare function __resetBlockCommandsForTests(): void;
+/**
+ * The cross-block arm a range command routes to, injected because this schema leaf may not
+ * import selection machinery. `canRun` is reachability, not participation: a press whose range
+ * reaches no block still consumes the chord and writes nothing.
+ */
+export interface CrossBlockCommandRouter {
+    canRun(id: AnyCommandId): boolean;
+    run(id: AnyCommandId): boolean;
+    isActive(id: AnyCommandId): boolean;
+}
+/**
+ * Editor state a command's admissibility reads, whatever invoked it. Getters, never values:
+ * they change under a live editor between one dispatch and the next. Every field is required,
+ * so a new dispatch site cannot silently skip the reading-mode gate, the range decline, or the
+ * cross-block route — `undefined` for the router is the answer a bubble caller gives.
+ */
+export interface CommandGates {
+    getPresentationMode: GlobalCommandContext['getPresentationMode'];
+    /** True while a cross-block range is painted. */
+    isCrossBlockRange(): boolean;
+    crossBlockCommands: CrossBlockCommandRouter | undefined;
+}
+/** What leaf dispatch and the `runCommand` door hand the seam: the gates plus the global tier. */
+export type CommandDispatchContext = GlobalCommandContext & CommandGates;
+export interface KindCommandTarget {
+    kind: AnyBlockKind;
+    runCommand(id: AnyCommandId, arg?: unknown): boolean;
+    getCommandContext?(): Omit<BlockCommandContext, 'arg'>;
+    /** The id's toggle-state at the surface's own caret or selection — what a toolbar paints
+     *  pressed. Absent means the surface has no toggle-state to report, which reads inactive. */
+    isCommandActive?(id: AnyCommandId): boolean;
+}
+/**
+ * A contained plugin command failure. A block command reports its `kind`; a global command
+ * reports its `plugin` and carries no kind. The dispatch seam hands this to the caller's sink,
+ * which routes it to the editor's error channel (`origin: 'command'`, `editor-events.ts`) —
+ * caller-injected so this schema leaf keeps no edge to the shell owning the event surface.
+ */
+export interface CommandErrorReport {
+    kind?: AnyBlockKind;
+    command: AnyCommandId;
+    plugin?: string;
+    error: unknown;
+}
+export type CommandErrorSink = (report: CommandErrorReport) => void;
+/**
+ * The door's admissibility read: the gates plus the same tier walk the dispatch spends, never a
+ * second derivation of them. Silent by design — a host may ask on every selection change, so an
+ * unreachable id spends none of the dispatch's one-time dead-key diagnostics.
+ * See `editor-props.ts` for the contract this answers.
+ */
+export declare function canRunCommandById(id: AnyCommandId, target: KindCommandTarget | null, gates: CommandGates): boolean;
+/** The door's pressed-state read, `canRunCommandById`'s sibling: state rather than
+ *  admissibility, so a disabled affordance may still paint pressed. Whoever would spend the
+ *  press answers — the cross-block arm over a range, the focused surface at a caret. */
+export declare function isCommandActiveById(id: AnyCommandId, target: KindCommandTarget | null, gates: CommandGates): boolean;
+/** The `EditorInstance.runCommand` door: an id with no keystroke behind it. */
+export declare function runCommandById(id: AnyCommandId, arg: unknown, target: KindCommandTarget | null, ctx: CommandDispatchContext, onCommandError?: CommandErrorSink): boolean;
+/** Leaf-path chord dispatch (the focused editable/chrome surface). */
+export declare function dispatchKeyCommand(chord: string, target: KindCommandTarget, ctx: CommandDispatchContext, overrides?: KeybindingOverrideMap, onCommandError?: CommandErrorSink): boolean;
+/**
+ * Container-bubble dispatch. Kind-only, no global tier: undo/redo belong to the focused leaf,
+ * and a container bubble re-firing them would double-fire (`resolveKindBinding` in `./commands`).
+ * The bubble callers hold no GlobalCommandContext, so they pass the gates directly — and an
+ * override that resolves a GLOBAL id here resolves DEAD, declining loudly rather than being
+ * dropped by a `runCommand` that has no arm for it.
+ */
+export declare function dispatchKindCommand(chord: string, target: KindCommandTarget, gates: CommandGates, overrides?: KeybindingOverrideMap, onCommandError?: CommandErrorSink): boolean;

package/dist/schema/block-commands.js

@@ -0,0 +1,179 @@
+import { mintCommandId, __resetMintedCommandIdsForTests } from './command-id';
+import { registerOnce } from './register-once';
+import { resolveBinding, resolveKindBinding, getCommand, warnDeadKeyCommand, isBuiltinCommandId, CROSS_BLOCK_RANGE_COMMAND_IDS, RANGE_DECLINED_COMMAND_IDS } from './commands';
+import { currentInstallingPlugin } from './plugin-install';
+import { isReadingMode } from '../presentation-mode';
+const blockCommands = new Map();
+const compositeKey = (kind, id) => `${kind} ${id}`;
+/**
+ * Register-once check precedes the mint, so a duplicate `(kind, name)` reports as
+ * "register-once" rather than as an already-minted collision. The name-validating mint runs
+ * inside `apply` before the map write, so an invalid name never leaves an orphaned handler.
+ */
+export function registerBlockCommand(kind, name, handler) {
+    const key = compositeKey(kind, name);
+    let id;
+    registerOnce(blockCommands.has(key), () => {
+        id = mintCommandId(name, currentInstallingPlugin());
+        blockCommands.set(key, handler);
+    }, `registerBlockCommand: (${kind}, ${name}) is already registered — block commands are register-once`);
+    return id;
+}
+export function getBlockCommand(kind, id) {
+    return blockCommands.get(compositeKey(kind, id));
+}
+export function __resetBlockCommandsForTests() {
+    blockCommands.clear();
+    __resetMintedCommandIdsForTests();
+}
+/**
+ * The kind tiers, in dispatch order. A GLOBAL id resolves DEAD here: the leaf path has already
+ * run it, and the container bubble deliberately has no global tier, so a container can never
+ * re-fire the focused leaf's undo.
+ */
+function resolveBlockLocalCommand(id, target) {
+    if (!target)
+        return { tier: 'no-surface' };
+    if (getCommand(id))
+        return { tier: 'dead' };
+    const handler = getBlockCommand(target.kind, id);
+    // A context is built only where a handler matched, so a built-in id costs nothing extra on the
+    // read a host may run per selection change.
+    const context = handler ? target.getCommandContext?.() : undefined;
+    if (handler && context)
+        return { tier: 'minted', target, handler, context };
+    return isBuiltinCommandId(id) ? { tier: 'builtin', target } : { tier: 'dead' };
+}
+/** The full walk: global first, then the kind tiers. Both the dispatch and the admissibility
+ *  read spend this one, so a greyed affordance cannot disagree with the click under it. */
+function resolveCommand(id, target) {
+    const globalRun = getCommand(id);
+    if (globalRun)
+        return { tier: 'global', run: globalRun };
+    return resolveBlockLocalCommand(id, target);
+}
+/**
+ * Spend a resolved kind tier. Containment is unconditional — the safety guarantee lives here, not
+ * at the call sites, so an unwired caller still turns a plugin throw into a no-op, it just doesn't
+ * report. A dead id declines loudly rather than reaching a `runCommand` with no arm for it.
+ */
+function runBlockLocalCommand(resolved, id, arg, path, onCommandError) {
+    switch (resolved.tier) {
+        case 'minted':
+            try {
+                return resolved.handler({ ...resolved.context, arg });
+            }
+            catch (error) {
+                onCommandError?.({ kind: resolved.target.kind, command: id, error });
+                return true;
+            }
+        case 'builtin':
+            return resolved.target.runCommand(id, arg);
+        case 'dead':
+            warnDeadKeyCommand(id, path);
+            return false;
+        case 'no-surface':
+            return false;
+    }
+}
+/**
+ * Where an id goes with a range painted. The one-block arms have no host block to take their
+ * offsets from, so they either route to the cross-block arm or decline; everything else is
+ * range-safe and runs on the focused surface (`RANGE_DECLINED_COMMAND_IDS` in `./commands`).
+ */
+function rangeRouteFor(id, gates) {
+    // Called directly, not optionally: a caller without the getter throws rather than skipping.
+    if (!gates.isCrossBlockRange())
+        return { kind: 'block-local', ranged: false };
+    if (RANGE_DECLINED_COMMAND_IDS.has(id))
+        return { kind: 'decline' };
+    if (!CROSS_BLOCK_RANGE_COMMAND_IDS.has(id))
+        return { kind: 'block-local', ranged: true };
+    const router = gates.crossBlockCommands;
+    return router?.canRun(id) ? { kind: 'cross-block', router } : { kind: 'decline' };
+}
+/**
+ * The gates every entry path owes, whatever resolved the id. Reading mode is inert: the whole
+ * vocabulary dead-keys, and navigation never routes through commands, so a reader loses nothing.
+ */
+function commandIsAdmissible(id, gates) {
+    if (isReadingMode(gates.getPresentationMode))
+        return false;
+    return rangeRouteFor(id, gates).kind !== 'decline';
+}
+/**
+ * The id-keyed seam: chord dispatch enters with a resolved binding, `EditorInstance.runCommand`
+ * with the id itself, so both meet the same gates and the same arms. Precedence is the leaf
+ * order: global (undo/redo) → minted block command → built-in kind command. A null target means
+ * no focused surface, where the global tier still runs and the block-local tiers decline.
+ */
+function runResolvedCommand(id, arg, target, ctx, path, onCommandError) {
+    if (isReadingMode(ctx.getPresentationMode))
+        return false;
+    const route = rangeRouteFor(id, ctx);
+    if (route.kind === 'decline')
+        return false;
+    if (route.kind === 'cross-block')
+        return route.router.run(id);
+    const resolved = resolveCommand(id, target);
+    // Inject the sink so a plugin-global handler's contained throw reports through the same
+    // channel as a block command's; the global tier is the only path reaching one.
+    if (resolved.tier === 'global')
+        return resolved.run({ ...ctx, onCommandError });
+    return runBlockLocalCommand(resolved, id, arg, path, onCommandError);
+}
+/**
+ * The door's admissibility read: the gates plus the same tier walk the dispatch spends, never a
+ * second derivation of them. Silent by design — a host may ask on every selection change, so an
+ * unreachable id spends none of the dispatch's one-time dead-key diagnostics.
+ * See `editor-props.ts` for the contract this answers.
+ */
+export function canRunCommandById(id, target, gates) {
+    if (isReadingMode(gates.getPresentationMode))
+        return false;
+    const route = rangeRouteFor(id, gates);
+    if (route.kind !== 'block-local')
+        return route.kind === 'cross-block';
+    const { tier } = resolveCommand(id, target);
+    return tier !== 'dead' && tier !== 'no-surface';
+}
+/** The door's pressed-state read, `canRunCommandById`'s sibling: state rather than
+ *  admissibility, so a disabled affordance may still paint pressed. Whoever would spend the
+ *  press answers — the cross-block arm over a range, the focused surface at a caret. */
+export function isCommandActiveById(id, target, gates) {
+    const route = rangeRouteFor(id, gates);
+    if (route.kind === 'cross-block')
+        return route.router.isActive(id);
+    // A range no arm reads has no pressed state: the focused surface holds a parked caret, whose
+    // bytes are not the ones a press would rewrite.
+    if (route.kind === 'decline' || route.ranged)
+        return false;
+    return target?.isCommandActive?.(id) ?? false;
+}
+/** The `EditorInstance.runCommand` door: an id with no keystroke behind it. */
+export function runCommandById(id, arg, target, ctx, onCommandError) {
+    return runResolvedCommand(id, arg, target, ctx, 'door', onCommandError);
+}
+/** Leaf-path chord dispatch (the focused editable/chrome surface). */
+export function dispatchKeyCommand(chord, target, ctx, overrides, onCommandError) {
+    const binding = resolveBinding(chord, target.kind, overrides, ctx.activation);
+    if (!binding)
+        return false;
+    return runResolvedCommand(binding.command, binding.arg, target, ctx, 'chord', onCommandError);
+}
+/**
+ * Container-bubble dispatch. Kind-only, no global tier: undo/redo belong to the focused leaf,
+ * and a container bubble re-firing them would double-fire (`resolveKindBinding` in `./commands`).
+ * The bubble callers hold no GlobalCommandContext, so they pass the gates directly — and an
+ * override that resolves a GLOBAL id here resolves DEAD, declining loudly rather than being
+ * dropped by a `runCommand` that has no arm for it.
+ */
+export function dispatchKindCommand(chord, target, gates, overrides, onCommandError) {
+    const binding = resolveKindBinding(chord, target.kind, overrides);
+    if (!binding)
+        return false;
+    if (!commandIsAdmissible(binding.command, gates))
+        return false;
+    const resolved = resolveBlockLocalCommand(binding.command, target);
+    return runBlockLocalCommand(resolved, binding.command, binding.arg, 'chord', onCommandError);
+}

package/dist/schema/block-completions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-kind Enter-completion registry, the block-opener registry's sibling: an opener recognizes
+ * a line while parsing, a completer recognizes a lone typed line at an Enter press and answers
+ * the canonical lines that complete it. Published on `plugin.ts`, so its plugin entries clear
+ * through `registry-reset.ts` like every other public register-once seam.
+ */
+import { type AnyBlockKind } from '../core/nodes';
+/**
+ * The replacement, as lines WITHOUT endings — the seam attaches the block's own (G4.20) — plus
+ * where the caret seats: `path` is child indices inside the minted block, empty for the block,
+ * and `line`/`column` address a position inside THAT node. Line-relative rather than a byte
+ * offset because the seam picks the line ending after the claim, so only it can count bytes.
+ */
+export interface CompletionResult {
+    lines: string[];
+    caret: {
+        path: number[];
+        line: number;
+        column: number;
+    };
+}
+export interface BlockCompleter {
+    /** Attempt to complete `line`; null declines, as does a claim whose lines would paint nothing. */
+    tryComplete(line: string): CompletionResult | null;
+}
+export declare function registerBlockCompleter(kind: AnyBlockKind, completer: BlockCompleter): void;
+/** The first claim on `line`, or null when no registered completer takes it. */
+export declare function completeTypedLine(line: string): CompletionResult | null;
+/** Whether `kind` already owns a completer — the probe a registrar re-run reads before it
+ *  registers, so a re-installed plugin never trips the register-once throw. */
+export declare function isBlockCompleterRegistered(kind: string): boolean;
+export declare function __resetBlockCompletersForTests(): void;
+export declare function __removePluginCompletersForTests(): void;

package/dist/schema/block-completions.js

@@ -0,0 +1,49 @@
+/**
+ * Per-kind Enter-completion registry, the block-opener registry's sibling: an opener recognizes
+ * a line while parsing, a completer recognizes a lone typed line at an Enter press and answers
+ * the canonical lines that complete it. Published on `plugin.ts`, so its plugin entries clear
+ * through `registry-reset.ts` like every other public register-once seam.
+ */
+import { isBuiltinBlockKind } from '../core/nodes';
+import { deletePluginEntries, registerOnce } from './register-once';
+const completers = new Map();
+let orderedCache = null;
+export function registerBlockCompleter(kind, completer) {
+    registerOnce(completers.has(kind), () => {
+        completers.set(kind, completer);
+        orderedCache = null;
+    }, `registerBlockCompleter: "${kind}" is already registered. Completers are register-once.`);
+}
+// Kind-name order, so which completer is consulted first is a pure function of the declarations
+// and never of registration order — the openers' rule, minus a priority no conflict has asked for.
+function ordered() {
+    if (!orderedCache) {
+        orderedCache = [...completers.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([, completer]) => completer);
+    }
+    return orderedCache;
+}
+/** The first claim on `line`, or null when no registered completer takes it. */
+export function completeTypedLine(line) {
+    for (const completer of ordered()) {
+        const claim = completer.tryComplete(line);
+        if (claim)
+            return claim;
+    }
+    return null;
+}
+/** Whether `kind` already owns a completer — the probe a registrar re-run reads before it
+ *  registers, so a re-installed plugin never trips the register-once throw. */
+export function isBlockCompleterRegistered(kind) {
+    return completers.has(kind);
+}
+export function __resetBlockCompletersForTests() {
+    completers.clear();
+    orderedCache = null;
+}
+// The unified schema reset preserves built-ins for tests that merely add plugin kinds.
+export function __removePluginCompletersForTests() {
+    deletePluginEntries(completers, isBuiltinBlockKind);
+    orderedCache = null;
+}

package/dist/schema/block-component-registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Runtime `BlockKind → component` map. BlockHost looks up by kind; plugin
+ * kinds register a descriptor plus a component entry.
+ */
+import type { Component } from 'svelte';
+import { type AnyBlockKind } from '../core/nodes';
+import type { NodeView } from '../core/node-views';
+import type { BlockComponentExports, BlockComponentProps } from '../block-component';
+export interface BlockComponentEntry {
+    /**
+     * Declaring `BlockComponentExports` as the Exports lets BlockHost's `bind:this` type-check
+     * against a runtime-picked component, and pins the two shapes a block may publish: the
+     * surface itself (a leaf) or a container's single `containerApi`.
+     */
+    component: Component<Record<string, unknown>, BlockComponentExports>;
+    extraProps?: (node: NodeView) => Record<string, unknown>;
+}
+/**
+ * Typed constructor for a registry entry: the component publishes one of the two sanctioned
+ * surface shapes, and its props are a subset of what BlockHost passes. A container that forgot
+ * its `containerApi` fails here rather than mounting as a block nothing can focus. The internal
+ * cast widens contravariant props to the registry's `Record<string, unknown>`.
+ */
+export declare function defineBlockComponent<P extends Partial<BlockComponentProps> & Record<string, unknown>>(component: Component<P, BlockComponentExports>, extraProps?: (node: NodeView) => Record<string, unknown>): BlockComponentEntry;
+export declare function registerBlockComponent(kind: AnyBlockKind, entry: BlockComponentEntry): void;
+export declare function getBlockComponent(kind: AnyBlockKind): BlockComponentEntry | undefined;
+/**
+ * Probe whether a component is registered — `registerBlockComponent` throws on duplicate, so a
+ * plugin registering idempotently (HMR / re-import) guards on this. Takes a plain name.
+ */
+export declare function isBlockComponentRegistered(kind: string): boolean;
+/** Test-only. Removes every non-built-in component entry; built-ins survive. */
+export declare function __removePluginComponentsForTests(): void;