@voithos-labs/aragonite 0.10.1

package/dist/editor-actions/table-context.js

@@ -0,0 +1,292 @@
+/**
+ * The TableContext mutation bundle. The component keeps sticky-column state,
+ * focused-cell tracking, DOM helpers, and BlockComponent — only structural mutations
+ * live here.
+ */
+import { metadataOf } from '../core/nodes';
+import { extendDocPath, docPathFrom } from '../cursor/coordinate-spaces';
+import { getStateForNode } from '../reactivity/state-registry';
+import { assertInvariant } from '../assert';
+import { columnAligned, COLUMN_ALIGNMENT_CLEARED, DELETED_COLUMN, DELETED_ROW, INSERTED_COLUMN, INSERTED_ROW, movedColumnToPosition, movedRowToPosition } from '../a11y-strings';
+import { ensureUnsharedChildren } from '../tree-operations/unshare';
+import { rebuildTableRowRaw, rebuildTableRaw } from '../schema/container-rebuilders';
+import { reorderChildren } from '../tree-operations/reorder';
+import { insertEmptyRow, insertEmptyColumn, deleteRow as mutDeleteRow, deleteColumn as mutDeleteColumn, moveColumn as mutMoveColumn, cycleAlignment as mutCycleAlignment, setAlignment as mutSetAlignment, canDeleteRow, canDeleteColumn } from '../tree-operations/table-mutations';
+/**
+ * The header (row 0) is positionally fixed. Null skips the commit, so a boundary
+ * press pushes no undo entry.
+ */
+export function tableRowReorderTarget(rowIdx, dir, rowCount) {
+    if (rowIdx === 0)
+        return null;
+    const to = rowIdx + dir;
+    if (to < 1 || to > rowCount - 1)
+        return null;
+    return to;
+}
+/**
+ * Unlike rows, columns have no fixed header, so every index is a valid source and
+ * target and clamping spans the full range.
+ */
+export function tableColumnReorderTarget(colIdx, dir, colCount) {
+    const to = colIdx + dir;
+    if (to < 0 || to > colCount - 1)
+        return null;
+    return to;
+}
+export function createTableMutationsContext(deps) {
+    async function insertRow(rowIdx, side) {
+        const { node, myPath, rowsState, parentContainerEdit, focusCell } = deps;
+        const insertAt = side === 'above' ? rowIdx : rowIdx + 1;
+        await parentContainerEdit.commitContainer({
+            containerNode: node,
+            path: [...myPath],
+            state: rowsState,
+            snapshot: { path: extendDocPath(myPath, rowIdx), offset: 0 },
+            mutate: (scope) => {
+                insertEmptyRow(scope.node, rowIdx, side);
+                scope.sharing.stamp(scope.children[insertAt]);
+                rebuildTableRowRaw(scope.children[insertAt]);
+                return { op: 'insert', at: insertAt, count: 1 };
+            },
+            op: {
+                kind: 'tableInsertRow',
+                detail: { rowIdx, side },
+                eventPath: extendDocPath(myPath, insertAt)
+            },
+            afterTick: () => {
+                focusCell(insertAt, 0, 'start');
+                deps.announceReorder(INSERTED_ROW);
+            }
+        });
+    }
+    /**
+     * The table scope plus one per MOUNTED row: a row's BlockListState registers on
+     * mount, so scoping a windowed-out row throws and takes the gesture with it. The
+     * bytes still reach every row, through the table scope.
+     */
+    function mountedColumnScopes() {
+        const { node, myPath, rowsState } = deps;
+        const scopes = [{ node, state: rowsState, path: [...myPath] }];
+        const rowIndices = [];
+        (node.children ?? []).forEach((row, i) => {
+            const state = getStateForNode(row);
+            if (!state)
+                return;
+            scopes.push({ node: row, state, path: [...myPath, i] });
+            rowIndices.push(i);
+        });
+        return { scopes, rowIndices };
+    }
+    async function commitColumnEdit(opts) {
+        const { myPath, controller } = deps;
+        const { scopes, rowIndices } = mountedColumnScopes();
+        await controller.commitMultiScope({
+            scopes,
+            // Columns aren't nodes: the table itself is the restore coordinate.
+            snapshot: { path: docPathFrom(myPath), offset: 0 },
+            mutate: ([tableScope, ...rowScopes]) => {
+                // Reaches the windowed-out rows the scopes skip, so the per-row cell splice
+                // below never writes through a snapshot-shared row (G1.9).
+                ensureUnsharedChildren(tableScope.node, tableScope.sharing);
+                // The splice walks the owned table's rows, so the row scopes' ids/refs only
+                // sync correctly while each row view IS the child at the index it covers.
+                assertInvariant('column-scope-alignment', () => rowScopes.every((s, i) => s.node === tableScope.node.children?.[rowIndices[i]])
+                    ? null
+                    : {
+                        code: 'column-scope-alignment',
+                        message: 'commitColumnEdit: row scopes misaligned with owned table children'
+                    });
+                // One change per row, in row order — pair the mounted rows with theirs.
+                const perRow = opts.mutateColumns(tableScope.node);
+                return [{ op: 'noop' }, ...rowIndices.map((i) => perRow[i])];
+            },
+            op: { ...opts.op, eventPath: docPathFrom(myPath) },
+            afterTick: opts.afterTick
+        });
+    }
+    async function insertColumn(colIdx, side) {
+        const { focusCell, focusedCell } = deps;
+        const insertAt = side === 'left' ? colIdx : colIdx + 1;
+        await commitColumnEdit({
+            mutateColumns: (table) => insertEmptyColumn(table, colIdx, side),
+            op: { kind: 'tableInsertColumn', detail: { colIdx, side } },
+            afterTick: () => {
+                const targetRow = focusedCell?.rowIdx ?? 0;
+                focusCell(targetRow, insertAt, 'start');
+                deps.announceReorder(INSERTED_COLUMN);
+            }
+        });
+    }
+    async function reorderRowTo(from, to) {
+        if (from === to)
+            return;
+        const { node, myPath, rowsState, parentContainerEdit, focusCell, focusedCell } = deps;
+        const rowCount = node.children?.length ?? 0;
+        // Guard the SOURCE against the live count: a keyboard/menu/drag commit can carry
+        // a `from` staled by a concurrent structural edit. `to` is already clamped.
+        if (from < 0 || from >= rowCount)
+            return;
+        // focusout nulls focusedCell on the post-commit re-render, so capture the column
+        // now; the afterTick would otherwise land at column 0.
+        const col = focusedCell?.colIdx ?? 0;
+        await parentContainerEdit.commitContainer({
+            containerNode: node,
+            path: [...myPath],
+            state: rowsState,
+            snapshot: { path: extendDocPath(myPath, from), offset: 0 },
+            mutate: (scope) => {
+                // rebuildTableRaw rewrites EVERY row's raw, so the rows must be unshared
+                // first — reorderChildren only permutes references.
+                ensureUnsharedChildren(scope.node, scope.sharing);
+                const change = reorderChildren(scope.node.children, from, to);
+                rebuildTableRaw(scope.node);
+                return change;
+            },
+            op: { kind: 'tableReorderRow', detail: { from, to }, eventPath: extendDocPath(myPath, to) },
+            afterTick: () => {
+                focusCell(to, col, 'start');
+                deps.announceReorder(movedRowToPosition(to, rowCount - 1));
+            }
+        });
+    }
+    async function moveRow(rowIdx, dir) {
+        const rowCount = deps.node.children?.length ?? 0;
+        const to = tableRowReorderTarget(rowIdx, dir, rowCount);
+        if (to === null)
+            return;
+        await reorderRowTo(rowIdx, to);
+    }
+    async function reorderColumnTo(from, to) {
+        if (from === to)
+            return;
+        const { node, focusCell, focusedCell } = deps;
+        const columnCount = metadataOf(node, 'table').columnCount;
+        // Guard the SOURCE against the live count — see reorderRowTo.
+        if (from < 0 || from >= columnCount)
+            return;
+        // focusout nulls focusedCell on the post-commit re-render, so capture the row
+        // now; the afterTick would otherwise land at row 0.
+        const row = focusedCell?.rowIdx ?? 0;
+        await commitColumnEdit({
+            mutateColumns: (table) => mutMoveColumn(table, from, to),
+            op: { kind: 'tableReorderColumn', detail: { from, to } },
+            afterTick: () => {
+                focusCell(row, to, 'start');
+                deps.announceReorder(movedColumnToPosition(to + 1, columnCount));
+            }
+        });
+    }
+    async function moveColumn(colIdx, dir) {
+        const columnCount = metadataOf(deps.node, 'table').columnCount;
+        const to = tableColumnReorderTarget(colIdx, dir, columnCount);
+        if (to === null)
+            return;
+        await reorderColumnTo(colIdx, to);
+    }
+    return {
+        insertRowAbove: (rowIdx) => insertRow(rowIdx, 'above'),
+        insertRowBelow: (rowIdx) => insertRow(rowIdx, 'below'),
+        insertColumnLeft: (colIdx) => insertColumn(colIdx, 'left'),
+        insertColumnRight: (colIdx) => insertColumn(colIdx, 'right'),
+        reorderRowTo,
+        moveRowUp: (rowIdx) => moveRow(rowIdx, -1),
+        moveRowDown: (rowIdx) => moveRow(rowIdx, 1),
+        reorderColumnTo,
+        moveColumnLeft: (colIdx) => moveColumn(colIdx, -1),
+        moveColumnRight: (colIdx) => moveColumn(colIdx, 1),
+        async deleteRow(rowIdx) {
+            const { node, myPath, rowsState, parentContainerEdit, focusCell, focusedCell } = deps;
+            if (!canDeleteRow(rowIdx, node.children?.length ?? 0))
+                return;
+            await parentContainerEdit.commitContainer({
+                containerNode: node,
+                path: [...myPath],
+                state: rowsState,
+                snapshot: { path: extendDocPath(myPath, rowIdx), offset: 0 },
+                mutate: (scope) => {
+                    // deleteRow promotes the next row to header (a metadata write).
+                    ensureUnsharedChildren(scope.node, scope.sharing);
+                    mutDeleteRow(scope.node, rowIdx);
+                    return { op: 'delete', at: rowIdx, count: 1 };
+                },
+                op: {
+                    kind: 'tableDeleteRow',
+                    detail: { rowIdx },
+                    eventPath: extendDocPath(myPath, rowIdx)
+                },
+                afterTick: () => {
+                    deps.announceReorder(DELETED_ROW);
+                    // Read through `deps.node`: the captured `node` is the pre-commit object
+                    // the snapshot still shares, so its child count is stale after the delete.
+                    const newRowCount = deps.node.children?.length ?? 0;
+                    if (newRowCount === 0)
+                        return;
+                    const columnCount = metadataOf(deps.node, 'table').columnCount;
+                    const targetRow = Math.min(rowIdx, newRowCount - 1);
+                    const targetCol = focusedCell ? Math.min(focusedCell.colIdx, columnCount - 1) : 0;
+                    focusCell(targetRow, targetCol, 'start');
+                }
+            });
+        },
+        async deleteColumn(colIdx) {
+            const { node, focusCell, focusedCell } = deps;
+            const meta = metadataOf(node, 'table');
+            if (!canDeleteColumn(meta.columnCount))
+                return;
+            await commitColumnEdit({
+                mutateColumns: (table) => mutDeleteColumn(table, colIdx),
+                op: { kind: 'tableDeleteColumn', detail: { colIdx } },
+                afterTick: () => {
+                    deps.announceReorder(DELETED_COLUMN);
+                    // deps.node, not the stale pre-commit capture — see deleteRow.
+                    const newColumnCount = metadataOf(deps.node, 'table').columnCount;
+                    if (newColumnCount === 0)
+                        return;
+                    const targetCol = Math.min(colIdx, newColumnCount - 1);
+                    const targetRow = focusedCell?.rowIdx ?? 0;
+                    focusCell(targetRow, targetCol, 'start');
+                }
+            });
+        },
+        async cycleAlignment(colIdx) {
+            const { node, myPath, rowsState, parentContainerEdit } = deps;
+            // Distinct OperationKind so consumers can count alignment cycles apart from
+            // metadata edits. The event targets the TABLE: a column index is not a path.
+            await parentContainerEdit.commitContainer({
+                containerNode: node,
+                path: [...myPath],
+                state: rowsState,
+                snapshot: { path: docPathFrom(myPath), offset: 0 },
+                mutate: (scope) => {
+                    mutCycleAlignment(scope.node, colIdx);
+                    return { op: 'noop' };
+                },
+                op: { kind: 'tableCycleAlignment', detail: { colIdx }, eventPath: docPathFrom(myPath) }
+            });
+        },
+        async setColumnAlignment(colIdx, alignment) {
+            const { node, myPath, rowsState, parentContainerEdit, focusCell, focusedCell } = deps;
+            // Capture before the menu's focusout nulls it: the alignment button unmounts
+            // on commit, so without a refocus the caret falls to <body>.
+            const cell = focusedCell;
+            // Commits unconditionally: the first table mutation also normalizes cell
+            // padding, so a same-value set is not a byte no-op.
+            await parentContainerEdit.commitContainer({
+                containerNode: node,
+                path: [...myPath],
+                state: rowsState,
+                snapshot: { path: docPathFrom(myPath), offset: 0 },
+                mutate: (scope) => {
+                    mutSetAlignment(scope.node, colIdx, alignment);
+                    return { op: 'noop' };
+                },
+                op: { kind: 'tableSetAlignment', detail: { colIdx }, eventPath: docPathFrom(myPath) },
+                afterTick: () => {
+                    focusCell(cell?.rowIdx ?? 0, colIdx, 'start');
+                    deps.announceReorder(alignment === 'none' ? COLUMN_ALIGNMENT_CLEARED : columnAligned(alignment));
+                }
+            });
+        }
+    };
+}

package/dist/editor-actions/unwrap-strategies.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unwrap strategy implementations, selected by a container's declared
+ * `unwrapRole` (schema/block-kind-descriptor.ts) from the nested blockEdit
+ * dispatcher.
+ */
+import type { UnwrapRole } from '../schema/block-kind-descriptor';
+import type { BlockListState } from '../reactivity/block-list-state.svelte';
+import type { NestedActionsDeps } from './nested/nested-actions';
+export interface UnwrapStrategyDeps {
+    deps: NestedActionsDeps;
+    state: BlockListState;
+}
+export declare const firstChildUnwrapStrategies: Record<UnwrapRole['firstChildBackspace'], (deps: UnwrapStrategyDeps) => Promise<void>>;
+export declare const middleChildUnwrapStrategies: Record<'list-item-cascade', (deps: UnwrapStrategyDeps, innerIndex: number) => Promise<void>>;

package/dist/editor-actions/unwrap-strategies.js

@@ -0,0 +1,131 @@
+/**
+ * Unwrap strategy implementations, selected by a container's declared
+ * `unwrapRole` (schema/block-kind-descriptor.ts) from the nested blockEdit
+ * dispatcher.
+ */
+import { CURSOR_END, CURSOR_START } from '../block-component';
+import { deleteNode as performDelete, unwrapFirstItemFromList, unwrapFirstChildFromQuote, liftFirstChildKeepingContainer, mergeListItemIntoPrevious, renumberOrderedList, isItemUserEmpty } from '../tree-operations';
+import { mergedElseFocusPrevious } from './merge-fallback';
+import { scopeParentOf } from './block-edit-scope';
+import { extendDocPath } from '../cursor/coordinate-spaces';
+/** Drop a user-empty item and renumber from its slot; `land` seats the caret the strategy chose. */
+async function deleteEmptyItem({ deps, state }, itemIndex, land) {
+    await deps.parent.containerEdit.commitContainer({
+        containerNode: deps.node,
+        path: deps.path,
+        state,
+        snapshot: { path: extendDocPath(deps.path, itemIndex), offset: 0 },
+        mutate: (scope) => {
+            const change = performDelete(scopeParentOf(scope), itemIndex, scope.sharing);
+            renumberOrderedList(scope.node, itemIndex, scope.sharing);
+            return change;
+        },
+        op: { kind: 'delete', eventPath: extendDocPath(deps.path, itemIndex) },
+        afterTick: land
+    });
+}
+// ── First-child strategies ──────────────────────────────────────────────────
+/** Rule U2 for the quote shape: the opener lives on the first line, so the lift drops it. */
+async function liftFirstChildDroppingOpener({ deps }) {
+    await spliceLift(deps, unwrapFirstChildFromQuote(deps.node));
+}
+/** Rule U2 for a container whose syntax survives the lift: the remainder keeps its kind. */
+async function liftFirstChildAndKeepContainer({ deps }) {
+    await spliceLift(deps, liftFirstChildKeepingContainer(deps.node));
+}
+/** Rule U2's declared decline: child 0 is the container's chrome, and a lift would carry it out. */
+async function keepReservedChrome() { }
+async function spliceLift(deps, replacement) {
+    if (replacement.length === 0)
+        return;
+    await deps.parent.blockEdit.replaceBlock(deps.index, replacement, {
+        replacementIndex: 0,
+        offset: 0
+    });
+}
+/** List first-item cascade: nested promote / empty delete / empty-sole delete-list / Rule U1. */
+async function listItemCascadeFirst(strategy) {
+    const { deps, state } = strategy;
+    const node = deps.node;
+    const index = deps.index;
+    if (!node.children)
+        return;
+    if (deps.parentListContext) {
+        await deps.parentListContext.promoteNestedItem(deps.parentListContext.getContainingItemIndex(), node, 0);
+        return;
+    }
+    const item = node.children[0];
+    const firstChildEmpty = isItemUserEmpty(item);
+    if (firstChildEmpty && node.children.length > 1) {
+        await deleteEmptyItem(strategy, 0, () => {
+            state.innerBlockRefs[0]?.focus(CURSOR_START);
+        });
+    }
+    else if (firstChildEmpty && node.children.length === 1) {
+        await deps.parent.blockEdit.deleteBlock(index);
+        await deps.parent.focus.moveFocus(index - 1, 'end');
+    }
+    else {
+        const replacement = unwrapFirstItemFromList(node);
+        if (replacement.length === 0)
+            return;
+        await deps.parent.blockEdit.replaceBlock(index, replacement, {
+            replacementIndex: 0,
+            offset: 0
+        });
+    }
+}
+// ── Middle-child strategies ─────────────────────────────────────────────────
+/** List middle-item: empty delete+renumber, else Rule M1 merge into deepest text above. */
+async function listItemCascadeMiddle(strategy, itemIndex) {
+    const { deps, state } = strategy;
+    const node = deps.node;
+    if (!node.children)
+        return;
+    const item = node.children[itemIndex];
+    if (isItemUserEmpty(item)) {
+        await deleteEmptyItem(strategy, itemIndex, () => {
+            state.innerBlockRefs[itemIndex - 1]?.focus(CURSOR_END);
+        });
+        return;
+    }
+    // Rule M1: merge into the deepest visible text above. An opaque prev leaf gives
+    // the merge no target, so the tree stays put and the caret falls back.
+    let mergePoint = null;
+    await deps.parent.containerEdit.commitContainer({
+        containerNode: node,
+        path: deps.path,
+        state,
+        snapshot: { path: extendDocPath(deps.path, itemIndex), offset: 0 },
+        mutate: (scope) => {
+            const result = mergeListItemIntoPrevious(scope.node, scope.children, itemIndex, scope.sharing, deps.getPresentationMode?.(), deps.linkRef);
+            mergePoint = result?.mergePoint ?? null;
+            return mergePoint ? { op: 'delete', at: itemIndex, count: 1 } : { op: 'noop' };
+        },
+        op: {
+            kind: 'merge',
+            detail: { direction: 'prev' },
+            eventPath: extendDocPath(deps.path, itemIndex)
+        },
+        afterTick: () => {
+            const merged = mergedElseFocusPrevious(mergePoint, state.innerBlockRefs[itemIndex - 1]);
+            if (!merged)
+                return;
+            const [firstPathIdx, ...restPath] = merged.targetPath;
+            state.innerBlockRefs[firstPathIdx]?.focusByPath?.(restPath, merged.offset);
+        },
+        // A no-target merge changes nothing; discard the entry but keep afterTick,
+        // which still lands the caret.
+        discardIfNoop: true
+    });
+}
+// ── Registries (selected by UnwrapRole names) ───────────────────────────────
+export const firstChildUnwrapStrategies = {
+    'lift-first-child-drop-opener': liftFirstChildDroppingOpener,
+    'lift-first-child-keep-container': liftFirstChildAndKeepContainer,
+    'keep-reserved-chrome': keepReservedChrome,
+    'list-item-cascade': listItemCascadeFirst
+};
+export const middleChildUnwrapStrategies = {
+    'list-item-cascade': listItemCascadeMiddle
+};

package/dist/editor-actions/whole-block-focus-surface.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The focus surface of a block that IS its own focus target, and the hidden editing host beside
+ * it. Such a block has no editing surface of its own, so `beforeinput` and `compositionend` —
+ * the only doors AltGr productions and IME composition arrive through — fire nowhere. The proxy
+ * is that host. It mounts in the block's BOX, never in the declared focus element, which a
+ * render swap replaces.
+ */
+/** The hidden host looks exactly like a plugin's own editable; this is what tells them apart. */
+export declare const WHOLE_BLOCK_INPUT_ATTR = "data-whole-block-input";
+export declare function isWholeBlockInputProxy(target: EventTarget | null): boolean;
+/**
+ * A key originating in a plugin's own text-editing surface belongs to that surface, never the
+ * whole-block affordances: Backspace inside an edit textarea edits text. The hidden host is
+ * excluded here rather than at each gate, so a later reader cannot forget it.
+ */
+export declare function isEditableEventTarget(target: EventTarget | null): boolean;
+/**
+ * The hidden host is the block's ONE tab stop, so a declared surface that is not itself an
+ * editing host leaves the tab order (editor.md § 8). Applied on every read rather than once at
+ * mount: a kind's declared element is whatever its current render state supplies, and the state
+ * that appears after mount would otherwise keep its stop. Inverse of `focusWholeBlockEl`, which
+ * only ever MINTS focusability on a box that has none.
+ */
+export declare function demoteDeclaredFromTabOrder(declared: HTMLElement | null): HTMLElement | null;
+/**
+ * The class guard behind `getFocusEl`: an absent declared element degrades to the
+ * focusable box, never a silent no-op that strands the caret. The one legitimate null
+ * survives — a plugin-owned editable inside the box holding focus.
+ */
+export declare function composeWholeBlockFocusSurface(getFocusEl: () => HTMLElement | null | undefined, getBoxEl: () => HTMLElement | null | undefined, getKind: () => string): () => HTMLElement | null;
+export declare function focusWholeBlockEl(el: HTMLElement): void;
+/** Whole-block focus sits on the declared surface OR on the hidden host beside it. */
+export declare function holdsWholeBlockFocus(declared: HTMLElement | null | undefined, proxy: HTMLElement | null | undefined): boolean;
+export interface WholeBlockInputProxyDeps {
+    /** The chrome box: stable across the render swaps that replace a declared focus element. */
+    getBoxEl: () => HTMLElement | null | undefined;
+    /** The kind's declared surface. An editable one is the plugin's own caret host and keeps
+     *  focus for itself. */
+    getFocusEl: () => HTMLElement | null | undefined;
+    isReading: () => boolean;
+    /** Commit the bytes the host produced — the keydown tail's mint, through another door. */
+    mint: (text: string) => void;
+}
+export interface WholeBlockInputProxy {
+    /** The mounted host, or null while the block has no box. */
+    el(): HTMLElement | null;
+    /** Land DOM focus for a whole-block entry, degrading to `declared` when the plugin owns
+     *  the caret or the host has not mounted. */
+    focus(declared: HTMLElement): void;
+}
+export declare function createWholeBlockInputProxy(deps: WholeBlockInputProxyDeps): WholeBlockInputProxy;

package/dist/editor-actions/whole-block-focus-surface.js

@@ -0,0 +1,171 @@
+/**
+ * The focus surface of a block that IS its own focus target, and the hidden editing host beside
+ * it. Such a block has no editing surface of its own, so `beforeinput` and `compositionend` —
+ * the only doors AltGr productions and IME composition arrive through — fire nowhere. The proxy
+ * is that host. It mounts in the block's BOX, never in the declared focus element, which a
+ * render swap replaces.
+ */
+import { onMount } from 'svelte';
+import { WHOLE_BLOCK_INPUT_LABEL } from '../a11y-strings';
+import { devWarn } from '../dev-warn';
+// ── Editable-target guards ───────────────────────────────────────────────────
+/** The hidden host looks exactly like a plugin's own editable; this is what tells them apart. */
+export const WHOLE_BLOCK_INPUT_ATTR = 'data-whole-block-input';
+export function isWholeBlockInputProxy(target) {
+    return target instanceof Element && target.hasAttribute(WHOLE_BLOCK_INPUT_ATTR);
+}
+/**
+ * A key originating in a plugin's own text-editing surface belongs to that surface, never the
+ * whole-block affordances: Backspace inside an edit textarea edits text. The hidden host is
+ * excluded here rather than at each gate, so a later reader cannot forget it.
+ */
+export function isEditableEventTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    if (isWholeBlockInputProxy(target))
+        return false;
+    const tag = target.tagName;
+    return tag === 'TEXTAREA' || tag === 'INPUT' || target.isContentEditable;
+}
+// ── Tab order ────────────────────────────────────────────────────────────────
+/**
+ * The hidden host is the block's ONE tab stop, so a declared surface that is not itself an
+ * editing host leaves the tab order (editor.md § 8). Applied on every read rather than once at
+ * mount: a kind's declared element is whatever its current render state supplies, and the state
+ * that appears after mount would otherwise keep its stop. Inverse of `focusWholeBlockEl`, which
+ * only ever MINTS focusability on a box that has none.
+ */
+export function demoteDeclaredFromTabOrder(declared) {
+    if (declared && declared.tabIndex >= 0 && !isEditableEventTarget(declared)) {
+        declared.tabIndex = -1;
+    }
+    return declared;
+}
+/**
+ * The class guard behind `getFocusEl`: an absent declared element degrades to the
+ * focusable box, never a silent no-op that strands the caret. The one legitimate null
+ * survives — a plugin-owned editable inside the box holding focus.
+ */
+export function composeWholeBlockFocusSurface(getFocusEl, getBoxEl, getKind) {
+    let warned = false;
+    return () => {
+        const declared = getFocusEl();
+        if (declared)
+            return demoteDeclaredFromTabOrder(declared);
+        const box = getBoxEl();
+        if (!box)
+            return null;
+        const active = document.activeElement;
+        if (isEditableEventTarget(active) && box.contains(active))
+            return null;
+        if (!warned) {
+            warned = true;
+            devWarn('container-block', `whole-block kind "${getKind()}" supplied no focus element for this state; falling back to the box`);
+        }
+        return box;
+    };
+}
+// The degraded path's own policy, and the inverse of the demotion above: the fallback box is a
+// plain div, focusable only once a tabindex is minted. A surface already focusable keeps whatever
+// it has — this door only ever adds reachability, never removes it.
+export function focusWholeBlockEl(el) {
+    if (el.tabIndex < 0 && !el.hasAttribute('tabindex'))
+        el.tabIndex = -1;
+    el.focus();
+}
+/** Whole-block focus sits on the declared surface OR on the hidden host beside it. */
+export function holdsWholeBlockFocus(declared, proxy) {
+    const active = document.activeElement;
+    return !!(declared?.contains(active) || (proxy && proxy === active));
+}
+export function createWholeBlockInputProxy(deps) {
+    let proxy = null;
+    let composing = false;
+    /** Every read of the declared surface inside the proxy goes through the demotion, so a kind
+     *  supplying its own `getFocusEl` (no composed surface) is held to the rule too. */
+    const declaredSurface = () => demoteDeclaredFromTabOrder(deps.getFocusEl() ?? null);
+    function mint(text) {
+        if (!deps.isReading())
+            deps.mint(text);
+    }
+    function onBeforeInput(event) {
+        // The browser owns the host between compositionstart and compositionend (the editor's
+        // standing IME stance) — refusing here swallows the composition.
+        if (composing)
+            return;
+        event.preventDefault();
+        if (event.inputType === 'insertText' && event.data)
+            mint(event.data);
+    }
+    function onCompositionEnd() {
+        composing = false;
+        const composed = proxy?.textContent ?? '';
+        // A caret host, never a surface a serializer reads: whatever the IME left belongs to the
+        // minted paragraph, and the host goes back to empty either way.
+        if (proxy)
+            proxy.textContent = '';
+        if (composed)
+            mint(composed);
+    }
+    // A pointer or a Tab lands natively on the kind's own surface, where no beforeinput fires;
+    // without this hand-off the first character after a click is keydown-minted again.
+    function onFocusIn(event) {
+        // Read before the identity test, so an arrival ANYWHERE in the box (the host's own included)
+        // re-applies the demotion to whatever surface the current render state supplies — which is
+        // what puts it out of the tab order before the next press, not after it.
+        if (!proxy || event.target !== declaredSurface())
+            return;
+        if (isEditableEventTarget(event.target))
+            return;
+        // The host's own Shift+Tab lands here on its way out; bouncing it back would trap focus
+        // in the block. Every other arrival is passed on — a toolbar button included, or the
+        // click after one leaves the declared surface holding focus and drops IME again.
+        if (event.relatedTarget === proxy)
+            return;
+        focusProxy();
+    }
+    function focusProxy() {
+        if (!proxy)
+            return;
+        // Read per focus, not per mount: reading mode writes no bytes, so its host is inert.
+        proxy.setAttribute('contenteditable', deps.isReading() ? 'false' : 'true');
+        proxy.focus();
+    }
+    onMount(() => {
+        const box = deps.getBoxEl();
+        if (!box)
+            return;
+        proxy = document.createElement('div');
+        proxy.setAttribute(WHOLE_BLOCK_INPUT_ATTR, '');
+        proxy.className = 'whole-block-input';
+        proxy.setAttribute('contenteditable', deps.isReading() ? 'false' : 'true');
+        proxy.setAttribute('role', 'textbox');
+        proxy.setAttribute('aria-label', WHOLE_BLOCK_INPUT_LABEL);
+        proxy.spellcheck = false;
+        // The block's tab stop, because focus belongs here: a declared surface left in the tab
+        // order is a second stop the backward tab parks on, where no input door exists.
+        proxy.tabIndex = 0;
+        declaredSurface();
+        proxy.addEventListener('beforeinput', onBeforeInput);
+        proxy.addEventListener('compositionstart', () => (composing = true));
+        proxy.addEventListener('compositionend', onCompositionEnd);
+        box.addEventListener('focusin', onFocusIn);
+        box.appendChild(proxy);
+        return () => {
+            box.removeEventListener('focusin', onFocusIn);
+            proxy?.remove();
+            proxy = null;
+        };
+    });
+    return {
+        el: () => proxy,
+        focus(declared) {
+            if (!proxy || isEditableEventTarget(declared)) {
+                focusWholeBlockEl(declared);
+                return;
+            }
+            demoteDeclaredFromTabOrder(declared);
+            focusProxy();
+        }
+    };
+}