@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/components/link-card/LinkCardHost.svelte

@@ -1,61 +1,63 @@
 <script lang="ts">
 	import type { Document } from '../../core/nodes';
-	import type { UndoController } from '../../editor-actions/deps';
+	import type { InlineRangeCommit } from '../../editor-actions/inline-range-commit';
 	import type { EditorEvents } from '../../editor-events';
-	import type { LinkReferenceResolverRef } from '../../editor-keys';
-	import type { GrammarView } from '../../schema/block-openers';
 	import type { CaretRestore } from '../../selection/caret-restore';
 	import { resolveHref } from '../../core/inline-render';
 	import LinkCard from './LinkCard.svelte';
 	import { createLinkCardCommitter } from './link-card-commit';
 	import type { LinkCardState } from './link-card-state.svelte';
+	import type { MenuPresence } from '../menu/menu-presence.svelte';
+	import type { Reading } from '../../schema/reading';
+	import type { CommandDispatchContext } from '../../schema/block-commands';
+	import { commandForKey } from '../../schema/commands';
+	import { blockNodeAt } from '../../tree-operations/node-primitives';
 
 	// Mounted unconditionally by Editor: the anchoring and dismiss effects must observe the card's
 	// target changing, so the open/closed `{#if}` lives here rather than at the mount site.
 	let {
 		card,
-		controller,
+		inlineRange,
 		events,
 		getDoc,
 		getEditorEl,
 		measureRange,
-		landCaret,
 		activateLink,
 		resolveLinkUrl,
 		caretRestore,
-		linkRef,
-		grammar
+		reading,
+		menuPresence,
+		commands
 	}: {
 		card: LinkCardState;
-		controller: UndoController;
+		inlineRange: InlineRangeCommit;
 		events: EditorEvents;
 		getDoc: () => Document;
 		getEditorEl: () => HTMLElement | null;
 		measureRange: (path: number[], start: number, end: number) => DOMRect[];
-		landCaret: (path: number[], offset: number) => Promise<boolean>;
 		activateLink: (url: string, event: MouseEvent) => void;
-		/** The consumer's href rewrite, the render path's first funnel stage. */
+		/** The consumer's href rewrite, the first thing the render path applies. */
 		resolveLinkUrl: (rawUrl: string) => string;
 		caretRestore: CaretRestore;
-		linkRef?: LinkReferenceResolverRef;
-		grammar?: GrammarView;
+		reading: Reading;
+		menuPresence: MenuPresence;
+		/** The editor's command dispatch, which says what a keypress means at the card's block. */
+		commands: CommandDispatchContext;
 	} = $props();
 
 	let cardEl: HTMLDivElement | undefined = $state();
 
-	// Props are stable for the editor's lifetime; reactive values already cross as getters.
+	// Props are stable for the editor's lifetime; reactive values already come in as getters.
 	// svelte-ignore state_referenced_locally
 	const linkCard = createLinkCardCommitter({
 		getDoc,
 		getEditorEl,
 		getTarget: card.getTarget,
 		getCreateTarget: card.getCreateTarget,
-		controller,
+		inlineRange,
 		events,
 		measureRange,
-		landCaret,
-		linkRef,
-		grammar
+		reading
 	});
 
 	$effect(() => {
@@ -64,17 +66,15 @@
 		return linkCard.syncCardToLink(() => cardEl ?? null);
 	});
 
-	// A target that stops resolving unrenders the card but leaves the state set, so its
-	// document-capture listeners live on and the next write that makes it resolve again
-	// resurrects it holding a draft from before. Closing is the only honest answer.
+	// A target that stops resolving closes the card, or a later write that makes it resolve
+	// again would bring it back holding an old draft.
 	$effect(() => {
 		const target = card.getTarget();
 		if (target && !linkCard.resolve(target)) card.close();
 	});
 
-	// A create target addresses bytes by range alone, so a write landing from outside the gesture
-	// moves them under it. The commit path closes before it writes, and the handler re-reads the
-	// target, so only an outside edit closes the card here.
+	// A create target is a bare range, which any other write would shift under it; the card's own
+	// commit closes it before writing, so only an outside edit closes it here.
 	$effect(() => {
 		if (!card.getCreateTarget()) return;
 		return events.on('edit', () => {
@@ -82,9 +82,8 @@
 		});
 	});
 
-	// An outside press is a non-destructive dismiss and leaves the caret where it just landed.
-	// Escape is document-level because the opening click leaves the caret in the DOCUMENT: the
-	// card is chrome beside a live caret until the user steps into it, and both states close.
+	// A click outside closes the card and leaves the caret where it landed. Escape is read at the
+	// document because a clicked card sits beside a caret that stays there.
 	$effect(() => {
 		if (!card.getTarget() && !card.getCreateTarget()) return;
 		const onPointerDown = (e: PointerEvent) => {
@@ -96,14 +95,14 @@
 			// A composing Escape cancels the IME's conversion, not the card.
 			if (e.key !== 'Escape' || e.isComposing) return;
 			const inCard = cardEl?.contains(document.activeElement) ?? false;
-			// Only a card that HOLDS the focus consumes the key and owes the caret back; beside a
-			// live caret it just closes, leaving Escape to whatever else was listening.
+			// Only a card that holds the focus takes the key and has to give the caret back;
+			// beside a live caret it just closes, leaving Escape to whatever else was listening.
 			if (inCard) {
 				e.preventDefault();
 				e.stopPropagation();
 			}
 			card.close();
-			if (inCard) caretRestore.restore();
+			if (inCard) void caretRestore.restore();
 		};
 		document.addEventListener('pointerdown', onPointerDown, true);
 		document.addEventListener('keydown', onKeyDown, true);
@@ -122,13 +121,21 @@
 
 	function commitCreate(url: string): void {
 		const target = card.getCreateTarget();
-		// An empty draft has nothing to mint; Enter stays inert rather than closing having done
-		// nothing, which would drop the focus the card holds.
+		// An empty draft has nothing to write; Enter does nothing rather than closing the card
+		// having achieved nothing, which would drop the focus the card holds.
 		if (!target || url.trim() === '') return;
 		card.close();
 		linkCard.commitCreate(target, url);
 	}
 
+	// Resolved at the block the card edits, so a consumer's rebinding of the chord is the one
+	// the card takes.
+	function opensCard(e: KeyboardEvent): boolean {
+		const path = card.getTarget()?.path ?? card.getCreateTarget()?.path;
+		const kind = path ? (blockNodeAt(getDoc(), path)?.kind ?? null) : null;
+		return commandForKey(e, kind, commands) === 'link.openCard';
+	}
+
 	function remove(): void {
 		const target = card.getTarget();
 		if (!target) return;
@@ -141,7 +148,7 @@
 	{@const target = card.getTarget()!}
 	{@const resolved = linkCard.resolve(target)}
 	{#if resolved}
-		<div bind:this={cardEl} class="md-link-card-anchor">
+		<div bind:this={cardEl} class="md-link-card-anchor" {@attach menuPresence.track}>
 			{#key `${target.path.join(',')}@${target.sourceStart}`}
 				<LinkCard
 					url={resolved.url}
@@ -150,6 +157,7 @@
 					onCommit={commit}
 					onOpenLink={activateLink}
 					onRemove={remove}
+					{opensCard}
 					resolveHref={(url) => resolveHref({ resolveLinkUrl }, url)}
 				/>
 			{/key}
@@ -157,7 +165,7 @@
 	{/if}
 {:else if card.getCreateTarget()}
 	{@const create = card.getCreateTarget()!}
-	<div bind:this={cardEl} class="md-link-card-anchor">
+	<div bind:this={cardEl} class="md-link-card-anchor" {@attach menuPresence.track}>
 		{#key `${create.path.join(',')}@${create.start}-${create.end}`}
 			<LinkCard
 				url=""
@@ -165,6 +173,7 @@
 				canWrite={true}
 				onCommit={commitCreate}
 				onOpenLink={activateLink}
+				{opensCard}
 				resolveHref={(url) => resolveHref({ resolveLinkUrl }, url)}
 			/>
 		{/key}

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

@@ -1,24 +1,26 @@
 import type { Document } from '../../core/nodes';
-import type { UndoController } from '../../editor-actions/deps';
+import type { InlineRangeCommit } from '../../editor-actions/inline-range-commit';
 import type { EditorEvents } from '../../editor-events';
-import type { LinkReferenceResolverRef } from '../../editor-keys';
-import type { GrammarView } from '../../schema/block-openers';
 import type { CaretRestore } from '../../selection/caret-restore';
 import type { LinkCardState } from './link-card-state.svelte';
+import type { MenuPresence } from '../menu/menu-presence.svelte';
+import type { Reading } from '../../schema/reading';
+import type { CommandDispatchContext } from '../../schema/block-commands';
 type $$ComponentProps = {
     card: LinkCardState;
-    controller: UndoController;
+    inlineRange: InlineRangeCommit;
     events: EditorEvents;
     getDoc: () => Document;
     getEditorEl: () => HTMLElement | null;
     measureRange: (path: number[], start: number, end: number) => DOMRect[];
-    landCaret: (path: number[], offset: number) => Promise<boolean>;
     activateLink: (url: string, event: MouseEvent) => void;
-    /** The consumer's href rewrite, the render path's first funnel stage. */
+    /** The consumer's href rewrite, the first thing the render path applies. */
     resolveLinkUrl: (rawUrl: string) => string;
     caretRestore: CaretRestore;
-    linkRef?: LinkReferenceResolverRef;
-    grammar?: GrammarView;
+    reading: Reading;
+    menuPresence: MenuPresence;
+    /** The editor's command dispatch, which says what a keypress means at the card's block. */
+    commands: CommandDispatchContext;
 };
 declare const LinkCardHost: import("svelte").Component<$$ComponentProps, {}, "">;
 type LinkCardHost = ReturnType<typeof LinkCardHost>;

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

@@ -1,47 +1,44 @@
 /**
- * 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 type { Document } from '../../core/nodes';
 import type { InlineNode } from '../../core/nodes';
 import type { NodeView } from '../../core/node-views';
-import type { UndoController } from '../../editor-actions/deps';
+import type { InlineRangeCommit } from '../../editor-actions/inline-range-commit';
 import type { EditorEvents } from '../../editor-events';
-import type { LinkReferenceResolverRef } from '../../editor-keys';
-import type { GrammarView } from '../../schema/block-openers';
 import { type LinkTarget } from '../blocks/text/link-at-point';
 import type { CreateLinkTarget } from './link-card-state.svelte';
+import type { Reading } from '../../schema/reading';
 export interface LinkCardCommitterDeps {
     getDoc: () => Document;
     getEditorEl: () => HTMLElement | null;
-    /** The open card's target, read live: the anchor re-measures against whatever it names now. */
+    /** The open card's target, read live: the position re-measures against whatever it names. */
     getTarget: () => LinkTarget | null;
-    /** The create gesture's range, the anchor when no construct exists yet. */
+    /** The create gesture's range, what the card sits under when no construct exists yet. */
     getCreateTarget: () => CreateLinkTarget | null;
-    controller: UndoController;
+    /** The editor's inline range write, which every card edit goes through. */
+    inlineRange: InlineRangeCommit;
     events: EditorEvents;
-    /** Rect measure for a raw range in a mounted block — the anchoring geometry. */
+    /** Measures the rectangles of a raw range in a mounted block, which is what positions it. */
     measureRange: (path: number[], start: number, end: number) => DOMRect[];
-    /** Reveal + land the caret at a raw offset, so the next keystroke addresses the document. */
-    landCaret: (path: number[], offset: number) => Promise<boolean>;
-    linkRef?: LinkReferenceResolverRef;
-    grammar?: GrammarView;
+    reading: Reading;
 }
 export interface ResolvedLinkTarget {
     block: NodeView;
     link: InlineNode;
-    /** The destination as the author wrote it, decoded — what the card's field shows. */
+    /** The destination as the author wrote it, decoded: what the card's field shows. */
     url: string;
 }
 export interface LinkCardCommitter {
-    /** The construct the target names, re-read from the live tree; null once an edit removed it. */
+    /** The construct the target names, re-read from the live tree; null once an edit removes it. */
     resolve(target: LinkTarget): ResolvedLinkTarget | null;
-    /** The bytes a url commit would write, or null if the seam would decline — the card's dirty
-     *  check compares against these rather than deciding bytes itself. */
+    /** The bytes a url commit would write, or null if the write path would refuse; the card
+     *  compares against these rather than deciding the bytes itself. */
     buildBytes(target: LinkTarget, url: string): string | null;
     commitUrl(target: LinkTarget, url: string): void;
-    /** Mint `[selected text](url)` over the create range — the one write of the create gesture. */
+    /** Write `[selected text](url)` over the create range: the create gesture's one write. */
     commitCreate(target: CreateLinkTarget, url: string): void;
     removeLink(target: LinkTarget): void;
     /** Position `getCard()` under the link and keep it there across edits and scrolls. */

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;