@quillmark/svelte 0.1.0 → 0.2.0

package/dist/core/lifecycle.js

@@ -1,21 +1,47 @@
 // `@quillmark/wasm` ships wasm-bindgen's web target: the core build is
-// instantiated by an explicit `await init()`, and every export throws
-// `runtime::not_initialized` until it resolves. Instantiation carries the panic
-// hook on its start section, so a Rust panic reaches JS as a stack trace.
+// instantiated by an explicit `await init()`, which RESOLVES TO the classes and
+// free functions — the artifact exports none of them statically, so awaiting is
+// the only way to hold one. Instantiation carries the panic hook on its start
+// section, so a Rust panic reaches JS as a stack trace.
 import { init as initWasm } from '@quillmark/wasm';
 let started;
+/** The resolved surface, for the sync verbs below that cannot await one. */
+let latched;
 /**
- * Instantiate the core WASM build. Await once before any other boundary verb,
- * from any surface's setup path; the promise is memoized, so concurrent callers
- * share one instantiation and repeat calls are free. A failed init clears the
- * memo, leaving a retry possible.
+ * Instantiate the core WASM build and resolve to its surface. Await once before
+ * any other boundary verb, from any surface's setup path; the promise is memoized,
+ * so concurrent callers share one instantiation and repeat calls are free. A failed
+ * init clears the memo, leaving a retry possible.
+ *
+ * The surface is the artifact's own, handed back unchanged: `const { Quill, Document }
+ * = await init()` is the whole of a host's access to the classes, and this package
+ * re-declares none of it.
  */
 export function init() {
     if (started)
         return started;
-    started = initWasm().catch((err) => {
+    started = initWasm().then((surface) => {
+        latched = surface;
+        return surface;
+    }, (err) => {
         started = undefined;
         throw err;
     });
     return started;
 }
+/**
+ * The surface synchronously, for this package's pure verbs: the `DocPath` formatter
+ * on the public API and the codec inside a ProseMirror transaction, neither of which
+ * can await. Package-internal, and read at the call rather than destructured at
+ * module scope, so no module's import graph carries an ordering constraint.
+ *
+ * Reaching one before {@link init} resolves throws, naming the fix. This is the seam
+ * that turns an awaited surface back into sync verbs, so it is the one place the
+ * precondition the gate made structural has to be stated again.
+ */
+export function core() {
+    if (!latched) {
+        throw new Error('@quillmark/svelte: the WASM core is not initialized. Await `init()` from `@quillmark/svelte/core` before mounting a surface or calling a boundary verb.');
+    }
+    return latched;
+}

package/dist/core/rebind.svelte.d.ts

@@ -3,10 +3,24 @@ import { type EditorErrorHandler } from './errors.js';
 export type Bound = Record<string, unknown> & {
     onError?: EditorErrorHandler;
 };
+/**
+ * Report the violation, then throw it in a dev build. Both surfaces raise it here; the
+ * guards themselves stay separate, since the preview snapshots its props once and the
+ * editor re-reads its pair on every re-key.
+ *
+ * The report alone reaches whoever bound `onError` at mount, and a consumer swapping
+ * that handler beside the handle it belongs to is the case this exists for: they are
+ * told through the sink they just abandoned. A throw needs no handler to arrive.
+ *
+ * It costs the surface nothing: an effect that throws neither unmounts its tree nor
+ * stops the ones beside it, so the surface goes on serving what it bound, which is the
+ * very state being reported.
+ */
+export declare function reportRebindIgnored(onError: EditorErrorHandler | undefined, message: string): void;
 /**
  * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped
- * in place. `remount` closes the message with the surface's own remount spelling
- * (`Remount the preview ({#key session}) to rebind.`).
+ * in place, and in a dev build throw it after. `remount` closes the message with the
+ * surface's own remount spelling (`Remount the preview ({#key session}) to rebind.`).
  *
  * Mounted identities are recorded on the effect's FIRST run, the flush the surface
  * binds in; every later comparison reads them through the same `snapshot`.

package/dist/core/rebind.svelte.js

@@ -1,16 +1,38 @@
 // The remount contract, enforced. `Preview` binds its props ONCE, in `onMount`, and
 // observes nothing after: the vanilla core below it owns scroll position, mounted
 // slots and observer sets that a remount would discard on every apply. So a prop
-// swapped in place is reported, not dropped in silence.
+// swapped in place is reported, not dropped in silence, and thrown in a dev build.
 //
 // A guard over ONE prop of a set is worse than none: a consumer who learns the
 // surface complains when it ignores a prop reads silence on the rest as reactivity.
 // The snapshot is every once-bound prop, and one report names whichever went stale.
 import { reportError } from './errors.js';
+// True in a dev build whose bundler injects `import.meta.env`. Cast, since the package
+// declares no bundler's ambient types; false where nothing injects it, so a toolchain
+// that does not answer gets the report alone.
+const DEV = import.meta.env?.DEV === true;
+/**
+ * Report the violation, then throw it in a dev build. Both surfaces raise it here; the
+ * guards themselves stay separate, since the preview snapshots its props once and the
+ * editor re-reads its pair on every re-key.
+ *
+ * The report alone reaches whoever bound `onError` at mount, and a consumer swapping
+ * that handler beside the handle it belongs to is the case this exists for: they are
+ * told through the sink they just abandoned. A throw needs no handler to arrive.
+ *
+ * It costs the surface nothing: an effect that throws neither unmounts its tree nor
+ * stops the ones beside it, so the surface goes on serving what it bound, which is the
+ * very state being reported.
+ */
+export function reportRebindIgnored(onError, message) {
+    reportError(onError, { code: 'rebind-ignored', severity: 'dev', message });
+    if (DEV)
+        throw new Error(`[quillmark/ui] rebind-ignored: ${message}`);
+}
 /**
  * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped
- * in place. `remount` closes the message with the surface's own remount spelling
- * (`Remount the preview ({#key session}) to rebind.`).
+ * in place, and in a dev build throw it after. `remount` closes the message with the
+ * surface's own remount spelling (`Remount the preview ({#key session}) to rebind.`).
  *
  * Mounted identities are recorded on the effect's FIRST run, the flush the surface
  * binds in; every later comparison reads them through the same `snapshot`.
@@ -35,10 +57,6 @@ export function guardRebind(snapshot, remount) {
         if (stale.length === 0)
             return;
         reported = true;
-        reportError(bound.onError, {
-            code: 'rebind-ignored',
-            severity: 'dev',
-            message: `${stale.join(', ')} swapped in place; the mounted surface still holds what it bound at mount. ${remount}`
-        });
+        reportRebindIgnored(bound.onError, `${stale.join(', ')} swapped in place; the mounted surface still holds what it bound at mount. ${remount}`);
     });
 }

package/dist/core/theme.css

@@ -12,6 +12,13 @@
    on the root rule (`font-family`) that every root then inherits, and a free
    `style` attribute for the consumer.
 
+   That import carries no binding, so it survives a consumer's bundler only because
+   the package claims `sideEffects: true`. Pruned, every rung below is undefined,
+   every `var()` reading one is invalid at computed-value time, and the declaration
+   holding it drops: a control with no border, no background and no padding, under
+   chrome that still reads as intact. `check:bundle` holds both ends, the claim and
+   the built bytes.
+
    Every value stays a `var()` reference, so the dials resolve against the CASCADE
    at each root: a consumer's `[data-theme="dark"]` ancestor rule flows in
    unchanged, the light/dark default follows the `color-scheme` the host declares
@@ -98,12 +105,13 @@
 		--_qm-border: color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 17%);
 		/* A rule that separates without structuring: the lines BETWEEN a table's cells,
 		   where the frame around them is the structure. Half the border's mix rather
-		   than a fourth surface rung, because it is a stroke and reads against the
+		   than a surface rung of its own, because it is a stroke and reads against the
 		   surface behind it, not a fill stacked on one. */
 		--_qm-border-faint: color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 9%);
+		/* A fourth step between `label` and `ghost` is a number with no fourth kind of
+		   text under it. */
 		--_qm-ink: var(--_qm-fg);
 		--_qm-ink-label: color-mix(in oklab, var(--_qm-fg), var(--_qm-bg) 35%);
-		--_qm-ink-meta: color-mix(in oklab, var(--_qm-fg), var(--_qm-bg) 45%);
 		--_qm-ink-ghost: color-mix(in oklab, var(--_qm-fg), var(--_qm-bg) 60%);
 		/* The correlation wash (`core/bloom.ts`). Its alpha is a PEAK, not a tint: the
 		   wash animates from and back to zero, never held, so it reads at pane scale
@@ -134,7 +142,12 @@
 		   only up to the point where it is assembled. ONE width: focus is the only
 		   state that draws a ring anywhere, so there is no held-back tier under it. */
 		--_qm-ring-width: 2px;
-		--_qm-ring-focus: var(--_qm-ring-width) solid var(--_qm-accent);
+		/* Every ring the surface draws, whatever the state under it: focus and selection
+		   alike, which is why the name carries neither. Assembled here because the parts
+		   spelled out at a use site pass every axis — each reads a rung — while drawing a
+		   ring nothing else agrees with. The width stays separately reachable: a drop
+		   indicator is the ring's thickness without being a ring. */
+		--_qm-ring: var(--_qm-ring-width) solid var(--_qm-accent);
 		--_qm-ring-offset: 1px;
 
 		/* ── Motion ──────────────────────────────────────────────────────────────
@@ -147,12 +160,11 @@
 		   animates over WAAPI and reads it from here. */
 		--_qm-bloom-dwell: 1100ms;
 
-		/* One curve per role, the role being what the trip's two endpoints ARE.
-		   `reverse` is the only one that has to be symmetric: it is the only one an
-		   interruption turns around. */
+		/* ONE curve, symmetric because an interruption turns these trips around: a hover
+		   leaves before it arrives, a card collapses mid-expand. The one-way pair a scale
+		   like this often carries is minted when a trip long enough to read one arrives;
+		   the popover's pop is the nearest and at `fast` it is under that threshold. */
 		--_qm-ease-reverse: cubic-bezier(0.4, 0, 0.6, 1);
-		--_qm-ease-arrive: cubic-bezier(0, 0, 0.2, 1);
-		--_qm-ease-depart: cubic-bezier(0.4, 0, 1, 1);
 
 		/* ── Geometry ──────────────────────────────────────────────────────────*/
 		/* ONE stroke width for every edge the chrome draws: a card's, a control's,
@@ -164,6 +176,9 @@
 		   against a token. */
 		--_qm-border-width: 1px;
 		--_qm-radius: var(--qm-radius, 8px);
+		/* The INTERIOR corner, and HALF is the relationship rather than the number: a
+		   corner inside a corner reads as nested only while it is visibly tighter, and
+		   halving holds that at every setting of the dial, zero included. */
 		--_qm-radius-inner: calc(var(--_qm-radius) / 2);
 		/* A fully-rounded end cap: a shape tier, not a step on the radius ramp, so
 		   it does not derive from the dial: a pill stays a pill at any radius. */
@@ -173,6 +188,13 @@
 		--_qm-space-2: calc(var(--_qm-space) * 2);
 		--_qm-space-3: calc(var(--_qm-space) * 3);
 		--_qm-space-4: calc(var(--_qm-space) * 4);
+		/* A rung because the two axes are two decisions and the ladder alone cannot hold
+		   them together: `check:style`'s rhythm axis sees each box read a rung, never that
+		   they read the SAME one, which is the drift `visual/controls.css` already names
+		   for the type half. Asymmetric because the vertical is what leading leaves once
+		   it has taken the line box, and the horizontal is how far in the text starts,
+		   which nothing else fixes. */
+		--_qm-inset-control: var(--_qm-space) var(--_qm-space-3);
 		/* The scroll TAIL: dead space under the last card, so it can be read at the
 		   middle of a pane rather than at its bottom edge. A fraction of the VIEWPORT
 		   rather than a step on the ramp, because what it answers is how far the eye
@@ -196,26 +218,36 @@
 		--_qm-glyph-control: 14px;
 
 		/* ── Type ────────────────────────────────────────────────────────────────
-		   `--qm-font-size` anchors the body rung; 1.125 is the ratio between adjacent
-		   rungs: a step up (title) and two down (label, meta). The ratio and the
-		   weights are fixed conventions, not dials: no consumer tunes a typographic
-		   ratio, and a dial nobody turns is a name every reader still holds. */
+		   `--qm-font-size` anchors the CHROME rung; 1.125 is the ratio between adjacent
+		   rungs: a step up (title) and one down (label). The ratio and the
+		   weight are fixed conventions, not dials: no consumer tunes a typographic
+		   ratio, and a dial nobody turns is a name every reader still holds. THREE chrome
+		   rungs: a second step below `label` lands near 11px, under a size anything here
+		   wants to be read at, and the supporting text that would take it is what `label`
+		   already is. */
 		--_qm-text-body: var(--qm-font-size, 0.875rem);
 		--_qm-text-title: calc(var(--_qm-text-body) * 1.125);
 		--_qm-text-label: calc(var(--_qm-text-body) / 1.125);
-		--_qm-text-meta: calc(var(--_qm-text-label) / 1.125);
+		/* PAPER: the document body answers to the preview's paper where every other
+		   surface here answers to the control beside it, so a rung shared with the chrome
+		   makes a consumer asking for larger prose take larger inputs with it. 16/15 where
+		   the ramp steps at 9/8: small enough to read as a change of REGISTER rather than
+		   a rung of hierarchy, and clear of the title rung, which one 9/8 step lands on
+		   exactly. */
+		--_qm-text-paper: calc(var(--_qm-text-body) * 16 / 15);
+		/* ONE weight over the regular: every heading here is a name over the value under
+		   it, so a second is a rung with no register beneath it. Hierarchy is the size
+		   ramp's. */
 		--_qm-weight-label: 600;
-		--_qm-weight-soft: 500;
 		/* Leading: the ramp's third axis, and it does not track the sizes one for one:
 		   two rungs, because a wrapped label and a wrapped paragraph want different
 		   rhythms and nothing wants four. `body` is reading rhythm (both prose leaves,
 		   every control beside them, the tips card's guidance); `tight` is a line that is
 		   a label rather than a passage. Unitless, so a rung inherits MULTIPLICATIVELY
 		   and holds against whichever size rung the surface reads: a `rem` leading
-		   would freeze at one size and disagree with the rest of the ramp. Leading is
-		   also the WHOLE of what separates paper from chrome: the body leaf reads
-		   `--_qm-text-body`, the same size as the input beside it, and there is no fifth
-		   size rung over it. `line-height: 1` is outside the axis: it collapses the
+		   would freeze at one size and disagree with the rest of the ramp. It is the
+		   axis paper and chrome SHARE: both read `body`, and the size rung is what
+		   separates them. `line-height: 1` is outside the axis: it collapses the
 		   line box onto its content, a glyph or a button's one-line label. */
 		--_qm-leading-body: 1.5;
 		--_qm-leading-tight: 1.3;

package/dist/preset/recipes.css

@@ -86,11 +86,7 @@ html:has(.qm-workspace) {
    The GAP is the endorsed default and not a fact about splitting: two surfaces standing
    apart on a page read as two things, which is what a host showing its instruments wants.
    A host that spends the whole screen on the mounts closes it to nothing and carries a
-   hairline on one pane instead: one property, and the tracks are untouched.
-
-   Below the width that fits two mounts abreast the split stops being one: the tracks
-   stack and each takes a pane's height. WHICH element scrolls then is the host's, since
-   it is the host that knows where the room comes from. */
+   hairline on one pane instead: one property, and the tracks are untouched. */
 .qm-split {
 	display: grid;
 	grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
@@ -99,11 +95,62 @@ html:has(.qm-workspace) {
 	min-height: 0;
 }
 
-@media (width < 60rem) {
+/* THE BAND THAT SWITCHES THEM, and nothing at the widths where both tracks are showing
+   and there is nothing to switch. Where it stands is the host's, like any other band; what
+   goes in it is a pair of `.qm-control`s, which already carry the on-state a pressed
+   control takes. Its visibility is the PRESET's because the threshold is: a host hiding
+   its own tab row writes this file's number a second time, which is the one thing the
+   single source is for. */
+.qm-switch {
+	display: none;
+}
+
+/* ONE MOUNT AT A TIME under the threshold, rather than two of them abreast. Half a narrow
+   viewport is under the width either surface reads at, so the split stops being one and
+   the tracks become views of the same room: the host says which with `data-qm-show`, and
+   the attribute names the TRACK rather than what is in it, so nothing here knows an editor
+   from a preview. No attribute is the first track.
+
+   The other track is `display: none` and not a clip, which is the whole of the hiding: it
+   leaves the tab order, hit-testing and the accessibility tree in one property, so the
+   pane needs no `inert` and the host needs no breakpoint in JS. Both stay MOUNTED (a
+   preview binds its handle once, an editor holds a caret, a history and a scroll), so
+   the switch is presentational, never conditional. A pane hidden this way keeps the
+   pixels it had (the paint loop's band sweep no-ops on an empty visible set) and repaints
+   from its live box when it comes back, which its resize observer sees as a width moving
+   off zero.
+
+   HEIGHT is the second clause because a landscape phone passes the first one: it clears
+   the width with room for two tracks and has no body left to put them in. A desktop window
+   that short wants one mount for the same reason. */
+@media (width < 50rem), (height < 30rem) {
+	.qm-switch {
+		display: flex;
+		gap: var(--qmh-space);
+	}
+
+	/* Even halves of the band, at the height a THUMB needs. The floor is the recipe's and
+	   not the host's, because the band exists only at the sizes where the pointer is a
+	   finger: a host is free to stand the band deeper, and has nothing to gain from
+	   standing it shallower than the thing it is tapping. */
+	.qm-switch > * {
+		flex: 1 1 0;
+		min-height: var(--qmh-tap);
+	}
+
+	/* Centred, which is what a control filling half a band reads as; `.qm-control` itself
+	   reads left, for the menus it also dresses. */
+	.qm-switch > .qm-control {
+		text-align: center;
+	}
+
 	.qm-split {
 		grid-template-columns: minmax(0, 1fr);
-		grid-template-rows: none;
-		grid-auto-rows: var(--qmh-pane);
+	}
+
+	.qm-split:not([data-qm-show='2']) > :nth-child(2),
+	.qm-split[data-qm-show='2'] > :nth-child(1) {
+		display: none;
 	}
 }
 

package/dist/preset/scale.css

@@ -58,10 +58,11 @@
 	   so it does not derive from the spacing dial. */
 	--qmh-measure: 34rem;
 
-	/* What one mount takes once a split has stacked. Reading geometry too, and about
-	   the surface rather than the text: how much of a document is worth showing when it
-	   cannot stand beside the thing it answers to. */
-	--qmh-pane: 34rem;
+	/* The floor under a control a THUMB lands on. Hand geometry rather than rhythm, which
+	   is why it does not derive from the spacing dial either: 44px is where both platform
+	   guidelines and WCAG put a touch target, and a control padded to a pointer's size is
+	   under it whatever rung the padding reads. */
+	--qmh-tap: 2.75rem;
 
 	/* ── Type ────────────────────────────────────────────────────────────────── */
 	/* Two faces with a job each: prose is sans, chrome is mono. Both are system stacks,

package/dist/preview/Preview.svelte

@@ -11,13 +11,13 @@
 	import { createPreview, type PreviewController } from './controller.js';
 	import { guardRebind } from '../core/rebind.svelte.js';
 	import type { PreviewStringsInput } from './strings.js';
-	import type { LiveSession, ContentHit, ChangeSet } from '@quillmark/wasm';
-	import type { DocPath, Place } from '../core/address.js';
+	import type { LiveSession, ChangeSet } from '@quillmark/wasm';
+	import type { DocPath, Landing, Place } from '../core/address.js';
 	import type { EditorErrorHandler } from '../core/errors.js';
 
 	/**
 	 * REMOUNT CONTRACT. `createPreview` binds once in `onMount`; a later change to any
-	 * prop it closed over (`session`, `margin`, `overlays`, `onCaretPick`, `onError`,
+	 * prop it closed over (`session`, `margin`, `overlays`, `onPick`, `onError`,
 	 * `strings`) is NOT observed, and each reports `rebind-ignored` when swapped. Swap
 	 * the session by REMOUNTING (`{#key session}`, as the playground does); drive
 	 * in-place edits through the `refresh(change)` method, not a prop change.
@@ -36,7 +36,7 @@
 		style?: string;
 		margin?: number;
 		overlays?: boolean;
-		onCaretPick?: (hit: ContentHit) => void;
+		onPick?: (at: Landing) => void;
 		/** A page paint the backend refused; the error message state shows either way. */
 		onError?: EditorErrorHandler;
 		/** The message-state wording, keyed and partial (`PreviewStrings`). */
@@ -47,7 +47,7 @@
 		session,
 		margin,
 		overlays,
-		onCaretPick,
+		onPick,
 		onError,
 		strings,
 		class: className,
@@ -58,7 +58,7 @@
 	let controller: PreviewController | undefined;
 
 	guardRebind(
-		() => ({ session, margin, overlays, onCaretPick, onError, strings }),
+		() => ({ session, margin, overlays, onPick, onError, strings }),
 		'Remount the preview ({#key session}) to rebind.'
 	);
 
@@ -68,7 +68,7 @@
 			container: containerEl,
 			margin,
 			overlays,
-			onCaretPick,
+			onPick,
 			onError,
 			strings
 		});
@@ -81,8 +81,9 @@
 	export function refresh(change: ChangeSet): void {
 		controller?.refresh(change);
 	}
-	export function scrollToField(field: DocPath): void {
-		controller?.scrollToField(field);
+	/** `false` when this compile places nothing at `field` ({@link PreviewController}). */
+	export function scrollToField(field: DocPath): boolean {
+		return controller?.scrollToField(field) ?? false;
 	}
 	/** Takes the editor's `onCaretMove` payload: `onCaretMove={preview.focusPosition}`. */
 	export function focusPosition(at: Place): void {

package/dist/preview/Preview.svelte.d.ts

@@ -1,10 +1,10 @@
 import type { PreviewStringsInput } from './strings.js';
-import type { LiveSession, ContentHit, ChangeSet } from '@quillmark/wasm';
-import type { DocPath, Place } from '../core/address.js';
+import type { LiveSession, ChangeSet } from '@quillmark/wasm';
+import type { DocPath, Landing, Place } from '../core/address.js';
 import type { EditorErrorHandler } from '../core/errors.js';
 /**
  * REMOUNT CONTRACT. `createPreview` binds once in `onMount`; a later change to any
- * prop it closed over (`session`, `margin`, `overlays`, `onCaretPick`, `onError`,
+ * prop it closed over (`session`, `margin`, `overlays`, `onPick`, `onError`,
  * `strings`) is NOT observed, and each reports `rebind-ignored` when swapped. Swap
  * the session by REMOUNTING (`{#key session}`, as the playground does); drive
  * in-place edits through the `refresh(change)` method, not a prop change.
@@ -23,7 +23,7 @@ interface Props {
     style?: string;
     margin?: number;
     overlays?: boolean;
-    onCaretPick?: (hit: ContentHit) => void;
+    onPick?: (at: Landing) => void;
     /** A page paint the backend refused; the error message state shows either way. */
     onError?: EditorErrorHandler;
     /** The message-state wording, keyed and partial (`PreviewStrings`). */
@@ -31,7 +31,7 @@ interface Props {
 }
 declare const Preview: import("svelte").Component<Props, {
     refresh: (change: ChangeSet) => void;
-    scrollToField: (field: DocPath) => void;
+    scrollToField: (field: DocPath) => boolean;
     focusPosition: (at: Place) => void;
     setZoom: (scale: number) => void;
 }, "">;

package/dist/preview/bridge.d.ts

@@ -1,8 +1,10 @@
-import type { LiveSession, ContentHit } from '@quillmark/wasm';
+import type { LiveSession } from '@quillmark/wasm';
+import type { Landing } from '../core/address.js';
 import type { PageSlot } from './paint.js';
 export interface BridgeController {
-    /** Scroll `field`'s first content box to centre (a no-op if it has none). */
-    scrollToField(field: string): void;
+    /** Scroll `field`'s first box to centre; `false` when this compile places none
+     *  for that address, which is the whole of what the preview can say about it. */
+    scrollToField(field: string): boolean;
     /**
      * Bring the caret rect at `field`/`pos` into view (a no-op off-content, and a
      * no-op when it is already clear of the fold).
@@ -10,4 +12,4 @@ export interface BridgeController {
     focusPosition(field: string, pos: number): void;
     destroy(): void;
 }
-export declare function createBridge(session: LiveSession, container: HTMLElement, slots: readonly PageSlot[], onCaretPick: ((hit: ContentHit) => void) | undefined): BridgeController;
+export declare function createBridge(session: LiveSession, container: HTMLElement, slots: readonly PageSlot[], onPick: ((at: Landing) => void) | undefined): BridgeController;

package/dist/preview/bridge.js

@@ -1,7 +1,13 @@
-import { rectToPercent, clickToPdfPt, applyPercentRect } from './geometry.js';
-export function createBridge(session, container, slots, onCaretPick) {
+import { boxesForField, rectToPercent, clickToPdfPt, applyPercentRect } from './geometry.js';
+export function createBridge(session, container, slots, onPick) {
     const unlisten = [];
-    if (onCaretPick) {
+    // TWO RUNGS: `positionAt` over span-tracked content, `fieldAt` over every placement
+    // the compile tracks, a strict superset of it (PREVIEW.md §"Click bridge" carries
+    // the measurement). The second fires where a field is placed without its content
+    // being tracked, and the pick carries NO `pos` there: a fabricated `0` would be an
+    // invented offset wearing a real one's type. No third rung hit-tests `regions()`,
+    // whose rects bound ink the field does not fill.
+    if (onPick) {
         for (const { page, el } of slots) {
             const handleClick = (ev) => {
                 // Re-read through the live array: a same-count `refresh` swaps the
@@ -16,7 +22,10 @@ export function createBridge(session, container, slots, onCaretPick) {
                 const pt = clickToPdfPt(px, py, box.width, box.height, slot.size);
                 const hit = session.positionAt(slot.page, pt.x, pt.y);
                 if (hit)
-                    onCaretPick(hit);
+                    return void onPick(hit);
+                const field = session.fieldAt(slot.page, pt.x, pt.y);
+                if (field)
+                    onPick({ field });
             };
             el.addEventListener('click', handleClick);
             unlisten.push(() => el.removeEventListener('click', handleClick));
@@ -54,15 +63,16 @@ export function createBridge(session, container, slots, onCaretPick) {
     }
     return {
         scrollToField(field) {
-            const box = session.fieldBoxes(field)[0];
+            const box = boxesForField(field, session.fieldBoxes(field), session.regions())[0];
             if (!box)
-                return;
+                return false;
             const slot = slots[box.page];
             if (!slot)
-                return;
+                return false;
             // A discrete act ("show me this field"), so it centres every time: the
             // asymmetry the bloom draws between a continuous signal and a one-shot one.
             centre(measure(slot, rectToPercent(box.rect, slot.size)));
+            return true;
         },
         focusPosition(field, pos) {
             const region = session.locate(field, pos);

package/dist/preview/controller.d.ts

@@ -1,5 +1,5 @@
-import type { LiveSession, ChangeSet, ContentHit } from '@quillmark/wasm';
-import type { DocPath, Place } from '../core/address.js';
+import type { LiveSession, ChangeSet } from '@quillmark/wasm';
+import type { DocPath, Landing, Place } from '../core/address.js';
 import { type EditorErrorHandler } from '../core/errors.js';
 import { type PreviewStringsInput } from './strings.js';
 export interface PreviewOptions {
@@ -9,8 +9,10 @@ export interface PreviewOptions {
     margin?: number;
     /** Draw field-box overlays. Default true. */
     overlays?: boolean;
-    /** A click resolved to a content position; the hook does not fire off-ink. */
-    onCaretPick?(hit: ContentHit): void;
+    /** A click resolved to an address ({@link Landing}): a caret where the compile
+     *  tracks the content under the point, the field alone where it tracks only the
+     *  placement. The hook does not fire where the compile tracks neither. */
+    onPick?(at: Landing): void;
     /** A page paint the backend refused ({@link EditorErrorHandler}). The preview
      *  shows its error message state either way; this routes it to an app's sink. */
     onError?: EditorErrorHandler;
@@ -21,8 +23,13 @@ export interface PreviewOptions {
 export interface PreviewController {
     /** Repaint `dirtyPages ∩ visible` and re-read geometry; the only apply-driven hop. */
     refresh(change: ChangeSet): void;
-    /** Scroll `field`'s first box into view and bloom it. */
-    scrollToField(field: DocPath): void;
+    /**
+     * Scroll `field`'s first box into view and bloom it. `false` when this compile
+     * places nothing at that address — an answer, not a failure: the plate places
+     * plenty it does not track, and the preview carries no schema to tell that from a
+     * field the host misnamed. The editor's `focusField` is what distinguishes them.
+     */
+    scrollToField(field: DocPath): boolean;
     /**
      * Bring the caret at `at` into view and bloom its field on arrival. Both halves
      * are change-guarded: the pane moves only when the caret has left the fold, the

package/dist/preview/controller.js

@@ -59,7 +59,7 @@ export function createPreview(session, opts) {
     // swapped on reconcile, and both attach DOM/listeners per slot.
     function attach() {
         overlay = overlaysEnabled ? createOverlay(session, paintLoop.slots) : undefined;
-        bridge = createBridge(session, container, paintLoop.slots, opts.onCaretPick);
+        bridge = createBridge(session, container, paintLoop.slots, opts.onPick);
     }
     function detach() {
         overlay?.destroy();
@@ -120,8 +120,11 @@ export function createPreview(session, opts) {
                 bridge?.focusPosition(followed.field, followed.pos);
         },
         scrollToField(field) {
-            bridge?.scrollToField(field);
+            const found = bridge?.scrollToField(field) ?? false;
+            // Marked either way: a compile that gains the address later blooms it on the
+            // rebuild, since the flash carries its own start time (`core/bloom.ts`).
             overlay?.flashField(field);
+            return found;
         },
         focusPosition(at) {
             followed = at;

package/dist/preview/geometry.d.ts

@@ -1,4 +1,4 @@
-import type { PageSize } from '@quillmark/wasm';
+import type { FieldRegion, PageSize } from '@quillmark/wasm';
 /** A page rect in PDF points, `[x0, y0, x1, y1]`, bottom-left origin (`FieldRegion.rect`'s shape). */
 export type PdfRect = readonly [number, number, number, number];
 /** A rect as CSS percent of the page box (top-left origin; Y is flipped from PDF-pt). */
@@ -13,6 +13,21 @@ export interface PdfPoint {
     x: number;
     y: number;
 }
+/**
+ * An address's boxes: `fieldBoxes`'s union, else its own `regions()` rects, else the
+ * rects of everything UNDER it. The one rule the overlay and the scroll both read, so
+ * an address `regions()` names never draws nothing (PREVIEW.md §"Three
+ * responsibilities").
+ *
+ * `fieldBoxes` answers `[]` for a scalar reference the plate places without tracking
+ * its content and for a `richtext[]` element; runtime.d.ts says what such a field's
+ * box is, a single `regions()` rect. The third rung is that sentence one granularity
+ * down — an array's ink is its elements' — and is a fallback, not a union, so an
+ * address with rects of its own never also draws its children's. The `.` keeps the
+ * prefix a path boundary: `main.references` matches `main.references.0`, not
+ * `main.references_note`.
+ */
+export declare function boxesForField(field: string, boxes: readonly FieldRegion[], regions: readonly FieldRegion[]): readonly FieldRegion[];
 /**
  * Forward: a PDF-pt rect -> CSS % of the page box. Percent positioning tracks
  * the page's displayed size across DPR and container resize for free; this is