@quillmark/svelte 0.1.1 → 0.3.0

package/dist/preset/scale.css

@@ -1,12 +1,15 @@
-/* THE HOST'S DERIVATION: the same public dials in, a closed `--qmh-*` scale for the
-   page AROUND the surfaces out. `core/theme.css` is the same shape one level down
-   (dials in, `--_qm-*` out), and the two are calibrated against each other: the mixes
-   here are the percentages there (4pp between surface steps, 17% border, 45% and 60%
-   ink), so a host plate and a card on it agree about which way "raised" goes and land
-   on the same tone at both poles.
+/* The host'S derivation: the same public dials in, a closed `--qmh-*` scale for the
+   page around the surfaces out. `core/theme.css` is the same shape one level down
+   (dials in, `--_qm-*` out), and the two are calibrated against each other: the
+   figures here are the figures there (the ground step's two arms, 8% hover, 17%
+   border, 45% and 60% ink) and the dial means the same plane in both, so a host plate
+   and a card on it land on the same tone at both poles and a host page meets an
+   editor's own column exactly. The well under the ground has no counterpart here: a
+   host's own controls are boxed and carry a hairline, so nothing on a page needs the
+   step an edgeless field does.
 
-   TWO SCALES rather than one because they answer to different roots. `--_qm-*` is
-   declared ON each mounted root, out of reach from an ancestor, so a surface holds its
+   Two scales rather than one because they answer to different roots. `--_qm-*` is
+   declared on each mounted root, out of reach from an ancestor, so a surface holds its
    scale wherever it is dropped. A host scale has the opposite job: it is the document,
    so it is declared at `:root` and everything on the page reads it. A single namespace
    could not be both.
@@ -14,26 +17,34 @@
    Literals live here and nowhere else in the preset: `check:style` runs its axes over
    `recipes.css` beside it, with this file exempt as the place the defaults are minted.
 
-   The poles fall back to the SYSTEM colours, so a host that turns no dial still lands
-   where its own unstyled text does. The dials sit in front, so `--qm-bg`/`--qm-fg` on
-   an ancestor retunes page and surface together. */
+   The poles fall back to the system colours, so a host that turns no dial still lands
+   where its own unstyled text does — `Canvas` being the plane the UA would have
+   painted a page with, which is what a plate should be. The dials sit in front, so
+   `--qm-bg`/`--qm-fg` on an ancestor retunes page and surface together. */
 
 :root {
 	/* ── Colour ──────────────────────────────────────────────────────────────── */
-	--qmh-page: var(--qm-bg, Canvas);
+	/* The dial is the plate, exactly as it is the card one level down: a plate beside
+	   a mounted editor is the same plane as a card in it, so both read the pole and
+	   the page sinks from it by the same two arms. That is what puts a host page and
+	   an editor's own column on one tone rather than a plane apart. Planes step by
+	   light and everything else by ink, which is the package's own split
+	   (ARCHITECTURE §Styling); the figures are its figures. */
+	--qmh-surface: var(--qm-bg, Canvas);
+	--qmh-page: light-dark(
+		oklab(from var(--qmh-surface) calc(l - 0.0214) calc(a - 0.00065) calc(b - 0.00158)),
+		oklab(from var(--qmh-surface) calc(l - 0.0553) calc(a - 0.00048) calc(b + 0.00165))
+	);
 	--qmh-ink: var(--qm-fg, CanvasText);
-	--qmh-ink-meta: color-mix(in oklab, var(--qmh-ink), var(--qmh-page) 45%);
-	--qmh-ghost: color-mix(in oklab, var(--qmh-ink), var(--qmh-page) 60%);
-	/* Two planes behind content, 4pp apart exactly as the surfaces step, so a host
-	   plate and a card on it agree about which way "raised" goes in both schemes. */
-	--qmh-surface: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 4%);
-	--qmh-surface-hover: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 8%);
-	--qmh-border: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 17%);
+	--qmh-ink-meta: color-mix(in oklab, var(--qmh-ink), var(--qmh-surface) 45%);
+	--qmh-ghost: color-mix(in oklab, var(--qmh-ink), var(--qmh-surface) 60%);
+	--qmh-surface-hover: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 8%);
+	--qmh-border: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 17%);
 	/* The edge that says "engaged" where the hairline says "edge": a pressed switch,
 	   the underline under a link. */
-	--qmh-border-strong: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 40%);
+	--qmh-border-strong: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 40%);
 
-	/* The two hues a host spends, and it spends them on a message. Both read the DIAL,
+	/* The two hues a host spends, and it spends them on a message. Both read the dial,
 	   so a page carries one colour meaning error and one meaning warning rather than a
 	   second pair beside the surfaces'. The dark half is a lift the dials do not carry:
 	   a hue calibrated against white reads as a stain on a dark page. */
@@ -42,7 +53,7 @@
 
 	/* ── Rhythm ──────────────────────────────────────────────────────────────── */
 	/* One base and its multiples, the same four steps the surfaces derive. A host
-	   separating SECTIONS down a page wants steps above these; it derives them from
+	   separating sections down a page wants steps above these; it derives them from
 	   this base rather than minting them, which is what keeps its ramp one ramp. */
 	--qmh-space: var(--qm-space, 0.25rem);
 	--qmh-space-half: calc(var(--qmh-space) / 2);
@@ -58,10 +69,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,
@@ -72,7 +84,7 @@
 	--qmh-font: var(--qm-font, ui-sans-serif, system-ui, sans-serif);
 	--qmh-font-mono: var(--qm-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
 
-	/* The page's own ramp, and it does NOT read `--qm-font-size`: that dial anchors the
+	/* The page's own ramp, and it does not read `--qm-font-size`: that dial anchors the
 	   surfaces' ramp, which is chrome inside a card, and a page's body text is a
 	   different job at a different size. A host that wants them locked sets both. */
 	--qmh-text: 1rem;
@@ -93,7 +105,7 @@
 	--qmh-ease-reverse: cubic-bezier(0.4, 0, 0.6, 1);
 }
 
-/* Collapse the SCALE, not each transition: every animated recipe reads the rung, so one
+/* Collapse the scale, not each transition: every animated recipe reads the rung, so one
    override reaches all of them with no `*` rule touching mounted package elements. */
 @media (prefers-reduced-motion: reduce) {
 	:root {

package/dist/preview/Preview.svelte

@@ -4,22 +4,22 @@
   paint.ts/overlay.ts/bridge.ts/controller.ts own the behavior. Exposes the
   `PreviewController` verbs as instance methods (`bind:this`) for a consumer
   that drives `refresh`/`scrollToField`/`focusPosition`/`setZoom` imperatively
-  (e.g. after `session.apply` elsewhere); pure passthrough, no added logic.
+  (e.g. after `session.apply` elsewhere).
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
 	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`,
-	 * `strings`) is NOT observed, and each reports `rebind-ignored` when swapped. Swap
-	 * the session by REMOUNTING (`{#key session}`, as the playground does); drive
+	 * Remount contract. `createPreview` binds once in `onMount`; a later change to any
+	 * 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.
 	 *
 	 * `onError` is itself once-bound, so a swapped handler means the report of its own
@@ -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 {
@@ -96,15 +97,17 @@
 <div bind:this={containerEl} class="qm-preview {className ?? ''}" {style} data-qm-root></div>
 
 <style>
-	/* A DETACHED root: the preview is not a descendant of the editor, so it carries
+	/* A detached root: the preview is not a descendant of the editor, so it carries
 	   `data-qm-root` for the page/overlay rungs paint.ts and overlay.ts read
 	   (core/theme.css).
 
-	   The DESK as well as the paper: a sheet is at `--_qm-surface` (paint.ts), so the
-	   tone behind it is one rung raised and the gutter is the margin the sheet floats
-	   in. Both are the surface's own, so a bare `<div>` is a mounting site. The
+	   The desk as well as the paper: a sheet is at `--_qm-surface` (paint.ts), so the
+	   tone behind it is the sunken rung and the gutter is the margin the sheet floats
+	   in. Paper is the brighter plane at both poles, exactly as a card is over the
+	   editor's own column, so the two panes step the same way. Both are
+	   the surface's own, so a bare `<div>` is a mounting site. The
 	   padding is safe against the paint loop: a slot is a `width: 100%` child and
-	   measures the CONTENT box, and the container's own `clientWidth` is read only as
+	   measures the content box, and the container's own `clientWidth` is read only as
 	   a change detector, which a constant inset does not disturb. */
 	.qm-preview {
 		box-sizing: border-box;
@@ -113,6 +116,6 @@
 		height: 100%;
 		overflow-y: auto;
 		padding: var(--_qm-space-4);
-		background: var(--_qm-surface-raised);
+		background: var(--_qm-surface-sunken);
 	}
 </style>

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

@@ -1,12 +1,12 @@
 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`,
- * `strings`) is NOT observed, and each reports `rebind-ignored` when swapped. Swap
- * the session by REMOUNTING (`{#key session}`, as the playground does); drive
+ * Remount contract. `createPreview` binds once in `onMount`; a later change to any
+ * 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.
  *
  * `onError` is itself once-bound, so a swapped handler means the report of its own
@@ -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));
@@ -44,7 +53,7 @@ export function createBridge(session, container, slots, onCaretPick) {
         else if (target.right > port.right)
             container.scrollLeft += target.right - port.right;
     }
-    // Clear of the fold is the target's OWN height of clearance at each edge, not bare
+    // Clear of the fold is the target's own height of clearance at each edge, not bare
     // intersection: a caret rect flush against one is visible and unusable, and the
     // next line typed lands past it. Derived from the target rather than a margin
     // dial, so it scales with zoom exactly as the caret does.
@@ -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);
@@ -71,7 +81,7 @@ export function createBridge(session, container, slots, onCaretPick) {
             const slot = slots[region.page];
             if (!slot)
                 return;
-            // The CONTINUOUS hop: one call per keystroke and per arrow key, so it moves
+            // The continuous hop: one call per keystroke and per arrow key, so it moves
             // the pane only when the caret has left the fold. Centring unconditionally
             // takes the scrollport back from the user on every one of them, including
             // the ones that changed nothing about where the caret already was.

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();
@@ -83,8 +83,8 @@ export function createPreview(session, opts) {
             showMessage(pageCount === 0 ? t.noPages : t.unsupported, pageCount === 0 ? EMPTY_CLASS : UNSUPPORTED_CLASS);
             return;
         }
-        // Read the count against the current slots BEFORE reconcile moves it, and
-        // clear any prior message BEFORE painting so a paint that throws mid-refresh
+        // Read the count against the current slots before reconcile moves it, and
+        // clear any prior message before painting so a paint that throws mid-refresh
         // leaves its error surfaced rather than have `hideMessage` clobber it.
         const countChanged = pageCount !== paintLoop.slots.length;
         hideMessage();
@@ -104,7 +104,7 @@ export function createPreview(session, opts) {
     }
     render(session.pageCount, []);
     // The last place the editor put the caret, re-located after every recompile.
-    // `session.locate` answers against the LAST COMPILED layout and a consumer
+    // `session.locate` answers against the last compiled layout and a consumer
     // debounces `update`, so a caret typed past that layout's content is off-content
     // for the whole burst: `focusPosition` no-ops and the pane sits still, and a
     // caret event is otherwise the only thing that asks again. The re-locate is the
@@ -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
@@ -28,7 +43,7 @@ export declare function rectToPercent(rect: PdfRect, pageSize: PageSize): Percen
 export declare function applyPercentRect(el: HTMLElement, pct: PercentRect): void;
 /**
  * Inverse: a click at CSS px `(px, py)` within a page element of CSS size
- * `(cssW, cssH)` -> PDF-pt. The EXACT inverse of {@link rectToPercent}: the
+ * `(cssW, cssH)` -> PDF-pt. The exact inverse of {@link rectToPercent}: the
  * fraction `rectToPercent` would place a point's box corner at is the same
  * fraction this reads back from `px/cssW`, `py/cssH`; DPR-independent, since
  * the page element's CSS size (not its canvas backing store) is the only input.

package/dist/preview/geometry.js

@@ -1,3 +1,23 @@
+/**
+ * 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 function boxesForField(field, boxes, regions) {
+    if (boxes.length)
+        return boxes;
+    const own = regions.filter((r) => r.field === field);
+    return own.length ? own : regions.filter((r) => r.field.startsWith(`${field}.`));
+}
 /**
  * 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
@@ -30,7 +50,7 @@ export function applyPercentRect(el, pct) {
 }
 /**
  * Inverse: a click at CSS px `(px, py)` within a page element of CSS size
- * `(cssW, cssH)` -> PDF-pt. The EXACT inverse of {@link rectToPercent}: the
+ * `(cssW, cssH)` -> PDF-pt. The exact inverse of {@link rectToPercent}: the
  * fraction `rectToPercent` would place a point's box corner at is the same
  * fraction this reads back from `px/cssW`, `py/cssH`; DPR-independent, since
  * the page element's CSS size (not its canvas backing store) is the only input.

package/dist/preview/index.d.ts

@@ -1,3 +1,4 @@
+import '../core/theme.css';
 export { createPreview } from './controller.js';
 export type { PreviewOptions, PreviewController } from './controller.js';
 export { default as Preview } from './Preview.svelte';

package/dist/preview/index.js

@@ -1,13 +1,20 @@
 // `@quillmark/svelte/preview`: the live-preview surface.
 //
 // `createPreview(session)` (vanilla-TS core) + a thin `<Preview>` Svelte wrapper
-// land here. RESERVED-PACKAGE INVARIANT: this subpath imports no editor-side code
+// land here. Reserved-package invariant: this subpath imports no editor-side code
 // (the codec, the VisualEditor) so a `@quillmark/preview` promotion stays a
 // re-export, not a refactor: it may reach `/core` (the shared WASM boundary) and
 // nothing else. Enforced by `check:deps`, which walks the subpath's import graph.
+// The theme derivation, which the page slots and the overlay read through `var()`.
+// Imported at the barrel because a subpath is what a consumer gets: this surface
+// reaches modules inside `core/` and never its entry, so a sheet hanging off that
+// entry arrives only for a consumer importing `/core` for some other reason. The
+// sheet rather than the entry, because the barrel needs the derivation and not
+// `init`. `check:deps` (rule 4) walks this file's own graph and holds the reach.
+import '../core/theme.css';
 export { createPreview } from './controller.js';
 export { default as Preview } from './Preview.svelte';
-// What the preview SAYS when there is nothing to paint. Keyed and partial; the
+// What the preview says when there is nothing to paint. Keyed and partial; the
 // English is exported so a consumer composes against it rather than restating it.
 // The merge is the surface's own: a consumer hands `strings` to a prop, never
 // merges one.

package/dist/preview/overlay.d.ts

@@ -3,7 +3,8 @@ import type { PageSlot } from './paint.js';
 export interface OverlayController {
     /** Re-read geometry and rebuild every box; call after a layout-affecting refresh. */
     refresh(): void;
-    /** Bloom `field`'s boxes: transient, and a no-op when `field` is already the marked one. */
+    /** Bloom the boxes at `field` and under it: transient, and a no-op when `field`
+     *  is already the marked one. */
     flashField(field: string): void;
     destroy(): void;
 }

package/dist/preview/overlay.js

@@ -1,5 +1,5 @@
 import { bloom, bloomTiming, primeWash } from '../core/bloom.js';
-import { rectToPercent, applyPercentRect } from './geometry.js';
+import { boxesForField, rectToPercent, applyPercentRect } from './geometry.js';
 const FIELD_ATTR = 'data-qm-field';
 export function createOverlay(session, slots) {
     const layers = slots.map((slot) => {
@@ -9,7 +9,7 @@ export function createOverlay(session, slots) {
         slot.el.appendChild(layer);
         return layer;
     });
-    // The marked address, and with it the bloom's start. ONE variable does both jobs:
+    // The marked address, and with it the bloom's start. One variable does both jobs:
     // the change guard has to outlive the decay (a caret move after the wash ended
     // must not re-mark the same field), and `bloom` refuses an `elapsed` past the
     // decay, so a spent flash is inert on every later rebuild and never needs
@@ -20,32 +20,47 @@ export function createOverlay(session, slots) {
     let flash;
     /** field → its boxes, rebuilt with them. The bloom's only lookup. */
     let byField = new Map();
-    // Start or RESUME the bloom on whatever boxes exist for it now: one path, because
+    // The boxes a flash covers: the address's own, plus every one under it, since the
+    // boxes are keyed as `regions()` names them (`main.references.0`) and an
+    // editor-side signal names the declared field (`main.references`). Resolved per
+    // apply rather than at `flashField`, so a rebuild picks up boxes the recompile
+    // moved or added.
+    function flashed(field) {
+        const els = [];
+        for (const [key, group] of byField) {
+            if (key === field || key.startsWith(`${field}.`))
+                els.push(...group);
+        }
+        return els;
+    }
+    // Start or resume the bloom on whatever boxes exist for it now: one path, because
     // starting is resuming at ~0. A field surfaces several boxes and they share
     // `startedAt`, so they bloom in step rather than shimmering unevenly.
     function applyFlash() {
-        const els = flash && byField.get(flash.field);
-        if (!flash || !els?.length)
+        if (!flash)
+            return;
+        const els = flashed(flash.field);
+        if (!els.length)
             return;
         const elapsed = performance.now() - flash.startedAt;
         const timing = bloomTiming(els[0]);
         for (const el of els)
             bloom(el, elapsed, timing);
     }
-    // Field names come from `regions()` (the only session query that enumerates
-    // them; Preview carries no schema); the boxes themselves come from
-    // `fieldBoxes(field)`, which is content-only and `[]` for a scalar-reference
-    // or widget field, so a nameless-of-content field contributes no boxes.
+    // Field names come from `regions()` (the only session query that enumerates them;
+    // Preview carries no schema); the rects from `boxesForField`, whose fallback is
+    // what makes every address `regions()` names draw.
     function build() {
         for (const layer of layers)
             layer.replaceChildren();
         byField = new Map();
+        const regions = session.regions();
         const fields = new Set();
-        for (const region of session.regions())
+        for (const region of regions)
             fields.add(region.field);
         for (const field of fields) {
             const els = [];
-            for (const box of session.fieldBoxes(field)) {
+            for (const box of boxesForField(field, session.fieldBoxes(field), regions)) {
                 const layer = layers[box.page];
                 const slot = slots[box.page];
                 if (!layer || !slot)