@quillmark/svelte 0.23.0 → 0.25.0

package/dist/core/codec/markdown-paste.js

@@ -4,26 +4,88 @@
 // the paste stores what the source editor stores of the same text. Text holding none stays
 // literal: a sentence with a dash in it, or a `**` with no block around it, keeps every
 // character.
+//
+// A list typed in an email or a memo draft marks its items with what markdown does not
+// spell: a bullet character, a letter, a number in parentheses. Those lines are items too,
+// nested by the outline the memo writes them in (`1.`, `a.`, `(1)`, `(a)`): each kind of
+// marker is a level, the first line of a kind opening one under the level above.
 import { Slice } from 'prosemirror-model';
 import { Plugin } from 'prosemirror-state';
 import { core } from '../lifecycle.js';
-import { decode } from './decode.js';
+import { decode, fitsLeaf } from './decode.js';
 import { blockSchema } from './schema.js';
+/** A line opening an item: its indent, then the marker as markdown spells one (`-`, `*`,
+ *  `+`, `1.`, `1)`), or as a plain-text list does (`•` and the bullet characters word
+ *  processors write as text, a lowercase letter closed by `.` or `)`, and a number or a
+ *  lowercase letter in parentheses). A capital is a name's initial as often as a marker,
+ *  so `J. Doe` is not an item. */
+const ITEM = /^([ \t]*)(?:([-*+])|(\d{1,9})[.)]|([•◦▪▫‣⁃●○■□·])|([a-z])[.)]|\((\d{1,9})\)|\(([a-z])\))[ \t]+(?=\S)/;
+/** The markers plain text writes and markdown does not. */
+const LOOSE_ITEM = /^[ \t]*(?:[•◦▪▫‣⁃●○■□·]|[a-z][.)]|\((?:\d{1,9}|[a-z])\))[ \t]+\S/m;
 /** A line opening a block markdown spells and prose does not: a bullet or an ordered item at
  *  any indent, and within CommonMark's three spaces an ATX heading, a quote, a fence, or a
- *  pipe table's delimiter row. */
+ *  pipe table's delimiter row; or an item a plain-text list marks. */
 const BLOCK_HEAD = new RegExp([
     String.raw `^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]`,
+    LOOSE_ITEM.source,
     String.raw `^ {0,3}(?:#{1,6}|>)(?:[ \t]|$)`,
     '^ {0,3}(?:```|~~~)',
     String.raw `^ {0,3}(?=[^\n]*\|)\|?(?:[ \t]*:?-+:?[ \t]*\|)*[ \t]*:?-+:?[ \t]*\|?[ \t]*$`
 ].join('|'), 'm');
+/**
+ * `text` with every item line spelled as markdown, where some line marks its item as
+ * markdown does not; otherwise `text` as it stands. A line's level is the open one of its
+ * kind at its indent, give or take a column, the levels below it closing; a marker no open
+ * level holds opens one beneath the deepest. Markdown nests by indent alone, so each line
+ * is indented past the markers of the levels above it. A letter's ordinal is its place in
+ * the alphabet. Lines in a fence and lines opening no item stand as they are.
+ */
+export function plainTextList(text) {
+    if (!LOOSE_ITEM.test(text))
+        return text;
+    const levels = [];
+    let fence = false;
+    let prev = '';
+    return text
+        .split(/\r\n?|\n/)
+        .map((line) => {
+        const above = prev;
+        prev = line;
+        if (/^ {0,3}(?:```|~~~)/.test(line))
+            fence = !fence;
+        const m = fence ? null : ITEM.exec(line);
+        if (!m)
+            return line;
+        const [head, lead, dash, num, bullet, alpha, pnum, palpha] = m;
+        const indent = lead.replace(/\t/g, '    ').length;
+        const kind = dash ?? bullet ?? String(m.slice(2).findIndex(Boolean));
+        const letter = alpha ?? palpha;
+        const ordinal = letter ? letter.charCodeAt(0) - 96 : Number(num ?? pnum);
+        const marker = dash || bullet ? '- ' : `${ordinal}. `;
+        let depth = levels.findLastIndex((l) => l.kind === kind && Math.abs(l.indent - indent) <= 1);
+        const opens = depth < 0;
+        if (opens) {
+            while (levels.length && levels.at(-1).indent > indent + 1)
+                levels.pop();
+            depth = levels.length;
+        }
+        levels.length = depth;
+        levels.push({ kind, indent, width: marker.length });
+        const pad = levels.slice(0, depth).reduce((sum, l) => sum + l.width, 0);
+        // Only a list counting from 1 interrupts the line above it; a blank line lets
+        // any other open where it stands.
+        const gap = opens && ordinal !== 1 && marker !== '- ' && above.trim() ? '\n' : '';
+        return gap + ' '.repeat(pad) + marker + line.slice(head.length);
+    })
+        .join('\n');
+}
 /**
  * A block leaf's markdown paste, consulted after the table paste: ProseMirror hands text
  * over only where the clipboard holds no HTML, whose DOM parse reads the source's own
- * structure, so HTML wins. A paste as plain text keeps the text. An island the parse
- * builds arrives under the id `importMarkdown` minted, which the paste's island pass
- * re-mints where the field holds it (`islands.ts`).
+ * structure, so HTML wins. A paste as plain text keeps the text, and so does a parse
+ * building a construct no leaf edits (`fitsLeaf`). An island the parse builds arrives
+ * under the id `importMarkdown` minted, which the paste's island pass re-mints where the
+ * field holds it (`islands.ts`).
  */
 export function markdownPastePlugin() {
     return new Plugin({
@@ -36,12 +98,14 @@ export function markdownPastePlugin() {
                 const { importMarkdown } = core();
                 let rt;
                 try {
-                    rt = importMarkdown(text).content;
+                    rt = importMarkdown(plainTextList(text)).content;
                 }
                 catch {
                     // Nesting past the store's depth is refused; the literal text holds it.
                     return null;
                 }
+                if (!fitsLeaf(rt, { inline: false, plaintext: false, islands: true }))
+                    return null;
                 return new Slice(decode(rt, blockSchema).content, 0, 0);
             })
         }

package/dist/core/codec/nesting.d.ts

@@ -1,5 +1,5 @@
 import type { Node as PMNode } from 'prosemirror-model';
-import { Plugin } from 'prosemirror-state';
+import { Plugin, type Transaction } from 'prosemirror-state';
 /** The store's bound on the containers around one line: a commit nesting past it is
  *  refused, and `@quillmark/wasm` exports no constant to read it from. */
 export declare const MAX_NESTING_DEPTH = 12;
@@ -10,6 +10,10 @@ export declare function nestingDepth(doc: PMNode): number;
 /** Whether `doc` nests within {@link MAX_NESTING_DEPTH}: what a command that nests asks
  *  of the doc it would dispatch. */
 export declare function withinNesting(doc: PMNode): boolean;
+/** Whether a step of `tr` can move a block under another container: any replace but
+ *  inline content inside one textblock, which is every keystroke's. Mark and attribute
+ *  steps move no node. */
+export declare function mayNest(tr: Transaction): boolean;
 /**
  * Refuses a transaction leaving `doc` past {@link MAX_NESTING_DEPTH}, which the commit
  * would lose: a paste or a drop into a deep item, whose slice the import bounded alone.

package/dist/core/codec/nesting.js

@@ -28,7 +28,7 @@ export function withinNesting(doc) {
 /** Whether a step of `tr` can move a block under another container: any replace but
  *  inline content inside one textblock, which is every keystroke's. Mark and attribute
  *  steps move no node. */
-function mayNest(tr) {
+export function mayNest(tr) {
     return tr.steps.some((step, i) => {
         if (step instanceof ReplaceAroundStep)
             return true;

package/dist/core/codec/prose.css

@@ -56,26 +56,30 @@ li.ProseMirror-selectednode::after {
 
 /* One rhythm between sibling blocks, in place of the UA's collapsed pair. Scoped by
    parent rather than by tag, which is what keeps it true as the schema grows: the
-   containers below are every node whose content is `block+` (`schema.ts`), so
-   their children are blocks by definition, whatever kinds exist. `ul`/`ol` are
-   deliberately absent: a run of list items is tight, and the gap before a list is
-   the list's, not each item's.
-
-   An item is the exception to its own container. A list nested under an item is
-   part of the run that omission already keeps tight — `a. …` under `1. …` is the
-   next line of one list, not a new block after a paragraph — so an item's children
-   take the gap only up to the point where one of them is a list. Written as its own
-   arm rather than as a `:not()` over the shared one, because the exception is the
-   item's: a list after a paragraph inside a blockquote is an ordinary sibling pair
-   and keeps the gap.
+   containers below are every node whose children are blocks (`schema.ts`), whatever
+   kinds exist; a task item holds its blocks in a body past its checkbox (`tasks.ts`),
+   so the body is the container rather than the item. A list and an item are
+   containers like any other: an item stands off its neighbours as a paragraph does, a
+   list nested under an item stands off the item's text, and an item's unnumbered line
+   has the gap below it that the next item draws above, where a tight run would read it
+   as the head of the next item.
 
    A line box is ~22px at the paper size and the body leading, so the rung is a
    little over half a line: enough that a break reads as a break, short of the full
    blank line that doubles the leading and makes a short document read as a list of
    fragments. */
 .ProseMirror > * + *,
-.ProseMirror :is(blockquote, [data-qm-unknown-container]) > * + *,
-.ProseMirror li > * + :not(ul, ol) {
+.ProseMirror
+	:is(
+		blockquote,
+		ul,
+		ol,
+		li:not([data-qm-checked]),
+		[data-qm-task-body],
+		[data-qm-unknown-container]
+	)
+	> *
+	+ * {
 	margin-top: var(--_qm-space-3);
 }
 
@@ -162,6 +166,21 @@ li.ProseMirror-selectednode::after {
 	pointer-events: none;
 }
 
+/* A footnote and an equation are read, not edited (CODEC §Decode), and draw as what
+   their markdown writes: a footnote its reference mark, numbered in reading order off a
+   counter each leaf resets, its note the marker's title (`islands.ts`); an equation its
+   TeX between its dollars, in the code face. */
+.ProseMirror {
+	counter-reset: qm-footnote;
+}
+.ProseMirror sup[data-qm-island='footnote']::after {
+	counter-increment: qm-footnote;
+	content: counter(qm-footnote);
+}
+.ProseMirror [data-qm-island='math'] {
+	font-family: var(--_qm-font-mono);
+}
+
 /* A link takes the surface's ink (the UA's blue is the `#8cf` defect again) and a
    dotted underline. Dotted rather than solid because `underline` is a mark in the
    same schema, and a solid rule renders an authored `<u>` and a link identically in a
@@ -185,9 +204,6 @@ li.ProseMirror-selectednode::after {
 
 /* The UA's 40px list indent is the one box the reset above does not take (it is
    padding, not margin), and it is a length nothing chose. A rung replaces it.
-   Per-item spacing is untouched, which is the point of putting this on the list
-   rather than the item: the sibling-gap rule deliberately omits `ul`/`ol`, and
-   padding on the container cannot reintroduce what it withholds.
 
    The markers are the UA's, reclaimed rather than inherited. `disc` and `decimal`
    are right and this restates neither: a host reset (Tailwind's preflight sets
@@ -354,9 +370,9 @@ li.ProseMirror-selectednode::after {
    absorbs the gap, at both ends. A negative margin would hang the band over the
    neighbouring block, and an `opacity: 0` control is still hit-tested, so it would take
    that block's presses. The `.ProseMirror` qualifier is what makes the override hold
-   wherever the island lands: two of the gap rule's arms name a container, so a bare
-   class loses to them for an island inside a list item or a quote, both of which the
-   schema admits. */
+   wherever the island lands: the gap rule's container arm outweighs a bare class, and
+   loses to this one on order alone, for an island inside a list item or a quote, both
+   of which the schema admits. */
 .ProseMirror .qm-table-island {
 	margin-top: 0;
 	margin-left: calc(var(--_qm-space-3) * -1);

package/dist/core/codec/slash.d.ts

@@ -32,7 +32,8 @@ export declare const DEFAULT_SLASH_STRINGS: SlashStrings;
  * by, each asked whether it would fire here. A row that declines when picked is worse
  * than an absent one, and asking the command rather than restating its guards is what
  * keeps the menu from drifting off what a pick does. So the offers narrow as the caret
- * moves: the lists and the island alone mid-paragraph, no list at an item's head.
+ * moves: the lists and the island alone mid-paragraph, and at an item's head only the
+ * list of the other kind, which retypes the item's list.
  *
  * `state` is the state a pick leaves behind — the run already consumed — since that is
  * the caret every command answers for (`blocks.ts`).

package/dist/core/codec/touching.d.ts

@@ -0,0 +1,12 @@
+import type { Node as PMNode } from 'prosemirror-model';
+import type { Transaction } from 'prosemirror-state';
+/** Whether two lists of one kind meet at `pos`. */
+export declare function touching(doc: PMNode, pos: number): boolean;
+/** Join the two lists of one kind meeting at `pos`, the first's `start` counting for
+ *  both. */
+export declare function joinLists(tr: Transaction, pos: number): boolean;
+/** Join the list at `pos` to a list of its kind touching it on either side. */
+export declare function joinAround(tr: Transaction, pos: number): void;
+/** Join at every seam of `seams` that two lists of one kind meet at, the last first so
+ *  each join leaves the positions before it standing. */
+export declare function joinAll(tr: Transaction, seams: Iterable<number>): void;

package/dist/core/codec/touching.js

@@ -0,0 +1,33 @@
+import { canJoin } from 'prosemirror-transform';
+function isList(node) {
+    return node.firstChild?.type === node.type.schema.nodes.list_item;
+}
+/** Whether two lists of one kind meet at `pos`. */
+export function touching(doc, pos) {
+    const $pos = doc.resolve(pos);
+    const before = $pos.nodeBefore;
+    const after = $pos.nodeAfter;
+    return !!before && !!after && before.type === after.type && isList(before);
+}
+/** Join the two lists of one kind meeting at `pos`, the first's `start` counting for
+ *  both. */
+export function joinLists(tr, pos) {
+    if (!touching(tr.doc, pos) || !canJoin(tr.doc, pos))
+        return false;
+    tr.join(pos);
+    return true;
+}
+/** Join the list at `pos` to a list of its kind touching it on either side. */
+export function joinAround(tr, pos) {
+    const node = tr.doc.nodeAt(pos);
+    if (!node)
+        return;
+    joinLists(tr, pos + node.nodeSize);
+    joinLists(tr, pos);
+}
+/** Join at every seam of `seams` that two lists of one kind meet at, the last first so
+ *  each join leaves the positions before it standing. */
+export function joinAll(tr, seams) {
+    for (const seam of [...new Set(seams)].sort((a, b) => b - a))
+        joinLists(tr, seam);
+}

package/dist/core/codec/undo.d.ts

@@ -0,0 +1,5 @@
+import { Plugin } from 'prosemirror-state';
+/** Marks each block-moving transaction as the start of an undo step. `filterTransaction`
+ *  is the one hook that sees a transaction before history's `apply` does; it passes
+ *  every one. A transaction a plugin appended stays in its root's step. */
+export declare function undoStepPlugin(): Plugin;

package/dist/core/codec/undo.js

@@ -0,0 +1,21 @@
+// Undo steps. History groups a run of adjacent edits under its delay, so a burst of
+// typing with a list change in it would undo as one step. A transaction that moves a
+// block (`mayNest`: a split, a join, a wrap, a lift) opens a step of its own, the typing
+// after it joining that step.
+import { closeHistory, isHistoryTransaction } from 'prosemirror-history';
+import { Plugin } from 'prosemirror-state';
+import { mayNest } from './nesting.js';
+/** Marks each block-moving transaction as the start of an undo step. `filterTransaction`
+ *  is the one hook that sees a transaction before history's `apply` does; it passes
+ *  every one. A transaction a plugin appended stays in its root's step. */
+export function undoStepPlugin() {
+    return new Plugin({
+        filterTransaction: (tr) => {
+            if (!tr.docChanged || isHistoryTransaction(tr) || tr.getMeta('appendedTransaction'))
+                return true;
+            if (mayNest(tr))
+                closeHistory(tr);
+            return true;
+        }
+    });
+}

package/dist/index.js

@@ -1,4 +1,4 @@
-// `@quillmark/svelte` root: the framework-free substrate.
+// `@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

package/dist/preview/Preview.svelte

@@ -38,7 +38,7 @@
 		onPick?: (at: Landing) => void;
 		/** A page paint the backend refused; the error message state shows either way. */
 		onError?: EditorErrorHandler;
-		/** The message-state wording, keyed and partial (`PreviewStrings`). */
+		/** The surface's wording, keyed and partial (`PreviewStrings`). */
 		strings?: PreviewStringsInput;
 	}
 
@@ -78,8 +78,9 @@
 	export function endFollow(): void {
 		controller?.endFollow();
 	}
-	export function setZoom(scale: number): void {
-		controller?.setZoom(scale);
+	/** A fraction of actual size; `undefined` is the default fit ({@link PreviewController}). */
+	export function setZoom(zoom: number | undefined): void {
+		controller?.setZoom(zoom);
 	}
 </script>
 
@@ -93,25 +94,99 @@
 	   tone behind it is the sunken rung and the gutter is the margin the sheet floats
 	   in. Paper is the brighter plane at both poles, exactly as a card is over the
 	   editor's own column, so the two panes step the same way. Both are
-	   the surface's own, so a bare `<div>` is a mounting site. The
-	   padding is safe against the paint loop: a slot is a `width: 100%` child and
-	   measures the content box, and the container's own `clientWidth` is read only as
-	   a change detector, which a constant inset does not disturb.
+	   the surface's own, so a bare `<div>` is a mounting site. The viewport fits the
+	   pages to the content box, padding off.
+
+	   A flex column, so the zoom pill's dock can take the space under pages shorter than
+	   the pane and stand at its corner (viewport.ts). The gutter is reserved, so a
+	   scrollbar arriving with a taller zoom narrows nothing the default fits against.
+	   Scroll anchoring is off because the viewport holds the reader's place itself, on
+	   every zoom and re-fit, and the browser's correction would land on top of it.
+	   `touch-action` leaves a pinch to the viewport, which zooms the pages rather than
+	   the host's page.
 
 	   `:global(:where(…))` puts this promised class at zero rank (ARCHITECTURE §Styling). */
 	:global(:where(.qm-preview)) {
 		box-sizing: border-box;
 		position: relative;
+		display: flex;
+		flex-direction: column;
 		width: 100%;
-		/* The width is the host's, never the document's, which is the same boundary the
-		   editor states (`visual/VisualEditorInner.svelte` §`.qm-editor`): a mount standing
-		   in a column that floors at what it holds is asked for nothing the sheets in it
-		   are. `inline-size`, not `size`: the column is as tall as the pages painted in
-		   it. */
+		/* The pane's width is the host's, never the document's, which is the same boundary
+		   the editor states (`visual/VisualEditorInner.svelte` §`.qm-editor`): a page zoomed
+		   wider than the pane scrolls inside it rather than widening it. `inline-size`, not
+		   `size`: the column is as tall as the pages painted in it. */
 		contain: inline-size;
 		height: 100%;
-		overflow-y: auto;
+		overflow: auto;
+		scrollbar-gutter: stable;
+		overflow-anchor: none;
+		touch-action: pan-x pan-y;
 		padding: var(--_qm-space-4);
 		background: var(--_qm-surface-sunken);
 	}
+
+	/* Sticky to the pane's bottom edge and stretched across it, so the pill's corner is
+	   the pane's however the pages scroll; zero height, so it displaces nothing. */
+	:global(:where(.qm-preview-dock)) {
+		order: 1;
+		flex: none;
+		position: sticky;
+		bottom: 0;
+		inset-inline-start: 0;
+		height: 0;
+		margin-top: auto;
+	}
+
+	/* Floats over the desk, so it lifts the way a floating surface does (ARCHITECTURE
+	   §Styling), and says only the zoom: the label never changes. Tabular figures and a
+	   floor as wide as `100%`, so a third digit never shifts its edge. It arrives at once and leaves on the reveal, so a glance at
+	   it after a gesture still finds it. */
+	:global(:where(.qm-preview-zoom)) {
+		position: absolute;
+		inset-inline-end: 0;
+		bottom: 0;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: calc(4ch + 2 * var(--_qm-space-2));
+		min-height: var(--_qm-tap-min);
+		padding: 0 var(--_qm-space-2);
+		border: var(--_qm-border-width) solid var(--_qm-border);
+		border-radius: var(--_qm-radius-pill);
+		background: var(--_qm-surface-popover);
+		backdrop-filter: blur(var(--_qm-blur));
+		box-shadow: var(--_qm-lift);
+		color: var(--_qm-ink-label);
+		font-family: var(--_qm-font);
+		font-size: var(--_qm-text-label);
+		font-variant-numeric: tabular-nums;
+		cursor: pointer;
+		user-select: none;
+		transition:
+			opacity var(--_qm-duration-fast) var(--_qm-ease-reverse),
+			color var(--_qm-duration-fast) var(--_qm-ease-reverse);
+	}
+	:global(:where(.qm-preview-zoom:hover)) {
+		color: var(--_qm-ink);
+	}
+	:global(:where(.qm-preview-zoom:active)) {
+		background: var(--_qm-surface-hover);
+	}
+	:global(:where(.qm-preview-zoom[data-idle])) {
+		opacity: 0;
+		pointer-events: none;
+		transition: opacity var(--_qm-reveal);
+	}
+	:global(:where(.qm-preview-zoom:focus-visible)) {
+		opacity: 1;
+		pointer-events: auto;
+		outline: var(--_qm-ring);
+		outline-offset: var(--_qm-ring-offset);
+	}
+	@media (prefers-reduced-motion: reduce) {
+		:global(:where(.qm-preview-zoom, .qm-preview-zoom[data-idle])) {
+			transition: none;
+		}
+	}
 </style>

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

@@ -25,7 +25,7 @@ interface Props {
     onPick?: (at: Landing) => void;
     /** A page paint the backend refused; the error message state shows either way. */
     onError?: EditorErrorHandler;
-    /** The message-state wording, keyed and partial (`PreviewStrings`). */
+    /** The surface's wording, keyed and partial (`PreviewStrings`). */
     strings?: PreviewStringsInput;
 }
 declare const Preview: import("svelte").Component<Props, {
@@ -33,7 +33,7 @@ declare const Preview: import("svelte").Component<Props, {
     scrollToField: (field: DocPath) => boolean;
     focusPosition: (at: Place) => void;
     endFollow: () => void;
-    setZoom: (scale: number) => void;
+    setZoom: (zoom: number | undefined) => void;
 }, "">;
 type Preview = ReturnType<typeof Preview>;
 export default Preview;

package/dist/preview/bridge.js

@@ -86,6 +86,9 @@ export function createBridge(session, container, slots, onPick, held = {}) {
     // and this one moves the container's box, and one forced layout serves the whole hop.
     function centre(target, port) {
         container.scrollTop += target.top + target.height / 2 - (port.top + port.height / 2);
+        reveal(target, port);
+    }
+    function reveal(target, port) {
         if (target.left < port.left)
             container.scrollLeft += target.left - port.left;
         else if (target.right > port.right)
@@ -145,10 +148,13 @@ export function createBridge(session, container, slots, onPick, held = {}) {
         // 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.
         const target = measure(slot, rectToPercent(region.rect, slot.size));
         if (clearOfTheFold(target, port))
-            return;
-        centre(target, port);
+            reveal(target, port);
+        else
+            centre(target, port);
     }
     return {
         scrollToField,

package/dist/preview/controller.d.ts

@@ -14,8 +14,8 @@ export interface PreviewOptions {
     /** 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. */
     onError?: EditorErrorHandler;
-    /** The three message-state strings, keyed and partial: unset keys take the
-     *  package's English. */
+    /** The surface's strings, keyed and partial: unset keys take the package's
+     *  English. */
     strings?: PreviewStringsInput;
 }
 export interface PreviewController {
@@ -50,8 +50,12 @@ export interface PreviewController {
      * own next caret.
      */
     endFollow(): void;
-    /** Fold a density multiplier into every future paint (crispness, not layout). */
-    setZoom(scale: number): 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.
+     */
+    setZoom(zoom: number | undefined): void;
     destroy(): void;
 }
 export declare function createPreview(session: LiveSession, opts: PreviewOptions): PreviewController;

package/dist/preview/controller.js

@@ -1,6 +1,7 @@
 import { reportError, errorMessage } from '../core/errors.js';
 import { createPaintLoop } from './paint.js';
 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
@@ -82,7 +83,11 @@ export function createPreview(session, opts) {
             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.
+    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
@@ -94,6 +99,8 @@ export function createPreview(session, opts) {
     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)
@@ -115,11 +122,12 @@ export function createPreview(session, opts) {
         endFollow() {
             followed = undefined;
         },
-        setZoom(scale) {
-            paintLoop.setDensityZoom(scale);
+        setZoom(zoom) {
+            viewport.setZoom(zoom);
         },
         destroy() {
             detach();
+            viewport.destroy();
             paintLoop.destroy();
             hideMessage();
             container.classList.remove(CONTAINER_CLASS);

package/dist/preview/index.js

@@ -13,7 +13,7 @@
 import '../core/theme.css';
 export { createPreview } from './controller.js';
 export { default as Preview } from './Preview.svelte';
-// What the preview says when there is nothing to paint. Keyed and partial; the
+// What the preview says: 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.

package/dist/preview/paint.d.ts

@@ -10,8 +10,12 @@ export interface PaintLoop {
     readonly slots: readonly PageSlot[];
     /** Reconcile slot count to `pageCount`, re-cache geometry, repaint mounted `dirtyPages`. */
     refresh(dirtyPages: readonly number[], pageCount: number): void;
-    /** Fold a density multiplier into every future paint; repaints mounted pages now. */
-    setDensityZoom(zoom: 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.
+     */
+    setScale(scale: number, settle?: number): void;
     destroy(): void;
 }
 export declare function createPaintLoop(session: LiveSession, container: HTMLElement, margin: number, onPaintError?: (page: number, err: unknown) => void): PaintLoop;