@quillmark/svelte 0.2.0 → 0.3.1

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, 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.
 
-   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);
@@ -50,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);
 
@@ -58,7 +69,7 @@
 	   so it does not derive from the spacing dial. */
 	--qmh-measure: 34rem;
 
-	/* The floor under a control a THUMB lands on. Hand geometry rather than rhythm, which
+	/* 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. */
@@ -73,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;
@@ -94,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

@@ -1,10 +1,10 @@
 <!--
   `@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); pure passthrough, no added logic.
+  (e.g. after `session.apply` elsewhere).
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
@@ -16,10 +16,10 @@
 	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
-	 * 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`, `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
@@ -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
@@ -97,15 +86,16 @@
 <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).
+	/* A detached root: the preview is not a descendant of the editor, so it carries
+	   `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 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;
@@ -114,6 +104,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

@@ -3,10 +3,10 @@ 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`, `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
+ * Remount contract. `createPreview` binds once in `onMount`; a later change to any
+ * 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.
  *
  * `onError` is itself once-bound, so a swapped handler means the report of its own
@@ -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

@@ -1,10 +1,10 @@
 import { boxesForField, rectToPercent, clickToPdfPt, applyPercentRect } from './geometry.js';
 export function createBridge(session, container, slots, onPick) {
     const unlisten = [];
-    // TWO RUNGS: `positionAt` over span-tracked content, `fieldAt` over every placement
+    // 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
+    // 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) {
@@ -53,7 +53,7 @@ export function createBridge(session, container, slots, onPick) {
         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.
@@ -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;
         },
@@ -81,7 +81,7 @@ export function createBridge(session, container, slots, onPick) {
             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

@@ -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,61 +45,46 @@ 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);
             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();
         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.
-    // `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,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,20 +29,19 @@ 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;
 /**
  * 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,8 +1,7 @@
 /**
  * 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
@@ -20,8 +19,8 @@ export function boxesForField(field, boxes, regions) {
 }
 /**
  * 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 function rectToPercent(rect, pageSize) {
     const [x0, y0, x1, y1] = rect;
@@ -34,10 +33,9 @@ export function rectToPercent(rect, pageSize) {
     };
 }
 /**
- * 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 function applyPercentRect(el, pct) {
     Object.assign(el.style, {
@@ -50,7 +48,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.js

@@ -1,12 +1,12 @@
 // `@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
+// The theme derivation, which the page slots 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
@@ -14,7 +14,7 @@
 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/paint.d.ts

@@ -1,5 +1,5 @@
 import type { LiveSession, PageSize } from '@quillmark/wasm';
-/** One page's DOM slot: the box overlay.ts/bridge.ts position against, plus its cached geometry. */
+/** One page's DOM slot: the box bridge.ts measures against, plus its cached geometry. */
 export interface PageSlot {
     readonly page: number;
     readonly size: PageSize;