@voithos-labs/aragonite 0.10.1

package/dist/components/blocks/widget-portal.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The reuse pool that makes `component` inline widgets churn-safe. The editor rebuilds a block's
+ * whole inline-DOM on every keystroke; without a pool each rebuild remounts every widget's Svelte
+ * component, losing state and paying KaTeX-scale cost per character. Instances key by
+ * `${kind} ${source}`, and `mount`/`unmount` from 'svelte' stay contained here.
+ */
+import type { AnyInlineKind, InlineNode } from '../../core/nodes';
+import type { DocumentView } from '../../core/node-views';
+import type { PresentationMode } from '../../presentation-mode';
+export interface WidgetPoolAdapter<H> {
+    /** Build one instance, or null when it cannot be built (a caught mount throw). */
+    create(kind: AnyInlineKind, inline: InlineNode, source: string): H | null;
+    destroy(handle: H): void;
+    element(handle: H): HTMLElement;
+}
+export interface WidgetPool {
+    /**
+     * Adopt the oldest un-adopted live instance for the key, marking it adopted this
+     * pass; else build a new one. Render-pass only — every acquire sits inside a
+     * beginPass/sweep bracket. Key-only lookup cannot distinguish byte-identical
+     * duplicates, so an out-of-pass caller holding a specific element must restore it.
+     */
+    acquire(kind: AnyInlineKind, inline: InlineNode, source: string): HTMLElement | null;
+    /** Open a rebuild pass: un-adopt every instance so this pass re-earns them. */
+    beginPass(): void;
+    /** Close a rebuild pass: destroy every instance not adopted in it. */
+    sweep(): void;
+    /** Destroy everything — the block is unmounting. */
+    dispose(): void;
+}
+export declare function createWidgetPool<H>(adapter: WidgetPoolAdapter<H>): WidgetPool;
+/** The live channels a mounted widget reads beside its frozen `{ inline, source }`
+ *  snapshot. Every member is optional so a bare harness can mount without a shell. */
+export interface SvelteWidgetPoolDeps {
+    /** A widget component's synchronous mount throw goes here (the editor's `error`
+     *  channel). Absent leaves the caller falling back to the raw span silently. */
+    reportError?: (error: unknown) => void;
+    getPresentationMode?: () => PresentationMode;
+    /** The editor's theme name — the mode read's sibling, for a widget whose body an
+     *  engine paints (its own colors, unreachable from CSS) rather than CSS styles. */
+    getTheme?: () => string;
+    getDocument?: () => DocumentView | undefined;
+    getContentVersion?: () => number;
+    /** The editor's navigation door, for a widget whose gesture jumps elsewhere in the
+     *  document. Absent in a bare harness. */
+    navigateTo?: (path: number[], offset?: number) => Promise<boolean>;
+}
+/**
+ * The pool wired to Svelte mounting. A synchronous mount throw is caught, reported and surfaced as
+ * null so the caller falls back to the raw span. The getters ride ALONGSIDE the frozen
+ * `{ inline, source }` snapshot as live props: reuse keys on `${kind} ${source}`, so an instance
+ * outlives a mode flip or an edit elsewhere that a frozen value would not.
+ */
+export declare function createSvelteWidgetPool(deps?: SvelteWidgetPoolDeps): WidgetPool;

package/dist/components/blocks/widget-portal.js

@@ -0,0 +1,136 @@
+/**
+ * The reuse pool that makes `component` inline widgets churn-safe. The editor rebuilds a block's
+ * whole inline-DOM on every keystroke; without a pool each rebuild remounts every widget's Svelte
+ * component, losing state and paying KaTeX-scale cost per character. Instances key by
+ * `${kind} ${source}`, and `mount`/`unmount` from 'svelte' stay contained here.
+ */
+import { mount, unmount } from 'svelte';
+import { getInlineWidgetComponent } from '../../core/inline/inline-widgets';
+import { tracePoolPass } from '../../debug/interaction-trace';
+import { assertInvariant } from '../../assert';
+import { checkPoolBracket } from '../../invariants/inline-transitions';
+export function createWidgetPool(adapter) {
+    // Multiset per `${kind} ${source}` key: two identical sources in one block are
+    // two entries in one bucket, each adopted at most once per pass.
+    const buckets = new Map();
+    // The acquire bracket (see WidgetPool.acquire) held as explicit state so a
+    // violation fires at this seam instead of surfacing as a widget leak (G1.25).
+    let passOpen = false;
+    // Per-pass adopt/build tallies for the interaction trace, recorded at sweep.
+    let passAdopt = 0;
+    let passBuild = 0;
+    function beginPass() {
+        assertInvariant('pool-bracket', () => checkPoolBracket(passOpen, 'beginPass'));
+        passOpen = true;
+        passAdopt = 0;
+        passBuild = 0;
+        for (const bucket of buckets.values()) {
+            for (const entry of bucket)
+                entry.adopted = false;
+        }
+    }
+    function acquire(kind, inline, source) {
+        assertInvariant('pool-bracket', () => checkPoolBracket(passOpen, 'acquire'));
+        const key = `${kind} ${source}`;
+        const bucket = buckets.get(key);
+        const reused = bucket?.find((entry) => !entry.adopted);
+        if (reused) {
+            reused.adopted = true;
+            passAdopt++;
+            // Source and rendered body are identical by key; only the widget's position
+            // may have shifted, so re-stamp the offsets cursor/selection reads.
+            const el = adapter.element(reused.handle);
+            el.dataset.sourceStart = String(inline.start);
+            el.dataset.sourceEnd = String(inline.end);
+            return el;
+        }
+        const handle = adapter.create(kind, inline, source);
+        if (handle === null)
+            return null;
+        passBuild++;
+        const entry = { handle, adopted: true };
+        if (bucket)
+            bucket.push(entry);
+        else
+            buckets.set(key, [entry]);
+        return adapter.element(handle);
+    }
+    function sweep() {
+        assertInvariant('pool-bracket', () => checkPoolBracket(passOpen, 'sweep'));
+        passOpen = false;
+        let destroyed = 0;
+        for (const [key, bucket] of [...buckets]) {
+            const survivors = [];
+            for (const entry of bucket) {
+                if (entry.adopted) {
+                    entry.adopted = false;
+                    survivors.push(entry);
+                }
+                else {
+                    adapter.destroy(entry.handle);
+                    destroyed++;
+                }
+            }
+            if (survivors.length)
+                buckets.set(key, survivors);
+            else
+                buckets.delete(key);
+        }
+        tracePoolPass(passAdopt, passBuild, destroyed);
+    }
+    function dispose() {
+        passOpen = false;
+        for (const bucket of buckets.values()) {
+            for (const entry of bucket)
+                adapter.destroy(entry.handle);
+        }
+        buckets.clear();
+    }
+    return { acquire, beginPass, sweep, dispose };
+}
+/**
+ * The pool wired to Svelte mounting. A synchronous mount throw is caught, reported and surfaced as
+ * null so the caller falls back to the raw span. The getters ride ALONGSIDE the frozen
+ * `{ inline, source }` snapshot as live props: reuse keys on `${kind} ${source}`, so an instance
+ * outlives a mode flip or an edit elsewhere that a frozen value would not.
+ */
+export function createSvelteWidgetPool(deps = {}) {
+    const { reportError, getPresentationMode, getTheme, getDocument, getContentVersion, navigateTo } = deps;
+    return createWidgetPool({
+        create(kind, inline, source) {
+            const component = getInlineWidgetComponent(kind);
+            if (!component)
+                return null;
+            const wrapper = document.createElement('span');
+            wrapper.dataset.inlineWidget = '';
+            wrapper.dataset.sourceStart = String(inline.start);
+            wrapper.dataset.sourceEnd = String(inline.end);
+            wrapper.setAttribute('contenteditable', 'false');
+            try {
+                const instance = mount(component, {
+                    target: wrapper,
+                    props: {
+                        inline,
+                        source,
+                        getPresentationMode,
+                        getTheme,
+                        getDocument,
+                        getContentVersion,
+                        navigateTo
+                    }
+                });
+                return { wrapper, instance };
+            }
+            catch (error) {
+                reportError?.(error);
+                return null;
+            }
+        },
+        destroy(handle) {
+            void unmount(handle.instance);
+        },
+        element(handle) {
+            return handle.wrapper;
+        }
+    });
+}

package/dist/components/built-in-blocks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in block component registrations, applied by an explicit `registerBuiltInBlocks()` call:
+ * the `sideEffects` allowlist names dist paths and so never covers the src specifiers this
+ * library imports from itself, leaving a bare side-effect import here droppable. Lives in
+ * `components/` rather than `schema/` so the schema layer keeps no downstream imports.
+ */
+export declare function registerBuiltInBlocks(): void;

package/dist/components/built-in-blocks.js

@@ -0,0 +1,77 @@
+/**
+ * Built-in block component registrations, applied by an explicit `registerBuiltInBlocks()` call:
+ * the `sideEffects` allowlist names dist paths and so never covers the src specifiers this
+ * library imports from itself, leaving a bare side-effect import here droppable. Lives in
+ * `components/` rather than `schema/` so the schema layer keeps no downstream imports.
+ */
+import { metadataOf } from '../core/nodes';
+import { defineBlockComponent, registerBlockComponent } from '../schema/block-component-registry';
+import { augmentBuiltin } from '../schema/block-kind-descriptor';
+import { registerBuiltInDescriptors } from '../schema/built-in-descriptors';
+import { augmentInlineWidgetKind } from '../core/inline/inline-widgets';
+import { registerLiveJoinSeamCleaner, registerLiveSplitRebalancer } from '../schema/inline-construct-policy';
+import { registerPasteSurface } from '../tree-operations/paste-surfaces';
+import { imageWidgetOnSelectedKey } from './image/image-widget-editing';
+import { cleanLiveJoinSeam } from './blocks/text/live-join-seam';
+import { rebalanceLiveSplit } from './blocks/text/live-split-rebalance';
+import TextEditableBlock from './blocks/text/TextEditableBlock.svelte';
+import CodeBlock from './blocks/code/CodeBlock.svelte';
+import ThematicBreakBlock from './blocks/ThematicBreakBlock.svelte';
+import BlockquoteBlock from './blocks/BlockquoteBlock.svelte';
+import ListBlock from './blocks/list/ListBlock.svelte';
+import TableBlock from './blocks/table/TableBlock.svelte';
+import { tableCellPasteSurface } from './blocks/table/table-cell-paste';
+import { tableCaretAtPoint } from './blocks/table/table-caret-at-point';
+import { tableDragHitTest } from './blocks/table/table-drag-hit-test';
+function headingExtraProps(node) {
+    const level = metadataOf(node, 'heading')?.level ?? 1;
+    return { blockClass: `heading-${level}` };
+}
+const textAsRawBlock = defineBlockComponent(TextEditableBlock, () => ({
+    blockClass: 'raw-block'
+}));
+// Idempotence guard, not a registry bypass: a dev-server re-eval resets it so
+// the register-once dev valve still replaces.
+let registered = false;
+export function registerBuiltInBlocks() {
+    if (registered)
+        return;
+    registered = true;
+    // Descriptors first — augmentBuiltin('table') below needs `table` registered.
+    registerBuiltInDescriptors();
+    registerBlockComponent('paragraph', defineBlockComponent(TextEditableBlock, () => ({ blockClass: 'paragraph-block' })));
+    registerBlockComponent('heading', defineBlockComponent(TextEditableBlock, headingExtraProps));
+    registerBlockComponent('setextHeading', defineBlockComponent(TextEditableBlock, headingExtraProps));
+    registerBlockComponent('thematicBreak', defineBlockComponent(ThematicBreakBlock));
+    registerBlockComponent('fencedCode', defineBlockComponent(CodeBlock));
+    registerBlockComponent('blockquote', defineBlockComponent(BlockquoteBlock));
+    registerBlockComponent('list', defineBlockComponent(ListBlock));
+    registerBlockComponent('table', defineBlockComponent(TableBlock));
+    // Raw-editable fallback for kinds with no rendered surface. tableRow/tableCell
+    // render inside TableBlock; these catch only orphans that reach BlockHost directly.
+    registerBlockComponent('indentedCode', textAsRawBlock);
+    registerBlockComponent('htmlBlock', textAsRawBlock);
+    registerBlockComponent('linkReferenceDefinition', textAsRawBlock);
+    registerBlockComponent('tableRow', textAsRawBlock);
+    registerBlockComponent('tableCell', textAsRawBlock);
+    registerBlockComponent('unrecognized', textAsRawBlock);
+    // tableCell is the one supportsInline kind with bespoke paste semantics, so it
+    // registers here and the default loop in paste/hooks.ts skips it — running both
+    // would let ordering silently revert cell paste to the plain inline default.
+    registerPasteSurface(tableCellPasteSurface);
+    // Table owns cell addressing, so it registers both point→cell hooks through the
+    // descriptor registry rather than the selection layer importing the component.
+    // Two hooks: a drag needs the exact hit and its decline, a caret the nearest cell.
+    augmentBuiltin('table', {
+        foreignDragHitTest: tableDragHitTest,
+        caretTargetAtPoint: tableCaretAtPoint
+    });
+    // Image resize is editor-layer behavior, so the core image kind stays data-only
+    // and gains its selected-key handler here, where the render layer is reachable.
+    augmentInlineWidgetKind('image', { onSelectedKey: imageWidgetOnSelectedKey });
+    // The split rebalancer and the join-seam cleaner need the inline parser and the render path,
+    // neither of which `tree-operations` may import, so the policy table holds the slots and this
+    // layer fills them.
+    registerLiveSplitRebalancer(rebalanceLiveSplit);
+    registerLiveJoinSeamCleaner(cleanLiveJoinSeam);
+}

package/dist/components/editor-root-clipboard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Editor-root clipboard routing: copy/cut/paste for an event that reached no block surface. A
+ * selection whose block hosts no text position leaves the native selection empty, so Chromium
+ * dispatches at `document.body`, where no per-block binding sees it. Reading-mode gates live at
+ * the arms each route calls into, not here.
+ */
+import type { BlockComponent } from '../block-component';
+import type { DocumentGetter, PasteImageHook } from '../editor-keys';
+import type { SelectionState } from '../selection/selection-state.svelte';
+import type { CrossBlockHandlers } from '../selection/cross-block/dispatch';
+import { type EditorEvents } from '../editor-events';
+export interface EditorRootClipboardDeps {
+    selection: SelectionState;
+    getDoc: DocumentGetter;
+    crossBlock: CrossBlockHandlers;
+    /** Required-nullable so this seam cannot silently skip the arm the block surfaces
+     *  run; `undefined` = no hook. */
+    onPasteImage: PasteImageHook | undefined;
+    events: EditorEvents;
+    /** The block owning the selected inline widget, or null when none is selected. */
+    getSelectedWidgetBlock(): BlockComponent | null;
+}
+export interface EditorRootClipboard {
+    /** `root` is the element the installing effect captured, not a live binding. */
+    handleCopy(event: ClipboardEvent, root: HTMLElement): void;
+    handleCut(event: ClipboardEvent, root: HTMLElement): void;
+    handlePaste(event: ClipboardEvent, root: HTMLElement): void;
+}
+export declare function createEditorRootClipboard(deps: EditorRootClipboardDeps): EditorRootClipboard;

package/dist/components/editor-root-clipboard.js

@@ -0,0 +1,105 @@
+/**
+ * Editor-root clipboard routing: copy/cut/paste for an event that reached no block surface. A
+ * selection whose block hosts no text position leaves the native selection empty, so Chromium
+ * dispatches at `document.body`, where no per-block binding sees it. Reading-mode gates live at
+ * the arms each route calls into, not here.
+ */
+import { claimsBodyChord } from '../active-editor';
+import { emitClipboardError } from '../editor-events';
+import { createImagePasteArm } from './paste-image-arm';
+import { writeCrossBlockCopy, writeCrossBlockCut } from '../selection/cross-block/clipboard';
+export function createEditorRootClipboard(deps) {
+    const crossDeps = {
+        selection: deps.selection,
+        getDoc: deps.getDoc,
+        crossBlock: deps.crossBlock
+    };
+    const imageArm = createImagePasteArm({
+        onPasteImage: deps.onPasteImage,
+        events: deps.events,
+        crossBlock: deps.crossBlock
+    });
+    /**
+     * The event landed nowhere: on this root, or on the body via the retarget above.
+     * Deliberately NOT "inside the root but not a block" — the search input and a
+     * host's header field are both inside and own their own clipboard. The body arm is
+     * claimant-scoped because the listener sees every editor on the page.
+     */
+    function landedNowhere(root, target) {
+        if (target === root)
+            return true;
+        return (target === null || target === root.ownerDocument.body) && claimsBodyChord(root);
+    }
+    /**
+     * Who owns an event that reached no block surface. `defaultPrevented` is the block surfaces'
+     * receipt: every arm of their shared clipboard skeleton prevents before it writes, and the one
+     * arm that declines to native is a collapsed cell caret, which is neither state below. Order
+     * decides nothing — widget selection and cross-block selection clear each other.
+     */
+    function targetOf(event, root) {
+        if (event.defaultPrevented)
+            return null;
+        if (!landedNowhere(root, event.target))
+            return null;
+        const block = deps.getSelectedWidgetBlock();
+        if (block)
+            return { arm: 'widget', block };
+        return deps.selection.isCrossBlock ? { arm: 'cross-block' } : null;
+    }
+    return {
+        handleCopy(event, root) {
+            const target = targetOf(event, root);
+            if (!target)
+                return;
+            if (target.arm === 'widget')
+                target.block.claimRootClipboard?.(event);
+            else
+                writeCrossBlockCopy(event, crossDeps);
+        },
+        handleCut(event, root) {
+            const target = targetOf(event, root);
+            if (!target)
+                return;
+            if (target.arm === 'widget')
+                target.block.claimRootClipboard?.(event);
+            else
+                void writeCrossBlockCut(event, crossDeps);
+        },
+        handlePaste(event, root) {
+            const target = targetOf(event, root);
+            if (!target)
+                return;
+            if (target.arm === 'widget')
+                target.block.claimRootClipboard?.(event);
+            else
+                void paste(event);
+        }
+    };
+    /**
+     * The image arm first, exactly as a block surface orders it: the root reaches this
+     * seam for a pure-image paste whenever the focus endpoint hosts no caret, and going
+     * straight to the cross-block arm discarded it for want of any `text/plain`.
+     */
+    async function paste(event) {
+        // Read the range synchronously with the event, while the cross-block arm still
+        // guarantees a selection — below the await, a read could only report nothing.
+        const rangeStartPath = deps.selection.start?.path.slice();
+        const images = imageArm.filesOf(event.clipboardData);
+        if (images.length === 0) {
+            await deps.crossBlock.handlePaste(event);
+            return;
+        }
+        // Prevent before awaiting the hook, as the surface skeleton does: the browser's
+        // own paste would otherwise fire during the import and inject DOM the CST never sees.
+        event.preventDefault();
+        const markdown = await imageArm.run(event, images);
+        if (markdown === null)
+            return;
+        // The selection collapsed mid-import, leaving an imported asset and no caret —
+        // the one landing this seam cannot supply, having no block surface to fall back on.
+        emitClipboardError(deps.events, {
+            error: new Error('imported image had no insertion point at the editor root; nothing inserted'),
+            ...(rangeStartPath ? { path: rangeStartPath } : {})
+        });
+    }
+}

package/dist/components/editor-root-keydown.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Editor-root chord routing: dispatch for keystrokes no mounted block consumed. Pure
+ * dispatch over live getters; the installing `$effect` stays in `Editor.svelte`.
+ *
+ * Arm order is load-bearing (pinned by `test/components/editor-root-keydown.test.ts`): search /
+ * Escape runs FIRST because the global-chord arm's focus gate is an unconditional
+ * early return, which would swallow a Mod+F pressed with the caret inside a block.
+ */
+import type { PluginEditorLookup } from '../editor-keys';
+import type { PluginActivation } from '../schema/plugin-activation';
+import type { PresentationMode } from '../presentation-mode';
+import type { SearchState } from '../search/search-state.svelte';
+import type { CrossBlockHandlers } from '../selection/cross-block/dispatch';
+import type { CommandErrorSink } from '../schema/block-commands';
+import type { KeybindingOverrideMap } from '../schema/keybinding-overrides';
+import { type GlobalCommandContext } from '../schema/commands';
+export interface EditorRootKeydownDeps {
+    /** Getters, never values: a capture freezes the reading-mode gate and the
+     *  override map at construction time. */
+    get searchBarEnabled(): boolean;
+    get mode(): PresentationMode;
+    /** One predicate, so the root Mod+H and the bar's chevron cannot diverge on when
+     *  the replace row may open. */
+    get canReplace(): boolean;
+    get keybindingOverrides(): KeybindingOverrideMap;
+    get isCrossBlock(): boolean;
+    search: SearchState;
+    history: GlobalCommandContext['history'];
+    pluginEditor: PluginEditorLookup;
+    /** The plugins this instance activated, so the root claims only its own plugins'
+     *  chords. `undefined` = every installed plugin. */
+    activation: PluginActivation | undefined;
+    onCommandError: CommandErrorSink;
+    crossBlock: Pick<CrossBlockHandlers, 'handleKeyDown'>;
+    /** True for nodes in the host's `header` slot: they sit inside `root.contains`
+     *  without being the editor's own content. */
+    isHostChrome(node: Node | null): boolean;
+    /** Snapshot the pre-search caret; the bar's close handler restores it. */
+    saveSearchRange(range: Range | null): void;
+    setReplaceExpanded(expanded: boolean): void;
+}
+export interface EditorRootKeydown {
+    /** `root` is the element the installing effect captured, not a live binding: a
+     *  teardown that nulled the component's reference must not reach here. */
+    handleKeyDown(event: KeyboardEvent, root: HTMLElement): void;
+}
+export declare function createEditorRootKeydown(deps: EditorRootKeydownDeps): EditorRootKeydown;

package/dist/components/editor-root-keydown.js

@@ -0,0 +1,88 @@
+/**
+ * Editor-root chord routing: dispatch for keystrokes no mounted block consumed. Pure
+ * dispatch over live getters; the installing `$effect` stays in `Editor.svelte`.
+ *
+ * Arm order is load-bearing (pinned by `test/components/editor-root-keydown.test.ts`): search /
+ * Escape runs FIRST because the global-chord arm's focus gate is an unconditional
+ * early return, which would swallow a Mod+F pressed with the caret inside a block.
+ */
+import { claimsBodyChord, isForeignTextEntry } from '../active-editor';
+import { isReservedUiChord, runGlobalChord } from '../schema/commands';
+import { eventToChord } from '../schema/keybindings';
+export function createEditorRootKeydown(deps) {
+    /**
+     * Search / Escape: focus inside this editor, or a search chord this instance
+     * claims. `claimsBodyChord` gives a lone editor Find/Replace page-wide while
+     * keeping a second mounted editor from stealing it. A foreign text-entry surface
+     * owns page-global Find while the user types in it, so the editor yields there.
+     */
+    function handleSearchChords(event, root, chord, active) {
+        if (!(root.contains(active) || (claimsBodyChord(root) && !isForeignTextEntry(active))))
+            return false;
+        if (deps.searchBarEnabled && chord && isReservedUiChord(chord)) {
+            event.preventDefault();
+            // Seed the query before open(): focusing the find input collapses the
+            // selection. The !isOpen guard keeps a repeat Mod+F from clobbering the
+            // saved pre-search caret with the collapsed one.
+            const selection = window.getSelection();
+            const selected = selection?.toString() ?? '';
+            if (!deps.search.isOpen) {
+                deps.saveSearchRange(selection && selection.rangeCount ? selection.getRangeAt(0).cloneRange() : null);
+            }
+            deps.setReplaceExpanded(chord === 'Mod+H' && deps.canReplace);
+            deps.search.open();
+            if (selected)
+                deps.search.setQuery(selected);
+            return true;
+        }
+        if (event.key === 'Escape' && deps.search.isOpen) {
+            event.preventDefault();
+            deps.search.close();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Undo/redo, plugin-global chords and cross-block motion fire only when no block holds focus:
+     * unlike the search chords, these collide with a focused outside element's native behavior (a
+     * text input owns Mod+Z). The gap caret's proxy is focused DOM of its own and resolves the same
+     * chords at the target (`GapCaret.svelte`), so this arm stays out of its way.
+     */
+    function ownsWindowedOutCaret(root, active) {
+        const noElementFocused = active === null || active === root.ownerDocument.body;
+        return active === root || (noElementFocused && claimsBodyChord(root));
+    }
+    return {
+        handleKeyDown(event, root) {
+            // Normalizes the key (CapsLock uppercases e.key without Shift), matching
+            // every other chord-dispatch site.
+            const chord = eventToChord(event);
+            const active = root.ownerDocument.activeElement;
+            // Host chrome owns its own keystrokes whole. The yield lives at the dispatch
+            // entry rather than in each arm; `isForeignTextEntry` can't answer it, since
+            // it means "outside every mounted editor" and the slot is inside one.
+            if (deps.isHostChrome(active))
+                return;
+            if (handleSearchChords(event, root, chord, active))
+                return;
+            if (!ownsWindowedOutCaret(root, active))
+                return;
+            // No block is focused here, so resolve at global scope — override tier included, or a
+            // consumer's global rebind would be dead at this surface alone. The seam carries the
+            // reading gate and answers whether the press was consumed.
+            if (chord &&
+                runGlobalChord(chord, deps.keybindingOverrides, {
+                    isReading: deps.mode === 'reading',
+                    history: deps.history,
+                    pluginEditor: deps.pluginEditor,
+                    activation: deps.activation,
+                    onCommandError: deps.onCommandError
+                })) {
+                event.preventDefault();
+                return;
+            }
+            if (deps.isCrossBlock)
+                void deps.crossBlock.handleKeyDown(event);
+        }
+    };
+}

package/dist/components/editor-root-listeners.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Editor-root ambient listeners: the mod-active cursor tracker, the selectionchange
+ * bridge, and the viewport-height watcher. Pure dispatch over live getters; each
+ * installing `$effect` stays in `Editor.svelte` as a guard plus one install call,
+ * returning the teardown. `onRoot`/`removeAll` capture that add/remove pair once.
+ */
+import type { UserScrollport } from '../cursor/scroll-ancestors';
+export declare function onRoot<E extends Event>(target: EventTarget, type: string, handler: (event: E) => void, options?: {
+    capture?: boolean;
+    passive?: boolean;
+}): () => void;
+export declare function removeAll(...removers: (() => void)[]): () => void;
+/**
+ * Only Ctrl/Cmd+click activates a link, so CSS switches links to a pointer cursor
+ * off `data-mod-active`. Reset on blur and visibility loss, or a modifier released
+ * while the page is unfocused sticks the cursor on.
+ */
+export declare function installModActiveTracker(root: HTMLElement): () => void;
+export interface SelectionChangeBridgeDeps {
+    /** The element the installing effect captured, not a live binding. */
+    root: HTMLElement;
+    /** Live predicate, never a capture: the header slot can mount after install. */
+    isHostChrome(node: Node | null): boolean;
+    /** Emits this editor's current selection snapshot, read at event time. */
+    emit(): void;
+}
+/**
+ * Single-block caret motion never goes through SelectionState, so without this
+ * bridge subscribers miss every intra-block move. Scoped to `root` to avoid noise
+ * from selections elsewhere on the page.
+ */
+export declare function installSelectionChangeBridge(deps: SelectionChangeBridgeDeps): () => void;
+/**
+ * A focus departure is a selection change no browser channel reports: the native range can
+ * survive unfocused while the editor's own read goes null, so the channel announces it. Judged
+ * after the flush, never at focusout: a structural commit unmounts the focused surface and
+ * lands focus again after its own tick, and a departure that came back is no departure.
+ */
+export declare function installEditorBlurAnnouncer(deps: {
+    root: HTMLElement;
+    emit: () => void;
+}): () => void;
+/** Calls `bump` on a height change of the resolved scrollport `target`. */
+export declare function installViewportHeightWatcher(target: UserScrollport, bump: () => void): () => void;