@quillmark/svelte 0.0.0

package/dist/preview/Preview.svelte

@@ -0,0 +1,118 @@
+<!--
+  `@quillmark/svelte/preview`'s Svelte wrapper: mounts `createPreview` over a
+  container div on mount and tears it down on unmount. No logic beyond wiring;
+  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.
+-->
+<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 { 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
+	 * 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
+	 * swap reaches the handler it replaced. `class` and `style` are the exceptions:
+	 * they land on the root element Svelte owns, so they stay live.
+	 */
+	interface Props {
+		session: LiveSession;
+		/** Appended to the root's own class: the surface is a mounted element the
+		 *  consumer positions, so it needs a handle for layout it owns. */
+		class?: string;
+		/** Merged onto the root. Free: theming lands on `data-qm-root` (core/theme.css),
+		 *  not this attribute. */
+		style?: string;
+		margin?: number;
+		overlays?: boolean;
+		onCaretPick?: (hit: ContentHit) => void;
+		/** A page paint the backend refused; the error message state shows either way. */
+		onError?: EditorErrorHandler;
+		/** The message-state wording, keyed and partial (`PreviewStrings`). */
+		strings?: PreviewStringsInput;
+	}
+
+	let {
+		session,
+		margin,
+		overlays,
+		onCaretPick,
+		onError,
+		strings,
+		class: className,
+		style
+	}: Props = $props();
+
+	let containerEl: HTMLDivElement | undefined = $state();
+	let controller: PreviewController | undefined;
+
+	guardRebind(
+		() => ({ session, margin, overlays, onCaretPick, onError, strings }),
+		'Remount the preview ({#key session}) to rebind.'
+	);
+
+	onMount(() => {
+		if (!containerEl) return;
+		controller = createPreview(session, {
+			container: containerEl,
+			margin,
+			overlays,
+			onCaretPick,
+			onError,
+			strings
+		});
+		return () => {
+			controller?.destroy();
+			controller = undefined;
+		};
+	});
+
+	export function refresh(change: ChangeSet): void {
+		controller?.refresh(change);
+	}
+	export function scrollToField(field: DocPath): void {
+		controller?.scrollToField(field);
+	}
+	/** Takes the editor's `onCaretMove` payload: `onCaretMove={preview.focusPosition}`. */
+	export function focusPosition(at: Place): void {
+		controller?.focusPosition(at);
+	}
+	export function setZoom(scale: number): void {
+		controller?.setZoom(scale);
+	}
+</script>
+
+<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
+	   `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
+	   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
+	   a change detector, which a constant inset does not disturb. */
+	.qm-preview {
+		box-sizing: border-box;
+		position: relative;
+		width: 100%;
+		height: 100%;
+		overflow-y: auto;
+		padding: var(--_qm-space-4);
+		background: var(--_qm-surface-raised);
+	}
+</style>

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

@@ -0,0 +1,39 @@
+import type { PreviewStringsInput } from './strings.js';
+import type { LiveSession, ContentHit, ChangeSet } from '@quillmark/wasm';
+import type { DocPath, 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
+ * 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
+ * swap reaches the handler it replaced. `class` and `style` are the exceptions:
+ * they land on the root element Svelte owns, so they stay live.
+ */
+interface Props {
+    session: LiveSession;
+    /** Appended to the root's own class: the surface is a mounted element the
+     *  consumer positions, so it needs a handle for layout it owns. */
+    class?: string;
+    /** Merged onto the root. Free: theming lands on `data-qm-root` (core/theme.css),
+     *  not this attribute. */
+    style?: string;
+    margin?: number;
+    overlays?: boolean;
+    onCaretPick?: (hit: ContentHit) => void;
+    /** A page paint the backend refused; the error message state shows either way. */
+    onError?: EditorErrorHandler;
+    /** The message-state wording, keyed and partial (`PreviewStrings`). */
+    strings?: PreviewStringsInput;
+}
+declare const Preview: import("svelte").Component<Props, {
+    refresh: (change: ChangeSet) => void;
+    scrollToField: (field: DocPath) => void;
+    focusPosition: (at: Place) => void;
+    setZoom: (scale: number) => void;
+}, "">;
+type Preview = ReturnType<typeof Preview>;
+export default Preview;

package/dist/preview/bridge.d.ts

@@ -0,0 +1,13 @@
+import type { LiveSession, ContentHit } from '@quillmark/wasm';
+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;
+    /**
+     * 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).
+     */
+    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;

package/dist/preview/bridge.js

@@ -0,0 +1,88 @@
+import { rectToPercent, clickToPdfPt, applyPercentRect } from './geometry.js';
+export function createBridge(session, container, slots, onCaretPick) {
+    const unlisten = [];
+    if (onCaretPick) {
+        for (const { page, el } of slots) {
+            const handleClick = (ev) => {
+                // Re-read through the live array: a same-count `refresh` swaps the
+                // slot objects to re-cache `size`, and the click math must use the
+                // current compile's PageSize, not the one captured at bridge build.
+                const slot = slots[page];
+                if (!slot)
+                    return;
+                const box = slot.el.getBoundingClientRect();
+                const px = ev.clientX - box.left;
+                const py = ev.clientY - box.top;
+                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);
+            };
+            el.addEventListener('click', handleClick);
+            unlisten.push(() => el.removeEventListener('click', handleClick));
+        }
+    }
+    // Where the % rect `pct` on `slot` currently sits, in the scrollport's own
+    // coordinates: a throwaway marker, measured and removed. Absolutely positioned,
+    // so it displaces nothing and no layout survives the read.
+    function measure(slot, pct) {
+        const marker = document.createElement('div');
+        applyPercentRect(marker, pct);
+        slot.el.appendChild(marker);
+        const rect = marker.getBoundingClientRect();
+        marker.remove();
+        return rect;
+    }
+    // Centre `target` vertically in the scrollport; the cross axis takes the minimum
+    // trip instead, since the container is a vertical scroller and only a page wider
+    // than the port has anything to move there.
+    function centre(target) {
+        const port = container.getBoundingClientRect();
+        container.scrollTop += target.top + target.height / 2 - (port.top + port.height / 2);
+        if (target.left < port.left)
+            container.scrollLeft += target.left - port.left;
+        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
+    // 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.
+    function clearOfTheFold(target) {
+        const port = container.getBoundingClientRect();
+        return target.top - target.height >= port.top && target.bottom + target.height <= port.bottom;
+    }
+    return {
+        scrollToField(field) {
+            const box = session.fieldBoxes(field)[0];
+            if (!box)
+                return;
+            const slot = slots[box.page];
+            if (!slot)
+                return;
+            // 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)));
+        },
+        focusPosition(field, pos) {
+            const region = session.locate(field, pos);
+            if (!region)
+                return;
+            const slot = slots[region.page];
+            if (!slot)
+                return;
+            // 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.
+            const target = measure(slot, rectToPercent(region.rect, slot.size));
+            if (clearOfTheFold(target))
+                return;
+            centre(target);
+        },
+        destroy() {
+            for (const off of unlisten)
+                off();
+        }
+    };
+}

package/dist/preview/controller.d.ts

@@ -0,0 +1,40 @@
+import type { LiveSession, ChangeSet, ContentHit } from '@quillmark/wasm';
+import type { DocPath, Place } from '../core/address.js';
+import { type EditorErrorHandler } from '../core/errors.js';
+import { type PreviewStringsInput } from './strings.js';
+export interface PreviewOptions {
+    /** The element the preview mounts into; becomes the scroll viewport. */
+    container: HTMLElement;
+    /** Pages kept painted beyond the visible band. Default 1. */
+    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 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;
+    /** The three message-state strings, keyed and partial: unset keys take the
+     *  package's English. */
+    strings?: PreviewStringsInput;
+}
+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;
+    /**
+     * 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
+     * bloom fires only on a change of address.
+     *
+     * Takes the editor's own `onCaretMove` payload, so the editor→preview half of
+     * the bridge is `onCaretMove={preview.focusPosition}` and translates nothing. A
+     * `ContentHit` carries both members and fits here too.
+     */
+    focusPosition(at: Place): void;
+    /** Fold a density multiplier into every future paint (crispness, not layout). */
+    setZoom(scale: number): void;
+    destroy(): void;
+}
+export declare function createPreview(session: LiveSession, opts: PreviewOptions): PreviewController;

package/dist/preview/controller.js

@@ -0,0 +1,141 @@
+import { reportError, errorMessage } from '../core/errors.js';
+import { createPaintLoop } from './paint.js';
+import { createOverlay } from './overlay.js';
+import { createBridge } from './bridge.js';
+import { mergePreviewStrings } from './strings.js';
+const CONTAINER_CLASS = 'qm-preview';
+// The message states share one element; each carries `MESSAGE_CLASS` plus a
+// state class so a consumer (and the tests) can target them. `EMPTY_CLASS` is
+// the zero-page hook consumers and tests target.
+const MESSAGE_CLASS = 'qm-preview-message';
+const EMPTY_CLASS = 'qm-preview-empty';
+const UNSUPPORTED_CLASS = 'qm-preview-unsupported';
+const ERROR_CLASS = 'qm-preview-error';
+export function createPreview(session, opts) {
+    const container = opts.container;
+    const margin = opts.margin ?? 1;
+    const overlaysEnabled = opts.overlays ?? true;
+    const t = mergePreviewStrings(opts.strings);
+    container.classList.add(CONTAINER_CLASS);
+    // The full-container message slot, shared by every non-paint state: the empty
+    // seed / drop-to-zero, a compile that cannot paint (`supportsCanvas` false),
+    // and a paint that threw. One element, restamped; these states are mutually
+    // exclusive, and the zero-page case keeps its `qm-preview-empty` hook.
+    let message;
+    function showMessage(text, state) {
+        if (!message) {
+            message = document.createElement('div');
+            container.appendChild(message);
+        }
+        message.className = `${MESSAGE_CLASS} ${state}`;
+        message.textContent = text;
+    }
+    function hideMessage() {
+        message?.remove();
+        message = undefined;
+    }
+    // The paint loop is safe at any page count: zero pages reconciles to zero
+    // slots and never calls the `paint`/`pageSize` verbs the boundary refuses
+    // there. A paint that unexpectedly throws is caught per-slot and surfaced
+    // through the shared message rather than aborting the observer callback
+    // mid-sweep (runtime.d.ts: even a `supportsCanvas` compile can hit a paint
+    // the boundary refuses; brittle to leave uncaught).
+    const paintLoop = createPaintLoop(session, container, margin, (page, err) => {
+        reportError(opts.onError, {
+            code: 'paint-failed',
+            severity: 'error',
+            message: `painting page ${page} failed: ${errorMessage(err)}`,
+            cause: err,
+            page
+        });
+        showMessage(t.renderFailed, ERROR_CLASS);
+    });
+    // overlay/bridge query geometry at build (`session.regions()`), so they are
+    // held until slots exist; (re)built by `render` when a compile is paintable.
+    let overlay;
+    let bridge;
+    // overlay/bridge live and die with the slot set. Rebuilt (not patched) whenever
+    // the count changes: the slots array is a stable identity but its members are
+    // 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);
+    }
+    function detach() {
+        overlay?.destroy();
+        bridge?.destroy();
+        overlay = undefined;
+        bridge = undefined;
+    }
+    // Reflect one compile's paintability into the DOM: page slots + overlay/bridge
+    // when there is something to paint, the shared message otherwise. Called at
+    // construction and after every `apply`, so `supportsCanvas` is re-read per
+    // compile (runtime.d.ts: re-check after `open`) and a 0-page or non-canvas
+    // compile that later gains paintable pages recovers; the check spans the
+    // paint capability generally, not just the page count.
+    function render(pageCount, dirtyPages) {
+        if (!session.supportsCanvas || pageCount === 0) {
+            // Nothing paintable: collapse slots, drop geometry attachments, say why.
+            // A 0-page compile is a recoverable empty; a compile with pages the
+            // boundary cannot raster is a genuine unsupported.
+            paintLoop.refresh([], 0);
+            detach();
+            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
+        // leaves its error surfaced rather than have `hideMessage` clobber it.
+        const countChanged = pageCount !== paintLoop.slots.length;
+        hideMessage();
+        paintLoop.refresh(dirtyPages, pageCount);
+        if (countChanged || !bridge) {
+            // The slot set moved under overlay/bridge's feet (pages added/removed,
+            // or we are leaving a message state): rebuild both against the
+            // reconciled slots rather than patch a stale snapshot in place.
+            detach();
+            attach();
+        }
+        else {
+            // Box positions can still shift within the same page set (text reflow),
+            // so geometry is always re-read, not just dirty pages.
+            overlay?.refresh();
+        }
+    }
+    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
+    // 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
+    // preview's, not the consumer's: the staleness sits between two session queries
+    // this module owns both ends of.
+    let followed;
+    return {
+        refresh(change) {
+            render(change.pageCount, change.dirtyPages);
+            // Guarded like any other caret hop, so a caret already clear of the fold
+            // leaves a pane the user scrolled where they left it.
+            if (followed)
+                bridge?.focusPosition(followed.field, followed.pos);
+        },
+        scrollToField(field) {
+            bridge?.scrollToField(field);
+            overlay?.flashField(field);
+        },
+        focusPosition(at) {
+            followed = at;
+            bridge?.focusPosition(at.field, at.pos);
+            overlay?.flashField(at.field);
+        },
+        setZoom(scale) {
+            paintLoop.setDensityZoom(scale);
+        },
+        destroy() {
+            detach();
+            paintLoop.destroy();
+            hideMessage();
+            container.classList.remove(CONTAINER_CLASS);
+        }
+    };
+}

package/dist/preview/geometry.d.ts

@@ -0,0 +1,37 @@
+import type { 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). */
+export interface PercentRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** A point in PDF points, bottom-left origin (the space `positionAt`/`fieldAt` read). */
+export interface PdfPoint {
+    x: number;
+    y: number;
+}
+/**
+ * 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
+ * what the overlay draws (overlay.ts).
+ */
+export declare function rectToPercent(rect: PdfRect, pageSize: PageSize): PercentRect;
+/**
+ * Position `el` absolutely at `pct` (the % rect this module produces); the one
+ * `PercentRect` → `element.style` write, shared by the overlay's field boxes and
+ * the bridge's scroll marker so the positioning convention lives in one place.
+ * The caller sets any box chrome (border, background) on top.
+ */
+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
+ * 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.
+ * This is what the click bridge feeds `session.positionAt`/`fieldAt` (bridge.ts).
+ */
+export declare function clickToPdfPt(px: number, py: number, cssW: number, cssH: number, pageSize: PageSize): PdfPoint;

package/dist/preview/geometry.js

@@ -0,0 +1,45 @@
+/**
+ * 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
+ * what the overlay draws (overlay.ts).
+ */
+export function rectToPercent(rect, pageSize) {
+    const [x0, y0, x1, y1] = rect;
+    const { widthPt, heightPt } = pageSize;
+    return {
+        left: (x0 / widthPt) * 100,
+        top: (1 - y1 / heightPt) * 100,
+        width: ((x1 - x0) / widthPt) * 100,
+        height: ((y1 - y0) / heightPt) * 100
+    };
+}
+/**
+ * Position `el` absolutely at `pct` (the % rect this module produces); the one
+ * `PercentRect` → `element.style` write, shared by the overlay's field boxes and
+ * the bridge's scroll marker so the positioning convention lives in one place.
+ * The caller sets any box chrome (border, background) on top.
+ */
+export function applyPercentRect(el, pct) {
+    Object.assign(el.style, {
+        position: 'absolute',
+        left: `${pct.left}%`,
+        top: `${pct.top}%`,
+        width: `${pct.width}%`,
+        height: `${pct.height}%`
+    });
+}
+/**
+ * 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
+ * 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.
+ * This is what the click bridge feeds `session.positionAt`/`fieldAt` (bridge.ts).
+ */
+export function clickToPdfPt(px, py, cssW, cssH, pageSize) {
+    const { widthPt, heightPt } = pageSize;
+    return {
+        x: (px / cssW) * widthPt,
+        y: heightPt - (py / cssH) * heightPt
+    };
+}

package/dist/preview/index.d.ts

@@ -0,0 +1,5 @@
+export { createPreview } from './controller.js';
+export type { PreviewOptions, PreviewController } from './controller.js';
+export { default as Preview } from './Preview.svelte';
+export { DEFAULT_PREVIEW_STRINGS } from './strings.js';
+export type { PreviewStrings, PreviewStringsInput } from './strings.js';

package/dist/preview/index.js

@@ -0,0 +1,14 @@
+// `@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
+// (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.
+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
+// 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.
+export { DEFAULT_PREVIEW_STRINGS } from './strings.js';

package/dist/preview/overlay.d.ts

@@ -0,0 +1,10 @@
+import type { LiveSession } from '@quillmark/wasm';
+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. */
+    flashField(field: string): void;
+    destroy(): void;
+}
+export declare function createOverlay(session: LiveSession, slots: readonly PageSlot[]): OverlayController;

package/dist/preview/overlay.js

@@ -0,0 +1,82 @@
+import { bloom, bloomTiming, primeWash } from '../core/bloom.js';
+import { rectToPercent, applyPercentRect } from './geometry.js';
+const FIELD_ATTR = 'data-qm-field';
+export function createOverlay(session, slots) {
+    const layers = slots.map((slot) => {
+        const layer = document.createElement('div');
+        layer.className = 'qm-overlay-layer';
+        Object.assign(layer.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
+        slot.el.appendChild(layer);
+        return layer;
+    });
+    // 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
+    // clearing. The editor→preview signal is continuous (every caret move, so every
+    // keystroke), and only a change of address is an event; marking the field being
+    // typed into is noise the recompile already answers, since the changed text
+    // repaints under the caret 120ms later.
+    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
+    // 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)
+            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.
+    function build() {
+        for (const layer of layers)
+            layer.replaceChildren();
+        byField = new Map();
+        const fields = new Set();
+        for (const region of session.regions())
+            fields.add(region.field);
+        for (const field of fields) {
+            const els = [];
+            for (const box of session.fieldBoxes(field)) {
+                const layer = layers[box.page];
+                const slot = slots[box.page];
+                if (!layer || !slot)
+                    continue;
+                const pct = rectToPercent(box.rect, slot.size);
+                const el = document.createElement('div');
+                el.className = 'qm-field-box';
+                el.setAttribute(FIELD_ATTR, field);
+                applyPercentRect(el, pct);
+                el.style.borderRadius = 'var(--_qm-radius-inner)';
+                primeWash(el);
+                layer.appendChild(el);
+                els.push(el);
+            }
+            if (els.length)
+                byField.set(field, els);
+        }
+        applyFlash();
+    }
+    build();
+    return {
+        refresh: build,
+        flashField(field) {
+            if (field === flash?.field)
+                return;
+            flash = { field, startedAt: performance.now() };
+            applyFlash();
+        },
+        destroy() {
+            for (const layer of layers)
+                layer.remove();
+        }
+    };
+}

package/dist/preview/paint.d.ts

@@ -0,0 +1,17 @@
+import type { LiveSession, PageSize } from '@quillmark/wasm';
+/** One page's DOM slot: the box overlay.ts/bridge.ts position against, plus its cached geometry. */
+export interface PageSlot {
+    readonly page: number;
+    readonly size: PageSize;
+    readonly el: HTMLElement;
+}
+export interface PaintLoop {
+    /** Live view of the current per-page slots; same array identity for the loop's life. */
+    readonly slots: readonly PageSlot[];
+    /** Reconcile slot count to `pageCount`, re-cache geometry, repaint mounted `dirtyPages`. */
+    refresh(dirtyPages: readonly number[], pageCount: number): void;
+    /** Fold a density multiplier into every future paint; repaints mounted pages now. */
+    setDensityZoom(zoom: number): void;
+    destroy(): void;
+}
+export declare function createPaintLoop(session: LiveSession, container: HTMLElement, margin: number, onPaintError?: (page: number, err: unknown) => void): PaintLoop;