@voithos-labs/aragonite 0.10.4 → 0.10.7

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

@@ -0,0 +1,189 @@
+/**
+ * Editor-root pointer gestures: clicks in priority order (the link card, link activation, the
+ * caret for empty space, a block's own box), the margin drag the browser cannot start from a
+ * non-editable element, multi-click selection, and where a right-click leaves the caret.
+ */
+import { placeContextPress, resetForPointerDown } from '../selection/cross-block/pointer';
+import { createDeadSpaceCaret } from '../selection/dead-space-caret';
+import { installDragListener } from '../selection/drag-pointer';
+import { installMultiClickSelect } from '../selection/multi-click';
+import { findSurfacePathForElement } from '../selection/path-lookup';
+import { claimsPointerGesture } from '../selection/pointer-gesture';
+import { isBlockNode, nodeAt } from '../tree-operations/node-primitives';
+import { widgetSourceRange } from '../core/inline/inline-widgets';
+import { LINK_ELEMENT_SELECTOR, resolveLinkAtPoint } from './blocks/text/link-at-point';
+import { onRoot, removeAll } from './editor-root-listeners';
+// Empty space and a block's non-editable parts (a rendered equation, a diagram, a whole-block
+// input proxy) grow no native selection, so the editor runs the drag from there.
+const NOT_A_DRAG_START = '[contenteditable="true"]:not([data-whole-block-input]), ' +
+    'button:not(.editor-tail-row), input, textarea, select, a, summary, [role="checkbox"], ' +
+    '.code-rail, .table-add-zone, .md-menu, .block-drag-handle';
+const DRAG_SLOP_PX = 3;
+export function createRootGestures(deps) {
+    const deadSpaceCaret = createDeadSpaceCaret({
+        getBlockComponent: (path) => deps.getBlockComponent(path),
+        resetSelectionForClick: () => resetForPointerDown(deps.selection, deps.caretMemory, false),
+        gapScope: {
+            getDoc: deps.getDoc,
+            selection: deps.selection,
+            getPresentationMode: deps.reading.mode
+        },
+        lastBlockIndex: () => deps.getDoc().children.length - 1,
+        land: (pos) => deps.land(pos)
+    });
+    function pressesSelectedWidget(target) {
+        const el = target instanceof Element ? target.closest('[data-inline-widget][data-source-start]') : null;
+        const source = el && widgetSourceRange(el);
+        const path = el && findSurfacePathForElement(el);
+        return source !== null && path != null && deps.widgetSelection.isSelected(path, source.start);
+    }
+    function dragStartsHere(root, target) {
+        if (claimsPointerGesture(target))
+            return false;
+        if (deadSpaceCaret.isDeadSpaceTarget(root, target))
+            return true;
+        if (!(target instanceof Element) || !root.contains(target))
+            return false;
+        return target.closest(NOT_A_DRAG_START) === null;
+    }
+    /** Open the card on the link `el` renders, or report that nothing there is one. The caret
+     *  has already landed from mousedown, which is the one the card state snapshots. */
+    function openLinkCard(el) {
+        const path = findSurfacePathForElement(el);
+        if (!path)
+            return false;
+        const block = nodeAt(deps.getDoc(), path);
+        if (block === null || !isBlockNode(block))
+            return false;
+        const contentEl = deps.getBlockElByPath(path);
+        if (!contentEl)
+            return false;
+        const hit = resolveLinkAtPoint({ contentEl, block, path, reading: deps.reading });
+        if (!hit)
+            return false;
+        return deps.linkCard.open(hit.target);
+    }
+    function blurEditingSurface(root) {
+        const active = document.activeElement;
+        if (active instanceof HTMLElement && root.contains(active) && active !== root)
+            active.blur();
+    }
+    function install(root) {
+        // Per install: rebinding the root starts with no click in progress.
+        let marginDrag = false;
+        let marginDown = { x: 0, y: 0 };
+        let marginSession = null;
+        const handleAnchorClick = (anchor, e) => {
+            // The host's own header follows the page's link behaviour, not click-to-edit.
+            if (deps.isHostChrome(anchor))
+                return;
+            const href = anchor.getAttribute('href');
+            if (!href)
+                return;
+            // Always suppressed: cursor placement comes from mousedown. Reading mode has no caret
+            // for a plain click to place, so there links behave as in a rendered document.
+            e.preventDefault();
+            if (e.ctrlKey || e.metaKey || deps.reading.mode() === 'reading')
+                deps.activateLink(href, e);
+        };
+        const handleClick = (e) => {
+            const target = e.target;
+            // Ahead of the link branch: a link with a blocked scheme renders as a plain span, and
+            // it is exactly the link a user opens the card to fix. Mod-click still activates, below.
+            if (deps.reading.mode() === 'live' && !e.ctrlKey && !e.metaKey) {
+                const linkEl = target?.closest(LINK_ELEMENT_SELECTOR);
+                if (linkEl && !deps.isHostChrome(linkEl) && openLinkCard(linkEl)) {
+                    e.preventDefault();
+                    return;
+                }
+            }
+            const anchor = target?.closest('a[href]');
+            if (anchor) {
+                handleAnchorClick(anchor, e);
+                return;
+            }
+            // A double or triple click places no caret: the multi-click select painted its range.
+            if (e.detail >= 2) {
+                marginDrag = false;
+                return;
+            }
+            const pressed = marginDrag;
+            const dragged = pressed &&
+                (Math.abs(e.clientX - marginDown.x) > DRAG_SLOP_PX ||
+                    Math.abs(e.clientY - marginDown.y) > DRAG_SLOP_PX);
+            marginDrag = false;
+            if (dragged)
+                return;
+            if (deadSpaceCaret.handleClick(root, e))
+                return;
+            // A still click on a block's own box (padding beside a table, a rule, a closed
+            // equation's face) places the caret in that block, as empty space does.
+            if (pressed && !deadSpaceCaret.isDeadSpaceTarget(root, e.target)) {
+                if (deadSpaceCaret.placeAtPoint(root, e.clientX, e.clientY))
+                    return;
+            }
+            // A click on nothing still ends the edit in progress, since the margin click suppressed
+            // the browser's own blur.
+            if (pressed)
+                blurEditingSurface(root);
+        };
+        // Starts where a click would put the caret; mousedown's default is suppressed so no native
+        // selection fights the drag, and `click` still fires.
+        const startMarginDrag = (e) => {
+            marginDrag = false;
+            marginDown = { x: e.clientX, y: e.clientY };
+            if (e.button !== 0 || e.shiftKey || e.ctrlKey || e.metaKey || e.altKey)
+                return;
+            if (deps.reading.mode() === 'reading' || !dragStartsHere(root, e.target))
+                return;
+            const anchor = deadSpaceCaret.anchorAtPoint(root, e.clientX, e.clientY);
+            if (!anchor)
+                return;
+            marginDrag = true;
+            resetForPointerDown(deps.selection, deps.caretMemory, false);
+            // A block that runs its own drag from a nearby click (a table's cell rectangle) takes
+            // it; the generic drag is for blocks that have none.
+            if (!('offset' in anchor)) {
+                const component = deps.getBlockComponent(anchor.path);
+                if (component?.startDragAtPoint?.(e.clientX, e.clientY, e))
+                    return;
+            }
+            marginSession = installDragListener({
+                editorRoot: root,
+                scrollContainer: deps.getScrollHost() ?? root,
+                selection: deps.selection,
+                getBlockElByPath: deps.getBlockElByPath,
+                lifetimeSignal: deps.getLifetime(),
+                paintSameBlock: () => true
+            }, anchor, e);
+        };
+        const handleMouseDown = (e) => {
+            deadSpaceCaret.notePress(root, e);
+            // The second click of a run belongs to the multi-click select, which runs its own drag.
+            if (marginDrag && e.detail >= 2) {
+                marginSession?.dispose();
+                marginSession = null;
+                marginDrag = false;
+            }
+            if (marginDrag)
+                e.preventDefault();
+        };
+        return removeAll(onRoot(root, 'click', handleClick), installMultiClickSelect({
+            editorRoot: root,
+            selection: deps.selection,
+            getBlockElByPath: deps.getBlockElByPath,
+            getScrollContainer: () => deps.getScrollHost() ?? root,
+            lifetimeSignal: deps.getLifetime(),
+            marginBlockAt: (target, x, y) => deps.reading.mode() !== 'reading' && dragStartsHere(root, target)
+                ? deadSpaceCaret.blockPathNearPoint(root, x, y)
+                : null,
+            pressesSelectedWidget
+        }), onRoot(root, 'pointerdown', startMarginDrag), onRoot(root, 'mousedown', handleMouseDown), onRoot(root, 'contextmenu', (e) => placeContextPress(deps.selection, e), {
+            capture: true
+        }));
+    }
+    return {
+        install,
+        placeCaretAtPoint: (root, x, y) => deadSpaceCaret.placeAtPoint(root, x, y)
+    };
+}

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

@@ -1,42 +1,27 @@
 /**
- * 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.
+ * Editor-root chord routing for keystrokes no mounted block handled. Search and Escape run
+ * first: the global-chord branch returns early on its focus check, which would swallow a Mod+F
+ * pressed inside a block (`test/components/editor-root-keydown.test.ts` pins the order).
  */
-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';
+import type { CommandDispatchContext } from '../schema/block-commands';
 export interface EditorRootKeydownDeps {
-    /** Getters, never values: a capture freezes the reading-mode gate and the
-     *  override map at construction time. */
+    /** Getters, never values: capturing them would freeze the flags 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;
+    /** The editor's command dispatch, which takes only this instance's plugins' chords. */
+    commands: CommandDispatchContext;
     crossBlock: Pick<CrossBlockHandlers, 'handleKeyDown' | 'insertText'>;
-    /** True for nodes in the host's `header` slot: they sit inside `root.contains`
+    /** True for nodes in the host's own header: 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;
+    /** Snapshot the pre-search selection; the bar's close handler restores it. */
+    saveSearchCaret(): void;
     setReplaceExpanded(expanded: boolean): void;
 }
 export interface EditorRootKeydown {

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

@@ -1,34 +1,24 @@
 /**
- * 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.
+ * Editor-root chord routing for keystrokes no mounted block handled. Search and Escape run
+ * first: the global-chord branch returns early on its focus check, which would swallow a Mod+F
+ * pressed inside a block (`test/components/editor-root-keydown.test.ts` pins the order).
  */
 import { claimsBodyChord, isForeignTextEntry } from '../active-editor';
 import { isReservedUiChord, runGlobalChord } from '../schema/commands';
 import { eventToChord, isCharacterKey } 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.
-     */
+    /** Search and Escape, with focus in this editor or a search chord this instance holds; a text
+     *  field outside every editor keeps page-wide Find while the user types in it. */
     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);
-            }
+            // Read before open(), whose focus collapses the selection; the !isOpen check keeps a
+            // repeat Mod+F from overwriting the saved caret.
+            const selected = window.getSelection()?.toString() ?? '';
+            if (!deps.search.isOpen)
+                deps.saveSearchCaret();
             deps.setReplaceExpanded(chord === 'Mod+H' && deps.canReplace);
             deps.search.open();
             if (selected)
@@ -42,12 +32,8 @@ export function createEditorRootKeydown(deps) {
         }
         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.
-     */
+    /** Undo, redo, plugin-global chords and cross-block motion need no element focused, since an
+     *  outside one may own them (a text input owns Mod+Z); the gap caret handles its own. */
     function ownsWindowedOutCaret(root, active) {
         const noElementFocused = active === null || active === root.ownerDocument.body;
         return active === root || (noElementFocused && claimsBodyChord(root));
@@ -58,34 +44,24 @@ export function createEditorRootKeydown(deps) {
             // 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.
+            // The host's header owns its keystrokes; `isForeignTextEntry` cannot tell, since the
+            // header is inside the editor.
             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
-                })) {
+            // No block is focused here, so resolve globally, overrides included, or a consumer's
+            // global rebind would be dead in this one place.
+            if (chord && runGlobalChord(chord, deps.commands)) {
                 event.preventDefault();
                 return;
             }
             if (!deps.isCrossBlock)
                 return;
-            // A range whose blocks host no character position leaves no editing surface focused, so
-            // no `beforeinput` ever fires for a typed character and this is the only door it has.
-            // Composition still belongs to the browser, and a chorded key is not text.
+            // With nothing editable focused, no `beforeinput` fires for a typed character, so it
+            // comes in here; composition and chorded keys are left alone.
             if (isCharacterKey(event.key) && !event.isComposing && !event.ctrlKey && !event.metaKey) {
                 event.preventDefault();
                 void deps.crossBlock.insertText(event.key);

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

@@ -1,41 +1,39 @@
 /**
- * Editor-root ambient listeners: the mod-active cursor tracker, the selectionchange
- * bridge, the blur announcer and the double-click word select. 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.
+ * The editor root's document and window listeners, each installed by one call that returns its
+ * teardown. `onRoot` and `removeAll` keep every add paired with its remove.
  */
+import type { SelectionState } from '../selection/selection-state.svelte';
 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.
- */
+/** Only Ctrl/Cmd+click activates a link, so CSS shows the pointer off `data-mod-active`; reset on
+ *  blur and visibility loss, so a key released while unfocused cannot stick it. */
 export declare function installModActiveTracker(root: HTMLElement): () => void;
+/** The user's input in `root` ends the open undo step, so typing while a plugin's commit waits
+ *  gets its own entry; window capture ends it before the root's handlers open the next. */
+export declare function installUndoStepEnd(root: HTMLElement, endStep: () => void): () => void;
+/** A block stays held in place until the user's next gesture on the scroll container; not
+ *  `scroll`, which a programmatic correction fires too. */
+export declare function installRevealAnchorRelease(port: EventTarget, release: () => void): () => 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. */
+    /** A live check, never captured: the host's header can mount after install. */
     isHostChrome(node: Node | null): boolean;
-    /** Emits this editor's current selection snapshot, read at event time. */
-    emit(): void;
+    /** Announces this editor's current selection, and does nothing when it is the one
+     *  subscribers were already told about. */
+    announceIfMoved(): void;
+    /** Read for an inline widget selected whole, which owns the keys while it is. */
+    selection: Pick<SelectionState, 'widget'>;
 }
-/**
- * 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.
- */
+/** Announces caret motion the editor did not make (a click, a move within one block), and drops
+ *  a caret that appears while an inline widget is selected whole. */
 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.
- */
+/** Announces losing focus, a selection change no browser event reports; decided after the
+ *  flush, since a structural commit refocuses its block a tick later. */
 export declare function installEditorBlurAnnouncer(deps: {
     root: HTMLElement;
-    emit: () => void;
+    announce: () => void;
 }): () => void;

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

@@ -1,10 +1,10 @@
 /**
- * Editor-root ambient listeners: the mod-active cursor tracker, the selectionchange
- * bridge, the blur announcer and the double-click word select. 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.
+ * The editor root's document and window listeners, each installed by one call that returns its
+ * teardown. `onRoot` and `removeAll` keep every add paired with its remove.
  */
 import { tick } from 'svelte';
+import { findSurfacePathForElement } from '../selection/path-lookup';
+import { BARE_MODIFIER_KEYS } from '../schema/keybindings';
 // ── Listener plumbing ───────────────────────────────────────────────
 // Typed off `Event`, not the per-target event maps: those names are type-only,
 // and `target` ranges over every EventTarget the root effects listen on.
@@ -19,11 +19,8 @@ export function removeAll(...removers) {
     return () => removers.forEach((remove) => remove());
 }
 // ── Install bundles ─────────────────────────────────────────────────
-/**
- * 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.
- */
+/** Only Ctrl/Cmd+click activates a link, so CSS shows the pointer off `data-mod-active`; reset on
+ *  blur and visibility loss, so a key released while unfocused cannot stick it. */
 export function installModActiveTracker(root) {
     // Track the last reflected state so ordinary typing never touches the DOM,
     // keeping the attribute write off the keystroke hot path (perf:check).
@@ -45,11 +42,30 @@ export function installModActiveTracker(root) {
     };
     return removeAll(onRoot(document, 'keydown', onKey), onRoot(document, 'keyup', onKey), onRoot(window, 'blur', reset), onRoot(document, 'visibilitychange', onVisibility));
 }
-/**
- * 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.
- */
+/** The user's input in `root` ends the open undo step, so typing while a plugin's commit waits
+ *  gets its own entry; window capture ends it before the root's handlers open the next. */
+export function installUndoStepEnd(root, endStep) {
+    const win = root.ownerDocument.defaultView;
+    if (!win)
+        return () => { };
+    const handler = (e) => {
+        if (!(e.target instanceof Node) || !root.contains(e.target))
+            return;
+        // A held Shift or Ctrl is not input yet; the key it modifies is.
+        if (e instanceof KeyboardEvent && BARE_MODIFIER_KEYS.includes(e.key))
+            return;
+        endStep();
+    };
+    const removers = ['keydown', 'beforeinput', 'paste', 'cut', 'drop'].map((type) => onRoot(win, type, handler, { capture: true }));
+    return () => removers.forEach((remove) => remove());
+}
+/** A block stays held in place until the user's next gesture on the scroll container; not
+ *  `scroll`, which a programmatic correction fires too. */
+export function installRevealAnchorRelease(port, release) {
+    return removeAll(onRoot(port, 'keydown', release), onRoot(port, 'pointerdown', release), onRoot(port, 'wheel', release, { passive: true }));
+}
+/** Announces caret motion the editor did not make (a click, a move within one block), and drops
+ *  a caret that appears while an inline widget is selected whole. */
 export function installSelectionChangeBridge(deps) {
     const handler = () => {
         const sel = window.getSelection();
@@ -58,20 +74,29 @@ export function installSelectionChangeBridge(deps) {
         const anchorNode = sel.anchorNode;
         if (!anchorNode || !deps.root.contains(anchorNode))
             return;
-        // A selection in host chrome is not a document selection: emitting there
+        // A selection in the host's header is not a document selection: announcing there
         // reports this editor's own unchanged selection on every header caret move.
         if (deps.isHostChrome(anchorNode))
             return;
-        deps.emit();
+        // The paragraph keeps focus while its widget is selected, and the browser puts a caret at
+        // its start on any mouse input. A drag's range and a caret in a popover field stay.
+        if (sel.isCollapsed && deps.selection.widget !== null && inBlockSurface(anchorNode)) {
+            sel.removeAllRanges();
+            return;
+        }
+        deps.announceIfMoved();
     };
-    return onRoot(document, 'selectionchange', handler);
+    return removeAll(onRoot(document, 'selectionchange', handler), 
+    // The browser reports a click's caret on a later task, which a byte typed straight after
+    // beats. On `document` so the block's own click handling refines the caret first.
+    onRoot(document, 'click', handler));
 }
-/**
- * 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.
- */
+function inBlockSurface(node) {
+    const el = node instanceof Element ? node : node.parentElement;
+    return findSurfacePathForElement(el) !== null;
+}
+/** Announces losing focus, a selection change no browser event reports; decided after the
+ *  flush, since a structural commit refocuses its block a tick later. */
 export function installEditorBlurAnnouncer(deps) {
     let pending = false;
     const handler = (event) => {
@@ -84,7 +109,7 @@ export function installEditorBlurAnnouncer(deps) {
             const active = document.activeElement;
             if (active instanceof Node && deps.root.contains(active))
                 return;
-            deps.emit();
+            deps.announce();
         });
     };
     return onRoot(deps.root, 'focusout', handler);

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

@@ -0,0 +1,51 @@
+/**
+ * Editor-root menus: the block context menu (a right-click on a block runs its kind's registered
+ * actions; prose and a selection get the clipboard rows, and prose an insert flyout). The open
+ * menu is `$state` in `Editor.svelte`, written through `setMenu`; a menu takes no focus, so
+ * the caret it acts on stays exactly where it is.
+ */
+import type { BlockEditActions } from '../action-contracts';
+import type { DocumentGetter } from '../editor-keys';
+import type { InsertMarkdownOptions } from '../editor-props';
+import type { PresentationMode } from '../presentation-mode';
+import type { PluginActivation } from '../schema/plugin-activation';
+import type { InsertEntry } from '../schema/insert-catalogue';
+import type { MenuEntry } from './menu/BlockMenu.svelte';
+import type { Reading } from '../schema/reading';
+export interface BlockMenuModel {
+    x: number;
+    y: number;
+    anchor: () => {
+        x: number;
+        y: number;
+    };
+    items: MenuEntry[];
+    label: string;
+    pick: (id: string) => void;
+}
+export interface RootMenusDeps {
+    /** Getters, never values: the root binds after construction and the mode moves. */
+    get editorEl(): HTMLElement | undefined;
+    get mode(): PresentationMode;
+    getDoc: DocumentGetter;
+    isHostChrome(node: Node | null): boolean;
+    blockEdit: Pick<BlockEditActions, 'deleteBlock'>;
+    /** Rewrite top-level block `index` as one undo entry, apart from any typing before it. */
+    replaceRaw(index: number, raw: string): Promise<void>;
+    /** Where a click on empty space puts the caret, so a right-click on prose acts at the
+     *  pointer. */
+    placeCaretAtPoint(x: number, y: number): boolean;
+    /** The public insert entry point; a flyout row inserts `below` the block the caret is in. */
+    insertMarkdown(md: string, options?: InsertMarkdownOptions): Promise<boolean>;
+    /** The insert entries this editor lists, read fresh per menu. */
+    insertCatalogue(): readonly InsertEntry[];
+    /** The plugins this editor lists, whose block actions and paste transforms the menu offers. */
+    activation: PluginActivation;
+    /** The editor's reading, which tells a paragraph of pictures from prose. */
+    reading: Reading;
+    setMenu(menu: BlockMenuModel | null): void;
+}
+export interface RootMenus {
+    onRootContextMenu(event: MouseEvent): void;
+}
+export declare function createRootMenus(deps: RootMenusDeps): RootMenus;