@voithos-labs/aragonite 0.10.3 → 0.10.7

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

@@ -1,19 +1,15 @@
 <script lang="ts">
-	import { untrack } from 'svelte';
+	import { tick, untrack } from 'svelte';
 	import {
 		LINK_CARD_LABEL,
 		LINK_CARD_OPEN,
 		LINK_CARD_REMOVE,
 		LINK_CARD_URL
 	} from '../../a11y-strings';
+	import MenuIcon from '../menu/MenuIcon.svelte';
 
-	// Anchored chrome over one link construct. Enter commits; Escape is the host's, since it must
-	// also close a card the document still has the caret for.
-	//
-	// `role="dialog"` WITHOUT `aria-modal`: a click leaves the card beside a live caret and the
-	// document behind stays the user's to type in, which is what aria-modal would tell a screen
-	// reader is false. The trap engages on ENTRY (Mod+K, or focus reaching the field), where the
-	// claim is true, and Escape returns the caret it borrowed.
+	// The URL panel over one link. Enter commits; Escape is the host's. Not `aria-modal`: a
+	// clicked card sits beside a live caret, and its focus trap starts only once focus enters.
 	let {
 		url,
 		canWrite,
@@ -21,46 +17,50 @@
 		onCommit,
 		onOpenLink,
 		onRemove,
+		opensCard,
 		resolveHref
 	}: {
 		url: string;
 		/** Bumped by each keyboard entry; the field takes focus when it changes. */
 		focusEpoch: number;
-		/** False when the write seam declines this construct outright — a rung-claimed link, which
-		 *  no url makes writable. Enter then does nothing rather than silently dropping the edit. */
+		/** False when the write path refuses this construct outright: a link owned by an inline
+		 *  syntax handler. Enter then does nothing rather than silently dropping the edit. */
 		canWrite: boolean;
 		onCommit: (url: string) => void;
 		onOpenLink: (url: string, event: MouseEvent) => void;
-		/** Absent in create mode: there is no construct to remove until Enter mints one. */
+		/** Absent in create mode: there is no construct to remove until Enter writes one. */
 		onRemove?: () => void;
-		/** The render path's own href funnel — a consumer rewrite, then the scheme allowlist.
-		 *  Undefined is a blocked scheme, and Open is the sink that must not receive one. */
+		/** Whether a keypress is a chord the keymap binds to opening this card. */
+		opensCard: (e: KeyboardEvent) => boolean;
+		/** The href as the render path resolves it: a consumer rewrite, then the scheme
+		 *  allowlist. Undefined means a blocked scheme, which Open must never be handed. */
 		resolveHref: (url: string) => string | undefined;
 	} = $props();
 
 	let draft = $state(untrack(() => url));
-	// The card OPENS on a blocked link so the URL can be repaired, but may not hand that URL
-	// onward: `onLinkActivate` reaches a shell's own opener, and this is the only door into it
-	// carrying a URL the user typed rather than the document's. An empty draft resolves as a
-	// relative URL, so it declines too.
+	// Open hands a typed URL to the host's opener, so it gets the render path's scheme check;
+	// an empty draft would resolve as a relative URL, so it is refused too.
 	const openable = $derived(draft.trim() === '' ? undefined : resolveHref(draft));
 	let seed = $state(untrack(() => url));
 	let cardEl: HTMLDivElement | undefined = $state();
 	let urlInput: HTMLInputElement | undefined = $state();
-	// Starts at the click's zero rather than at the prop: a card MOUNTED by the chord has a
-	// non-zero epoch already, and seeding from the prop would read that as "nothing to do".
+	// Starts at the click's zero rather than at the prop: a card mounted by the chord already
+	// has a non-zero counter, and starting from the prop would read that as "nothing to do".
 	let focusedEpoch = 0;
 
 	$effect(() => {
 		if (focusEpoch === focusedEpoch) return;
 		focusedEpoch = focusEpoch;
-		urlInput?.focus();
-		urlInput?.select();
+		// After the tick, not now: focusing the field before the host has placed the card, while it
+		// still sits at the editor's origin, scrolls the viewport to the top of the document.
+		void tick().then(() => {
+			urlInput?.focus();
+			urlInput?.select();
+		});
 	});
 
-	// The card follows the document while it is open: an undo — or any write landing from outside
-	// this gesture — moves the destination past the draft, and Enter would put the old bytes back.
-	// The in-flight draft is discarded rather than a committed change reverted.
+	// A write from outside the card (an undo) discards the draft, or Enter would put the earlier
+	// bytes back.
 	$effect(() => {
 		if (url === seed) return;
 		seed = url;
@@ -91,12 +91,9 @@
 			stepTrap(e.shiftKey);
 			return;
 		}
-		// The entry chord re-asserts the card the focus is already inside, so it is a no-op here —
-		// but a consumed one: no surface the editor owns hands `Mod+K` back to the browser.
-		// CapsLock uppercases the key without a Shift modifier, which is still the plain chord.
-		if ((e.ctrlKey || e.metaKey) && !e.altKey && !e.shiftKey && (e.key === 'k' || e.key === 'K')) {
-			e.preventDefault();
-		}
+		// The chord that opens the card does nothing inside it, but is still consumed so the
+		// browser never runs its own action for that chord.
+		if (opensCard(e)) e.preventDefault();
 	}
 
 	function handleUrlKeyDown(e: KeyboardEvent): void {
@@ -117,74 +114,128 @@
 	tabindex="-1"
 	onkeydown={handleKeyDown}
 >
-	<label>
-		<span>URL</span>
+	<label class="md-link-card-field">
+		<span class="md-link-card-caption">URL</span>
 		<input
 			bind:this={urlInput}
 			bind:value={draft}
 			type="text"
 			aria-label={LINK_CARD_URL}
+			placeholder="https://"
 			onkeydown={handleUrlKeyDown}
 		/>
 	</label>
 	<div class="md-link-card-actions">
 		<button
 			type="button"
+			class="md-link-card-btn"
+			aria-label={LINK_CARD_OPEN}
+			title={LINK_CARD_OPEN}
 			disabled={openable === undefined}
-			onclick={(e) => openable !== undefined && onOpenLink(openable, e)}>{LINK_CARD_OPEN}</button
+			onclick={(e) => openable !== undefined && onOpenLink(openable, e)}
 		>
+			<MenuIcon name="external-link" />
+		</button>
 		{#if onRemove}
-			<button type="button" onclick={onRemove}>{LINK_CARD_REMOVE}</button>
+			<button
+				type="button"
+				class="md-link-card-btn"
+				aria-label={LINK_CARD_REMOVE}
+				title={LINK_CARD_REMOVE}
+				onclick={onRemove}
+			>
+				<MenuIcon name="unlink" />
+			</button>
 		{/if}
 	</div>
 </div>
 
 <style>
+	/* Styled like the editor's menus (`.md-menu`, editor.css) and the image alt field, so the card
+	   reads as one of the editor's popovers rather than a form. */
 	.md-link-card {
 		position: absolute;
 		top: 0;
 		left: 0;
 		z-index: 100;
-		display: grid;
+		display: flex;
+		align-items: flex-end;
 		gap: 6px;
-		min-width: 280px;
-		padding: 8px;
-		border: 1px solid var(--color-ui-muted, #a4a4a4);
-		border-radius: 4px;
-		background: var(--color-bg-elevated, #2a2a2a);
-		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+		width: 300px;
+		padding: 8px 8px 8px 10px;
+		box-sizing: border-box;
+		background: var(--color-bg, #2c2c2a);
+		border: 1px solid var(--color-border, #3e3e3b);
+		border-radius: 8px;
+		box-shadow: var(--menu-shadow, 0 12px 32px rgba(0, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.35));
+		font-family: var(--font-ui, system-ui, sans-serif);
+		font-size: 13px;
+		line-height: 1.4;
+		color: var(--color-text-primary, #e8e8e5);
 	}
-	label {
-		display: grid;
-		grid-template-columns: 40px 1fr;
-		align-items: center;
-		gap: 8px;
+	.md-link-card-field {
+		flex: 1;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 5px;
+	}
+	.md-link-card-caption {
+		font-size: 10.5px;
+		font-weight: 600;
+		letter-spacing: 0.06em;
+		text-transform: uppercase;
+		color: var(--color-text-muted, #aaaaaa);
 	}
-	input {
-		padding: 4px 6px;
-		border: 1px solid var(--color-ui-muted, #a4a4a4);
-		border-radius: var(--radius-ui, 3px);
-		background: var(--color-surface, #2d3033);
-		color: var(--color-text-secondary, #eee);
+	/* Underlined, not boxed: a box inside the rounded card would read as a frame in a frame. */
+	.md-link-card-field input {
+		width: 100%;
+		box-sizing: border-box;
+		background: transparent;
+		color: var(--color-text-primary, #e8e8e5);
+		border: none;
+		border-bottom: 1px solid var(--color-border, #3e3e3b);
+		border-radius: 0;
+		padding: 3px 1px 5px;
 		font-family: inherit;
-		font-size: 12px;
+		font-size: 13px;
+		line-height: 1.4;
+		outline: none;
+		transition: border-color 120ms ease-out;
+	}
+	.md-link-card-field input:focus {
+		border-bottom-color: var(--color-accent, #567b67);
+	}
+	.md-link-card-field input::placeholder {
+		color: var(--color-text-muted, #aaaaaa);
 	}
 	.md-link-card-actions {
 		display: flex;
-		gap: 6px;
-		justify-content: flex-end;
+		gap: 2px;
+		/* The buttons sit level with the input's rule, not with the caption. */
+		padding-bottom: 1px;
 	}
-	button {
-		padding: 3px 8px;
-		border: 1px solid var(--color-ui-muted, #a4a4a4);
-		border-radius: var(--radius-ui, 3px);
+	.md-link-card-btn {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 26px;
+		height: 26px;
+		padding: 0;
+		border: none;
+		border-radius: 6px;
 		background: transparent;
-		color: var(--color-text-secondary, #eee);
-		font: inherit;
-		font-size: 12px;
+		color: var(--color-ui-muted, #93938d);
 		cursor: pointer;
 	}
-	button:hover {
-		background: var(--color-ui-faint, rgba(255, 255, 255, 0.07));
+	.md-link-card-btn:hover:not(:disabled),
+	.md-link-card-btn:focus-visible {
+		background: var(--menu-item-hover, rgba(255, 255, 255, 0.07));
+		color: var(--color-text-primary, #e8e8e5);
+		outline: none;
+	}
+	.md-link-card-btn:disabled {
+		opacity: 0.4;
+		cursor: default;
 	}
 </style>

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

@@ -2,15 +2,17 @@ type $$ComponentProps = {
     url: string;
     /** Bumped by each keyboard entry; the field takes focus when it changes. */
     focusEpoch: number;
-    /** False when the write seam declines this construct outright — a rung-claimed link, which
-     *  no url makes writable. Enter then does nothing rather than silently dropping the edit. */
+    /** False when the write path refuses this construct outright: a link owned by an inline
+     *  syntax handler. Enter then does nothing rather than silently dropping the edit. */
     canWrite: boolean;
     onCommit: (url: string) => void;
     onOpenLink: (url: string, event: MouseEvent) => void;
-    /** Absent in create mode: there is no construct to remove until Enter mints one. */
+    /** Absent in create mode: there is no construct to remove until Enter writes one. */
     onRemove?: () => void;
-    /** The render path's own href funnel — a consumer rewrite, then the scheme allowlist.
-     *  Undefined is a blocked scheme, and Open is the sink that must not receive one. */
+    /** Whether a keypress is a chord the keymap binds to opening this card. */
+    opensCard: (e: KeyboardEvent) => boolean;
+    /** The href as the render path resolves it: a consumer rewrite, then the scheme
+     *  allowlist. Undefined means a blocked scheme, which Open must never be handed. */
     resolveHref: (url: string) => string | undefined;
 };
 declare const LinkCard: import("svelte").Component<$$ComponentProps, {}, "">;

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. */