@voithos-labs/aragonite 0.10.1

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

@@ -0,0 +1,190 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import {
+		LINK_CARD_LABEL,
+		LINK_CARD_OPEN,
+		LINK_CARD_REMOVE,
+		LINK_CARD_URL
+	} from '../../a11y-strings';
+
+	// 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.
+	let {
+		url,
+		canWrite,
+		focusEpoch,
+		onCommit,
+		onOpenLink,
+		onRemove,
+		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. */
+		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. */
+		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. */
+		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.
+	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".
+	let focusedEpoch = 0;
+
+	$effect(() => {
+		if (focusEpoch === focusedEpoch) return;
+		focusedEpoch = focusEpoch;
+		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.
+	$effect(() => {
+		if (url === seed) return;
+		seed = url;
+		draft = url;
+	});
+
+	function focusStops(): HTMLElement[] {
+		return cardEl
+			? Array.from(cardEl.querySelectorAll<HTMLElement>('input, button:not([disabled])'))
+			: [];
+	}
+
+	function stepTrap(backwards: boolean): void {
+		const stops = focusStops();
+		if (stops.length === 0) return;
+		const current =
+			document.activeElement instanceof HTMLElement ? stops.indexOf(document.activeElement) : -1;
+		const next = (current === -1 ? 0 : current + (backwards ? -1 : 1)) % stops.length;
+		stops[(next + stops.length) % stops.length].focus();
+	}
+
+	function handleKeyDown(e: KeyboardEvent): void {
+		// An IME's confirm/step keystrokes arrive as ordinary keydowns mid-composition; they are
+		// the composition's, never the card's.
+		if (e.isComposing) return;
+		if (e.key === 'Tab') {
+			e.preventDefault();
+			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();
+		}
+	}
+
+	function handleUrlKeyDown(e: KeyboardEvent): void {
+		if (e.isComposing) return;
+		if (e.key === 'Enter') {
+			e.preventDefault();
+			if (canWrite) onCommit(draft);
+		}
+	}
+</script>
+
+<div
+	bind:this={cardEl}
+	class="md-link-card"
+	data-link-card
+	role="dialog"
+	aria-label={LINK_CARD_LABEL}
+	tabindex="-1"
+	onkeydown={handleKeyDown}
+>
+	<label>
+		<span>URL</span>
+		<input
+			bind:this={urlInput}
+			bind:value={draft}
+			type="text"
+			aria-label={LINK_CARD_URL}
+			onkeydown={handleUrlKeyDown}
+		/>
+	</label>
+	<div class="md-link-card-actions">
+		<button
+			type="button"
+			disabled={openable === undefined}
+			onclick={(e) => openable !== undefined && onOpenLink(openable, e)}>{LINK_CARD_OPEN}</button
+		>
+		{#if onRemove}
+			<button type="button" onclick={onRemove}>{LINK_CARD_REMOVE}</button>
+		{/if}
+	</div>
+</div>
+
+<style>
+	.md-link-card {
+		position: absolute;
+		top: 0;
+		left: 0;
+		z-index: 100;
+		display: grid;
+		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);
+	}
+	label {
+		display: grid;
+		grid-template-columns: 40px 1fr;
+		align-items: center;
+		gap: 8px;
+	}
+	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);
+		font-family: inherit;
+		font-size: 12px;
+	}
+	.md-link-card-actions {
+		display: flex;
+		gap: 6px;
+		justify-content: flex-end;
+	}
+	button {
+		padding: 3px 8px;
+		border: 1px solid var(--color-ui-muted, #a4a4a4);
+		border-radius: var(--radius-ui, 3px);
+		background: transparent;
+		color: var(--color-text-secondary, #eee);
+		font: inherit;
+		font-size: 12px;
+		cursor: pointer;
+	}
+	button:hover {
+		background: var(--color-ui-faint, rgba(255, 255, 255, 0.07));
+	}
+</style>

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

@@ -0,0 +1,18 @@
+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. */
+    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. */
+    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. */
+    resolveHref: (url: string) => string | undefined;
+};
+declare const LinkCard: import("svelte").Component<$$ComponentProps, {}, "">;
+type LinkCard = ReturnType<typeof LinkCard>;
+export default LinkCard;

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

@@ -0,0 +1,181 @@
+<script lang="ts">
+	import type { Document } from '../../core/nodes';
+	import type { UndoController } from '../../editor-actions/deps';
+	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';
+
+	// 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,
+		events,
+		getDoc,
+		getEditorEl,
+		measureRange,
+		landCaret,
+		activateLink,
+		resolveLinkUrl,
+		caretRestore,
+		linkRef,
+		grammar
+	}: {
+		card: LinkCardState;
+		controller: UndoController;
+		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. */
+		resolveLinkUrl: (rawUrl: string) => string;
+		caretRestore: CaretRestore;
+		linkRef?: LinkReferenceResolverRef;
+		grammar?: GrammarView;
+	} = $props();
+
+	let cardEl: HTMLDivElement | undefined = $state();
+
+	// Props are stable for the editor's lifetime; reactive values already cross as getters.
+	// svelte-ignore state_referenced_locally
+	const linkCard = createLinkCardCommitter({
+		getDoc,
+		getEditorEl,
+		getTarget: card.getTarget,
+		getCreateTarget: card.getCreateTarget,
+		controller,
+		events,
+		measureRange,
+		landCaret,
+		linkRef,
+		grammar
+	});
+
+	$effect(() => {
+		card.getTarget(); // re-run + re-anchor when the card moves to another link
+		card.getCreateTarget();
+		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.
+	$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.
+	$effect(() => {
+		if (!card.getCreateTarget()) return;
+		return events.on('edit', () => {
+			if (card.getCreateTarget()) card.close();
+		});
+	});
+
+	// 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.
+	$effect(() => {
+		if (!card.getTarget() && !card.getCreateTarget()) return;
+		const onPointerDown = (e: PointerEvent) => {
+			const el = e.target as Element | null;
+			if (el?.closest('[data-link-card]')) return;
+			card.close();
+		};
+		const onKeyDown = (e: KeyboardEvent) => {
+			// 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.
+			if (inCard) {
+				e.preventDefault();
+				e.stopPropagation();
+			}
+			card.close();
+			if (inCard) caretRestore.restore();
+		};
+		document.addEventListener('pointerdown', onPointerDown, true);
+		document.addEventListener('keydown', onKeyDown, true);
+		return () => {
+			document.removeEventListener('pointerdown', onPointerDown, true);
+			document.removeEventListener('keydown', onKeyDown, true);
+		};
+	});
+
+	function commit(url: string): void {
+		const target = card.getTarget();
+		if (!target) return;
+		card.close();
+		linkCard.commitUrl(target, url);
+	}
+
+	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.
+		if (!target || url.trim() === '') return;
+		card.close();
+		linkCard.commitCreate(target, url);
+	}
+
+	function remove(): void {
+		const target = card.getTarget();
+		if (!target) return;
+		card.close();
+		linkCard.removeLink(target);
+	}
+</script>
+
+{#if card.getTarget()}
+	{@const target = card.getTarget()!}
+	{@const resolved = linkCard.resolve(target)}
+	{#if resolved}
+		<div bind:this={cardEl} class="md-link-card-anchor">
+			{#key `${target.path.join(',')}@${target.sourceStart}`}
+				<LinkCard
+					url={resolved.url}
+					focusEpoch={card.getFocusEpoch()}
+					canWrite={linkCard.buildBytes(target, resolved.url) !== null}
+					onCommit={commit}
+					onOpenLink={activateLink}
+					onRemove={remove}
+					resolveHref={(url) => resolveHref({ resolveLinkUrl }, url)}
+				/>
+			{/key}
+		</div>
+	{/if}
+{:else if card.getCreateTarget()}
+	{@const create = card.getCreateTarget()!}
+	<div bind:this={cardEl} class="md-link-card-anchor">
+		{#key `${create.path.join(',')}@${create.start}-${create.end}`}
+			<LinkCard
+				url=""
+				focusEpoch={card.getFocusEpoch()}
+				canWrite={true}
+				onCommit={commitCreate}
+				onOpenLink={activateLink}
+				resolveHref={(url) => resolveHref({ resolveLinkUrl }, url)}
+			/>
+		{/key}
+	</div>
+{/if}
+
+<style>
+	/* Zero-size positioned box: `syncCardToLink` writes its top/left, the card paints inside it. */
+	.md-link-card-anchor {
+		position: absolute;
+		top: 0;
+		left: 0;
+	}
+</style>

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

@@ -0,0 +1,25 @@
+import type { Document } from '../../core/nodes';
+import type { UndoController } from '../../editor-actions/deps';
+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';
+type $$ComponentProps = {
+    card: LinkCardState;
+    controller: UndoController;
+    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. */
+    resolveLinkUrl: (rawUrl: string) => string;
+    caretRestore: CaretRestore;
+    linkRef?: LinkReferenceResolverRef;
+    grammar?: GrammarView;
+};
+declare const LinkCardHost: import("svelte").Component<$$ComponentProps, {}, "">;
+type LinkCardHost = ReturnType<typeof LinkCardHost>;
+export default LinkCardHost;

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

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+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 { 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';
+export interface LinkCardCommitterDeps {
+    getDoc: () => Document;
+    getEditorEl: () => HTMLElement | null;
+    /** The open card's target, read live: the anchor re-measures against whatever it names now. */
+    getTarget: () => LinkTarget | null;
+    /** The create gesture's range, the anchor when no construct exists yet. */
+    getCreateTarget: () => CreateLinkTarget | null;
+    controller: UndoController;
+    events: EditorEvents;
+    /** Rect measure for a raw range in a mounted block — the anchoring geometry. */
+    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;
+}
+export interface ResolvedLinkTarget {
+    block: NodeView;
+    link: InlineNode;
+    /** 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. */
+    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. */
+    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. */
+    commitCreate(target: CreateLinkTarget, url: string): void;
+    removeLink(target: LinkTarget): void;
+    /** Position `getCard()` under the link and keep it there across edits and scrolls. */
+    syncCardToLink(getCard: () => HTMLElement | null): () => void;
+}
+export declare function createLinkCardCommitter(deps: LinkCardCommitterDeps): LinkCardCommitter;

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

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+import { wireOverlayRemeasure } from '../../cursor/overlay-remeasure';
+import { createInlineRangeCommit } from '../../editor-actions/inline-range-commit';
+import { isBlockNode, nodeAt } from '../../tree-operations/node-ops';
+import { linkConstructAt } from '../blocks/text/link-at-point';
+import { buildLinkEditBytes, buildLinkUnwrapBytes, buildLinkWrapBytes, linkFieldsFromInline } from '../blocks/text/link-source-bytes';
+export function createLinkCardCommitter(deps) {
+    const inlineRange = createInlineRangeCommit({
+        getDoc: deps.getDoc,
+        controller: deps.controller,
+        grammar: deps.grammar
+    });
+    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);
+        return link === null ? null : { block, link, url: link.url ?? '' };
+    }
+    function editBytes(target, url) {
+        const resolved = resolve(target);
+        if (!resolved)
+            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.
+        const fields = url === current.url
+            ? current
+            : {
+                text: current.text,
+                url,
+                ...(current.title !== undefined ? { title: current.title } : {})
+            };
+        const bytes = buildLinkEditBytes(link, block.raw, fields, deps.linkRef?.current);
+        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.
+        const resolved = resolve(target);
+        if (!resolved || url === resolved.url)
+            return;
+        const edit = editBytes(target, url);
+        if (!edit)
+            return;
+        void write(target.path, edit.link.start, edit.link.end, edit.bytes);
+    }
+    function commitCreate(target, url) {
+        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);
+        if (bytes === null)
+            return;
+        void write(target.path, target.start, target.end, bytes);
+    }
+    function removeLink(target) {
+        const resolved = resolve(target);
+        if (!resolved)
+            return;
+        const bytes = buildLinkUnwrapBytes(resolved.link, resolved.block.raw, deps.linkRef?.current);
+        if (bytes === null)
+            return;
+        void write(target.path, resolved.link.start, resolved.link.end, bytes);
+    }
+    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);
+    }
+    /** The raw range the card anchors under: the resolved construct, or the create range as-is. */
+    function anchoredRange() {
+        const target = deps.getTarget();
+        if (target) {
+            const resolved = resolve(target);
+            return resolved
+                ? { path: target.path, start: resolved.link.start, end: resolved.link.end }
+                : null;
+        }
+        return deps.getCreateTarget();
+    }
+    function syncCardToLink(getCard) {
+        const cardEl = getCard();
+        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.
+        const measure = () => {
+            const range = anchoredRange();
+            if (!range)
+                return;
+            const rect = deps.measureRange(range.path, range.start, range.end)[0];
+            if (!rect)
+                return;
+            const editorRect = editorEl.getBoundingClientRect();
+            const style = getComputedStyle(editorEl);
+            const borderTop = parseFloat(style.borderTopWidth) || 0;
+            const borderLeft = parseFloat(style.borderLeftWidth) || 0;
+            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.
+        const unwireScroll = wireOverlayRemeasure({
+            el: cardEl,
+            editorRoot: editorEl,
+            blockRef: undefined,
+            measure,
+            untrackSetupMeasure: true
+        });
+        // An edit anywhere above the link shifts its y without touching the link itself.
+        const unsubscribe = deps.events.on('edit', measure);
+        window.addEventListener('resize', measure);
+        return () => {
+            unwireScroll();
+            unsubscribe();
+            window.removeEventListener('resize', measure);
+        };
+    }
+    return { resolve, buildBytes, commitUrl, commitCreate, removeLink, syncCardToLink };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * `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.
+ */
+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. */
+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. */
+    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. */
+    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.
+ */
+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.
+ */
+export declare function enterLinkCardAtCaret(query: LinkCardEntryQuery): void;