@voithos-labs/aragonite 0.10.1

package/dist/editor-actions/nested/nested-actions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Composer for container nestedActions bundles. HistoryActions is deliberately
+ * absent: containers never override history, and Svelte context delivers the
+ * document-level HISTORY_KEY to any descendant.
+ */
+import type { BlockEditActions, ContainerEditActions, FocusActions, ListContext } from '../../action-contracts';
+import type { NodeView } from '../../core/node-views';
+import type { GrammarView } from '../../schema/block-openers';
+import { type PresentationModeGetter } from '../../editor-keys';
+import type { StickyColumnState } from '../../cursor/sticky-column';
+import type { BlockListState } from '../../reactivity/block-list-state.svelte';
+import type { InlineResolverRef } from '../../schema/inline-construct-policy';
+export interface NestedActionsBundle {
+    blockEdit: BlockEditActions;
+    focus: FocusActions;
+    containerEdit: ContainerEditActions;
+}
+/**
+ * The three container coordinates every nested factory reads live. A component mints
+ * ONE of these and passes it BY REFERENCE to each factory it wires — never spread,
+ * which invokes the getters and captures stale values.
+ */
+export interface NodeScope {
+    get index(): number;
+    get node(): NodeView;
+    /** Doc-absolute path of `node`; spine unsharing + ancestry rebuilds key off it. */
+    get path(): number[];
+}
+export interface NestedActionsDeps {
+    index: number;
+    node: NodeView;
+    /** Doc-absolute path of `node`; spine unsharing + ancestry rebuilds key off it. */
+    path: number[];
+    stickyColumn: StickyColumnState;
+    /** The instance's block grammar, so a disabled kind's opener stays skipped when a
+     *  nested block re-parses. Absent = the global grammar. */
+    grammar?: GrammarView;
+    /** Live EFFECTIVE mode, for interior mutations whose bytes depend on what the mode paints
+     *  (the split rebalance). Nullable rather than optional so each container answers. */
+    getPresentationMode: PresentationModeGetter | undefined;
+    /** The instance's link-reference resolver, required-nullable beside the mode. */
+    linkRef: InlineResolverRef | undefined;
+    /** Enclosing list's context, when this container is a list nested in one. */
+    parentListContext?: ListContext;
+    parent: {
+        blockEdit: BlockEditActions;
+        focus: FocusActions;
+        containerEdit: ContainerEditActions;
+    };
+}
+/**
+ * `createStandardNestedActions`'s public input: the shared `NodeScope` by reference
+ * plus the static config `NestedActionsDeps` carries.
+ */
+export type NestedActionsInput = Omit<NestedActionsDeps, 'index' | 'node' | 'path'> & {
+    scope: NodeScope;
+};
+/** Receives stable default bundle references; chain via `defaults.blockEdit.foo(...)`. */
+export type NestedActionsOverrideFactory = (defaults: NestedActionsBundle) => {
+    blockEdit?: Partial<BlockEditActions>;
+    focus?: Partial<FocusActions>;
+    containerEdit?: Partial<ContainerEditActions>;
+};
+export declare function createStandardNestedActions(state: BlockListState, input: NestedActionsInput, overrideFactory?: NestedActionsOverrideFactory): NestedActionsBundle;
+export declare function setNestedActionsContexts(bundle: NestedActionsBundle): void;

package/dist/editor-actions/nested/nested-actions.js

@@ -0,0 +1,59 @@
+/**
+ * Composer for container nestedActions bundles. HistoryActions is deliberately
+ * absent: containers never override history, and Svelte context delivers the
+ * document-level HISTORY_KEY to any descendant.
+ */
+import { setContext } from 'svelte';
+import { BLOCK_EDIT_KEY, CONTAINER_EDIT_KEY, FOCUS_KEY, HISTORY_KEY } from '../../editor-keys';
+import { assertInvariant } from '../../assert';
+import { checkNoContainerHistoryKey } from '../../invariants/context-keys';
+import { createNestedBlockEdit } from './nested-block-edit';
+import { createNestedFocus } from './nested-focus';
+import { withEnterCompletion } from '../enter-completion';
+export function createStandardNestedActions(state, input, overrideFactory) {
+    // Adapt `scope` to the inline shape the sub-factories read, once at the choke point
+    // rather than at every call site. Getters stay live; destructuring would snapshot.
+    const deps = {
+        get index() {
+            return input.scope.index;
+        },
+        get node() {
+            return input.scope.node;
+        },
+        get path() {
+            return input.scope.path;
+        },
+        stickyColumn: input.stickyColumn,
+        grammar: input.grammar,
+        getPresentationMode: input.getPresentationMode,
+        linkRef: input.linkRef,
+        parentListContext: input.parentListContext,
+        parent: input.parent
+    };
+    const blockEdit = createNestedBlockEdit(state, deps);
+    const focus = createNestedFocus(state, deps);
+    // Commit coordinates are doc-absolute at their mint point (block-edit-scope), so
+    // intermediate containers have nothing to remap and this passes straight through.
+    const containerEdit = deps.parent.containerEdit;
+    const defaults = { blockEdit, focus, containerEdit };
+    // Above the override spread, so a container replacing `splitBlock` keeps the completion arm
+    // its subtree owes. `defaults` stays undecorated: an override chaining back into it is
+    // already past the consult, and re-entering would spend one press on two.
+    const childAt = (index) => deps.node.children?.[index];
+    if (!overrideFactory) {
+        return { ...defaults, blockEdit: withEnterCompletion(blockEdit, childAt) };
+    }
+    const overrides = overrideFactory(defaults);
+    return {
+        blockEdit: withEnterCompletion({ ...blockEdit, ...(overrides.blockEdit ?? {}) }, childAt),
+        focus: { ...focus, ...(overrides.focus ?? {}) },
+        containerEdit: { ...containerEdit, ...(overrides.containerEdit ?? {}) }
+    };
+}
+export function setNestedActionsContexts(bundle) {
+    const keys = [BLOCK_EDIT_KEY, FOCUS_KEY, CONTAINER_EDIT_KEY];
+    assertInvariant('container-history-key', () => checkNoContainerHistoryKey(keys, HISTORY_KEY));
+    setContext(BLOCK_EDIT_KEY, bundle.blockEdit);
+    setContext(FOCUS_KEY, bundle.focus);
+    setContext(CONTAINER_EDIT_KEY, bundle.containerEdit);
+}

package/dist/editor-actions/nested/nested-block-edit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Container BlockEditActions factory. Interior mutations route through the shared
+ * `block-edit-core` against a container `CommitScope`; this wrapper owns what the
+ * core can't: the children guards, boundary delegation up to `parent.blockEdit`, the
+ * unwrap dispatch, and `updateBlockContent`.
+ */
+import type { BlockEditActions } from '../../action-contracts';
+import type { BlockListState } from '../../reactivity/block-list-state.svelte';
+import type { NestedActionsDeps } from './nested-actions';
+export declare function createNestedBlockEdit(state: BlockListState, deps: NestedActionsDeps): BlockEditActions;

package/dist/editor-actions/nested/nested-block-edit.js

@@ -0,0 +1,181 @@
+/**
+ * Container BlockEditActions factory. Interior mutations route through the shared
+ * `block-edit-core` against a container `CommitScope`; this wrapper owns what the
+ * core can't: the children guards, boundary delegation up to `parent.blockEdit`, the
+ * unwrap dispatch, and `updateBlockContent`.
+ */
+import { tick } from 'svelte';
+import { updateNodeContent as performUpdate, ensureUnsharedChild, reconcileTaskMetadata } from '../../tree-operations';
+import { stampStructuralChange } from '../../tree-operations/structural-change';
+import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+import { isCollapsedContainer } from '../../schema/reserved-chrome';
+import { assertInvariant } from '../../assert';
+import { firstChildUnwrapStrategies, middleChildUnwrapStrategies } from '../unwrap-strategies';
+import { createContainerScope, scopeParentOf } from '../block-edit-scope';
+import { createBlockEditCore } from '../block-edit-core';
+import { previewContentReparse, focusAfterContentReplace } from '../replacement-focus';
+import { extendDocPath } from '../../cursor/coordinate-spaces';
+export function createNestedBlockEdit(state, deps) {
+    const { parent } = deps;
+    const scope = createContainerScope(state, deps);
+    const core = createBlockEditCore(scope);
+    /**
+     * Where a caret at `offset` lands once this container's body-write rule has
+     * rewritten `text`. Both caret doors read it, since either can arrive from a
+     * component that measured the DOM before the rewrite.
+     */
+    function mapCommittedOffset(text, offset) {
+        const bodyWrite = tryGetBlockKindDescriptor(deps.node.kind)?.bodyWrite;
+        return bodyWrite ? bodyWrite.mapOffset(text, offset) : offset;
+    }
+    const blockEdit = {
+        // ── Structural mutations (interior → core, edges → parent) ─────────────
+        async splitBlock(innerIndex, offset) {
+            if (!deps.node.children)
+                return;
+            await core.split(innerIndex, offset);
+        },
+        async descendToBody(innerIndex) {
+            if (!deps.node.children)
+                return;
+            await core.descendToBody(innerIndex);
+        },
+        async insertParagraph(boundaryIndex, text) {
+            if (!deps.node.children)
+                return;
+            await core.insertParagraph(boundaryIndex, text);
+        },
+        async mergeWithPrevious(innerIndex) {
+            if (!deps.node.children)
+                return;
+            const unwrapRole = tryGetBlockKindDescriptor(deps.node.kind)?.unwrapRole;
+            if (innerIndex <= 0) {
+                if (unwrapRole) {
+                    await firstChildUnwrapStrategies[unwrapRole.firstChildBackspace]({ deps, state });
+                    return;
+                }
+                // Undeclared containers delegate upward. Awaited so caller continuations
+                // (focus placement) run after the upward chain settles.
+                await parent.blockEdit.mergeWithPrevious(deps.index);
+                return;
+            }
+            if (unwrapRole && unwrapRole.middleChildBackspace !== 'default-merge') {
+                await middleChildUnwrapStrategies[unwrapRole.middleChildBackspace]({ deps, state }, innerIndex);
+                return;
+            }
+            await core.mergeWithPreviousInterior(innerIndex);
+        },
+        async mergeWithNext(innerIndex) {
+            if (!deps.node.children)
+                return;
+            if (innerIndex >= deps.node.children.length - 1) {
+                return parent.blockEdit.mergeWithNext(deps.index);
+            }
+            // A collapsed container's body is unmounted, so forward-Delete exits past the container
+            // rather than dead-ending on the invisible body — a focus move, no mutation.
+            // `append: false` keeps the last-block case inert rather than minting a paragraph.
+            if (isCollapsedContainer(deps.node)) {
+                await parent.focus.moveFocus(deps.index + 1, 'start', { append: false });
+                return;
+            }
+            await core.mergeWithNextInterior(innerIndex);
+        },
+        async deleteBlock(innerIndex) {
+            if (!deps.node.children)
+                return;
+            if (deps.node.children.length <= 1) {
+                return parent.blockEdit.deleteBlock(deps.index);
+            }
+            await core.deleteInterior(innerIndex);
+        },
+        updateBlockMetadata: (innerIndex, metadata, options) => core.updateBlockMetadata(innerIndex, metadata, options),
+        replaceBlock: (innerIndex, replacement, focus, options) => core.replaceBlock(innerIndex, replacement, focus, options),
+        // ── In-place leaf edits (per-level) ────────────────────────────────────
+        mapCommittedOffset,
+        async updateBlockContent(innerIndex, text, preEditOffset, postEditFocusOffset) {
+            // The batch's pause window opens once this keystroke's own work is done, throw
+            // included: an unarmed batch never ends by pause.
+            try {
+                await applyContentUpdate(innerIndex, text, preEditOffset, postEditFocusOffset);
+            }
+            finally {
+                parent.containerEdit.armDebouncedPause();
+            }
+        }
+    };
+    async function applyContentUpdate(innerIndex, text, preEditOffset, postEditFocusOffset) {
+        if (!deps.node.children)
+            return;
+        // No tail suffix: the document-level fold has no container twin yet.
+        const preview = previewContentReparse(deps.node.children[innerIndex], text, deps.grammar, deps.node.kind, '');
+        const leafPath = extendDocPath(deps.path, innerIndex);
+        if (preview.op !== 'noop') {
+            // Mapped, because a caret measured before the rewrite names a position in
+            // bytes that never landed. Reachable here and not only on the routine path:
+            // completing `</details>` is a kind change, and a kind change commits.
+            const focusOffset = mapCommittedOffset(text, postEditFocusOffset ?? preEditOffset ?? 0);
+            let settled = { change: { op: 'noop' }, textStart: 0 };
+            await parent.containerEdit.commitContainer({
+                containerNode: deps.node,
+                path: deps.path,
+                state,
+                snapshot: { path: leafPath, offset: preEditOffset ?? 0 },
+                mutate: (scope) => {
+                    ensureUnsharedChild(scope.node, innerIndex, scope.sharing);
+                    settled = performUpdate(scopeParentOf(scope), innerIndex, text, deps.grammar, scope.sharing);
+                    stampStructuralChange(scope.children, settled.change, scope.sharing);
+                    return settled.change;
+                },
+                op: {
+                    kind: 'updateContent',
+                    detail: { length: text.length },
+                    eventPath: leafPath
+                },
+                afterTick: () => focusAfterContentReplace(deps.path, innerIndex, settled, focusOffset, scope)
+            });
+            return;
+        }
+        // Routine typing — debounced undo path, no structural commit. The inner leaf's
+        // id is the batch key, so a focus move between sibling leaves breaks the batch.
+        parent.containerEdit.pushDebouncedCheckpoint(leafPath, preEditOffset ?? 0, state.innerBlockIds[innerIndex]);
+        let settled = { change: { op: 'noop' }, textStart: 0 };
+        const reclassified = parent.containerEdit.withUnsharedSpine(leafPath, (chain, sharing) => {
+            assertInvariant('unshared-spine-depth', () => chain.length === leafPath.length
+                ? null
+                : {
+                    code: 'unshared-spine-depth',
+                    message: `withUnsharedSpine: chain depth ${chain.length} != leaf path depth ${leafPath.length}`
+                });
+            const ownedContainer = chain[leafPath.length - 2];
+            if (!ownedContainer?.children)
+                return;
+            settled = performUpdate({
+                children: ownedContainer.children,
+                ownerKind: ownedContainer.kind,
+                owner: ownedContainer
+            }, innerIndex, text, deps.grammar, sharing);
+            // taskItem metadata is extracted at parse time from the first stripped
+            // line, so without this it freezes while the serialized source drifts.
+            if (ownedContainer.kind === 'listItem' && innerIndex === 0) {
+                reconcileTaskMetadata(ownedContainer);
+            }
+            return settled.change;
+        });
+        parent.containerEdit.nudgeReactivity();
+        // The rebuild re-kinded a container on this spine (a typed `> [!TIP]` marker
+        // moves into the container's own bytes), so the edited leaf no longer exists.
+        // Re-enter at the container's start; its focus walk lands in the body.
+        if (reclassified) {
+            await tick();
+            await parent.focus.moveFocus(deps.index, 'start');
+            return;
+        }
+        // A blank-fill settle can fold here, which the single-node preview probe cannot see;
+        // the spine wrapper published the splice, and the caret follows the re-tiled bytes.
+        if (settled.change.op === 'noop')
+            return;
+        await tick();
+        focusAfterContentReplace(deps.path, innerIndex, settled, mapCommittedOffset(text, postEditFocusOffset ?? preEditOffset ?? 0), scope);
+    }
+    return blockEdit;
+}

package/dist/editor-actions/nested/nested-focus.d.ts

@@ -0,0 +1,9 @@
+/**
+ * FocusActions factory for container nestedActions bundles. Delegates to the
+ * pure dispatcher in `focus-dispatch`, supplying the container's live child
+ * count so out-of-range delegation routes through the parent correctly.
+ */
+import type { FocusActions } from '../../action-contracts';
+import type { BlockListState } from '../../reactivity/block-list-state.svelte';
+import type { NestedActionsDeps } from './nested-actions';
+export declare function createNestedFocus(state: BlockListState, deps: NestedActionsDeps): FocusActions;

package/dist/editor-actions/nested/nested-focus.js

@@ -0,0 +1,30 @@
+/**
+ * FocusActions factory for container nestedActions bundles. Delegates to the
+ * pure dispatcher in `focus-dispatch`, supplying the container's live child
+ * count so out-of-range delegation routes through the parent correctly.
+ */
+import { dispatchMoveFocus } from '../focus/focus-dispatch';
+export function createNestedFocus(state, deps) {
+    const { stickyColumn, parent } = deps;
+    return {
+        // A nested scope's reveal IS the editor's recursive revealPath descending
+        // through this container, so this scope doesn't own it. The gap stop is forwarded
+        // for the same reason: the root holds the doc and selection reads.
+        revealPath: parent.focus.revealPath,
+        tryGapStop: parent.focus.tryGapStop,
+        // Sync, and does not reveal an off-window inner target, unlike the root
+        // `moveFocus`. The adjacent-only precondition is the caller's — VR-12
+        // (docs/design/virtual-rendering.md).
+        async moveFocus(innerIndex, position, options) {
+            await dispatchMoveFocus(state.innerBlockRefs, innerIndex, position, stickyColumn, { focus: parent.focus, index: deps.index }, {
+                // node.children.length is authoritative: refs.length lags after structural
+                // ops because bind:this fires asynchronously.
+                childCount: deps.node.children?.length,
+                options,
+                // The boundaries this scope owns are its own children's, so the container's
+                // doc-absolute path is their parent. Read live: `path` moves under edits.
+                gapStop: (boundaryIndex) => parent.focus.tryGapStop(deps.path, boundaryIndex)
+            });
+        }
+    };
+}

package/dist/editor-actions/paste-coordinator.d.ts

@@ -0,0 +1,4 @@
+/** Lets paste modules depend on a narrow interface in their own layer instead of reaching up into editor-actions. */
+import type { PasteCommitCoordinator } from '../tree-operations/paste/paste-deps';
+import type { EditorActionsDeps, UndoController } from './deps';
+export declare function createPasteCoordinator(controller: UndoController, revealPath: EditorActionsDeps['revealPath']): PasteCommitCoordinator;

package/dist/editor-actions/paste-coordinator.js

@@ -0,0 +1,20 @@
+/** Lets paste modules depend on a narrow interface in their own layer instead of reaching up into editor-actions. */
+import { getStateForNode } from '../reactivity/state-registry';
+export function createPasteCoordinator(controller, revealPath) {
+    return {
+        commitMultiScope: controller.commitMultiScope,
+        getDocScope: controller.getDocScope,
+        // editor-actions may read reactivity and reveal (downward edges); supplying
+        // them here keeps `tree-operations/paste/` from importing either itself.
+        resolveState: getStateForNode,
+        landCaret: async (path, offset) => {
+            const stamp = controller.historyGeneration();
+            const block = await revealPath(path);
+            // A history swap that resolved inside the reveal restored a different tree, so
+            // this path no longer addresses what the paste aimed at.
+            if (controller.historyGeneration() !== stamp)
+                return;
+            block?.focus(offset);
+        }
+    };
+}

package/dist/editor-actions/plugin/chrome-leaf.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Register a container-chrome leaf kind: editable text at a reserved child slot of a plugin
+ * container (a callout title, a details summary). The container declares the slot via
+ * `reservedChrome`; this seam supplies the leaf. Chrome only, never standalone recognizer-backed
+ * kinds — the contract is a single-line, plain-text child (`docs/design/plugin-contract.md`).
+ */
+import type { Component } from 'svelte';
+import { type MergeRole } from '../../schema/block-kind-descriptor';
+import { type KeyBinding } from '../../schema/keybindings';
+import { type AnyBlockKind, type CstNode } from '../../core/nodes';
+import type { BlockComponent, BlockComponentProps } from '../../block-component';
+/**
+ * Mint the reserved child-0 node for a chrome leaf. An empty title collapses to a
+ * bare newline, so the empty leaf still holds a line.
+ */
+export declare function chromeChild(kind: AnyBlockKind, text: string): CstNode;
+export interface ChromeLeafOptions {
+    /** CSS class on the leaf's surface, for chrome styling. */
+    blockClass?: string;
+    /** A binding replaces the seam default for its chord; the defaults fill the rest. */
+    keymap?: KeyBinding[];
+    /** Defaults to 'not-mergeable' (chrome: body prose cannot merge into it). */
+    mergeRole?: MergeRole;
+}
+export declare function registerChromeLeaf<P extends Partial<BlockComponentProps> & Record<string, unknown>>(kind: AnyBlockKind, component: Component<P, BlockComponent>, opts?: ChromeLeafOptions): void;

package/dist/editor-actions/plugin/chrome-leaf.js

@@ -0,0 +1,80 @@
+/**
+ * Register a container-chrome leaf kind: editable text at a reserved child slot of a plugin
+ * container (a callout title, a details summary). The container declares the slot via
+ * `reservedChrome`; this seam supplies the leaf. Chrome only, never standalone recognizer-backed
+ * kinds — the contract is a single-line, plain-text child (`docs/design/plugin-contract.md`).
+ */
+import { registerBlockKind } from '../../schema/block-kind-descriptor';
+import { registerBlockComponent, defineBlockComponent } from '../../schema/block-component-registry';
+import { normalizeChord } from '../../schema/keybindings';
+import { registerPasteSurface } from '../../tree-operations/paste-surfaces';
+import { defaultInlineHook } from '../../tree-operations/paste/hooks';
+import { makeBlockNode } from '../../core/nodes';
+/**
+ * Mint the reserved child-0 node for a chrome leaf. An empty title collapses to a
+ * bare newline, so the empty leaf still holds a line.
+ */
+export function chromeChild(kind, text) {
+    return makeBlockNode({ kind, leadingTrivia: '', raw: text ? `${text}\n` : '\n' });
+}
+// Chrome is single-line by serialization, so Enter descends into the body
+// instead of splitting; Backspace/Delete take the ordinary merge walk.
+const CHROME_DEFAULT_KEYMAP = [
+    { chord: 'Enter', command: 'chrome.descendToBody' },
+    { chord: 'Backspace', command: 'block.mergePrev' },
+    { chord: 'Delete', command: 'block.mergeNext' }
+];
+function mergeChromeKeymap(overrides) {
+    if (!overrides?.length)
+        return [...CHROME_DEFAULT_KEYMAP];
+    const overridden = new Set(overrides.map((b) => normalizeChord(b.chord)));
+    return [
+        ...overrides,
+        ...CHROME_DEFAULT_KEYMAP.filter((b) => !overridden.has(normalizeChord(b.chord)))
+    ];
+}
+export function registerChromeLeaf(kind, component, opts = {}) {
+    registerBlockKind(kind, {
+        gapEdges: 'none',
+        mergeRole: opts.mergeRole ?? 'not-mergeable',
+        editable: true,
+        supportsInline: false,
+        contextDependentKind: true,
+        keymap: mergeChromeKeymap(opts.keymap),
+        // No conformanceFixture: the container opener mints child-0, so a chrome leaf
+        // never stands alone as a document scan's result.
+        closure: {
+            roundTrip: {
+                mode: 'implemented',
+                via: 'contextDependentKind — the container rebuildRaw emits the chrome bytes into its opener line'
+            },
+            focus: {
+                mode: 'implemented',
+                via: 'native caret; Enter descends to the body (chrome.descendToBody)'
+            },
+            mergeBackspace: {
+                mode: 'implemented',
+                via: 'not-mergeable chrome — cleared-not-deleted by range ops; Backspace/Delete take the merge walk'
+            },
+            selectionPaint: { mode: 'implemented', via: 'measurePartialRects (raw offsets)' },
+            searchPaint: { mode: 'implemented', via: 'chrome raw scanned; matches painted as marks' },
+            reorder: {
+                mode: 'not-supported',
+                reason: 'reserved child 0 — no independent block identity to move'
+            },
+            undo: { mode: 'inherit-default' },
+            clipboard: {
+                mode: 'implemented',
+                via: 'byte-slice copy; a slice touching the chrome re-emits the container — a mid-chrome start reopens it around the collected body, a mid-chrome end yields a chrome-only container'
+            },
+            simOracle: {
+                mode: 'implemented',
+                via: 'reserved-chrome structural-ops e2e under the [invariant:] watcher'
+            }
+        }
+    });
+    registerBlockComponent(kind, defineBlockComponent(component, () => ({ blockClass: opts.blockClass })));
+    // Inline-only surface, so `surfaceForcesInline` holds if a paste ever reaches
+    // surface resolution — defense behind the gate that already flattens chrome pastes.
+    registerPasteSurface({ kind, onInlinePaste: defaultInlineHook });
+}

package/dist/editor-actions/plugin/container.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The container-authoring seam a plugin block component builds on: the built-in
+ * container wiring collapsed into one factory, so a plugin never touches an editor
+ * context key. Call synchronously during component init — `getContext` reads the
+ * ancestor contexts and `useContainerWindowing` sets its own.
+ */
+import type { BlockEditActions, CommitAfterTick, FocusActions } from '../../action-contracts';
+import type { NodeView } from '../../core/node-views';
+import type { AmbientPrefix, BlockComponent, ContainerBlockComponent } from '../../block-component';
+import { type KindCommandTarget } from '../../schema/block-commands';
+import { type PresentationMode } from '../../presentation-mode';
+import { type PluginEditorLookup } from '../../editor-keys';
+import type { WindowResult } from '../../reactivity/block-window.svelte';
+import type { RefSlots } from '../../reactivity/publish-ref.svelte';
+import { type NestedActionsOverrideFactory } from '../nested/nested-actions';
+/**
+ * The frozen inputs the host component feeds in. A function-valued field is a **live
+ * read**, re-evaluated on every use; a plain-valued field is static configuration.
+ * `getBoxEl` returns the chrome box whose direct `.block-list` child the windowing
+ * lookups walk, so chrome siblings beside the list are fine.
+ */
+export interface ContainerBlockDeps {
+    getNode(): NodeView;
+    getIndex(): number;
+    getPath(): number[];
+    getBoxEl(): HTMLElement | undefined;
+    /**
+     * Opt into whole-block focus for an opaque, childless container: the element that
+     * takes DOM focus. The kind must also declare `blockFocus: 'whole-block'`. Supply
+     * a surface for EVERY steady state — a null degrades to the box with a dev warning.
+     */
+    getFocusEl?: () => HTMLElement | null | undefined;
+    /** Escape hatch only: the clamp derives from a declared `reservedChrome.isCollapsed`. */
+    isCollapsed?: () => boolean;
+    /** View-state hooks handed to a minted block command as `ctx.hooks`; typed `unknown`. */
+    commandHooks?: () => unknown;
+    /** Ambient prefix painted before the FIRST child's bytes — the listItem `- ` model. */
+    getAmbientPrefix?: () => AmbientPrefix;
+}
+/**
+ * The `BlockList` props the host spreads onto its rendered `<BlockList>`. Authored
+ * rather than derived, so an internal prop edit fails the check below instead of
+ * silently rewriting this contract.
+ */
+export interface ContainerBlockListProps {
+    children: readonly NodeView[];
+    blockIds: string[];
+    slots: RefSlots<BlockComponent>;
+    parentPath?: number[];
+    window?: WindowResult;
+    reorderable?: boolean;
+    ambientPrefixForFirst?: AmbientPrefix;
+}
+export type { ContainerBlockComponent };
+export interface ContainerBlock {
+    /** Spread onto `<BlockList {...blockListProps} />` inside the chrome box. */
+    blockListProps: ContainerBlockListProps;
+    /** The live EFFECTIVE mode, for gating edit affordances. Preferred over the DOM probe. */
+    getPresentationMode(): PresentationMode;
+    /**
+     * The live editor theme name (`data-editor-theme`). A body painted by an engine
+     * rather than CSS must key its render on this and re-render when it changes.
+     */
+    getTheme(): string;
+    /**
+     * This editor instance's options for the plugin owning this block's kind — the
+     * `{ plugin, options }` entry's channel, so two editors in one process configure the
+     * same kind differently. `unknown`, like `commandHooks`: the plugin narrows it.
+     */
+    getOptions(): unknown;
+    /** The `BlockComponent` surface the host re-exports for BlockHost. */
+    containerApi: ContainerBlockComponent;
+    /**
+     * Commit a shallow metadata patch on THIS container as one undoable entry, through
+     * the kind's `rebuildRaw`. `afterTick` runs once the commit's DOM has settled.
+     */
+    updateOwnMetadata(patch: Record<string, unknown>, afterTick?: CommitAfterTick): void | Promise<void>;
+    /**
+     * Attach to the chrome box: a chord bubbling from an inner leaf resolves against
+     * this kind's keymap. Kind-only, so a bubbled undo/redo never double-fires.
+     */
+    handleKeydown(e: KeyboardEvent): void;
+    /**
+     * Hand the caret to the neighbour a plain arrow points at — the boundary exit for a
+     * plugin-owned editable whose caret has reached its own edge. Routes through the
+     * editor's focus traversal, so the landing inherits skip-non-focusable, container
+     * entry and windowing reveal. False for a modified or non-arrow key: leave it native.
+     */
+    moveFocusOut(e: KeyboardEvent): boolean;
+}
+/**
+ * Collapse-ness has ONE definition: the descriptor's `reservedChrome.isCollapsed`
+ * probe. An explicit dep is dev-cross-checked against it, except in reading mode,
+ * which cannot write — a reader's open section is legitimately ahead of the document.
+ */
+export declare function composeCollapseProbe(explicit: (() => boolean) | undefined, getNode: () => NodeView, getPresentationMode?: () => PresentationMode): () => boolean;
+/**
+ * The expand door a reveal opens before descending into a collapsed body. Commits
+ * `reservedChrome.expandPatch` as a real undoable edit, not a view-only divergence
+ * from the CST; declines in reading mode, which commits nothing.
+ */
+export declare function composeExpandDoor(deps: {
+    getNode: () => NodeView;
+    isCollapsed: () => boolean;
+    getPresentationMode: () => PresentationMode;
+    commit: (patch: Record<string, unknown>) => void | Promise<void>;
+}): () => Promise<boolean>;
+/**
+ * The `updateOwnMetadata` gate: reading mode writes no bytes (plugin-contract.md), so the
+ * commit declines as a no-op and DEV names the kind that knocked.
+ */
+export declare function composeMetadataDoor(deps: {
+    getNode: () => NodeView;
+    getPresentationMode: () => PresentationMode;
+    commit: (patch: Record<string, unknown>, afterTick?: CommitAfterTick) => void | Promise<void>;
+}): ContainerBlock['updateOwnMetadata'];
+/** While collapsed the body is unmounted, so `descendToBody` would mint an invisible one. */
+export declare function gateDescendOnCollapse(isCollapsed: (() => boolean) | undefined, descend: (innerIndex: number) => void | Promise<void>): (innerIndex: number) => Promise<void>;
+/**
+ * While collapsed only the chrome row is mounted, so an interior `moveFocus`
+ * targeting a body index dead-ends on the unmounted ref. Route body targets past the
+ * container instead — the same exit an open container's past-end move takes.
+ */
+export declare function gateMoveFocusOnCollapse(isCollapsed: (() => boolean) | undefined, moveWithin: FocusActions['moveFocus'], parentFocus: FocusActions, getIndex: () => number): FocusActions['moveFocus'];
+export type NestedActionsOverrides = ReturnType<NestedActionsOverrideFactory>;
+/** Each surface spreads its base first: a gate ADDS a member, never replaces one. */
+export declare function composeCollapseGates(base: NestedActionsOverrides, gates: {
+    descendToBody: NonNullable<BlockEditActions['descendToBody']>;
+    moveFocus: FocusActions['moveFocus'];
+}): NestedActionsOverrides;
+/**
+ * The kind-command target a plugin container bubbles into `dispatchKindCommand`.
+ * `runCommand` is inert — a plugin container owns no built-in kind commands, so a
+ * chord resolves only through a registered one.
+ */
+export declare function buildContainerKindTarget(deps: Pick<ContainerBlockDeps, 'getNode' | 'commandHooks'>, updateOwnMetadata: ContainerBlock['updateOwnMetadata'], pluginEditor?: PluginEditorLookup): KindCommandTarget;
+export declare function createContainerBlock(deps: ContainerBlockDeps): ContainerBlock;