@quillmark/svelte 0.1.0 → 0.2.0

package/dist/visual/Field.svelte

@@ -16,7 +16,7 @@
 <script lang="ts">
 	import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
 	import type { EditorErrorHandler } from '../core/errors.js';
-	import type { FieldController } from '../core/codec/index.js';
+	import type { LeafRegistry } from './leaves.js';
 	import type { FieldModel, FieldSpan } from './structure.js';
 	import { enumValues, ghostDefault, stringifyGhost } from './structure.js';
 	import type { FieldDomIds } from './domid.js';
@@ -42,22 +42,26 @@
 		doc: Document;
 		/** The schema a prose leaf reads its content through (`ProseField`). */
 		quill: Quill;
-		/** LIVE prose address (getter-`card`); used only when control === 'prose'. */
-		proseAddr: Addr;
+		/** This field's LIVE address (getter-`card`, so a card reorder re-targets in
+		 *  place): the prose leaf commits to it, and a focus reports it. */
+		addr: Addr;
 		leafKey: string;
 		/** This field's three DOM names, derived from `leafKey` (see `domid.ts`): how
 		 * the label and the control find each other. */
 		domIds: FieldDomIds;
 		onCommitScalar: (value: unknown) => void;
-		/** Enum-option policy: `false` disables that option. Only the enum
-		 * control reads it; other controls ignore it. */
+		/** Enum-option policy: `false` marks that option unavailable. Only the enum
+		 * control reads this pair. */
 		optionAllowed?: (value: string) => boolean;
+		/** How a refused option draws: greyed (default) or left out. */
+		enumDisallowed?: 'hide' | 'disable';
 		onFocus?: (addr: Addr) => void;
 		onCaretMove?: (addr: Addr, pos: number) => void;
 		onChange?: (addr: Addr) => void;
 		onError?: EditorErrorHandler;
-		register?: (key: string, controller: FieldController) => void;
-		unregister?: (key: string) => void;
+		/** The editor's leaf registry (`leaves.ts`): a form control registers its
+		 *  landing handle here, a prose leaf its controller from inside `ProseField`. */
+		leaves?: LeafRegistry;
 		diagnostics?: Diagnostic[];
 	}
 	let {
@@ -67,17 +71,17 @@
 		provenance,
 		doc,
 		quill,
-		proseAddr,
+		addr,
 		leafKey,
 		domIds,
 		onCommitScalar,
 		optionAllowed,
+		enumDisallowed,
 		onFocus,
 		onCaretMove,
 		onChange,
 		onError,
-		register,
-		unregister,
+		leaves,
 		diagnostics
 	}: Props = $props();
 
@@ -103,18 +107,66 @@
 	// nothing, and silently.
 	const describedBy = $derived(field.description ? domIds.description : undefined);
 
-	// Focus handoff for the two controls a label click cannot reach natively. Both
-	// expose their own `focus()` because "focusing" differs: a PM view restores a
-	// selection, a date field lands on its first segment.
+	// ── Focus: one answer, two callers (`leaves.ts`) ─────────────────────────────
+	// A label click and the editor's `focusField`/`setCaret` ask the same question, so
+	// they read the same function and cannot land in different places. The four
+	// labelable controls are reached through the DOM id `for` already points at; the
+	// rest own what focusing means and expose `focus()`, because it differs: a PM view
+	// restores a selection, a date field lands on its first segment, an array lands on
+	// its first element or on the add affordance that is all an empty one has, an
+	// object on its first property.
 	let proseEl = $state<{ focus: () => void } | undefined>();
 	let dateEl = $state<{ focus: () => void } | undefined>();
-	const onActivate = $derived(
-		field.control === 'prose'
-			? () => proseEl?.focus()
-			: field.control === 'date'
-				? () => dateEl?.focus()
-				: undefined
-	);
+	let arrayEl = $state<{ focus: () => void; focusElement: (k: number) => void } | undefined>();
+	let objectEl = $state<{ focus: () => void } | undefined>();
+	function focusControl(): void {
+		const owner = proseEl ?? dateEl ?? arrayEl ?? objectEl;
+		if (owner) return owner.focus();
+		document.getElementById(domIds.control)?.focus();
+	}
+	/** The array's per-ELEMENT landing, for the addresses the preview mints under an
+	 *  array field (`leaves.ts`); read at the call, so it tracks the mounted repeater. */
+	function focusElement(k: number): void {
+		arrayEl?.focusElement(k);
+	}
+	// Only where `for` cannot reach; the labelable four are the browser's own, and a
+	// second handler over them would be a focus the label already placed.
+	const onActivate = $derived(labelable ? undefined : focusControl);
+
+	/**
+	 * This field's landing handle. The wrapper is the bloom host rather than the
+	 * control: `bloomInside` appends an inset child and an `<input>` holds none.
+	 *
+	 * A prose leaf is absent here — it registers its own controller from inside
+	 * `ProseField`, carrying the codec seam this handle has no half of — and reactive
+	 * rather than mount-once, because a retype can swap the control under a leaf key
+	 * that does not remount.
+	 *
+	 * An array carries the per-element lane as well; no other control has elements for
+	 * an address to name.
+	 */
+	let controlEl = $state<HTMLElement | undefined>();
+	$effect(() => {
+		if (field.control === 'prose' || !controlEl || !leaves) return;
+		const key = leafKey;
+		const registry = leaves;
+		registry.registerControl(key, {
+			focus: focusControl,
+			focusElement: field.control === 'array' ? focusElement : undefined,
+			el: controlEl
+		});
+		return () => registry.unregisterControl(key);
+	});
+
+	/**
+	 * A form control has no controller to report its focus through, so the WRAPPER
+	 * reports: `focusin` bubbles, so one handler covers a plain input, an array's N
+	 * elements and an object's properties alike, and the active leaf names a scalar
+	 * field the way it names a prose one. A prose leaf reports through its own
+	 * controller — the source that drives its caret signals too — and is excluded here
+	 * rather than counted twice.
+	 */
+	const reportFocus = $derived(field.control === 'prose' ? undefined : () => onFocus?.(addr));
 </script>
 
 <div class="qm-field" class:cell={span === 'cell'} class:lone={span === 'lone'}>
@@ -129,13 +181,13 @@
 			description={field.description}
 		/>
 	{/if}
-	<div class="qm-field-control">
+	<div class="qm-field-control" bind:this={controlEl} onfocusin={reportFocus}>
 		{#if field.control === 'prose'}
 			<ProseField
 				{quill}
 				bind:this={proseEl}
 				{doc}
-				addr={proseAddr}
+				{addr}
 				inline={field.inline}
 				plaintext={field.plaintext}
 				labelledBy={domIds.label}
@@ -145,8 +197,7 @@
 				{onCaretMove}
 				{onChange}
 				{onError}
-				{register}
-				{unregister}
+				{leaves}
 			/>
 		{:else if field.control === 'enum'}
 			<EnumField
@@ -157,6 +208,7 @@
 				{describedBy}
 				onCommit={onCommitScalar}
 				{optionAllowed}
+				{enumDisallowed}
 			/>
 		{:else if field.control === 'number'}
 			<NumberField
@@ -186,6 +238,7 @@
 			/>
 		{:else if field.control === 'array'}
 			<ArrayField
+				bind:this={arrayEl}
 				value={value as unknown[] | undefined}
 				items={field.schema.items}
 				label={field.label}
@@ -194,10 +247,10 @@
 				labelId={domIds.label}
 				descriptionId={domIds.description}
 				onCommit={onCommitScalar}
-				onFocusEl={() => onFocus?.(proseAddr)}
 			/>
 		{:else if field.control === 'object'}
 			<ObjectField
+				bind:this={objectEl}
 				value={value as Record<string, unknown> | undefined}
 				properties={field.schema.properties}
 				label={field.label}
@@ -262,6 +315,15 @@
 	.qm-field.cell {
 		grid-column: span 1;
 	}
+	/* Positioned for the arrival wash a landing inserts (`core/bloom.ts`), the way
+	   `.qm-prose` is: an inset child over the control, since an `<input>` takes none.
+	   The radius is the control's own, so the wash's corners are the box's rather than
+	   square over a rounded one; on an array or a subform it bounds a group, where
+	   there is no single box for it to disagree with. */
+	.qm-field-control {
+		position: relative;
+		border-radius: var(--_qm-radius-inner);
+	}
 	/* A run of one takes half the capacity from column 1: `--cols-half` is the section's
 	 capacity halved, so the edge lands on a track boundary at every capacity. */
 	.qm-field.lone {

package/dist/visual/Field.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
-import type { FieldController } from '../core/codec/index.js';
+import type { LeafRegistry } from './leaves.js';
 import type { FieldModel, FieldSpan } from './structure.js';
 import type { FieldDomIds } from './domid.js';
 interface Props {
@@ -14,22 +14,26 @@ interface Props {
     doc: Document;
     /** The schema a prose leaf reads its content through (`ProseField`). */
     quill: Quill;
-    /** LIVE prose address (getter-`card`); used only when control === 'prose'. */
-    proseAddr: Addr;
+    /** This field's LIVE address (getter-`card`, so a card reorder re-targets in
+     *  place): the prose leaf commits to it, and a focus reports it. */
+    addr: Addr;
     leafKey: string;
     /** This field's three DOM names, derived from `leafKey` (see `domid.ts`): how
      * the label and the control find each other. */
     domIds: FieldDomIds;
     onCommitScalar: (value: unknown) => void;
-    /** Enum-option policy: `false` disables that option. Only the enum
-     * control reads it; other controls ignore it. */
+    /** Enum-option policy: `false` marks that option unavailable. Only the enum
+     * control reads this pair. */
     optionAllowed?: (value: string) => boolean;
+    /** How a refused option draws: greyed (default) or left out. */
+    enumDisallowed?: 'hide' | 'disable';
     onFocus?: (addr: Addr) => void;
     onCaretMove?: (addr: Addr, pos: number) => void;
     onChange?: (addr: Addr) => void;
     onError?: EditorErrorHandler;
-    register?: (key: string, controller: FieldController) => void;
-    unregister?: (key: string) => void;
+    /** The editor's leaf registry (`leaves.ts`): a form control registers its
+     *  landing handle here, a prose leaf its controller from inside `ProseField`. */
+    leaves?: LeafRegistry;
     diagnostics?: Diagnostic[];
 }
 declare const Field: import("svelte").Component<Props, {}, "">;

package/dist/visual/FieldHint.svelte

@@ -45,6 +45,39 @@
 	/** The root to portal INTO: `document.body` would escape the consumer's dials
 	 * along with the editor's subtree. `undefined` falls back to bits-ui's default. */
 	const portalTarget = $derived(triggerEl?.closest<HTMLElement>('[data-qm-root]') ?? undefined);
+
+	/** Placement, re-measured on each opening: the surface rides the label rung beside
+	 * the glyph, or stands over the field. */
+	let beside = $state(false);
+
+	/** Whether this description sets one line. Off a probe rather than the surface
+	 * itself, since the side is a prop the surface is positioned FROM, and a side chosen
+	 * after the fact moves a surface the reader is already looking at. The probe wears
+	 * the surface's own class inside the portal target, so it wraps to the same measure
+	 * under the same dials; `width: max-content` keeps that measure the class's rather
+	 * than the containing block's. Line boxes are counted off a range over the text
+	 * rather than derived from a height, which would need the line rung and the inset
+	 * restated here as numbers. A DOM with no layout yields none, which stands the
+	 * surface over the field. */
+	function ridesTheRung(): boolean {
+		const host = portalTarget ?? document.body;
+		const probe = document.createElement('div');
+		probe.className = 'qm-hint-popover';
+		probe.style.cssText =
+			'position:absolute;width:max-content;visibility:hidden;pointer-events:none';
+		probe.textContent = description;
+		host.appendChild(probe);
+		const range = document.createRange();
+		range.selectNodeContents(probe);
+		const lines = range.getClientRects().length;
+		probe.remove();
+		return lines === 1;
+	}
+
+	function raise(): void {
+		beside = ridesTheRung();
+		open = true;
+	}
 </script>
 
 <!-- The trigger is OURS, not `Popover.Trigger`, and the surface anchors to it:
@@ -60,7 +93,7 @@
 	aria-expanded={open}
 	aria-describedby={describedBy}
 	onpointerenter={(e) => {
-		if (e.pointerType !== 'touch') open = true;
+		if (e.pointerType !== 'touch') raise();
 	}}
 	onpointerleave={(e) => {
 		if (e.pointerType !== 'touch') open = false;
@@ -69,13 +102,16 @@
 		// Touch only, and a TOGGLE: the one modality with no hover to leave and no
 		// blur on the way out. A mouse press falls through to hover, which already
 		// has it open and will close it on the way off.
-		if (e.pointerType === 'touch') open = !open;
+		if (e.pointerType === 'touch') {
+			if (open) open = false;
+			else raise();
+		}
 	}}
 	onfocus={(e) => {
 		// Keyboard arrival only. A pointer press focuses the button too, and opening
 		// on that would re-open what the tap just toggled shut; `:focus-visible` is
 		// the UA's own answer to which arrival this was.
-		if (e.currentTarget.matches(':focus-visible')) open = true;
+		if (e.currentTarget.matches(':focus-visible')) raise();
 	}}
 	onblur={() => (open = false)}
 	onkeydown={(e) => {
@@ -88,12 +124,21 @@
 	}}><Icon name="info" size={13} /></button
 >
 
+<!-- PLACEMENT IS THE DESCRIPTION'S HEIGHT. One line rides the label rung beside its own
+ glyph, where the overhang past the rung's line box falls in the label-to-control gaps.
+ Anything taller stands over the field: beside the glyph it would hang onto THE CONTROL
+ IT DESCRIBES, the one overlap a reader cannot clear by reaching for what is hidden,
+ since a pointer leaving the trigger closes the surface. Over the field it covers a
+ neighbour's control instead, which reaching for it dismisses. -->
+<!-- `align="center"` for the rung, `"start"` over the field: centred, a surface taller
+ than the glyph's line box would hang half its height onto the field's own control. -->
+
 <Popover.Root bind:open>
 	<Popover.Portal to={portalTarget}>
 		<Popover.Content
 			customAnchor={triggerEl ?? null}
-			side="top"
-			align="start"
+			side={beside ? 'right' : 'top'}
+			align={beside ? 'center' : 'start'}
 			sideOffset={6}
 			trapFocus={false}
 			onOpenAutoFocus={(e: Event) => e.preventDefault()}
@@ -168,18 +213,22 @@
 	}
 	.qm-field-hint:hover,
 	.qm-field-hint:focus-visible {
-		color: var(--_qm-ink-meta);
+		color: var(--_qm-ink-label);
 	}
 	/* The lift, the translucency, the blur and the scale-in come from
 	 `.qm-popover-surface` (controls.css). This surface's own is a MEASURE: guidance
 	 is prose, and prose past ~40 characters a line stops being scannable; plus the
 	 inset and the meta type rung that keep it a note about a field rather than a
-	 second field. */
-	.qm-hint-popover {
+	 second field.
+
+	 Unscoped, because the placement probe wears this class on a node Svelte never
+	 compiled: a scoped rule would leave the probe wrapping to a different measure
+	 than the surface it stands in for, which is the one thing the probe must not do. */
+	:global(.qm-hint-popover) {
 		max-width: 22rem;
 		padding: var(--_qm-space) var(--_qm-space-2);
-		font-size: var(--_qm-text-meta);
+		font-size: var(--_qm-text-label);
 		line-height: var(--_qm-leading-body);
-		color: var(--_qm-ink-meta);
+		color: var(--_qm-ink-label);
 	}
 </style>

package/dist/visual/FormatPopover.svelte

@@ -385,10 +385,12 @@
 		gap: var(--_qm-space);
 		align-items: center;
 	}
+	/* The box's recipe without `.qm-input`, which adds the `width: 100%` that would
+	   stretch this to the popover. */
 	.qm-link-input {
 		font: inherit;
 		font-size: var(--_qm-text-body);
-		padding: var(--_qm-space) var(--_qm-space-2);
+		padding: var(--_qm-inset-control);
 		border: var(--_qm-border-width) solid var(--_qm-border);
 		border-radius: var(--_qm-radius-inner);
 		min-width: 12rem;

package/dist/visual/ObjectField.svelte

@@ -37,6 +37,19 @@
 	const entries = $derived(Object.entries(properties ?? {}));
 	const obj = $derived((value ?? {}) as Record<string, unknown>);
 
+	/** Take the caret: the FIRST property's control, a subform having no single control
+	 * of its own to land on. Resolved off the DOM rather than a ref per property: every
+	 * property is a scalar control the DOM already knows how to focus (the date field's
+	 * segments carry `tabindex`, the `literal` separators between them do not), so a
+	 * handle each would be five refs restating document order. An empty or wholly
+	 * unsupported subform lands nothing. */
+	let rootEl = $state<HTMLElement | undefined>();
+	export function focus(): void {
+		rootEl
+			?.querySelector<HTMLElement>('input, select, button, [tabindex]:not([tabindex="-1"])')
+			?.focus();
+	}
+
 	function commitProp(key: string, v: unknown): void {
 		if (v === undefined) {
 			// A nested control cleared (the unset rung): drop the key so the property
@@ -51,7 +64,13 @@
 	}
 </script>
 
-<div class="qm-object" role="group" aria-labelledby={labelledBy} aria-describedby={describedBy}>
+<div
+	bind:this={rootEl}
+	class="qm-object"
+	role="group"
+	aria-labelledby={labelledBy}
+	aria-describedby={describedBy}
+>
 	{#each entries as [key, sub] (key)}
 		{@const kind = controlKind(sub)}
 		{@const propLabel = `${label != null ? `${label} ` : ''}${sub.ui?.title ?? humanize(key)}`}
@@ -117,7 +136,7 @@
 		font-size: var(--_qm-text-label);
 		/* Soft (500), a rung under the top-level field label's 600: a nested object
 		   prop reads as secondary. Resolves the label-weight disagreement. */
-		font-weight: var(--_qm-weight-soft);
+		font-weight: var(--_qm-weight-label);
 		/* A label is a line, not a passage, so it overrides the root's reading
 		   rhythm the way every other label rung does. */
 		line-height: var(--_qm-leading-tight);

package/dist/visual/ObjectField.svelte.d.ts

@@ -12,6 +12,8 @@ interface Props {
     describedBy?: string;
     onCommit: (obj: Record<string, unknown>) => void;
 }
-declare const ObjectField: import("svelte").Component<Props, {}, "">;
+declare const ObjectField: import("svelte").Component<Props, {
+    focus: () => void;
+}, "">;
 type ObjectField = ReturnType<typeof ObjectField>;
 export default ObjectField;

package/dist/visual/ProseArrayElement.svelte

@@ -27,9 +27,8 @@
 		 * array repeater's Enter/Backspace (`ArrayField`). Fires BEFORE the view's own
 		 * keymap, so the state it reads is the one this keystroke has yet to change. */
 		onKey?: (e: KeyboardEvent) => void;
-		onFocusEl?: () => void;
 	}
-	let { value, plaintext, label, onChange, onKey, onFocusEl }: Props = $props();
+	let { value, plaintext, label, onChange, onKey }: Props = $props();
 
 	let containerEl: HTMLDivElement | undefined = $state();
 	let view: EditorView | undefined;
@@ -62,10 +61,6 @@
 				if (tr.docChanged) onChange(pmToContent(next.doc));
 			},
 			handleDOMEvents: {
-				focus: () => {
-					onFocusEl?.();
-					return false;
-				},
 				keydown: (_v, e) => {
 					onKey?.(e);
 					return false;

package/dist/visual/ProseArrayElement.svelte.d.ts

@@ -10,7 +10,6 @@ interface Props {
      * array repeater's Enter/Backspace (`ArrayField`). Fires BEFORE the view's own
      * keymap, so the state it reads is the one this keystroke has yet to change. */
     onKey?: (e: KeyboardEvent) => void;
-    onFocusEl?: () => void;
 }
 declare const ProseArrayElement: import("svelte").Component<Props, {
     focus: () => void;

package/dist/visual/ProseField.svelte

@@ -10,6 +10,7 @@
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import { createField, type FieldController, type SlashState } from '../core/codec/index.js';
+	import type { LeafRegistry } from './leaves.js';
 	import SlashMenu from './SlashMenu.svelte';
 	import { wording } from './strings.js';
 	import './controls.css';
@@ -54,8 +55,10 @@
 		/** A commit landed on this leaf: the prose change lane. */
 		onChange?: (addr: Addr) => void;
 		onError?: EditorErrorHandler;
-		register?: (key: string, controller: FieldController) => void;
-		unregister?: (key: string) => void;
+		/** The editor's leaf registry (`leaves.ts`). A prose leaf registers its
+		 *  CONTROLLER: the landing handle plus the codec seam a form control has no half
+		 *  of, which is what makes this leaf a caret target and not merely a focus one. */
+		leaves?: LeafRegistry;
 	}
 
 	let {
@@ -74,8 +77,7 @@
 		onCaretMove,
 		onChange,
 		onError,
-		register,
-		unregister
+		leaves
 	}: Props = $props();
 
 	let containerEl: HTMLDivElement | undefined = $state();
@@ -134,9 +136,9 @@
 			onChange,
 			onError
 		});
-		register?.(leafKey, controller);
+		leaves?.registerProse(leafKey, controller);
 		return () => {
-			unregister?.(leafKey);
+			leaves?.unregisterProse(leafKey);
 			controller?.destroy();
 			controller = undefined;
 		};
@@ -172,16 +174,22 @@
 		 own surface. */
 		position: relative;
 	}
-	/* A leaf the inline schema does NOT constrain (the body) is paper rather than a
-	 cell in a row of controls, so it opens at a few lines and grows. The floor is
-	 three LINE BOXES, not a length: size times leading is what one line measures, so
-	 both factors are named or the expression stops meaning the three lines it claims.
-	 It moves with the type ramp and with nothing else. Three is what an EMPTY body
+	/* A leaf the inline schema does NOT constrain is prose rather than a cell in a row
+	 of controls, so it opens at a few lines and grows. The floor is three LINE BOXES,
+	 not a length: `1em` rather than a size rung because which rung this leaf reads is
+	 the rule below's, and a second naming of it drifts. Three is what an EMPTY body
 	 costs, which is the only state the floor is ever the height: the ghost takes the
 	 first line, so the opening reads as an invitation with room under it rather than
 	 as a drop. */
 	.qm-prose-block {
-		min-height: calc(var(--_qm-text-body) * var(--_qm-leading-body) * 3);
+		min-height: calc(1em * var(--_qm-leading-body) * 3);
+	}
+	/* PAPER, and the box is what says so. Not `block` alone: `inline` is the quill's to
+	 declare, so a schema omitting it on a richtext field puts a block leaf in a field
+	 row, where the paper rung would break the height agreement `controls.css` builds by
+	 construction. */
+	.qm-prose-block:not(.qm-control-box) {
+		font-size: var(--_qm-text-paper);
 	}
 	/* The caret is the prose leaf's focus indicator, not a ring: a ring around a
 	 contenteditable reads as form chrome rather than as paper. So the outline is

package/dist/visual/ProseField.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type FieldController } from '../core/codec/index.js';
+import type { LeafRegistry } from './leaves.js';
 import './controls.css';
 import type { Document, Quill, Addr } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
@@ -40,8 +40,10 @@ interface Props {
     /** A commit landed on this leaf: the prose change lane. */
     onChange?: (addr: Addr) => void;
     onError?: EditorErrorHandler;
-    register?: (key: string, controller: FieldController) => void;
-    unregister?: (key: string) => void;
+    /** The editor's leaf registry (`leaves.ts`). A prose leaf registers its
+     *  CONTROLLER: the landing handle plus the codec seam a form control has no half
+     *  of, which is what makes this leaf a caret target and not merely a focus one. */
+    leaves?: LeafRegistry;
 }
 declare const ProseField: import("svelte").Component<Props, {
     focus: () => void;

package/dist/visual/TipsCard.svelte

@@ -185,7 +185,7 @@
 	   button carries a label and so widens its inset and takes the meta type rung. */
 	.qm-tips-action {
 		padding: var(--_qm-space-half) var(--_qm-space-2);
-		font-size: var(--_qm-text-meta);
+		font-size: var(--_qm-text-label);
 		color: var(--_qm-ink-label);
 	}
 </style>

package/dist/visual/VisualEditor.svelte

@@ -24,9 +24,8 @@
 -->
 <script lang="ts">
 	import { untrack } from 'svelte';
-	import { reportError } from '../core/errors.js';
-	import type { ContentHit } from '@quillmark/wasm';
-	import type { DocPath } from '../core/address.js';
+	import { reportRebindIgnored } from '../core/rebind.svelte.js';
+	import type { DocPath, Landing } from '../core/address.js';
 	import type { CardId } from './signals.js';
 	import type { VisualEditorProps } from './props.js';
 	import VisualEditorInner from './VisualEditorInner.svelte';
@@ -54,12 +53,10 @@
 			}
 			if (quill === boundQuill || reported) return;
 			reported = true;
-			reportError(props.onError, {
-				code: 'rebind-ignored',
-				severity: 'dev',
-				message:
-					'quill swapped in place; the mounted leaves still commit against the quill this doc mounted with. Swap the doc with it, or remount the editor, to rebind.'
-			});
+			reportRebindIgnored(
+				props.onError,
+				'quill swapped in place; the mounted leaves still commit against the quill this doc mounted with. Swap the doc with it, or remount the editor, to rebind.'
+			);
 		});
 	});
 
@@ -67,11 +64,13 @@
 	// landing between a swap and the incoming mount is a no-op rather than a throw,
 	// which is what lets a host hold ONE `bind:this` across two documents.
 
-	/** Place the caret at a preview hit. */
-	export async function setCaret(hit: ContentHit): Promise<void> {
-		await inner?.setCaret(hit);
+	/** Land a preview pick: a caret where the payload carries one and the leaf can
+	 *  spend it, an array element where the address names one, a focus otherwise. */
+	export async function setCaret(at: Landing): Promise<void> {
+		await inner?.setCaret(at);
 	}
-	/** Reveal and focus the leaf at `field`, without placing a caret inside it. */
+	/** Reveal and focus the field at `field` — any mounted one — without placing a
+	 *  caret inside it. */
 	export async function focusField(field: DocPath): Promise<void> {
 		await inner?.focusField(field);
 	}

package/dist/visual/VisualEditor.svelte.d.ts

@@ -1,9 +1,8 @@
-import type { ContentHit } from '@quillmark/wasm';
-import type { DocPath } from '../core/address.js';
+import type { DocPath, Landing } from '../core/address.js';
 import type { CardId } from './signals.js';
 import type { VisualEditorProps } from './props.js';
 declare const VisualEditor: import("svelte").Component<VisualEditorProps, {
-    setCaret: (hit: ContentHit) => Promise<void>;
+    setCaret: (at: Landing) => Promise<void>;
     focusField: (field: DocPath) => Promise<void>;
     insertCard: (kind: string, at?: number) => CardId | undefined;
     removeCard: (cardId: CardId) => void;