@quillmark/svelte 0.27.0 → 0.28.0

package/dist/core/theme.css

@@ -101,11 +101,10 @@
 	--_qm-font-mono: var(--qm-font-mono, ui-monospace, monospace);
 
 	/* ── Colour ──────────────────────────────────────────────────────────────
-	   Ink steps fg → bg, the border and hover rungs step bg → fg, all mixed in
-	   oklab; sRGB muddies the mid-tones and the label/meta/border rungs are
-	   exactly mid-tone. So inverting the poles inverts that half of the scale.
-	   The percentages are calibrated to the light-mode literals they stand in
-	   for (17% ≈ #d4d4d4, 35% ≈ #555).
+	   Ink steps fg → bg and the hover rung steps bg → fg, both mixed in oklab;
+	   sRGB muddies the mid-tones and the label rung is exactly mid-tone. So
+	   inverting the poles inverts that half of the scale. The percentages are
+	   calibrated to the light-mode literals they stand in for (35% ≈ #555).
 
 	   Planes are the half that does not read the ink pole, because what makes a
 	   card read as a card is that it is the brighter plane, in both schemes
@@ -115,57 +114,68 @@
 	   light, and the base plane — a card, the preview's paper — is the pole
 	   itself.
 
-	   Two planes sink. `sunken` is the ground — the column behind the cards, the
-	   desk behind the sheets — and lifting the plane above it takes very little
-	   at the light pole. `well` is the hole cut into a card: a field, the one
-	   native select, neither of which draws an edge, so the step is the whole of
-	   what says a value is typed there. The order at the
-	   light pole is card, ground, well; at the dark pole the two sink to within
-	   a channel of each other, which is where a card with little light left to
-	   give up leaves them.
+	   One plane sinks, in two roles. `well` is the hole cut into a card: a field,
+	   the one native select, neither of which draws an edge, so the step is the
+	   whole of what says a value is typed there. `sunken` is the ground — the
+	   column behind the cards, the desk behind the sheets — and it is the same
+	   tone: a card draws no edge either, so the step off the ground is the whole
+	   of where one card stops and the next starts, and the well's step is one
+	   that carries that at the light pole. The order is card, then ground
+	   and well together, at both poles.
 
-	   How far each sinks is a function of the card's own L, not of the scheme the
+	   How far it sinks is a function of the card's own L, not of the scheme the
 	   host declared: a dark surface has to spend more of what little it has
 	   before the card above it reads as lifted, so the two calibrated distances
-	   — 0.0214 off white, 0.0553 off the dark default — interpolate linearly
+	   — 0.04 off white, 0.0547 off the dark default — interpolate linearly
 	   between. A card pinned at neither pole takes a proportionate step whatever
 	   `color-scheme` says, which is the half of the derivation that reads a
 	   colour rather than a declaration.
 
-	   Both sink by subtraction where every other rung mixes: a mix toward black
+	   It sinks by subtraction where every other rung mixes: a mix toward black
 	   is a ratio, so it scales what it takes and pulls the result toward
 	   neutral, and a ground is a fixed distance. `a b` pass through, so the
 	   plane keeps the pole's hue and a turned `--qm-bg` tints it. The defaults
-	   land within a channel of `#f7f8f9` and `#1a1a1b`. Below L ≈ 0.065 the
-	   ground clamps to black, which is where a near-black card leaves no room
+	   land within a channel of `#f2f2f2` and `#1a1a1c`. Below L ≈ 0.06 the
+	   plane clamps to black, which is where a near-black card leaves no room
 	   for a ground of its own. */
 	--_qm-surface: var(--_qm-bg);
-	--_qm-surface-sunken: oklab(from var(--_qm-bg) calc(l - (0.0214 + 0.0467 * (1 - l))) a b);
 	--_qm-surface-well: oklab(from var(--_qm-bg) calc(l - (0.04 + 0.0202 * (1 - l))) a b);
+	--_qm-surface-sunken: var(--_qm-surface-well);
 	/* `raised` is the same ramp spelled as a mix, its step 0.08 × (1 − l): the light
 	   arm is zero, a white card having nowhere further to go, so a floating surface
 	   separates on its hairline and `--_qm-lift` there and the step joins them in
 	   dark. */
 	--_qm-surface-raised: color-mix(in oklab, var(--_qm-bg), #fff 8%);
-	--_qm-surface-hover: color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 8%);
-	/* A band laid on the card rather than cut into it: a table's header, and the pill a
-	   grip draws. It steps toward the ink at both poles, a shade under white in light
-	   and a shade over the card in dark, where `well` sinks to a black stripe. */
-	--_qm-surface-band: color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 6%);
-	/* The one rung whose arms are not a single ratio: a stroke is read against what it
-	   separates, and the mix that reads as a hairline on the dark default draws the
-	   light card in a line heavier than the type it frames. The light arm is
-	   calibrated rather than derived, which makes this the one rung under the poles
-	   that reads the declared scheme rather than only the colours it resolves to. */
+	/* A step toward the ink laid over whatever plane is under it, rather than a tone off
+	   the card: a hover lands on the card, a well, a band and a floating surface, and a
+	   fixed tone stepped off the first sits level with `raised` in dark. Translucent, as
+	   the accent's tint is, so the step is the same over each. */
+	--_qm-surface-hover: color-mix(in oklab, var(--_qm-fg) 8%, transparent);
+	/* A band laid on the card rather than cut into it: a table's header, the pill a
+	   grip draws, the off switch's track and the unticked box. A resting fill, where
+	   `hover` above is a state, so the two have to be told apart on a card that shows
+	   both at once: each arm stands one ground step past the hover step at its pole,
+	   which lands the band two steps off the card in dark and a little over in light.
+	   It steps toward the ink at both poles, a shade under white in light and a shade
+	   over the card in dark, where `well` sinks to a black stripe. */
+	--_qm-surface-band: light-dark(
+		color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 12%),
+		color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 18%)
+	);
+	/* The one stroke: a card's two horizontals, a section's and a subform's verticals,
+	   a table's frame and the lines between its cells, a floating surface's edge, the
+	   popover's divider. One and a half ground steps off the card at both poles, the
+	   same derivation the well takes, so a hairline stands off the card by the same
+	   measure a card stands off the ground whatever the scheme. Toward the ink, which
+	   is the half of the step `light-dark()` carries: the well always sinks, a stroke
+	   darkens a light card and lightens a dark one. On the defaults the arms land near
+	   #ececec and #3b3c3e. The multiple is the whole calibration: at it a stroke reads
+	   in light without outweighing the type beside it, and reads in dark without being
+	   the loudest line on the card. */
 	--_qm-border: light-dark(
-		color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 6%),
-		color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 17%)
+		oklab(from var(--_qm-bg) calc(l - 1.5 * (0.04 + 0.0202 * (1 - l))) a b),
+		oklab(from var(--_qm-bg) calc(l + 1.5 * (0.04 + 0.0202 * (1 - l))) a b)
 	);
-	/* A stroke ruled through content rather than round it: a table's frame and every
-	   line between its cells. The light arm of `border` is a card's edge against the
-	   ground, and drawn between lines of type it vanishes, so a grid takes one ratio at
-	   both poles, which lands within a few points of `border` in dark. */
-	--_qm-rule: color-mix(in oklab, var(--_qm-bg), var(--_qm-fg) 14%);
 	/* Three rungs, and nothing under the last: a step below `label` lands under 3:1 on
 	   the well a field draws it against, and what would take it — an unset value's word,
 	   an invitation — is content a reader has to read (WCAG 1.4.3), not decoration.
@@ -259,7 +269,7 @@
 	   only up to the point where it is assembled. One width: focus is the only
 	   state that draws a ring anywhere, so there is no held-back tier under it.
 	   Sub-pixel, because at two it reads as a second border on a card whose every
-	   other edge is a hairline. */
+	   other stroke is a hairline. */
 	--_qm-ring-width: 1.5px;
 	/* Every ring the surface draws, focus and selection alike, which is why the name
 	   carries neither. Assembled here because the parts spelled out at a use site pass
@@ -296,17 +306,17 @@
 
 	/* ── Geometry ──────────────────────────────────────────────────────────*/
 	/* One stroke width for every edge the chrome draws and every rule it ranks
-	   with: a card's, a control's, the two closing a card's payload. A threshold
-	   rather than a rhythm choice, like the tap floor: a hairline is a hairline at
-	   any `--qm-space`, so neither derives from a dial. Both exist as rungs because
+	   with: a control's, a floating surface's, the two closing a card's payload. A
+	   threshold rather than a rhythm choice, like the tap floor: a hairline is a
+	   hairline at any `--qm-space`, so neither derives from a dial. Both exist as rungs because
 	   `check:style`'s border-width axis can only hold a stroke against a token. */
 	--_qm-border-width: 1px;
 	/* Half a step over it, for the verticals alone — a section's, a subform's, a
 	   blockquote's. What a vertical states is depth, and depth is the one thing a
-	   reader has to find in a dense card; the strokes that close a block or rank two
-	   stay at the hairline, so the ladder is what carries the extra weight. Half,
-	   because a whole step reads as a different kind of line rather than the same
-	   one doing more work. */
+	   reader has to find in a dense card; the strokes that rank two or edge a
+	   floating surface stay at the hairline, so the ladder is what carries the extra
+	   weight. Half, because a whole step reads as a different kind of line rather
+	   than the same one doing more work. */
 	--_qm-vertical-width: 1.5px;
 	--_qm-radius: var(--qm-radius, 8px);
 	/* The interior corner, and half is the relationship rather than the number: a
@@ -342,6 +352,15 @@
 	   `check:style`'s rhythm axis sees each of them read a rung, never that they read
 	   the same one — the case `--_qm-inset-control` above is cut for. */
 	--_qm-nest: var(--_qm-space-3);
+	/* The numerals a list marker is given room for: two digits, so a tenth item's number
+	   stands inside the leaf as the first's does. In `ch`, so it tracks the face the
+	   numbers are set in. */
+	--_qm-marker-digits: 2ch;
+	/* The text column, measured in from a block's own inline inset: a section's vertical
+	   plus the rung its heading stands off it, so a heading riding that vertical and a
+	   line beside it start on one edge. A rung for the reason the nesting step is: the
+	   card and the tip tucked under `main` are two components holding one edge. */
+	--_qm-column: calc(var(--_qm-space) + var(--_qm-vertical-width));
 	/* The scroll tail: dead space under the last card, so it can be read at the
 	   middle of a pane rather than at its bottom edge. A fraction of the viewport
 	   rather than a step on the ramp, because what it answers is how far the eye
@@ -358,6 +377,10 @@
 	   rather than through the icon's `size`, so a stylesheet beats the SVG presentation
 	   attribute and one rung is the whole of what a control draws. */
 	--_qm-glyph-control: 14px;
+	/* The stroke a control glyph draws, in screen length: the frame's 2 units of 24 at
+	   the control rung. A glyph drawn at another edge reads it under
+	   `vector-effect: non-scaling-stroke`, so every glyph strokes at one weight. */
+	--_qm-glyph-stroke: calc(var(--_qm-glyph-control) / 12);
 	/* The narrowest track a control that fills its width stays usable in: a table's
 	   column floors at it, rises no further than its content, and a row of them scrolls
 	   sideways rather than crushing a cell. A column drawing a mark takes no floor — a
@@ -374,22 +397,19 @@
 	--_qm-track-prose: calc(var(--_qm-track-min) * 2);
 
 	/* ── Type ────────────────────────────────────────────────────────────────
-	   `--qm-font-size` anchors the chrome rung; 1.125 is the ratio between adjacent
-	   rungs: a step up (title) and one down (label). The ratio and the
-	   weight are fixed conventions, not dials: no consumer tunes a typographic
-	   ratio, and a dial nobody turns is a name every reader still holds. Three chrome
-	   rungs: a second step below `label` lands near 11px, under a size anything here
-	   wants to be read at, and the supporting text that would take it is what `label`
-	   already is. */
+	   `--qm-font-size` anchors the chrome rung and `label` stands one 1.125 step under
+	   it. The ratio and the weight are fixed conventions, not dials: no consumer tunes
+	   a typographic ratio, and a dial nobody turns is a name every reader still holds.
+	   Two chrome rungs: nothing the chrome names ranks above the value it names, a card
+	   title being body at the mid weight, and a second step below `label` lands near
+	   11px, under a size anything here wants to be read at. */
 	--_qm-text-body: var(--qm-font-size, 0.875rem);
-	--_qm-text-title: calc(var(--_qm-text-body) * 1.125);
 	--_qm-text-label: calc(var(--_qm-text-body) / 1.125);
 	/* Paper: the document body answers to the preview's paper where every other
 	   surface here answers to the control beside it, so a rung shared with the chrome
 	   makes a consumer asking for larger prose take larger inputs with it. 16/15 where
 	   the ramp steps at 9/8: small enough to read as a change of register rather than
-	   a rung of hierarchy, and clear of the title rung, which one 9/8 step lands on
-	   exactly. */
+	   a rung of hierarchy. */
 	--_qm-text-paper: calc(var(--_qm-text-body) * 16 / 15);
 	/* Two weights over the regular, and only one of them is chrome. `mid` names
 	   everything the surface names — a card title, a section header, a field

package/dist/index.js

@@ -1,9 +1,4 @@
-// `@quillmark/svelte` root: the substrate, free of any UI framework.
-//
-// The headline surfaces mount from their own subpaths (`@quillmark/svelte/preview`,
-// `/visual`) so a bundler pulls only what an entry reaches; the root
-// re-exports `/core` (the address vocabulary, the error channel, `init`) for a
-// consumer that wants one import for the substrate. It carries no framework code.
-// The `@quillmark/wasm` API is imported from the peer dependency directly, never
-// from here.
+// `@quillmark/svelte` root: the substrate, free of any UI framework. The headline surfaces mount
+// from their own subpaths (`/preview`, `/visual`); the root re-exports `/core` for a consumer that
+// wants one import for the substrate.
 export * from './core/index.js';

package/dist/preset/app.css

@@ -27,9 +27,11 @@
 	overflow-wrap: anywhere;
 }
 
-/* The foot: a line of meta type under a hairline, its links in the line's own ink. */
+/* The foot: a line of meta type on the head's plate under a hairline, its links in the
+   line's own ink. The two bands framing the panes stand on one plate. */
 :where(.qm-app-footer) {
 	padding: var(--qmh-space-2) var(--qmh-space-4);
+	background: var(--qmh-surface);
 	border-block-start: var(--qmh-border-width) solid var(--qmh-border);
 	font-size: var(--qmh-text-meta);
 	line-height: var(--qmh-leading-tight);

package/dist/preset/index.css

@@ -1,11 +1,9 @@
-/* `@quillmark/svelte/preset`, the package's one CSS entry point: the endorsed look for
-   the page a surface is mounted on. Opt-in and side-effect free until imported:
-   the surface barrels pull `core/theme.css` and never this, because this
-   styles the document and nothing may put that in a consumer's page uninvited.
-
-   `scale.css` is where the literals are minted and is exempt; the rest are held to
-   reading them. `recipes.css` ranks at ordinary specificity, `shell.css` and `app.css`
-   at zero. */
+/*
+ * `@quillmark/svelte/preset`, the package's one CSS entry point: the endorsed look for the page a
+ * surface is mounted on. Opt-in: the surface barrels pull `core/theme.css` and never this, because
+ * this styles the document. `scale.css` is where the literals are minted; the rest read them.
+ * `recipes.css` ranks at ordinary specificity, `shell.css` and `app.css` at zero.
+ */
 
 @import './scale.css';
 @import './recipes.css';

package/dist/preset/recipes.css

@@ -1,18 +1,15 @@
-/* The endorsed look: the rules a host draws around a mounted surface, as classes it puts
-   on its own elements; the shell it mounts one in is `shell.css` beside this, and an
-   app's own chrome is `app.css`. The rungs beside this in
-   `scale.css` are the invisible half (a scale alone still leaves a consumer writing
-   every declaration before anything on the page looks like anything), so the recipes
-   are what the preset is for. This file mints nothing; `check:style` runs its axes here.
-
-   These are host classes. They land on the consumer's DOM, never on a mounted root, so
-   they freeze nothing about the surfaces' interior: the reason the package withholds
-   its own internal classes does not reach them.
-
-   Unlayered, deliberately: a layer of the preset's own would put a name in the contract,
-   and unlayered a consumer's rules win over these by ordinary precedence. Ordinary
-   specificity too, not the surfaces' `:where()` zero: a consumer takes these classes on
-   purpose, so a rule of their own beside one is aimed rather than incidental. */
+/*
+ * The endorsed look: the rules a host draws around a mounted surface, as classes it puts on its
+ * own elements. The shell is `shell.css` and an app's chrome `app.css`; the rungs in `scale.css`
+ * are the invisible half. This file mints nothing; `check:style` runs its axes here.
+ *
+ * These are host classes: they land on the consumer's DOM, never on a mounted root, so they freeze
+ * nothing about the surfaces' interior.
+ *
+ * Unlayered, at ordinary specificity (not the surfaces' `:where()` zero): a consumer takes these
+ * classes on purpose, so a rule of their own beside one is aimed rather than incidental, and a
+ * layer of the preset's own would put a name in the contract.
+ */
 
 /* ── The page ──────────────────────────────────────────────────────────────── */
 

package/dist/preset/scale.css

@@ -1,13 +1,13 @@
 /* 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 ramp, 8% hover, the
-   ring's width, the status hue at both poles) and the
+   figures here are the figures there (the poles, the ground step's ramp, 8% hover, the
+   label ink's 35%, the ring's width, the status hue at both poles) 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 border
-   and ink rungs are each calibrated for their own plane rather than shared: a page's
-   chrome is read at one size against one ground, a card's interior at several against
-   the rungs under it, so the mixes are not the same figure. The well
+   is calibrated for its own plane rather than shared: a page's controls are boxed and
+   read against one ground, a card's strokes at several weights against the rungs
+   under it, so the mixes are not the same figure. 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.
 
@@ -20,9 +20,8 @@
    Literals live here and nowhere else in the preset: `check:style` runs its axes over
    the sheets 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 — `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
+   The poles fall back to the surfaces' own pair, so a host that turns no dial lands on
+   the plane an editor mounted in it paints at both poles. The dials sit in front, so
    `--qm-bg`/`--qm-fg` on an ancestor retunes page and surface together. */
 
 :root {
@@ -32,21 +31,20 @@
 	   the page sinks from it by the same ramp. 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. `Canvas` flips with the
-	   declared scheme on its own, so the ramp reads whichever plane it resolved to
-	   rather than trusting an arm to match. */
-	--qmh-surface: var(--qm-bg, Canvas);
-	--qmh-page: oklab(from var(--qmh-surface) calc(l - (0.0214 + 0.0467 * (1 - l))) a b);
-	--qmh-ink: var(--qm-fg, CanvasText);
+	   (ARCHITECTURE §Styling); the figures are its figures. */
+	--qmh-surface: var(--qm-bg, light-dark(#fff, #272729));
+	--qmh-page: oklab(from var(--qmh-surface) calc(l - (0.04 + 0.0202 * (1 - l))) a b);
+	--qmh-ink: var(--qm-fg, light-dark(#1c1c1c, #d7dadc));
 	/* One step off the ink and no second: a page's chrome type is small, tracked and
 	   uppercase, so a rung below this reads under 4.5:1 against the plate and the
 	   label and status lines that would take it are text (WCAG 1.4.3). */
-	--qmh-ink-meta: color-mix(in oklab, var(--qmh-ink), var(--qmh-surface) 45%);
+	--qmh-ink-meta: color-mix(in oklab, var(--qmh-ink), var(--qmh-surface) 35%);
 	--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-surface), var(--qmh-ink) 40%);
+	   the underline under a link. Half way to the ink, which clears WCAG 1.4.11's 3:1
+	   against the page and the plate at both poles. */
+	--qmh-border-strong: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 50%);
 
 	/* The one hue a host's page spends on purpose: the primary action wears it. The
 	   figures are the surfaces' own default for the same dial, so a page that turns no
@@ -62,6 +60,9 @@
 	   on a dark page. The dial sits in front of the pair, as every pole's does, so
 	   a host that turns one owns both schemes. */
 	--qmh-alert: var(--qm-danger, light-dark(#9e1518, #f9786c));
+	/* What a modal's backdrop lays over the page: the ground held translucent, so the
+	   page recedes under the dialog without a second tone to read. */
+	--qmh-scrim: color-mix(in srgb, var(--qmh-page) 80%, transparent);
 
 	/* ── Rhythm ──────────────────────────────────────────────────────────────── */
 	/* One base and its multiples, the same four steps the surfaces derive. A host

package/dist/preset/shell.css

@@ -145,3 +145,13 @@
 	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/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/shell.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);