@quillmark/svelte 0.3.0 → 0.3.1

package/NOTICE

@@ -6,9 +6,9 @@ Copyright 2026 Nibs
 This package contains SVG glyph geometry derived from Lucide, carried in source
 rather than installed.
 
-`visual/icons/nodes.ts` holds thirteen verbatim from @lucide/svelte 1.28.0:
-chevron-right, chevron-down, chevron-up, bold, italic, underline, strikethrough,
-code, link, hash, info, plus and x.
+`visual/icons/nodes.ts` holds sixteen verbatim from @lucide/svelte 1.28.0:
+chevron-right, arrow-right, chevron-down, chevron-up, bold, italic, underline,
+strikethrough, code, link, hash, info, plus, x, trash-2 and minus.
 
 `core/codec/table-view.ts` holds a plus and four text-alignment glyphs derived
 from an earlier release of the same project.
@@ -31,9 +31,9 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 --------------------------------------------------------------------------------
 
-Ten of those glyphs — chevron-down, chevron-right, chevron-up, code, hash, info,
-italic, link, plus and x — are derived from the Feather project and carry its
-license as well.
+Thirteen of those glyphs — arrow-right, chevron-down, chevron-right, chevron-up,
+code, hash, info, italic, link, minus, plus, trash-2 and x — are drawn exactly as
+the Feather project draws them and carry its license as well.
 
 The MIT License (MIT)
 

package/README.md

@@ -83,7 +83,7 @@ preview.refresh(session.update(doc)); // repaint dirtyPages ∩ visible
 
 In Svelte, `<Preview {session} onPick={…} />` exposes the same verbs (`refresh`, `scrollToField`, `focusPosition`, `setZoom`) via `bind:this`.
 
-`<Preview>` binds **once**, at mount: swapping `session`, `margin`, `overlays`, `onPick`, `onError` or `strings` in place changes nothing on screen and reports `rebind-ignored` through `onError` at `dev` severity, naming the prop. Swap by remounting (`{#key session}`); drive in-place edits through `refresh(change)`. `class` and `style` are the exceptions, landing on the root element and staying live.
+`<Preview>` binds **once**, at mount: swapping `session`, `margin`, `onPick`, `onError` or `strings` in place changes nothing on screen and reports `rebind-ignored` through `onError` at `dev` severity, naming the prop. Swap by remounting (`{#key session}`); drive in-place edits through `refresh(change)`. `class` and `style` are the exceptions, landing on the root element and staying live.
 
 ## Visual editor
 

package/THEMING.md

@@ -53,7 +53,7 @@ The poles take a colour, not `transparent` or `inherit`: the raised surfaces, th
 | ---------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--qm-bg`        | `#fff` / `#272729`                     | Base surface: a card, and the preview's sheet. Fields, the popover and the column behind the cards each step off it.                                           |
 | `--qm-fg`        | `#1c1c1c` / `#d7dadc`                  | Base ink. Body text, labels, and borders step off it.                                                                                                          |
-| `--qm-accent`    | `#2563eb`                              | Focus rings, active marks, the preview's active field box.                                                                                                     |
+| `--qm-accent`    | `#71717a` / `#a1a1aa`                  | Focus rings, active marks, the preview's active field box. The surface spends no hue of its own, so this is the one it wears.                                  |
 | `--qm-danger`    | `#c5221f`                              | Error diagnostics, the required marker, the delete glyph.                                                                                                      |
 | `--qm-warning`   | `#b25000`                              | Warning diagnostics.                                                                                                                                           |
 | `--qm-font`      | `ui-sans-serif, system-ui, sans-serif` | The editor surface's font family. Controls and buttons take it too, in place of the UA face.                                                                   |

package/dist/core/bloom.d.ts

@@ -1,37 +1,8 @@
-/** The resting state a bloom animates from and back to: the wash, held at zero. */
-export declare function primeWash(el: HTMLElement): void;
-/** What one bloom runs: resolved from the scale, and from the viewer's motion
- *  preference. */
-export interface BloomTiming {
-    duration: number;
-    frames: Keyframe[];
-}
-/**
- * Resolve the timing off `el`, so the dwell is single-sourced in CSS.
- *
- * One property, both motion preferences: `--_qm-bloom-dwell` already shortens under
- * `prefers-reduced-motion` in the derivation, so what is left to `matchMedia` here is
- * the shape: a hold and a cut carry no ramps, which is a frame list rather than a
- * number and the one half CSS cannot hand over.
- *
- * Read once per batch, not per element: `getComputedStyle` forces a style recalc and
- * `animate` re-dirties style, so a read inside a loop flushes once per element (~0.15ms
- * each). The rungs inherit, so every element in a batch resolves the same numbers.
- */
-export declare function bloomTiming(el: HTMLElement): BloomTiming;
-/**
- * Bloom the wash on `el` itself: the caller owns the element and has primed it
- * ({@link primeWash}). Returns the running animation, or `undefined` when there is
- * nothing left to run: `elapsed` past the decay, or an environment without WAAPI.
- * Pass `timing` to share one resolve across a batch.
- */
-export declare function bloom(el: HTMLElement, elapsed?: number, timing?: BloomTiming): Animation | undefined;
 /**
  * Bloom over `host`'s content: an inset child, so the wash neither tints the host's
  * own background nor fades the text under it. `host` must be positioned.
  *
  * One wash node per host, reused while it lives: two quick landings on the same leaf
- * must not stack two alphas over it. No `elapsed` seam: the surfaces that use this
- * (editor leaves) are not rebuilt under the animation the way the preview's boxes are.
+ * must not stack two alphas over it.
  */
 export declare function bloomInside(host: HTMLElement): void;

package/dist/core/bloom.js

@@ -1,21 +1,11 @@
-// The correlation bloom: a soft accent wash that rises over a target and decays to
-// nothing. The editor↔preview address is an event, not a state: the preview claims
-// to be the rendered output, so it carries no resting ink, and a highlight that
-// outlives the hop that caused it is ink the document did not ask for. Both
-// directions land here: the preview's field boxes bloom themselves (they are already
-// empty rects over the page), an editor leaf blooms a transient child over its
-// surface.
+// The arrival wash: a soft accent bloom that rises over a leaf the editor just
+// landed on and decays to nothing. A landing is an event, not a state, so a
+// highlight that outlives the hop that caused it is ink nothing asked for.
 //
 // Opacity is the animated property, never the colour. The wash's alpha is a peak
 // fixed by `--_qm-accent-wash`, so interpolating 0→1→0 keeps the scale in CSS where
 // `color-mix` resolves, instead of in keyframe values a script would have to
 // pre-resolve and re-resolve on a theme change.
-//
-// `elapsed` is what lets a bloom survive the element that carries it. `overlay.ts`
-// rebuilds every box on refresh and the playground recompiles 120ms after each
-// keystroke burst, so a bloom re-STARTED per rebuild would re-bloom continuously
-// while the user writes; a rebuilt node resumes at the offset the old one reached.
-/** Marks a transient wash node: the wash is decoration, never a hit target. */
 const BLOOM_CLASS = 'qm-bloom';
 const WASH = 'var(--_qm-accent-wash)';
 /** The dwell used when the derivation is out of reach (an unstyled root, or jsdom,
@@ -33,53 +23,30 @@ const FRAMES = [
     { opacity: 0, offset: 1 }
 ];
 const FRAMES_REDUCED = [{ opacity: 1 }, { opacity: 1 }];
-/** The resting state a bloom animates from and back to: the wash, held at zero. */
-export function primeWash(el) {
-    Object.assign(el.style, { background: WASH, opacity: '0' });
-}
 /**
- * Resolve the timing off `el`, so the dwell is single-sourced in CSS.
+ * Run one wash on `el`, resolving the dwell off it so the number is single-sourced
+ * in CSS.
  *
  * One property, both motion preferences: `--_qm-bloom-dwell` already shortens under
  * `prefers-reduced-motion` in the derivation, so what is left to `matchMedia` here is
  * the shape: a hold and a cut carry no ramps, which is a frame list rather than a
  * number and the one half CSS cannot hand over.
- *
- * Read once per batch, not per element: `getComputedStyle` forces a style recalc and
- * `animate` re-dirties style, so a read inside a loop flushes once per element (~0.15ms
- * each). The rungs inherit, so every element in a batch resolves the same numbers.
  */
-export function bloomTiming(el) {
+function bloom(el) {
+    if (typeof el.animate !== 'function')
+        return undefined;
     const reduced = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
     const raw = getComputedStyle(el).getPropertyValue('--_qm-bloom-dwell').trim();
     const n = Number.parseFloat(raw);
     const duration = !Number.isFinite(n) ? FALLBACK_MS : raw.endsWith('ms') ? n : n * 1000;
-    return { duration, frames: reduced ? FRAMES_REDUCED : FRAMES };
-}
-/**
- * Bloom the wash on `el` itself: the caller owns the element and has primed it
- * ({@link primeWash}). Returns the running animation, or `undefined` when there is
- * nothing left to run: `elapsed` past the decay, or an environment without WAAPI.
- * Pass `timing` to share one resolve across a batch.
- */
-export function bloom(el, elapsed = 0, timing) {
-    if (typeof el.animate !== 'function')
-        return undefined;
-    const { duration, frames } = timing ?? bloomTiming(el);
-    if (elapsed >= duration)
-        return undefined;
-    const anim = el.animate(frames, { duration });
-    if (elapsed > 0)
-        anim.currentTime = elapsed;
-    return anim;
+    return el.animate(reduced ? FRAMES_REDUCED : FRAMES, { duration });
 }
 /**
  * Bloom over `host`'s content: an inset child, so the wash neither tints the host's
  * own background nor fades the text under it. `host` must be positioned.
  *
  * One wash node per host, reused while it lives: two quick landings on the same leaf
- * must not stack two alphas over it. No `elapsed` seam: the surfaces that use this
- * (editor leaves) are not rebuilt under the animation the way the preview's boxes are.
+ * must not stack two alphas over it.
  */
 export function bloomInside(host) {
     let el = host.querySelector(`:scope > .${BLOOM_CLASS}`);
@@ -99,9 +66,10 @@ export function bloomInside(host) {
             position: 'absolute',
             inset: '0',
             pointerEvents: 'none',
-            borderRadius: 'inherit'
+            borderRadius: 'inherit',
+            background: WASH,
+            opacity: '0'
         });
-        primeWash(el);
         host.appendChild(el);
     }
     const node = el;

package/dist/core/codec/prose.css

@@ -136,7 +136,7 @@ li.ProseMirror-selectednode::after {
    same schema, and a solid rule renders an authored `<u>` and a link identically in a
    paragraph that can hold both. An underline at all, where the tips card's link takes
    none, because this leaf is editable: the `href` is otherwise imperceptible, so
-   removing the rule loses an answer rather than ornament. No hue:
+   removing the rule loses an answer rather than ornament. No tone of its own:
    `--_qm-accent` already means focus, and a body of accent-coloured links collides
    with the ring and with the correlation wash. */
 .ProseMirror a {
@@ -289,9 +289,9 @@ li.ProseMirror-selectednode::after {
    focus indicator here exactly as it is in the leaf: no ring.
 
    The height floor is one line box, named as size times leading so both factors move
-   with the type ramp (`.qm-prose-block` states the same expression for three). An
-   empty row is then the height it will be once typed, so the first keystroke changes
-   no geometry. */
+   with the type ramp (`.qm-prose-block` states the same floor against `1em`, whichever
+   rung that leaf sets). An empty row is then the height it will be once typed,
+   so the first keystroke changes no geometry. */
 .qm-table-cell-host {
 	min-width: 4rem;
 	min-height: calc(var(--_qm-text-body) * var(--_qm-leading-body));
@@ -475,8 +475,7 @@ li.ProseMirror-selectednode::after {
 
 /* A drag in flight. The lifted line reads as picked up by tone, never a shadow:
    elevation is a surface rung here, which says the same thing at both poles. The drop
-   rule is the accent, the surface's one saturated ink, spent where a change is about
-   to land. */
+   rule is the accent, the ink the surface keeps for a state rather than for text. */
 .qm-table-dragging .qm-table-cell.qm-table-lifted {
 	background: var(--_qm-surface-raised);
 	opacity: var(--_qm-opacity-muted);

package/dist/core/theme.css

@@ -86,7 +86,9 @@
 		   off it, and the column is a step down. */
 		--_qm-bg: var(--qm-bg, light-dark(#fff, #272729));
 		--_qm-fg: var(--qm-fg, light-dark(#1c1c1c, #d7dadc));
-		--_qm-accent: var(--qm-accent, #2563eb);
+		/* Neutral: the surface spends no hue on a state it can draw in grey. The pair
+		   clears WCAG 2.4.11's 3:1 against the card at both poles, at 4.8:1 and 5.8:1. */
+		--_qm-accent: var(--qm-accent, light-dark(#71717a, #a1a1aa));
 		--_qm-danger: var(--qm-danger, #c5221f);
 		--_qm-warning: var(--qm-warning, #b25000);
 		--_qm-font: var(--qm-font, ui-sans-serif, system-ui, sans-serif);
@@ -156,9 +158,9 @@
 		--_qm-ink: var(--_qm-fg);
 		--_qm-ink-label: color-mix(in oklab, var(--_qm-fg), var(--_qm-bg) 35%);
 		--_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
-		   over the preview's paper while the paper rests clean. */
+		/* The arrival 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 over the leaf it
+		   lands on while the leaf rests clean. */
 		--_qm-accent-wash: color-mix(in oklab, var(--_qm-accent) 18%, transparent);
 		/* The accent held: what a selected line of a table is tinted with, and what its
 		   grip is filled with, so the two ends of one gesture are one colour. A second
@@ -180,16 +182,26 @@
 		/* The tips card'S hue: the surface's one exit from the greyscale that is not
 		   a status, and what the amber and the typewriter face say together is
 		   draft (VISUAL_EDITOR §"Card operations"). A literal rather than a dial
-		   because there is nothing left to turn: the three rungs under it mix over
+		   because there is nothing left to turn: the rungs under it mix over
 		   the surface and the ink a consumer already tuned, so the card follows a
 		   brand untold. The mixes are faint on purpose: a warmth, not a badge. */
 		--_qm-tips: #e88c0a;
 		--_qm-tips-surface: color-mix(in oklab, var(--_qm-surface), var(--_qm-tips) 4%);
 		--_qm-tips-ink: color-mix(in oklab, var(--_qm-ink), var(--_qm-tips) 24%);
-		/* The chip behind a token in a tip. The card's own face is already
-		   monospace, so a `code` run needs a fill to read as literal text rather
-		   than as the sentence around it. */
-		--_qm-tips-chip: color-mix(in oklab, var(--_qm-tips) 12%, transparent);
+		/* The ink and the amber stepped up, and the pair is spent on the two runs that
+		   are not the sentence: a token in a tip, and the foot's control under the
+		   pointer. One rung each rather than one per run, a chip and a hover four
+		   percent apart being a number with no second decision under it. */
+		--_qm-tips-ink-warm: color-mix(in oklab, var(--_qm-ink), var(--_qm-tips) 45%);
+		--_qm-tips-fill: color-mix(in oklab, var(--_qm-tips) 12%, transparent);
+		/* The typewriter, the half of the slip the amber cannot carry: a modern mono
+		   reads as code where a Courier reads as typed. Its own rung rather than
+		   `--_qm-font-mono`, the chrome's readout face, which a consumer turns for
+		   tabular figures and not to dress this card. Courier Prime leads and is nobody's
+		   system font, so a host that loads it lands on it and every other host falls to
+		   the Courier the platform already carries; the package fetches nothing, a preset
+		   costing a network request being one a consumer cannot decline. */
+		--_qm-tips-font: 'Courier Prime', 'Courier New', Courier, ui-monospace, monospace;
 
 		/* ── Ratios and effects ──────────────────────────────────────────────────
 		   No palette fixes these, so they are their own rungs. There is no shadow
@@ -213,15 +225,18 @@
 		   ring, and on what state, is the other half: a rule, `.qm-focus-ring` in
 		   `visual/controls.css`, since a rung each control reassembles is a scale
 		   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;
-		/* 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. */
+		   state that draws a ring anywhere, so there is no held-back tier under it.
+		   Sub-pixel, because at two it reads as a second border on a card whose every
+		   other edge is a hairline. */
+		--_qm-ring-width: 1.5px;
+		/* Every ring the surface draws, 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. */
 		--_qm-ring: var(--_qm-ring-width) solid var(--_qm-accent);
 		--_qm-ring-offset: 1px;
+		/* What a clip box carries past its content for a focused control inside it to
+		   keep the whole mark. */
+		--_qm-ring-reach: calc(var(--_qm-ring-width) + var(--_qm-ring-offset));
 
 		/* ── Motion ──────────────────────────────────────────────────────────────
 		   Two rungs, by what the trip disturbs: `fast` stays inside the element's own
@@ -265,6 +280,7 @@
 		--_qm-space-2: calc(var(--_qm-space) * 2);
 		--_qm-space-3: calc(var(--_qm-space) * 3);
 		--_qm-space-4: calc(var(--_qm-space) * 4);
+		--_qm-space-5: calc(var(--_qm-space) * 5);
 		/* 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

package/dist/preset/scale.css

@@ -2,9 +2,9 @@
    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
+   border, 45% and 60% ink, the ring's width) 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.
 
@@ -61,7 +61,7 @@
 	--qmh-space-3: calc(var(--qmh-space) * 3);
 	--qmh-space-4: calc(var(--qmh-space) * 4);
 	--qmh-border-width: 1px;
-	--qmh-ring-width: 2px;
+	--qmh-ring-width: 1.5px;
 	--qmh-radius: var(--qm-radius, 8px);
 	--qmh-radius-inner: calc(var(--qmh-radius) / 2);
 

package/dist/preview/Preview.svelte

@@ -1,7 +1,7 @@
 <!--
   `@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
+  paint.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).
@@ -17,8 +17,8 @@
 
 	/**
 	 * 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
+	 * prop it closed over (`session`, `margin`, `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.
 	 *
@@ -35,7 +35,6 @@
 		 *  not this attribute. */
 		style?: string;
 		margin?: number;
-		overlays?: boolean;
 		onPick?: (at: Landing) => void;
 		/** A page paint the backend refused; the error message state shows either way. */
 		onError?: EditorErrorHandler;
@@ -43,22 +42,13 @@
 		strings?: PreviewStringsInput;
 	}
 
-	let {
-		session,
-		margin,
-		overlays,
-		onPick,
-		onError,
-		strings,
-		class: className,
-		style
-	}: Props = $props();
+	let { session, margin, onPick, onError, strings, class: className, style }: Props = $props();
 
 	let containerEl: HTMLDivElement | undefined = $state();
 	let controller: PreviewController | undefined;
 
 	guardRebind(
-		() => ({ session, margin, overlays, onPick, onError, strings }),
+		() => ({ session, margin, onPick, onError, strings }),
 		'Remount the preview ({#key session}) to rebind.'
 	);
 
@@ -67,7 +57,6 @@
 		controller = createPreview(session, {
 			container: containerEl,
 			margin,
-			overlays,
 			onPick,
 			onError,
 			strings
@@ -98,8 +87,7 @@
 
 <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).
+	   `data-qm-root` for the page rungs paint.ts reads (core/theme.css).
 
 	   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

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

@@ -4,8 +4,8 @@ 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`, `onPick`, `onError`,
- * `strings`) is not observed, and each reports `rebind-ignored` when swapped. Swap
+ * prop it closed over (`session`, `margin`, `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.
  *
@@ -22,7 +22,6 @@ interface Props {
      *  not this attribute. */
     style?: string;
     margin?: number;
-    overlays?: boolean;
     onPick?: (at: Landing) => void;
     /** A page paint the backend refused; the error message state shows either way. */
     onError?: EditorErrorHandler;

package/dist/preview/bridge.js

@@ -69,8 +69,8 @@ export function createBridge(session, container, slots, onPick) {
             const slot = slots[box.page];
             if (!slot)
                 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.
+            // A discrete act ("show me this field"), so it centres every time, unlike
+            // the continuous hop below.
             centre(measure(slot, rectToPercent(box.rect, slot.size)));
             return true;
         },

package/dist/preview/controller.d.ts

@@ -7,8 +7,6 @@ export interface PreviewOptions {
     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 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. */
@@ -21,19 +19,19 @@ export interface PreviewOptions {
     strings?: PreviewStringsInput;
 }
 export interface PreviewController {
-    /** Repaint `dirtyPages ∩ visible` and re-read geometry; the only apply-driven hop. */
+    /** Repaint `dirtyPages ∩ visible` and re-locate the followed caret; the only
+     *  apply-driven hop. */
     refresh(change: ChangeSet): 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.
+     * Scroll `field`'s first box into view. `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
-     * bloom fires only on a change of address.
+     * Bring the caret at `at` into view: the pane moves only when the caret has left
+     * the fold.
      *
      * Takes the editor's own `onCaretMove` payload, so the editor→preview half of
      * the bridge is `onCaretMove={preview.focusPosition}` and translates nothing. A

package/dist/preview/controller.js

@@ -1,12 +1,10 @@
 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.
+// The message states share one element; each carries `MESSAGE_CLASS` plus a state
+// class, the hooks a consumer and the tests target.
 const MESSAGE_CLASS = 'qm-preview-message';
 const EMPTY_CLASS = 'qm-preview-empty';
 const UNSUPPORTED_CLASS = 'qm-preview-unsupported';
@@ -14,13 +12,10 @@ 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.
+    // One element, restamped: the non-paint states (empty, unsupported, a paint that
+    // threw) are mutually exclusive.
     let message;
     function showMessage(text, state) {
         if (!message) {
@@ -50,34 +45,26 @@ export function createPreview(session, opts) {
         });
         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;
+    // The bridge lives and dies with the slot set, so it is held until `render` finds
+    // a compile paintable. Rebuilt rather than patched whenever the count changes: the
+    // slots array is a stable identity but its members are swapped on reconcile, and
+    // the listeners are per slot.
     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.onPick);
     }
     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.
+    // 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.
+            // A 0-page compile is a recoverable empty; pages the boundary cannot
+            // raster are a genuine unsupported.
             paintLoop.refresh([], 0);
             detach();
             showMessage(pageCount === 0 ? t.noPages : t.unsupported, pageCount === 0 ? EMPTY_CLASS : UNSUPPORTED_CLASS);
@@ -89,18 +76,11 @@ export function createPreview(session, opts) {
         const countChanged = pageCount !== paintLoop.slots.length;
         hideMessage();
         paintLoop.refresh(dirtyPages, pageCount);
+        // The slot set moved under the bridge's feet, or we are leaving a message state.
         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.
@@ -120,16 +100,11 @@ export function createPreview(session, opts) {
                 bridge?.focusPosition(followed.field, followed.pos);
         },
         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;
+            return bridge?.scrollToField(field) ?? false;
         },
         focusPosition(at) {
             followed = at;
             bridge?.focusPosition(at.field, at.pos);
-            overlay?.flashField(at.field);
         },
         setZoom(scale) {
             paintLoop.setDensityZoom(scale);

package/dist/preview/geometry.d.ts

@@ -15,9 +15,8 @@ export interface PdfPoint {
 }
 /**
  * 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").
+ * rects of everything under it. What the scroll reads, so an address `regions()`
+ * names is never one the preview cannot place (PREVIEW.md §"Two 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
@@ -30,15 +29,14 @@ export interface PdfPoint {
 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
- * what the overlay draws (overlay.ts).
+ * the page's displayed size across DPR and container resize for free, so the
+ * scroll's measurement needs no zoom or DPR term of its own (bridge.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.
+ * Position `el` absolutely at `pct` (the % rect this module produces): the one
+ * `PercentRect` → `element.style` write, so the positioning convention lives beside
+ * the transform that produces it rather than at the caller placing a marker.
  */
 export declare function applyPercentRect(el: HTMLElement, pct: PercentRect): void;
 /**