@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/components/link-card/link-card-commit.js

@@ -1,24 +1,19 @@
 /**
- * What an open link card can read and write: the construct re-resolved from its target identity
- * after every edit, the bytes the write seam would produce, and the anchoring measure. Kept out of
- * the component so the card stays a rendering shell.
+ * What an open link card can read and write: the construct looked up again from its target after
+ * every edit, the bytes the write path would produce, and the measurement that positions it. Kept
+ * out of the component so the card stays a rendering shell.
  */
 import { wireOverlayRemeasure } from '../../cursor/overlay-remeasure';
-import { createInlineRangeCommit } from '../../editor-actions/inline-range-commit';
 import { isBlockNode, nodeAt } from '../../tree-operations/node-primitives';
 import { linkConstructAt } from '../blocks/text/link-at-point';
-import { buildLinkEditBytes, buildLinkUnwrapBytes, buildLinkWrapBytes, linkFieldsFromInline } from '../blocks/text/link-source-bytes';
+import { buildLinkEditBytes, buildLinkUnwrapBytes, buildLinkWrapBytes, linkFieldsFromInline } from '../../core/inline/link-source-bytes';
 export function createLinkCardCommitter(deps) {
-    const inlineRange = createInlineRangeCommit({
-        getDoc: deps.getDoc,
-        controller: deps.controller,
-        grammar: deps.grammar
-    });
+    const { inlineRange } = deps;
     function resolve(target) {
         const block = nodeAt(deps.getDoc(), target.path);
         if (block === null || !isBlockNode(block))
             return null;
-        const link = linkConstructAt(block, target.sourceStart, deps.linkRef);
+        const link = linkConstructAt(block, target.sourceStart, deps.reading);
         return link === null ? null : { block, link, url: link.url ?? '' };
     }
     function editBytes(target, url) {
@@ -27,9 +22,8 @@ export function createLinkCardCommitter(deps) {
             return null;
         const { block, link } = resolved;
         const current = linkFieldsFromInline(link, block.raw);
-        // A reference form cannot carry a NEW destination without editing its definition, which
-        // lives in another block; changing the url is the user opting into the inline form. The
-        // title rides along either way — the card never shows it, so it is not the card's to drop.
+        // A reference form cannot take a new url without editing its definition elsewhere, so a
+        // changed url writes the inline form; the title comes along either way.
         const fields = url === current.url
             ? current
             : {
@@ -37,15 +31,15 @@ export function createLinkCardCommitter(deps) {
                 url,
                 ...(current.title !== undefined ? { title: current.title } : {})
             };
-        const bytes = buildLinkEditBytes(link, block.raw, fields, deps.linkRef?.current);
+        const bytes = buildLinkEditBytes(link, block.raw, fields, deps.reading);
         return bytes === null ? null : { bytes, link };
     }
     function buildBytes(target, url) {
         return editBytes(target, url)?.bytes ?? null;
     }
     function commitUrl(target, url) {
-        // An unchanged url is a close, not a write: the rebuild would respell author bytes the
-        // serializer normalizes (`(<a b>)` → `(a%20b)`) and mint an undo entry for nothing.
+        // An unchanged url just closes the card: a rebuild would respell author bytes the
+        // serializer normalizes (`(<a b>)` to `(a%20b)`) and add an undo entry for nothing.
         const resolved = resolve(target);
         if (!resolved || url === resolved.url)
             return;
@@ -58,7 +52,7 @@ export function createLinkCardCommitter(deps) {
         const block = nodeAt(deps.getDoc(), target.path);
         if (block === null || !isBlockNode(block))
             return;
-        const bytes = buildLinkWrapBytes(block.raw, target.start, target.end, url, deps.linkRef?.current);
+        const bytes = buildLinkWrapBytes(block.raw, target.start, target.end, url, deps.reading);
         if (bytes === null)
             return;
         void write(target.path, target.start, target.end, bytes);
@@ -67,19 +61,17 @@ export function createLinkCardCommitter(deps) {
         const resolved = resolve(target);
         if (!resolved)
             return;
-        const bytes = buildLinkUnwrapBytes(resolved.link, resolved.block.raw, deps.linkRef?.current);
+        const bytes = buildLinkUnwrapBytes(resolved.link, resolved.block.raw, deps.reading);
         if (bytes === null)
             return;
         void write(target.path, resolved.link.start, resolved.link.end, bytes);
     }
+    // The caret goes to the construct's outer start, which the undo entry records too, so the caret
+    // before and after an undo agree.
     async function write(path, start, end, bytes) {
-        await inlineRange.commitInlineRange(path, start, end, bytes, start);
-        // The construct's outer start, which is also the offset the undo entry records: the caret
-        // before an undo and the caret after it then agree, and a remove-link lands where the
-        // unwrapped text now begins.
-        await deps.landCaret(path, start);
+        await inlineRange.commitInlineRange(path, start, end, bytes, start, { landCaret: true });
     }
-    /** The raw range the card anchors under: the resolved construct, or the create range as-is. */
+    /** The raw range the card sits under: the resolved construct, or the create range as it is. */
     function anchoredRange() {
         const target = deps.getTarget();
         if (target) {
@@ -95,8 +87,8 @@ export function createLinkCardCommitter(deps) {
         const editorEl = deps.getEditorEl();
         if (!cardEl || !editorEl)
             return () => { };
-        // Measured through the rects API off RAW offsets, so the anchor survives the DOM rebuild
-        // every commit does — there is no element reference here to go stale.
+        // Measured through the rects API from raw offsets, so the position survives the DOM
+        // rebuild every commit does: there is no element reference here to go stale.
         const measure = () => {
             const range = anchoredRange();
             if (!range)
@@ -111,9 +103,8 @@ export function createLinkCardCommitter(deps) {
             cardEl.style.top = `${rect.bottom - editorRect.top - borderTop + editorEl.scrollTop}px`;
             cardEl.style.left = `${rect.left - editorRect.left - borderLeft + editorEl.scrollLeft}px`;
         };
-        // The setup measure reads the document, and letting that register would make the caller's
-        // $effect tear down and re-wire these listeners on every keystroke. The `edit` subscription
-        // below is the one document trigger.
+        // Untracked setup measure, or the caller's $effect would re-wire these listeners on every
+        // keystroke; the `edit` subscription below is the document trigger.
         const unwireScroll = wireOverlayRemeasure({
             el: cardEl,
             editorRoot: editorEl,

package/dist/components/link-card/link-card-entry.d.ts

@@ -1,39 +1,29 @@
 /**
- * `link.openCard` — the keyboard entry to the link card and the pressed state a toolbar paints for
- * it, off one resolution of the construct holding the caret or a range inside it. The chord ENTERS
- * the card (focus in the URL field), unlike a click, which opens it beside a caret that stays the
- * document's. Live mode only: every other mode paints the destination.
+ * `link.openCard`: the keyboard way into the link card, and the pressed state a toolbar paints
+ * for it, both from one lookup of the construct holding the caret or a range inside it. The chord
+ * enters the card, with focus in the URL field, unlike a click, which opens it beside a caret that
+ * stays in the document. Live mode only: every other mode paints the destination.
  */
-import type { PresentationMode } from '../../presentation-mode';
 import { type LinkPointQuery, type LinkTarget } from '../blocks/text/link-at-point';
 import type { LinkCardState } from './link-card-state.svelte';
-/** What locating the card's construct takes, whether a press or a pressed-state read asks. */
+/** What locating the card's construct takes, whether a click or a pressed-state read asks. */
 export interface LinkCardTargetQuery extends LinkPointQuery {
-    mode: PresentationMode;
-    /** The block-local raw selection, or null at a collapsed caret. Required, never defaulted:
-     *  a surface that must mint no link says so by passing null wherever it could create. */
+    /** The raw selection within this block, or null at a collapsed caret. Required, never given a
+     *  default: a caller that must create no link says so by passing null wherever it could. */
     selection: {
         start: number;
         end: number;
     } | null;
-    /** True while a range crosses block boundaries. Required for the same reason, and because
-     *  `selection` cannot report it: read off this block's own DOM walk, an endpoint in another
-     *  block comes back as end-of-walk — a range running to the block's end that nobody made. */
+    /** True while a range crosses blocks: `selection`, measured against this block's DOM, reports
+     *  an endpoint in another block as this block's end. */
     crossBlockRange: boolean;
 }
 export interface LinkCardEntryQuery extends LinkCardTargetQuery {
     card: LinkCardState;
 }
-/**
- * The construct the chord would EDIT: the card-editable one under the caret, which a range must
- * lie wholly inside since the card edits ONE link. Null where the chord creates instead or opens
- * nothing, so a pressed paint and the press it promises resolve the same construct.
- */
+/** The construct the chord would edit, under the caret or wholly containing the range; null
+ *  where the chord creates or opens nothing, so the pressed state matches the click. */
 export declare function linkCardTargetAt(query: LinkCardTargetQuery): LinkTarget | null;
-/**
- * Enter the card for the chord: the construct the caret — or a range lying wholly inside it —
- * sits in, EDIT mode; failing that, CREATE mode over the range, declined when it crosses another
- * construct's bytes, since wrapping inside or across one is a policy question. The chord is
- * consumed either way, by the keymap arm that calls this.
- */
+/** Edits the construct holding the caret or range, else creates one over the range unless it
+ *  crosses another construct's bytes. The keymap takes the chord either way. */
 export declare function enterLinkCardAtCaret(query: LinkCardEntryQuery): void;

package/dist/components/link-card/link-card-entry.js

@@ -1,18 +1,15 @@
 /**
- * `link.openCard` — the keyboard entry to the link card and the pressed state a toolbar paints for
- * it, off one resolution of the construct holding the caret or a range inside it. The chord ENTERS
- * the card (focus in the URL field), unlike a click, which opens it beside a caret that stays the
- * document's. Live mode only: every other mode paints the destination.
+ * `link.openCard`: the keyboard way into the link card, and the pressed state a toolbar paints
+ * for it, both from one lookup of the construct holding the caret or a range inside it. The chord
+ * enters the card, with focus in the URL field, unlike a click, which opens it beside a caret that
+ * stays in the document. Live mode only: every other mode paints the destination.
  */
-import { canWrapRangeAsLink } from '../blocks/text/link-source-bytes';
+import { canWrapRangeAsLink } from '../../core/inline/link-source-bytes';
 import { resolveLinkAtPoint } from '../blocks/text/link-at-point';
-/**
- * The construct the chord would EDIT: the card-editable one under the caret, which a range must
- * lie wholly inside since the card edits ONE link. Null where the chord creates instead or opens
- * nothing, so a pressed paint and the press it promises resolve the same construct.
- */
+/** The construct the chord would edit, under the caret or wholly containing the range; null
+ *  where the chord creates or opens nothing, so the pressed state matches the click. */
 export function linkCardTargetAt(query) {
-    if (query.mode !== 'live' || query.crossBlockRange)
+    if (query.reading.mode() !== 'live' || query.crossBlockRange)
         return null;
     const hit = resolveLinkAtPoint(query);
     if (hit === null)
@@ -22,22 +19,17 @@ export function linkCardTargetAt(query) {
         return null;
     return hit.target;
 }
-/**
- * Enter the card for the chord: the construct the caret — or a range lying wholly inside it —
- * sits in, EDIT mode; failing that, CREATE mode over the range, declined when it crosses another
- * construct's bytes, since wrapping inside or across one is a policy question. The chord is
- * consumed either way, by the keymap arm that calls this.
- */
+/** Edits the construct holding the caret or range, else creates one over the range unless it
+ *  crosses another construct's bytes. The keymap takes the chord either way. */
 export function enterLinkCardAtCaret(query) {
-    if (query.mode !== 'live')
+    if (query.reading.mode() !== 'live')
         return;
-    // The dispatch seam declines `link.openCard` over a cross-block range already
-    // (`RANGE_DECLINED_COMMAND_IDS`); the belt is here because the offsets this arm would
-    // otherwise trust are fabricated in exactly that state rather than absent.
+    // Command dispatch already refuses a cross-block range; checked again because the offsets
+    // here would be made up in that state.
     if (query.crossBlockRange)
         return;
-    // Edit before create, since create declines a range already inside a construct: taking the
-    // create fork there leaves the press inert under a button the pressed read paints ON.
+    // Edit before create, since create refuses a range already inside a construct: going the
+    // create way there leaves the click doing nothing under a button painted as pressed.
     const target = linkCardTargetAt(query);
     if (target) {
         query.card.enter(target);
@@ -46,6 +38,6 @@ export function enterLinkCardAtCaret(query) {
     const range = query.selection;
     if (range === null || range.start >= range.end)
         return;
-    if (canWrapRangeAsLink(query.block.raw, range.start, range.end, query.linkRef?.current))
+    if (canWrapRangeAsLink(query.block.raw, range.start, range.end, query.reading))
         query.card.enterCreate({ path: query.path, start: range.start, end: range.end });
 }

package/dist/components/link-card/link-card-state.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { LinkTarget } from '../blocks/text/link-at-point';
-/** The create gesture's target: the raw range a commit would wrap. A range, not a construct —
- *  the document holds nothing until Enter mints it, which is what lets Escape owe no cleanup. */
+/** The create gesture's target: the raw range a commit would wrap. A range, not a construct,
+ *  since the document holds nothing until Enter writes it, so Escape has nothing to clean up. */
 export interface CreateLinkTarget {
     path: number[];
     start: number;
@@ -10,35 +10,31 @@ export interface LinkCardState {
     getTarget(): LinkTarget | null;
     /** Set and `getTarget()` are mutually exclusive: one card, one target. */
     getCreateTarget(): CreateLinkTarget | null;
-    /**
-     * Zero for a click, a fresh positive number for each keyboard entry. The card focuses its field
-     * when this differs from the zero it starts at, which separates the two gestures without a mode
-     * flag AND survives the case with no remount to key on: `Mod+K` on an already-open card.
-     */
+    /** Zero for a click, a fresh number for each keyboard entry; the card focuses its field when
+     *  it changes, which also covers `Mod+K` on a card already open. */
     getFocusEpoch(): number;
-    /** Anchored beside a live caret; the document keeps focus. The click gesture.
-     *  False when `canOpen` declined and no card opened. */
+    /** Positioned beside a live caret; the document keeps focus. The click gesture.
+     *  False when `canOpen` refused and no card opened. */
     open(target: LinkTarget): boolean;
-    /** Opened AND focused, so the trap and Escape's caret restore engage. The chord gesture.
-     *  False when `canEnter` declined. */
+    /** Opened and focused, so the focus trap and Escape's caret restore both apply. The chord
+     *  gesture. False when `canEnter` refused. */
     enter(target: LinkTarget): boolean;
-    /** Entered over the range a commit would wrap. False when `canOpenCreate` declined. */
+    /** Entered over the range a commit would wrap. False when `canOpenCreate` refused. */
     enterCreate(target: CreateLinkTarget): boolean;
     close(): void;
 }
 export interface LinkCardOptions {
-    /** Runs on every entry path before the card takes the screen — the caret snapshot lives here
-     *  rather than at each caller, so entry path N+1 cannot forget it. */
+    /** Runs on every entry path before the card takes the screen: the caret snapshot lives here
+     *  rather than at each caller, so the next entry path cannot forget it. */
     onOpen: () => void;
-    /** The CLICK door: a live selection — native or the editor's cross-block range — is a gesture
-     *  an unasked-for card must not interrupt or write over. */
+    /** For a click: a live selection, native or the editor's cross-block range, is a gesture an
+     *  unasked-for card must not interrupt or write over. */
     canOpen: () => boolean;
-    /** The CHORD door, looser than the click's by exactly one case: the entry resolves the
-     *  construct from the selection itself, so a range it admits is the card's own bytes. */
+    /** For the chord, looser than the click's by exactly one case: the entry resolves the
+     *  construct from the selection itself, so a range it allows is the card's own bytes. */
     canEnter: () => boolean;
-    /** The create door: gates on the very selection `canOpen` forbids, since the range IS the
-     *  gesture's target. Separate and required so each entry states which gesture it carries;
-     *  a cross-block range declines at all three. */
+    /** For create: requires the selection `canOpen` forbids, since the range is the target. All
+     *  three checks refuse a cross-block range. */
     canOpenCreate: () => boolean;
 }
 export declare function createLinkCardState(options: LinkCardOptions): LinkCardState;

package/dist/components/link-card/link-card-state.svelte.js

@@ -1,5 +1,5 @@
-// The open link card's target. Identity only — path plus construct start — because every commit
-// rebuilds the inline tree, so a captured node would address bytes that moved.
+// The open link card's target: only what identifies it, a path plus where the construct starts,
+// because every commit rebuilds the inline tree and a captured node would point at moved bytes.
 export function createLinkCardState(options) {
     let target = $state(null);
     let createTarget = $state(null);

package/dist/components/lrd-map-gate.d.ts

@@ -1,17 +1,10 @@
 import type { DocumentView } from '../core/node-views';
 import type { EditEvent } from '../editor-events';
-/**
- * Whether a commit could change the LRD set, keeping the O(nodes) map rebuild off the keystroke
- * hot path. Any op that is not a kind-stable `input`/`metadataUpdate` could add or remove a
- * definition; a kind-stable one only can when its target is itself an LRD. `input` is kind-stable
- * by construction, held by the input-op kind-stability lint under `test/invariants/lint/`.
- */
+/** Keeps the whole-document map rebuild off the keystroke path: `input` and `metadataUpdate`
+ *  never change a block's kind, so they matter only when the block is itself a definition. */
 export declare function lrdMapCouldChange(doc: DocumentView, event: EditEvent): boolean;
-/**
- * A monotonic stamp that changes **exactly** when the signature string does.
- * Reference-bearing render memos key on the epoch instead of the whole (~MB)
- * signature, so bumping on every rebuild would re-render every bracket-bearing block.
- */
+/** Changes exactly when the signature does: render caches key on it rather than the (~MB)
+ *  signature, and a bump per rebuild would re-render every block with a bracket in it. */
 export declare function advanceSignatureEpoch(prevSignature: string, prevEpoch: number, nextSignature: string): {
     signature: string;
     epoch: number;

package/dist/components/lrd-map-gate.js

@@ -1,20 +1,14 @@
+// When to rebuild the link reference definition map, and the counter that render caches key on.
 import { nodeAt } from '../tree-operations/node-primitives';
-/**
- * Whether a commit could change the LRD set, keeping the O(nodes) map rebuild off the keystroke
- * hot path. Any op that is not a kind-stable `input`/`metadataUpdate` could add or remove a
- * definition; a kind-stable one only can when its target is itself an LRD. `input` is kind-stable
- * by construction, held by the input-op kind-stability lint under `test/invariants/lint/`.
- */
+/** Keeps the whole-document map rebuild off the keystroke path: `input` and `metadataUpdate`
+ *  never change a block's kind, so they matter only when the block is itself a definition. */
 export function lrdMapCouldChange(doc, event) {
     if (event.op !== 'input' && event.op !== 'metadataUpdate')
         return true;
     return nodeAt(doc, event.path)?.kind === 'linkReferenceDefinition';
 }
-/**
- * A monotonic stamp that changes **exactly** when the signature string does.
- * Reference-bearing render memos key on the epoch instead of the whole (~MB)
- * signature, so bumping on every rebuild would re-render every bracket-bearing block.
- */
+/** Changes exactly when the signature does: render caches key on it rather than the (~MB)
+ *  signature, and a bump per rebuild would re-render every block with a bracket in it. */
 export function advanceSignatureEpoch(prevSignature, prevEpoch, nextSignature) {
     if (nextSignature === prevSignature)
         return { signature: prevSignature, epoch: prevEpoch };

package/dist/components/menu/BlockMenu.svelte

@@ -1,19 +1,11 @@
 <script lang="ts" module>
 	/**
-	 * A limestone-styled list menu the editor opens at a point: the block picker behind the
-	 * bottom `+` (rows insert Markdown at the caret) and a block's context menu (rows run that
-	 * kind's registered actions). Pointer- and keyboard-driven without ever taking focus, so the
-	 * caret it acts on stays exactly where it is.
+	 * A list menu the editor opens at a point: a block's context menu (rows run
+	 * that kind's registered actions) and the prose menu's clipboard rows with its "Insert block"
+	 * flyout (rows insert Markdown into a new paragraph). Pointer- and keyboard-driven without
+	 * ever taking focus, so the caret it acts on stays exactly where it is.
 	 */
-	import { isPluginInstalled } from '../../schema/plugin-install';
-	import type { MenuIconName } from './MenuIcon.svelte';
-
-	interface BlockMenuItem {
-		id: string;
-		label: string;
-		icon: MenuIconName;
-		md: string;
-	}
+	import type { MenuIconName } from '../../menu-icons';
 
 	export interface MenuEntry {
 		id: string;
@@ -23,67 +15,9 @@
 		disabled?: boolean;
 		/** A separator row; nothing else on the entry is read. */
 		divider?: boolean;
-		/** A flyout: hover or ArrowRight opens these beside the row; a pick is one of THEIR ids. */
+		/** A flyout: hover or ArrowRight opens these beside the row; a pick is one of their ids. */
 		children?: MenuEntry[];
 	}
-
-	// Blocks that stand on their own when empty. A heading is not one — it is text turned into a
-	// heading, which the selection popover offers — so it is deliberately not here.
-	const BUILT_IN: readonly BlockMenuItem[] = [
-		{ id: 'bullet', label: 'Bulleted list', icon: 'list', md: '- ' },
-		{ id: 'numbered', label: 'Numbered list', icon: 'list-ordered', md: '1. ' },
-		{ id: 'todo', label: 'To-do list', icon: 'square-check', md: '- [ ] ' },
-		{ id: 'quote', label: 'Quote', icon: 'text-quote', md: '> ' },
-		{ id: 'divider', label: 'Divider', icon: 'minus', md: '---\n' },
-		{ id: 'code', label: 'Code block', icon: 'code', md: '```\n\n```\n' },
-		{
-			id: 'table',
-			label: 'Table',
-			icon: 'table',
-			md: '| Column | Column |\n| --- | --- |\n|  |  |\n'
-		}
-	];
-	// Listed only while the plugin that reads the syntax is installed.
-	const FROM_PLUGINS: readonly { plugin: string; item: BlockMenuItem }[] = [
-		{ plugin: 'latex', item: { id: 'math', label: 'Math block', icon: 'sigma', md: '$$\n\n$$\n' } },
-		{
-			plugin: 'admonitions',
-			item: { id: 'note', label: 'Note', icon: 'info', md: ':::note\n\n:::\n' }
-		}
-	];
-
-	/** Every insertable block, keyed by id, for resolving a pick from either level of the menu. */
-	export function insertSnippets(): Map<string, string> {
-		const all = [
-			...BUILT_IN,
-			...FROM_PLUGINS.filter((entry) => isPluginInstalled(entry.plugin)).map((entry) => entry.item)
-		];
-		return new Map(all.map((item) => [item.id, item.md]));
-	}
-
-	/** Every insertable block as one flat list, for a flyout that is already a level down. */
-	export function insertFlyoutEntries(): MenuEntry[] {
-		return [
-			...BUILT_IN,
-			...FROM_PLUGINS.filter((entry) => isPluginInstalled(entry.plugin)).map((entry) => entry.item)
-		].map(({ id, label, icon }) => ({ id, label, icon }));
-	}
-
-	const COMMON = new Set(['bullet', 'numbered', 'todo', 'code', 'table', 'math']);
-
-	/** The insert menu: the common blocks, the rest behind "More blocks". */
-	export function insertMenuEntries(): MenuEntry[] {
-		const all = [
-			...BUILT_IN,
-			...FROM_PLUGINS.filter((entry) => isPluginInstalled(entry.plugin)).map((entry) => entry.item)
-		];
-		const row = ({ id, label, icon }: BlockMenuItem): MenuEntry => ({ id, label, icon });
-		const common = all.filter((item) => COMMON.has(item.id)).map(row);
-		const more = all.filter((item) => !COMMON.has(item.id)).map(row);
-		return more.length
-			? [...common, { id: 'more', label: 'More blocks', icon: 'plus', children: more }]
-			: common;
-	}
 </script>
 
 <script lang="ts">
@@ -91,6 +25,7 @@
 	import { BLOCK_MENU_LABEL } from '../../a11y-strings';
 	import { keepFlyoutOnScreen } from './flyout-placement';
 	import MenuIcon from './MenuIcon.svelte';
+	import type { MenuPresence } from './menu-presence.svelte';
 
 	let {
 		x,
@@ -99,16 +34,18 @@
 		items,
 		label = BLOCK_MENU_LABEL,
 		onPick,
-		onClose
+		onClose,
+		menuPresence
 	}: {
 		x: number;
 		y: number;
-		/** Where the open point is NOW, re-read on scroll and resize so the menu stays on it. */
+		/** Where the open point is now, re-read on scroll and resize so the menu stays on it. */
 		anchor?: () => { x: number; y: number } | null;
 		items: MenuEntry[];
 		label?: string;
 		onPick: (id: string) => void;
 		onClose: () => void;
+		menuPresence: MenuPresence;
 	} = $props();
 
 	let menuEl: HTMLDivElement | undefined = $state();
@@ -134,7 +71,7 @@
 		onPick(entry.id);
 	}
 
-	// Same anchoring as the table's menu: follows the content, clamped once when first sized.
+	// Positioned like the table's menu: follows the content, clamped once when first sized.
 	// svelte-ignore state_referenced_locally
 	let at = $state({ x, y });
 	let shift = $state<{ x: number; y: number } | null>(null);
@@ -163,15 +100,15 @@
 	const left = $derived(at.x + (shift?.x ?? 0));
 	const top = $derived(at.y + (shift?.y ?? 0));
 
-	// Keys are read at the document, capture phase: the caret's surface keeps focus, and the
-	// menu answers first while it is open. Anything it does not claim reaches the editor as usual.
+	// Keys are read at the document in the capture phase: the block with the caret keeps focus,
+	// and the menu answers first while it is open. Anything it ignores reaches the editor.
 	$effect(() => {
 		const onPointerDown = (e: PointerEvent) => {
 			if (menuEl && e.target instanceof Node && menuEl.contains(e.target)) return;
 			onClose();
 		};
-		// Claimed keys stop here: the caret's surface would otherwise take the same press (an
-		// Enter splitting the block the menu is about to insert into).
+		// Keys the menu takes stop here: the block with the caret would otherwise get the same
+		// keystroke (an Enter splitting the block the menu is about to insert into).
 		const claim = (e: KeyboardEvent) => {
 			e.preventDefault();
 			e.stopImmediatePropagation();
@@ -228,6 +165,7 @@
 	class="md-menu block-menu"
 	role="menu"
 	aria-label={label}
+	{@attach menuPresence.track}
 	style:left="{left}px"
 	style:top="{top}px"
 >
@@ -265,6 +203,7 @@
 						class="md-menu block-menu block-menu-flyout"
 						role="menu"
 						{@attach keepFlyoutOnScreen}
+						{@attach menuPresence.track}
 					>
 						{#each item.children as child, j (child.id)}
 							<button
@@ -291,7 +230,7 @@
 </div>
 
 <style>
-	/* Surface and rows are the shared `.md-menu` family (editor.css). */
+	/* The panel and its rows are the shared `.md-menu` family (editor.css). */
 	.block-menu {
 		min-width: 188px;
 	}
@@ -301,7 +240,7 @@
 	.block-menu-label {
 		flex: 1;
 	}
-	/* limestone's submenu: a second surface hung off the row's right edge. */
+	/* The submenu: a second panel hung off the row's right edge. */
 	.block-menu-flyout {
 		position: absolute;
 		left: 100%;

package/dist/components/menu/BlockMenu.svelte.d.ts

@@ -1,4 +1,10 @@
-import type { MenuIconName } from './MenuIcon.svelte';
+/**
+ * A list menu the editor opens at a point: a block's context menu (rows run
+ * that kind's registered actions) and the prose menu's clipboard rows with its "Insert block"
+ * flyout (rows insert Markdown into a new paragraph). Pointer- and keyboard-driven without
+ * ever taking focus, so the caret it acts on stays exactly where it is.
+ */
+import type { MenuIconName } from '../../menu-icons';
 export interface MenuEntry {
     id: string;
     label: string;
@@ -7,19 +13,14 @@ export interface MenuEntry {
     disabled?: boolean;
     /** A separator row; nothing else on the entry is read. */
     divider?: boolean;
-    /** A flyout: hover or ArrowRight opens these beside the row; a pick is one of THEIR ids. */
+    /** A flyout: hover or ArrowRight opens these beside the row; a pick is one of their ids. */
     children?: MenuEntry[];
 }
-/** Every insertable block, keyed by id, for resolving a pick from either level of the menu. */
-export declare function insertSnippets(): Map<string, string>;
-/** Every insertable block as one flat list, for a flyout that is already a level down. */
-export declare function insertFlyoutEntries(): MenuEntry[];
-/** The insert menu: the common blocks, the rest behind "More blocks". */
-export declare function insertMenuEntries(): MenuEntry[];
+import type { MenuPresence } from './menu-presence.svelte';
 type $$ComponentProps = {
     x: number;
     y: number;
-    /** Where the open point is NOW, re-read on scroll and resize so the menu stays on it. */
+    /** Where the open point is now, re-read on scroll and resize so the menu stays on it. */
     anchor?: () => {
         x: number;
         y: number;
@@ -28,6 +29,7 @@ type $$ComponentProps = {
     label?: string;
     onPick: (id: string) => void;
     onClose: () => void;
+    menuPresence: MenuPresence;
 };
 declare const BlockMenu: import("svelte").Component<$$ComponentProps, {}, "">;
 type BlockMenu = ReturnType<typeof BlockMenu>;