@quillmark/svelte 0.27.0 → 0.28.0

package/dist/preview/controller.d.ts

@@ -7,15 +7,18 @@ export interface PreviewOptions {
     container: HTMLElement;
     /** Pages kept painted beyond the visible band. Default 1. */
     margin?: number;
-    /** 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. */
+    /**
+     * 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. Does not fire
+     * where it tracks neither.
+     */
     onPick?(at: Landing): void;
-    /** A page paint the backend refused ({@link EditorErrorHandler}). The preview
-     *  shows its error message state either way; this routes it to an app's sink. */
+    /**
+     * A page paint the backend refused ({@link EditorErrorHandler}); the error message state shows
+     * either way.
+     */
     onError?: EditorErrorHandler;
-    /** The surface's strings, keyed and partial: unset keys take the package's
-     *  English. */
+    /** The surface's strings; unset keys take the package's English. */
     strings?: PreviewStringsInput;
 }
 export interface PreviewController {
@@ -23,37 +26,26 @@ export interface PreviewController {
      *  apply-driven hop. */
     refresh(change: ChangeSet): void;
     /**
-     * Scroll `field`'s first box into view, and end any follow it outranks. `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, and end any follow it outranks. `false` when this
+     * compile places nothing at that address; the preview has no schema to tell that from a
+     * misnamed field.
      */
     scrollToField(field: DocPath): boolean;
     /**
-     * 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
-     * `ContentHit` carries both members and fits here too.
+     * Bring the caret at `at` into view; the pane moves only when the caret has left the fold.
+     * Takes the editor's `onCaretMove` payload, so `onCaretMove={preview.focusPosition}` wires it.
      */
     focusPosition(at: Place): void;
     /**
-     * End the follow: the pane stays where the user left it until the next
-     * `focusPosition`. A `scrollToField` that placed its target ends one too.
-     *
-     * The editor's `onActiveLeafChange` is the signal, firing for a form control as for
-     * a prose leaf: `onActiveLeafChange={preview.endFollow}`. A control has no caret
-     * coordinate to report, so unwired the follow keeps naming the leaf the focus left
-     * and every recompile pulls the pane back there. A prose leaf restarts it with its
-     * own next caret.
+     * End the follow: the pane stays where the user left it until the next `focusPosition`. Wire
+     * `onActiveLeafChange={preview.endFollow}`; a form control reports no caret, so unwired the
+     * follow keeps pulling the pane back to the leaf the focus left.
      */
     endFollow(): void;
     /**
-     * Draw every page at `zoom`, a fraction of actual size (`1` is 100%), held between
-     * the pane's floor and 200%; `undefined` is the default, the widest page fitting the
-     * pane's width up to 125%. The reader's own gestures move the same zoom.
+     * Draw every page at `zoom`, a fraction of actual size (`1` is 100%), held between the pane's
+     * floor and 200%; `undefined` is the default, the widest page fitting the pane's width up to
+     * 125%.
      */
     setZoom(zoom: number | undefined): void;
     destroy(): void;

package/dist/preview/controller.js

@@ -4,8 +4,6 @@ import { createBridge } from './bridge.js';
 import { createViewport } from './viewport.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, the hooks a consumer and the tests target.
 const MESSAGE_CLASS = 'qm-preview-message';
 const EMPTY_CLASS = 'qm-preview-empty';
 const ERROR_CLASS = 'qm-preview-error';
@@ -14,8 +12,7 @@ export function createPreview(session, opts) {
     const margin = opts.margin ?? 1;
     const t = mergePreviewStrings(opts.strings);
     container.classList.add(CONTAINER_CLASS);
-    // One element, restamped: the non-paint states (empty, a paint that
-    // threw) are mutually exclusive.
+    // One element, restamped: the message states are mutually exclusive.
     let message;
     function showMessage(text, state) {
         if (!message) {
@@ -29,12 +26,8 @@ export function createPreview(session, opts) {
         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 (a paint is the one surface that can still refuse a counted page;
-    // brittle to leave uncaught).
+    // A paint that throws is caught per slot and surfaced through the message rather than aborting
+    // the observer callback mid-sweep.
     const paintLoop = createPaintLoop(session, container, margin, (page, err) => {
         reportError(opts.onError, {
             code: 'paint-failed',
@@ -45,14 +38,10 @@ export function createPreview(session, opts) {
         });
         showMessage(t.renderFailed, ERROR_CLASS);
     });
-    // 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.
+    // Rebuilt whenever the page count changes: the listeners are per slot and slots are swapped on
+    // reconcile.
     let bridge;
-    // Outlives that rebuild, so a trip held for a pane with no box crosses it. Only the
-    // follow is re-asserted after a recompile, and a `scrollToField` the pane could not
-    // run has nothing else that would ask again for it.
+    // Outlives the bridge rebuild, so a trip held for a pane with no box crosses it.
     const held = {};
     function attach() {
         bridge = createBridge(session, container, paintLoop.slots, opts.onPick, held);
@@ -61,9 +50,6 @@ export function createPreview(session, opts) {
         bridge?.destroy();
         bridge = undefined;
     }
-    // Called at construction and after every `apply`, so a 0-page compile that later
-    // gains pages recovers. A counted page is the whole condition: every backend
-    // paints, and `paint`/`pageSize` refuse only a page the count excludes.
     function render(pageCount, dirtyPages) {
         if (pageCount === 0) {
             paintLoop.refresh([], 0);
@@ -71,46 +57,35 @@ export function createPreview(session, opts) {
             showMessage(t.noPages, EMPTY_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.
+        // Clear the message before painting so an error from this paint is not clobbered.
         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) {
             detach();
             attach();
         }
     }
-    // Built before the first bridge, so its ResizeObserver is the earlier one and a pane
-    // shown again re-fits before the bridge runs the trip it held at the old scale.
+    // Built before the first bridge so its ResizeObserver fires first: a re-shown pane re-fits
+    // before the bridge runs a held trip.
     const viewport = createViewport(container, paintLoop.slots, paintLoop.setScale, t.resetZoom);
     render(session.pageCount, []);
     viewport.update();
-    // The last place the editor put the caret, re-located after every recompile and
-    // dropped on a focus change or a discrete hop. `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.
+    // The last caret the editor reported, re-located after every recompile: `session.locate`
+    // answers against the last compiled layout, so a caret typed past it no-ops until the recompile
+    // lands.
     let followed;
     return {
         refresh(change) {
             render(change.pageCount, change.dirtyPages);
-            // The default fits the widest page, which a recompile can move.
             viewport.update();
-            // 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) {
             const placed = bridge?.scrollToField(field) ?? false;
-            // The discrete hop outranks the follow: a caret re-asserted at the next
-            // recompile would pull the pane straight off the field a host just asked
-            // for. A hop that placed nothing moved nothing, so the follow stands.
+            // The hop outranks the follow, which would otherwise pull the pane back at the next
+            // recompile.
             if (placed)
                 followed = undefined;
             return placed;

package/dist/preview/geometry.d.ts

@@ -14,50 +14,29 @@ export interface PdfPoint {
     y: number;
 }
 /**
- * An address's boxes: `fieldBoxes`'s union, else every `regions()` rect at or under it.
- * What the scroll reads, so an address `regions()` names is never one the preview
- * cannot place (PREVIEW.md §"Two responsibilities").
+ * An address's boxes: `fieldBoxes`'s union, else every `regions()` rect at or under it
+ * (PREVIEW.md §"Two responsibilities"). `fieldBoxes` answers `[]` for a scalar reference
+ * the plate places without tracking its content and for an array itself; the fallback
+ * takes the address and its descendants, matched at a path boundary (`.` or `[`):
+ * `main.keywords` matches `main.keywords[0]`, not `main.keywords_note`.
  *
- * `fieldBoxes` answers `[]` for a scalar reference the plate places without tracking
- * its content and for an array itself; runtime.d.ts says what such a field's box is, a
- * single `regions()` rect. The second rung takes an address and its descendants
- * together, since a container holds both: a plate composing an array's presentation
- * regions the array on the ink it composed — a separator, a heading — where each
- * element regions the ink it carries itself, and the field is placed at all of it. The
- * boundary character (`.` for a nested field, `[` for an array element) keeps the
- * prefix a path boundary: `main.keywords` matches `main.keywords[0]`, not
- * `main.keywords_note`.
- *
- * `regions` is a thunk because the first rung answers without it, and taking it
- * marshals every placement in the compile across the WASM boundary.
+ * `regions` is a thunk because taking it marshals every placement across the WASM boundary.
  */
 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, so the
- * scroll's measurement needs no zoom or DPR term of its own (bridge.ts).
+ * Forward: a PDF-pt rect -> CSS % of the page box, which tracks the displayed size without a zoom
+ * or DPR term.
  */
 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, so the positioning convention lives beside
- * the transform that produces it rather than at the caller placing a marker.
- */
+/** Position `el` absolutely at `pct`. */
 export declare function applyPercentRect(el: HTMLElement, pct: PercentRect): void;
 /**
- * A CSS-px length on a page element of CSS width `cssW` -> the PDF-pt length it spans.
- * Width alone, because that is the scale the slot is drawn at: `paint.ts` sizes a slot
- * by width under a locked aspect ratio, so {@link clickToPdfPt}'s two ratios are one
- * number and a length has one to convert through. What the click bridge reads its
- * pointer slack in points through.
+ * A CSS-px length on a page element of CSS width `cssW` -> PDF-pt. Width alone, since `paint.ts`
+ * locks the aspect ratio.
  */
 export declare function pxToPt(px: number, cssW: number, pageSize: PageSize): number;
 /**
- * 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).
+ * Inverse of {@link rectToPercent}: a click at CSS px `(px, py)` within a page element of CSS size
+ * `(cssW, cssH)` -> PDF-pt.
  */
 export declare function clickToPdfPt(px: number, py: number, cssW: number, cssH: number, pageSize: PageSize): PdfPoint;

package/dist/preview/geometry.js

@@ -1,20 +1,11 @@
 /**
- * An address's boxes: `fieldBoxes`'s union, else every `regions()` rect at or under it.
- * What the scroll reads, so an address `regions()` names is never one the preview
- * cannot place (PREVIEW.md §"Two responsibilities").
+ * An address's boxes: `fieldBoxes`'s union, else every `regions()` rect at or under it
+ * (PREVIEW.md §"Two responsibilities"). `fieldBoxes` answers `[]` for a scalar reference
+ * the plate places without tracking its content and for an array itself; the fallback
+ * takes the address and its descendants, matched at a path boundary (`.` or `[`):
+ * `main.keywords` matches `main.keywords[0]`, not `main.keywords_note`.
  *
- * `fieldBoxes` answers `[]` for a scalar reference the plate places without tracking
- * its content and for an array itself; runtime.d.ts says what such a field's box is, a
- * single `regions()` rect. The second rung takes an address and its descendants
- * together, since a container holds both: a plate composing an array's presentation
- * regions the array on the ink it composed — a separator, a heading — where each
- * element regions the ink it carries itself, and the field is placed at all of it. The
- * boundary character (`.` for a nested field, `[` for an array element) keeps the
- * prefix a path boundary: `main.keywords` matches `main.keywords[0]`, not
- * `main.keywords_note`.
- *
- * `regions` is a thunk because the first rung answers without it, and taking it
- * marshals every placement in the compile across the WASM boundary.
+ * `regions` is a thunk because taking it marshals every placement across the WASM boundary.
  */
 export function boxesForField(field, boxes, regions) {
     if (boxes.length)
@@ -22,9 +13,8 @@ export function boxesForField(field, boxes, regions) {
     return regions().filter((r) => r.field === field || r.field.startsWith(`${field}.`) || r.field.startsWith(`${field}[`));
 }
 /**
- * Forward: a PDF-pt rect -> CSS % of the page box. Percent positioning tracks
- * the page's displayed size across DPR and container resize for free, so the
- * scroll's measurement needs no zoom or DPR term of its own (bridge.ts).
+ * Forward: a PDF-pt rect -> CSS % of the page box, which tracks the displayed size without a zoom
+ * or DPR term.
  */
 export function rectToPercent(rect, pageSize) {
     const [x0, y0, x1, y1] = rect;
@@ -36,11 +26,7 @@ export function rectToPercent(rect, pageSize) {
         height: ((y1 - y0) / heightPt) * 100
     };
 }
-/**
- * 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.
- */
+/** Position `el` absolutely at `pct`. */
 export function applyPercentRect(el, pct) {
     Object.assign(el.style, {
         position: 'absolute',
@@ -51,22 +37,15 @@ export function applyPercentRect(el, pct) {
     });
 }
 /**
- * A CSS-px length on a page element of CSS width `cssW` -> the PDF-pt length it spans.
- * Width alone, because that is the scale the slot is drawn at: `paint.ts` sizes a slot
- * by width under a locked aspect ratio, so {@link clickToPdfPt}'s two ratios are one
- * number and a length has one to convert through. What the click bridge reads its
- * pointer slack in points through.
+ * A CSS-px length on a page element of CSS width `cssW` -> PDF-pt. Width alone, since `paint.ts`
+ * locks the aspect ratio.
  */
 export function pxToPt(px, cssW, pageSize) {
     return (px / cssW) * pageSize.widthPt;
 }
 /**
- * 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).
+ * Inverse of {@link rectToPercent}: a click at CSS px `(px, py)` within a page element of CSS size
+ * `(cssW, cssH)` -> PDF-pt.
  */
 export function clickToPdfPt(px, py, cssW, cssH, pageSize) {
     const { widthPt, heightPt } = pageSize;

package/dist/preview/index.js

@@ -1,20 +1,8 @@
-// `@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`, at the subpath's edge: a relative hop past a
-// module directly in `core/` is what pulls the codec, and all of ProseMirror with it.
-// 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, which carries no sheet.
-// `check:deps` holds the reach.
+// `@quillmark/svelte/preview`: the live-preview surface. Imports no editor-side code; it may reach
+// `/core` and nothing else (`check:deps`).
+// The theme derivation the page slots read through `var()`; a subpath import reaches `core/`
+// modules, never its entry, which carries no sheet.
 import '../core/theme.css';
 export { createPreview } from './controller.js';
 export { default as Preview } from './Preview.svelte';
-// What the preview says: its message states and the zoom pill's name. 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/paint.d.ts

@@ -11,9 +11,9 @@ export interface PaintLoop {
     /** Reconcile slot count to `pageCount`, re-cache geometry, repaint mounted `dirtyPages`. */
     refresh(dirtyPages: readonly number[], pageCount: number): void;
     /**
-     * Draw every page at `scale` CSS px per PDF pt and repaint the mounted ones: on the
-     * next frame, or once `settle` has passed without another call, which is what a
-     * gesture asks for, the stretched raster standing in until it rests.
+     * Draw every page at `scale` CSS px per PDF pt and repaint the mounted ones on the next frame,
+     * or once `settle` ms pass without another call (a gesture's request, the stretched raster
+     * standing in).
      */
     setScale(scale: number, settle?: number): void;
     destroy(): void;

package/dist/preview/paint.js

@@ -1,19 +1,13 @@
-// Vertical breathing room between stacked pages; cosmetic only, and a rung like
-// any other gap: the stack breathes on the same rhythm the cards do.
 const PAGE_GAP = 'var(--_qm-space-4)';
-// The least raster density, in device pixels per CSS pixel. Glyphs rasterize
-// unhinted, so a raster at a 1× or fractional ratio (1.25, 1.5; browser zoom)
-// is resampled nearly 1:1 and small text smears; a raster at least twice the
-// box is downsampled instead, which keeps body text legible.
+// The least raster density, in device pixels per CSS pixel: glyphs rasterize unhinted, so a 1× or
+// fractional raster smears small text where a 2× one downsamples cleanly.
 const MIN_DENSITY = 2;
 export function createPaintLoop(session, container, margin, 
-// Notified when a slot's `session.paint` throws: the loop swallows the throw
-// (see `paintSlot`) so one bad page never aborts the band sweep; the caller
-// decides how to surface it.
+// Notified when a slot's `session.paint` throws; the throw is swallowed so one bad page never
+// aborts the band sweep.
 onPaintError) {
-    // The IntersectionObserver root must be a scrollable ancestor of the slots;
-    // respect a consumer's own choice if they already set one (computed style, so
-    // a stylesheet rule counts as a choice, not just an inline style).
+    // The IntersectionObserver root must be a scrollable ancestor of the slots; a consumer's own
+    // choice stands.
     const computed = getComputedStyle(container);
     if (computed.overflowY === 'visible')
         container.style.overflowY = 'auto';
@@ -42,27 +36,15 @@ onPaintError) {
     }, { root: container, threshold: 0 });
     function makeSlot(page) {
         const size = session.pageSize(page);
-        // The sheet is a plane and the desk is the one under it: paper sits at
-        // `--_qm-surface` and the container paints `--_qm-surface-sunken`, so the
-        // edge is where two tones meet and no stroke is drawn around it
-        // (ARCHITECTURE §Styling). It leaves the no-ink rule untouched, since a
-        // boundary that is not painted is not a mark on the page (PREVIEW §"Two
-        // responsibilities"). `border-box` costs nothing here and keeps a slot a
-        // consumer insets from measuring wider than its paper.
+        // The paper edge is where `--_qm-surface` meets the container's `--_qm-surface-sunken`; no
+        // stroke is drawn (ARCHITECTURE §Styling).
         const el = document.createElement('div');
-        // Not `.qm-page`: that name is the preset's page baseline, an unlayered rule at
-        // ordinary specificity a host puts on `<body>`, and a slot wearing it takes that
-        // rule's `color-scheme` inside a mounted root, which the derivation leaves to the
-        // host (`core/theme.css`).
+        // Not `.qm-page`: that is the preset's page baseline, whose `color-scheme` a slot must not
+        // take inside a mounted root (`core/theme.css`).
         el.className = 'qm-page-slot';
-        // The page's index, in the DOM. `pageByEl` is this module's and a consumer
-        // drawing an overlay of its own needs the number: position among the slots is
-        // the only handle without it, which is right today and is not a contract.
         el.dataset.page = String(page);
-        // `flex: none` under the flex column `Preview.svelte` lays the desk out as, which
-        // would otherwise shrink a page to fit the pane; auto inline margins centre a page
-        // narrower than the pane and resolve to zero on one wider, so it overflows to the
-        // scrollable side.
+        // `flex: none` keeps the flex column from shrinking a page; auto inline margins centre a
+        // narrower page and overflow a wider one to the scrollable side.
         Object.assign(el.style, {
             position: 'relative',
             boxSizing: 'border-box',
@@ -74,7 +56,7 @@ onPaintError) {
         sizeSlot(el, size);
         if (page > 0)
             el.style.marginTop = PAGE_GAP;
-        // After the last slot rather than at the end: the zoom pill's dock is a child too.
+        // After the last slot: the zoom pill's dock is a child too.
         const last = slots.at(-1)?.el;
         if (last)
             last.after(el);
@@ -92,8 +74,6 @@ onPaintError) {
         const layoutScale = scale ?? (slot.el.clientWidth || slot.size.widthPt) / slot.size.widthPt;
         return layoutScale * Math.max(window.devicePixelRatio || 1, MIN_DENSITY);
     }
-    // Rasterize `slot` into its canvas (creating the canvas if this is its first
-    // paint since mounting).
     function paintSlot(slot) {
         let canvas = canvases.get(slot.page);
         if (!canvas) {
@@ -107,8 +87,7 @@ onPaintError) {
                 height: '100%'
             });
         }
-        // Contextless canvas: bail before registering, so `updateBand` still sees
-        // the page as unmounted and retries instead of keeping a blank page.
+        // Bail before registering so `updateBand` retries rather than keeping a blank page.
         const ctx = canvas.getContext('2d');
         if (!ctx)
             return;
@@ -122,11 +101,8 @@ onPaintError) {
             rastered.set(slot.page, at);
         }
         catch (err) {
-            // A paint that throws must not abort the band loop; `updateBand` runs in
-            // the IntersectionObserver callback and sweeps every entry, so an
-            // uncaught throw would strand the rest of the band unpainted. Unmount the
-            // half-mounted canvas (so the page is a retryable unmounted slot, not a
-            // blank registered one) and surface the failure; the sweep moves on.
+            // Unmount the half-mounted canvas so the page stays a retryable unmounted slot, and let
+            // the sweep move on.
             unmountPage(slot.page);
             onPaintError?.(slot.page, err);
         }
@@ -139,10 +115,8 @@ onPaintError) {
         canvases.delete(page);
         rastered.delete(page);
     }
-    // Mount pages newly inside [min(visible)-margin, max(visible)+margin], unmount
-    // pages that fell outside it. Only touches pages changing band membership;
-    // an already-mounted page in the band is left alone (paint contract: an idle
-    // canvas keeps its pixels for free; repainting it here would be pure waste).
+    // Mount pages newly inside [min(visible)-margin, max(visible)+margin] and unmount those outside
+    // it; a mounted page in the band keeps its pixels.
     function updateBand() {
         const painted = new Set();
         if (visible.size === 0 || slots.length === 0)
@@ -162,10 +136,7 @@ onPaintError) {
         }
         return painted;
     }
-    // Grow/shrink the slot array to `pageCount` (trailing add/remove; a recompile
-    // reports the new count, and dirtyPages already covers any reflow), then
-    // re-cache every page's geometry (cheap report-only reads; simplest way to
-    // stay correct across any recompile, not just a count change).
+    // Grow or shrink the slots to `pageCount`, then re-cache every page's geometry.
     function reconcile(pageCount) {
         while (slots.length > pageCount) {
             const slot = slots.pop();
@@ -183,22 +154,15 @@ onPaintError) {
         for (let i = 0; i < slots.length; i++) {
             const size = session.pageSize(i);
             slots[i] = { ...slots[i], size };
-            // Keep the page box's shape in step with the re-read size: a recompile
-            // can change a page's dimensions without changing the count, and every
-            // %-space click/scroll transform assumes box shape matches PageSize.
+            // A recompile can change a page's dimensions without changing the count.
             slots[i].el.style.aspectRatio = `${size.widthPt} / ${size.heightPt}`;
             sizeSlot(slots[i].el, size);
         }
     }
-    // Slots are built on the first `refresh` (the controller calls it immediately),
-    // not here: reconcile → `session.pageSize` must run after the controller's
-    // `pageCount` gate, since `pageSize` throws for a page the count excludes.
-    // ── Keep mounted rasters sharp ──────────────────────────────────────────────
-    // A canvas stretches with its slot, so a page that stays mounted while the scale
-    // or `devicePixelRatio` shifts keeps its place and goes soft. Both repaint mounted
-    // pages; canvases are `position:absolute`, so a repaint can't feed back into
-    // layout.
-    // Repaint mounted pages whose raster scale moved. A no-op for an unmounted page.
+    // Slots are built on the first `refresh`: `session.pageSize` throws for a page the count
+    // excludes.
+    // Repaint mounted pages whose raster scale moved; a canvas stretches with its slot and goes
+    // soft otherwise.
     function repaint() {
         for (const page of canvases.keys()) {
             const slot = slots[page];
@@ -229,11 +193,9 @@ onPaintError) {
             repaint();
         });
     }
-    // `devicePixelRatio` changes (window dragged to a different-DPI monitor, browser
-    // zoom) leave the scale untouched, so `setScale` never hears of them; watch DPR
-    // directly. A `(resolution: …dppx)` query pins the current ratio and
-    // is therefore one-shot: re-arm it against the new ratio on each change. Guarded
-    // for environments (jsdom) without `matchMedia`.
+    // A `devicePixelRatio` change never reaches `setScale`. A `(resolution: …dppx)` query pins the
+    // current ratio, so it is re-armed on each change. Guarded for jsdom, which has no
+    // `matchMedia`.
     let dprQuery;
     function onDprChange() {
         scheduleRepaint();
@@ -252,9 +214,7 @@ onPaintError) {
         },
         refresh(dirtyPages, pageCount) {
             reconcile(pageCount);
-            // Slot count may have moved the band (pages added/removed); a page the
-            // band just painted is already post-apply, so a second full
-            // rasterization from the dirty loop would add nothing.
+            // A page the band just painted is already post-apply.
             const painted = updateBand();
             for (const page of dirtyPages) {
                 if (painted.has(page))

package/dist/preview/strings.d.ts

@@ -6,7 +6,7 @@ export interface PreviewStrings {
     /** The zoom pill's action, after the percentage it shows. */
     resetZoom: string;
 }
-/** The package's English. Every key, so the merge below is total. */
+/** The package's English. */
 export declare const DEFAULT_PREVIEW_STRINGS: PreviewStrings;
 /** A consumer's wording: any subset, the rest the package's. */
 export type PreviewStringsInput = Partial<PreviewStrings>;

package/dist/preview/strings.js

@@ -1,17 +1,5 @@
-// Every word the preview says: the surface is a canvas, and its only prose is the
-// message states that stand in when there is nothing to paint, and the name a screen
-// reader gives the zoom pill.
-//
-// Separate from the visual surface's set rather than pooled with it: `/preview`
-// reaches `/core` and nothing editor-side, which is what lets it promote to its own
-// package, and a shared strings module would be an edge back across that line. The
-// shape is the same, so a consumer wording both writes the same kind of object
-// twice rather than learning two idioms.
-//
-// A plain options field rather than a context channel, unlike the visual surface's:
-// they are read in one module by one function, so there is no tree to make them
-// ambient for.
-/** The package's English. Every key, so the merge below is total. */
+// Separate from the visual surface's strings: `/preview` reaches `/core` and nothing editor-side.
+/** The package's English. */
 export const DEFAULT_PREVIEW_STRINGS = {
     renderFailed: 'Preview failed to render.',
     noPages: 'No pages to preview.',