@quillmark/svelte 0.26.2 → 0.28.0

package/dist/preset/shell.css

@@ -0,0 +1,157 @@
+/* The shell: the screen an app mounting two surfaces over one session is, drawn once
+   (THEMING §"The shell, if you are building a tool"). `recipes.css` dresses the page a
+   surface sits on; this is what it is mounted in, a tool where `.qm-page` is a document.
+
+   Every selector here computes at specificity zero, as the surfaces' own do: a host's
+   rule on the same element wins whatever order the sheets land in, and an app whose
+   stylesheet someone else writes (quillkit's app client, under an author's `app.css`)
+   needs no knowledge of which of these the client happened to set. `check:style` holds
+   the rank. This file mints nothing. */
+
+/* Pinned to the viewport rather than sized to it: a page-height box still leaves the
+   root scroller counting the overflow its panes clip, and a wheel over the chrome drags
+   the whole app off the top. Three bands (a head, the body, an optional foot), and the
+   body takes what is left and may shrink below its content, so the panes in it own
+   their overflow and hold still while their contents move.
+
+   The one column is stated for the same reason the rows are: an implicit track is `auto`,
+   which is sized by what a band holds, and a `.qm-split` under one contributes its items'
+   max-content through its `fr` tracks. The shell would take the width of the widest thing
+   mounted in it instead of the viewport's, and every band would be that wide with the
+   second pane past the edge. A host holding its content to a maximum never sees it; one
+   spending the whole screen sees it on the first surface it mounts. */
+:where(.qm-workspace) {
+	position: fixed;
+	inset: 0;
+	display: grid;
+	grid-template-columns: minmax(0, 1fr);
+	grid-template-rows: auto minmax(0, 1fr) auto;
+	overflow: hidden;
+}
+
+/* A gesture past the end of a pane chains out to the viewport and bounces the empty
+   document, which is the last way a pinned shell moves. Conditioned on the workspace, so
+   a host's other routes keep a page's own feel. */
+:where(html:has(.qm-workspace)) {
+	overscroll-behavior: none;
+}
+
+/* A band's line: the row a head or a foot puts its parts on, wrapping, centred. That is
+   the whole of it. What a band is made of is the host's: the rule under it, the gutter
+   beside it, and the depth of it, because where a band ends and how tall it stands are
+   page-shell decisions: a site holding its content to a maximum runs the rule past it at
+   its own rhythm, and a one-screen tool has no maximum to hold to. */
+:where(.qm-bar) {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: var(--qmh-space-2) var(--qmh-space-4);
+}
+
+/* Two even tracks for two surfaces, and no resizer, since a divider that can be dragged
+   is a control competing with what it divides. Each track may shrink below its content,
+   which is what lets the frame in it clip rather than grow.
+
+   The gap is the endorsed default and not a fact about splitting: two surfaces standing
+   apart on a page read as two things, which is what a host showing its instruments wants.
+   A host that spends the whole screen on the mounts closes it to nothing and carries a
+   hairline on one pane instead: one property, and the tracks are untouched. */
+:where(.qm-split) {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+	grid-template-rows: minmax(0, 1fr);
+	gap: var(--qmh-space-4);
+	min-height: 0;
+}
+
+/* The band that switches them, and nothing at the widths where both tracks are showing
+   and there is nothing to switch. Where it stands is the host's, like any other band; what
+   goes in it is a pair of `.qm-control`s, which already carry the on-state a pressed
+   control takes. Its visibility is the preset's because the threshold is: a host hiding
+   its own tab row writes this file's number a second time, which is the one thing the
+   single source is for. */
+:where(.qm-switch) {
+	display: none;
+}
+
+/* One mount at a time under the threshold, rather than two of them abreast. Half a narrow
+   viewport is under the width either surface reads at, so the split stops being one and
+   the tracks become views of the same room: the host says which with `data-qm-show`, and
+   the attribute names the track rather than what is in it, so nothing here knows an editor
+   from a preview. No attribute is the first track.
+
+   The other track is `display: none` and not a clip, which is the whole of the hiding: it
+   leaves the tab order, hit-testing and the accessibility tree in one property, so the
+   pane needs no `inert` and the host needs no breakpoint in JS. Both stay mounted (a
+   preview binds its handle once, an editor holds a caret, a history and a scroll), so
+   the switch is presentational, never conditional. A pane hidden this way keeps the
+   pixels it had: the paint loop's band sweep no-ops on an empty visible set, and its
+   resize observer holds the last real width rather than rastering at the 0×0 box a hidden
+   pane reports, so what comes back at the width it left needs no paint at all. The
+   preview's caret follow spans the same window — a trip asked for against a pane with no
+   box is held and run when it has one (`preview/bridge.ts`), the pane opening at the
+   caret rather than several edits behind it.
+
+   Height is the second clause because a landscape phone passes the first one: it clears
+   the width with room for two tracks and has no body left to put them in. A desktop window
+   that short wants one mount for the same reason. */
+@media (width < 50rem), (height < 30rem) {
+	:where(.qm-switch) {
+		display: flex;
+		gap: var(--qmh-space);
+	}
+
+	/* Even halves of the band, at the height a thumb needs. The floor is the recipe's and
+	   not the host's, because the band exists only at the sizes where the pointer is a
+	   finger: a host is free to stand the band deeper, and has nothing to gain from
+	   standing it shallower than the thing it is tapping. */
+	:where(.qm-switch > *) {
+		flex: 1 1 0;
+		min-height: var(--qmh-tap);
+	}
+
+	:where(.qm-split) {
+		grid-template-columns: minmax(0, 1fr);
+	}
+
+	:where(.qm-split:not([data-qm-show='2']) > :nth-child(2)),
+	:where(.qm-split[data-qm-show='2'] > :nth-child(1)) {
+		display: none;
+	}
+}
+
+/* The mounting site: an edge, a corner, and the clip that holds a surface to them, which
+   is all a surface painting its own column needs. No tone and no gutter: those are the
+   surface's own (THEMING §"Drop it in"). `border-box`, so a stated height is the height
+   it draws.
+
+   Positioned, because a clip reaches only what it is the containing block for: a
+   surface's out-of-flow parts (a parked description, an overlay) resolve against the
+   nearest positioned ancestor, and with none between them and the document they land at
+   their static position unclipped, leaving the page to scroll past its own foot by
+   however far the frame's contents run over.
+
+   The two minimums are what let a frame in a track clip rather than push: a grid or flex
+   item floors at its content, so a mount that paints wider than its column widens the
+   column instead. They ride the frame rather than the split's children, which keeps every
+   rule in this file landing where the host put a class. Outside a track they are the
+   initial value and do nothing. */
+:where(.qm-frame) {
+	box-sizing: border-box;
+	position: relative;
+	min-width: 0;
+	min-height: 0;
+	border: var(--qmh-border-width) solid var(--qmh-border);
+	border-radius: var(--qmh-radius);
+	overflow: hidden;
+}
+
+/* One track is the whole width under the threshold, so a frame's sides and corners would
+   frame the screen rather than a pane. It keeps the rules above and below it, which part
+   it from the bands. After the frame, since both rank zero and the later one wins. */
+@media (width < 50rem), (height < 30rem) {
+	:where(.qm-frame) {
+		border-inline: none;
+		border-radius: 0;
+	}
+}

package/dist/preview/Preview.svelte

@@ -178,6 +178,14 @@
 		pointer-events: none;
 		transition: opacity var(--_qm-reveal);
 	}
+	/* A screen with no hover has no pointer to bring it back, and the pill is the way back
+	   to the fit there, so it stays. */
+	@media (hover: none) {
+		:global(:where(.qm-preview-zoom[data-idle])) {
+			opacity: 1;
+			pointer-events: auto;
+		}
+	}
 	:global(:where(.qm-preview-zoom:focus-visible)) {
 		opacity: 1;
 		pointer-events: auto;

package/dist/preview/bridge.d.ts

@@ -1,15 +1,18 @@
 import type { LiveSession } from '@quillmark/wasm';
 import type { Landing } from '../core/address.js';
 import type { PageSlot } from './paint.js';
-/** Both trips are held while the pane has no box to measure against, and the last one
- *  held runs when it has one again. */
+/**
+ * Both trips are held while the pane has no box to measure against; the last one held runs when it
+ * has one again.
+ */
 export interface BridgeController {
-    /** Scroll `field`'s first box to centre; `false` when this compile places none
-     *  for that address, which is the whole of what the preview can say about it. */
+    /**
+     * Scroll `field`'s first box to centre; `false` when this compile places none for that address.
+     */
     scrollToField(field: string): boolean;
     /**
-     * Bring the caret rect at `field`/`pos` into view (a no-op off-content, and a
-     * no-op when it is already clear of the fold).
+     * Bring the caret rect at `field`/`pos` into view; a no-op off-content or when already clear of
+     * the fold.
      */
     focusPosition(field: string, pos: number): void;
     destroy(): void;
@@ -21,24 +24,17 @@ export interface VerticalSpan {
     height: number;
 }
 /**
- * Whether `target` sits clear of `port`'s edges by the fold's clearance, which is the
- * target's own height: a caret rect flush against an edge 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, and bounded at both ends so the
- * answer is reachable across the whole range of targets a compile locates.
- *
- * The floor is what a zero-height rect gets, which bare intersection would score as
- * clear at either edge. The cap is a third of the room the port has to spare, so a
- * target too tall for its own height of clearance — a located line at zoom, a short
- * split track — passes once centred and holds a band around it, rather than being
- * re-centred by every keystroke. A target taller than the port is clear while it covers
- * the port: no scroll shows more of it.
+ * Whether `target` sits clear of `port`'s edges by the fold's clearance, which is the target's own
+ * height, so it scales with zoom as the caret does. The floor is {@link MIN_CLEARANCE}, for a
+ * zero-height rect. The cap is a third of the room the port has to spare, so a target too tall for
+ * its own clearance passes once centred rather than being re-centred by every keystroke. A target
+ * taller than the port is clear while it covers the port.
  */
 export declare function clearOfTheFold(target: VerticalSpan, port: VerticalSpan): boolean;
-/** The trip a pane with no box could not run, held for the box coming back. One, and the
- *  last one asked for: a caret hop supersedes the hop before it on a showing pane too.
- *  A cell rather than closure state, so a bridge rebuilt under a changed page count
- *  inherits what the one it replaced was holding (`controller.ts`). */
+/**
+ * The last trip a pane with no box could not run. A cell so a rebuilt bridge inherits it
+ * (`controller.ts`).
+ */
 export interface HeldTrip {
     run?: () => void;
 }

package/dist/preview/bridge.js

@@ -1,32 +1,24 @@
 import { boxesForField, rectToPercent, clickToPdfPt, pxToPt, applyPercentRect } from './geometry.js';
-/** A pane hidden by the shell's narrow switch (`preset/recipes.css`) measures 0×0, and so
- *  does every box on it: the clearance arithmetic reads that as a caret clear of both
- *  edges, and a centring computes its trip out of zeros. Neither is an answer about where
- *  the caret is. */
+/**
+ * A pane hidden by the shell's narrow switch (`preset/shell.css`) measures 0×0, as does every box
+ * on it, which the clearance arithmetic would read as a caret clear of both edges.
+ */
 function hasBox(port) {
     return port.width > 0 && port.height > 0;
 }
-/** What a rect reporting no height clears an edge by, in CSS px: a caret's own at the
- *  smallest zoom a page still reads at. */
+/** What a rect reporting no height clears an edge by, in CSS px. */
 const MIN_CLEARANCE = 8;
-/** What a click may miss a field's ink by and still land on it, in CSS px of the page as
- *  drawn, so it converts per click at the scale the slot is showing. Sized as the
- *  pointer's imprecision and not as the leading it partly closes, which is a trade
- *  PREVIEW.md §"Click bridge" carries. */
+/**
+ * What a click may miss a field's ink by and still land on it, in CSS px of the page as drawn
+ * (PREVIEW.md §"Click bridge").
+ */
 const CLICK_SLACK_PX = 2;
 /**
- * Whether `target` sits clear of `port`'s edges by the fold's clearance, which is the
- * target's own height: a caret rect flush against an edge 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, and bounded at both ends so the
- * answer is reachable across the whole range of targets a compile locates.
- *
- * The floor is what a zero-height rect gets, which bare intersection would score as
- * clear at either edge. The cap is a third of the room the port has to spare, so a
- * target too tall for its own height of clearance — a located line at zoom, a short
- * split track — passes once centred and holds a band around it, rather than being
- * re-centred by every keystroke. A target taller than the port is clear while it covers
- * the port: no scroll shows more of it.
+ * Whether `target` sits clear of `port`'s edges by the fold's clearance, which is the target's own
+ * height, so it scales with zoom as the caret does. The floor is {@link MIN_CLEARANCE}, for a
+ * zero-height rect. The cap is a third of the room the port has to spare, so a target too tall for
+ * its own clearance passes once centred rather than being re-centred by every keystroke. A target
+ * taller than the port is clear while it covers the port.
  */
 export function clearOfTheFold(target, port) {
     if (target.height >= port.height)
@@ -36,19 +28,13 @@ export function clearOfTheFold(target, port) {
 }
 export function createBridge(session, container, slots, onPick, held = {}) {
     const unlisten = [];
-    // Two rungs: `positionAt` over span-tracked content, `fieldAt` over every placement
-    // the compile tracks, a strict superset of it (PREVIEW.md §"Click bridge" carries
-    // the measurement). The second fires where a field is placed without its content
-    // being tracked, and the pick carries no `pos` there: a fabricated `0` would be an
-    // invented offset wearing a real one's type. No third rung hit-tests `regions()`,
-    // whose rects bound ink the field does not fill; the slack both rungs carry is what
-    // that rung would have been reached for.
+    // Two rungs: `positionAt` over span-tracked content, then `fieldAt` over every tracked
+    // placement (PREVIEW.md §"Click bridge"). The second carries no `pos`: a fabricated `0` would
+    // be an invented offset.
     if (onPick) {
         for (const { page, el } of slots) {
             const handleClick = (ev) => {
-                // Re-read through the live array: a same-count `refresh` swaps the
-                // slot objects to re-cache `size`, and the click math must use the
-                // current compile's PageSize, not the one captured at bridge build.
+                // Re-read through the live array: a refresh swaps slot objects to re-cache `size`.
                 const slot = slots[page];
                 if (!slot)
                     return;
@@ -68,9 +54,8 @@ export function createBridge(session, container, slots, onPick, held = {}) {
             unlisten.push(() => el.removeEventListener('click', handleClick));
         }
     }
-    // Where the % rect `pct` on `slot` currently sits, in the scrollport's own
-    // coordinates: a throwaway marker, measured and removed. Absolutely positioned,
-    // so it displaces nothing and no layout survives the read.
+    // Where the % rect `pct` on `slot` currently sits: a throwaway absolute marker, measured and
+    // removed.
     function measure(slot, pct) {
         const marker = document.createElement('div');
         applyPercentRect(marker, pct);
@@ -79,11 +64,7 @@ export function createBridge(session, container, slots, onPick, held = {}) {
         marker.remove();
         return rect;
     }
-    // Centre `target` vertically in `port`, the scrollport's box; the cross axis takes the
-    // minimum trip instead, since the container is a vertical scroller and only a page
-    // wider than the port has anything to move there. `port` is the caller's own read: the
-    // marker `measure` places is absolute inside the slot, so nothing between that read
-    // and this one moves the container's box, and one forced layout serves the whole hop.
+    // Centre `target` vertically in `port`; the cross axis takes the minimum trip.
     function centre(target, port) {
         container.scrollTop += target.top + target.height / 2 - (port.top + port.height / 2);
         reveal(target, port);
@@ -94,10 +75,8 @@ export function createBridge(session, container, slots, onPick, held = {}) {
         else if (target.right > port.right)
             container.scrollLeft += target.right - port.right;
     }
-    // The re-assert. Nothing else asks on the way back: `refresh` re-asks only on a
-    // recompile, and the reader who has just tapped Preview is not typing, so the pane
-    // would open where the caret was several edits ago. Guarded for jsdom, which ships no
-    // ResizeObserver and lays out nothing for one to report.
+    // Runs the held trip once the pane has a box again. Guarded for jsdom, which has no
+    // ResizeObserver.
     if (typeof ResizeObserver !== 'undefined') {
         const observer = new ResizeObserver(() => {
             if (!held.run || !hasBox(container.getBoundingClientRect()))
@@ -117,14 +96,12 @@ export function createBridge(session, container, slots, onPick, held = {}) {
         if (!slot)
             return false;
         const port = container.getBoundingClientRect();
-        // The address is placed, which is the whole of what the `boolean` answers; a pane
-        // with no box yet is not a second no.
+        // Placed, so `true`; a pane with no box yet is not a no.
         if (!hasBox(port)) {
             held.run = () => void scrollToField(field);
             return true;
         }
-        // A discrete act ("show me this field"), so it centres every time, unlike
-        // the continuous hop below.
+        // A discrete act, so it centres every time.
         centre(measure(slot, rectToPercent(box.rect, slot.size)), port);
         return true;
     }
@@ -135,21 +112,15 @@ export function createBridge(session, container, slots, onPick, held = {}) {
         const slot = slots[region.page];
         if (!slot)
             return;
-        // Held before the guard below, which a pane measuring zero answers "already clear"
-        // for every keystroke of (`hasBox`): the follow would die silently for as long as
-        // a track is hidden. What is held is the request, not the trip, so it re-locates
-        // against whatever compile is current when the pane comes back.
+        // Held before the fold test, which would call a zero-sized pane clear. The request is held,
+        // so it re-locates against the compile current on return.
         const port = container.getBoundingClientRect();
         if (!hasBox(port)) {
             held.run = () => focusPosition(field, pos);
             return;
         }
-        // The continuous hop: one call per keystroke and per arrow key, so it moves
-        // the pane only when the caret has left the fold. Centring unconditionally
-        // takes the scrollport back from the user on every one of them, including
-        // the ones that changed nothing about where the caret already was.
-        // Across, a page zoomed wider than the pane has a caret to keep in view too, and
-        // the least trip does it without moving the line the reader is on.
+        // Called per keystroke, so it moves the pane only when the caret has left the fold; across,
+        // the least trip.
         const target = measure(slot, rectToPercent(region.rect, slot.size));
         if (clearOfTheFold(target, port))
             reveal(target, port);

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;