@laminapdf/viewer 0.2.0-alpha.3 → 0.2.0-alpha.5

package/dist/view/viewer.js

@@ -1,17 +1,30 @@
 // The viewer: a scroll container whose spacer is the whole document's height, and page
 // shells for only the pages in view plus a margin. Each mounted page borrows a canvas from a
 // fixed pool and paints in two passes, a low-resolution whole page and then sharp tiles over the
-// part in view, through the document worker at `visible` or `prefetch` priority. A page
+// part in view, through the document worker at `visible` or `prefetch` priority. A page too large
+// for its canvas at the full pixel ratio (past a pixel cap, or the pool's fit) keeps that canvas as
+// a backdrop at a lower one, and a detail canvas over the part in view takes the sharp tiles. A page
 // that leaves the margin aborts its renders, and a result that arrives for it anyway is dropped,
 // never drawn. Zoom keeps the document point under the cursor (or the viewport centre) where it
 // is; during a gesture the canvases are stretched by CSS and the sharp re-render waits until the
 // gesture settles. Framework-free: UI layers read `getState()`, `subscribe()` and the events.
-import { BitmapCache, DEFAULT_CACHE_BYTES } from "../canvas/cache.js";
+import { pagePixels } from "@laminapdf/render";
+import { BitmapCache } from "../canvas/cache.js";
 import { CanvasPool } from "../canvas/pool.js";
+import { FindController } from "../find/controller.js";
+import { NavigationHistory } from "../history/history.js";
+import { HighlightLayer } from "../layers/highlight-layer.js";
+import { LinkLayer } from "../layers/link-layer.js";
+import { TextLayer } from "../layers/text-layer.js";
 import { isRotation, PageLayout, rotated } from "../layout/page-layout.js";
-import { renderKey, renderKeyFields } from "../protocol.js";
-import { lowScale, tilesFor } from "../render/tiles.js";
+import { range } from "../layout/range.js";
+import { appearanceField, appearanceKey, renderKey, renderKeyFields, } from "../protocol.js";
+import { backdropRatio, bounds, contains, lowScale, sharpScale, tilesFor } from "../render/tiles.js";
+import { destinationView } from "../zoom/destination.js";
 import { contentPosition, percentOfScale, pointAt, scaleFor, scrollToPoint, } from "../zoom/zoom.js";
+import { deviceHints, viewerBudgets } from "./budgets.js";
+import { TouchGestures } from "./touch.js";
+import { setUserSelect } from "./user-select.js";
 /** The built-in layer slots, bottom to top, above the canvas. */
 const SLOTS = ["text", "annot", "highlight"];
 /** The tallest scroll space browsers handle (Firefox stops near 17.9 M CSS px). */
@@ -19,10 +32,27 @@ const MAX_HEIGHT = 16_000_000;
 function isAbort(e) {
     return e instanceof DOMException && e.name === "AbortError";
 }
+/** The state before a document opens. */
+function emptyState(zoom) {
+    return {
+        pageCount: 0,
+        currentPage: 0,
+        zoom,
+        percent: 100,
+        rotation: 0,
+        appearance: "original",
+        scrollTop: 0,
+        visibleRange: { first: 0, last: -1 },
+    };
+}
 /** What a painted canvas depends on: a zoom or a rotation makes it stale. */
 function geometryOf(layout) {
     return `${layout.scale}:${layout.rotation}`;
 }
+/** The view rotation a `geometryOf` string was painted for. */
+function rotationOf(geometry) {
+    return Number(geometry.slice(geometry.indexOf(":") + 1));
+}
 /** A closed ImageBitmap has no size: one the cache evicted while a pass held it. */
 function isClosed(bitmap) {
     return bitmap.width === 0 || bitmap.height === 0;
@@ -38,11 +68,34 @@ export class Viewer {
     #settleMs;
     #dpr;
     #pool;
+    #detailPool;
+    #backdropMaxPixels;
+    #canvasMaxPixels;
+    #touch;
     #cache;
     #root;
     #spacer;
     #pages = new Map();
     #layers = [];
+    /** The text layer, unless `text: false`. */
+    #text;
+    #highlights;
+    /** The link layer, unless `links: false`. */
+    #links;
+    /** Find in this viewer's document: query, options, matches, next and previous. */
+    find;
+    /**
+     * Back and forward through the places jumped from and to: links, `jumpToPage`,
+     * `jumpToDestination` and find's matches record a jump; scrolling doesn't.
+     */
+    history;
+    /** Pages kept mounted whatever the scroll (`keepMounted`): those a selection touches. */
+    #pinned = new Set();
+    #regions;
+    /** The page a jump landed on, focused once it is mounted. */
+    #focusTarget;
+    /** True while a jump that leaves focus where it is (a find match) runs. */
+    #keepFocus = false;
     #listeners = new Set();
     #events = new Map();
     #cleanup = [];
@@ -65,27 +118,61 @@ export class Viewer {
         this.#gap = options.gap ?? 16;
         this.#settleMs = options.settleMs ?? 150;
         this.#dpr = options.dpr ?? (() => globalThis.devicePixelRatio || 1);
-        this.#pool = new CanvasPool(options.pool);
-        this.#cache = new BitmapCache(options.cacheBytes ?? DEFAULT_CACHE_BYTES);
+        const budgets = viewerBudgets(options.device ?? deviceHints());
+        this.#pool = new CanvasPool({ ...budgets.pool, ...options.pool });
+        this.#detailPool = new CanvasPool({ ...budgets.detailPool, ...options.detailPool });
+        this.#cache = new BitmapCache(options.cacheBytes ?? budgets.cacheBytes);
+        this.#backdropMaxPixels = options.backdropMaxPixels ?? budgets.backdropMaxPixels;
+        this.#canvasMaxPixels = options.canvasMaxPixels ?? budgets.canvasMaxPixels;
+        this.#touch = new TouchGestures(this.#touchHost());
         this.#zoom = options.zoom ?? "fit-width";
         this.#root = document.createElement("div");
         this.#root.className = "lamina-viewer";
         this.#root.tabIndex = 0;
-        Object.assign(this.#root.style, { position: "relative", overflow: "auto", width: "100%", height: "100%" });
+        // `touch-action: none`: the viewer pans and zooms under a finger itself, so the browser's own
+        // page zoom never fights it, and zooming the chrome stays the browser's (UI/UX plan §5.4).
+        Object.assign(this.#root.style, {
+            position: "relative",
+            overflow: "auto",
+            width: "100%",
+            height: "100%",
+            touchAction: "none",
+        });
         this.#spacer = document.createElement("div");
         this.#spacer.className = "lamina-viewer-content";
         Object.assign(this.#spacer.style, { position: "relative" });
         this.#root.append(this.#spacer);
-        this.#state = {
-            pageCount: 0,
-            currentPage: 0,
-            zoom: this.#zoom,
-            percent: 100,
-            rotation: 0,
-            scrollTop: 0,
-            visibleRange: { first: 0, last: -1 },
-        };
+        this.#state = emptyState(this.#zoom);
         this.#listen();
+        this.#text = this.#textLayer(options.text);
+        if (this.#text !== undefined)
+            this.addLayer(this.#text);
+        this.history = new NavigationHistory({ place: () => this.#place(), show: (p) => this.#show(p) }, options.history);
+        this.#regions = options.pages ?? {};
+        if (this.#regions.focusOnJump === true) {
+            this.history.onEntry((entry, replaced) => {
+                if (replaced || this.#keepFocus)
+                    return;
+                this.#focusTarget = entry.point.page;
+                this.#schedule();
+            });
+        }
+        this.find = new FindController({
+            find: (query, find, pages, signal) => this.#client.find(query, find, pages, { signal }),
+            pageCount: () => this.#sizes.length,
+            currentPage: () => this.#state.currentPage,
+            // Each match find moves to is a jump, so Back returns to where the search started.
+            // A match is a jump too, but focus stays in the find field.
+            reveal: (page, quads) => this.#jumpKeepingFocus(() => this.#reveal(page, quads)),
+            redraw: (pages) => this.#highlights.refresh(pages),
+        });
+        this.#highlights = new HighlightLayer({
+            matchesOn: (page) => this.find.matchesOn(page),
+            points: (page) => this.#sizes[page],
+            rotation: () => this.#rotation,
+        });
+        this.addLayer(this.#highlights);
+        this.#links = this.#linkLayer(options.links);
     }
     /** The scroll container (append it, or use {@link mount}). */
     get element() {
@@ -101,6 +188,11 @@ export class Viewer {
         this.#unmountAll();
         this.#cache.clear();
         this.#document = document;
+        this.#pinned = new Set();
+        this.#focusTarget = undefined;
+        this.find.reset();
+        this.history.reset();
+        this.#text?.open(document);
         this.#sizes = document.pages.map((p) => ({ width: p.width, height: p.height }));
         this.#layout = undefined;
         this.#root.scrollTop = 0;
@@ -128,6 +220,35 @@ export class Viewer {
         set.add(l);
         return () => set.delete(l);
     }
+    /**
+     * Copies the text selection to the clipboard: by paragraph in reading order, or exact, as laid
+     * out. Call it in a user gesture (a click, a key). Resolves false when nothing is selected or
+     * the clipboard refused.
+     */
+    copySelection(mode = "paragraph") {
+        return this.#text?.copy(mode) ?? Promise.resolve(false);
+    }
+    /** Whether a plain drag selects a rectangle, as an Alt/Option-drag does (column selection). */
+    get columnSelect() {
+        return this.#text?.columnMode ?? false;
+    }
+    /** Turns column selection by plain drag on or off; Alt/Option-drag selects a rectangle either way. */
+    set columnSelect(on) {
+        if (this.#text !== undefined)
+            this.#text.columnMode = on;
+    }
+    /**
+     * Keeps `pages` mounted wherever the view scrolls, until the next call replaces them: the pages
+     * a text selection touches, so scrolling never takes the selection away. A pinned page out of
+     * view keeps its shell and its text; its canvas goes back to the pool like any other.
+     */
+    keepMounted(pages) {
+        const next = new Set(pages);
+        if (next.size === this.#pinned.size && [...next].every((p) => this.#pinned.has(p)))
+            return;
+        this.#pinned = next;
+        this.#schedule();
+    }
     /** Adds a layer to every page, mounted now and later; returns a function that removes it. */
     addLayer(layer) {
         this.#layers.push(layer);
@@ -143,6 +264,7 @@ export class Viewer {
     }
     /** Scrolls page `index` to the top of the viewport (or its centre). */
     goToPage(index, options = {}) {
+        this.#touch.stopMomentum();
         const layout = this.#layout;
         if (layout === undefined || layout.pageCount === 0)
             return;
@@ -154,6 +276,36 @@ export class Viewer {
                 : Math.max(0, top);
         this.#schedule();
     }
+    /**
+     * Goes to `target` (an outline item's, a named destination's or a link's, from
+     * `ViewerClient.outline` or `namedDestination`): its zoom if it sets one, then its point at the
+     * viewport's top-left, or its page's top when it names no point (ISO 32000-2 §12.3.2.2).
+     */
+    goToDestination(target) {
+        this.#touch.stopMomentum();
+        const size = this.#sizes[target.page];
+        if (this.#layout === undefined || size === undefined)
+            return;
+        const view = destinationView(target, size, this.#rotation, this.#viewport(), this.#gap);
+        if (view.zoom !== undefined) {
+            this.#zoom = view.zoom;
+            this.#rezoom(undefined);
+        }
+        const layout = this.#layout;
+        const at = contentPosition(layout, this.#root.clientWidth, { page: view.page, x: view.x ?? 0, y: view.y ?? 0 });
+        this.#root.scrollTop = Math.max(0, view.y === undefined ? layout.offsetOf(view.page) - this.#gap / 2 : at.y);
+        if (view.x !== undefined)
+            this.#root.scrollLeft = Math.max(0, at.x);
+        this.#schedule();
+    }
+    /** {@link goToPage} as a history jump: Back returns to where the view was. */
+    jumpToPage(index) {
+        this.history.jump(() => this.goToPage(index));
+    }
+    /** {@link goToDestination} as a history jump: Back returns to where the view was. */
+    jumpToDestination(target) {
+        this.history.jump(() => this.goToDestination(target));
+    }
     /**
      * Sets the zoom (a mode, or a percentage clamped to 10–800 %), keeping the document point at
      * `anchor` (viewport CSS px; default its centre) where it is.
@@ -173,6 +325,36 @@ export class Viewer {
             throw new RangeError(`rotate() takes a multiple of 90, got ${delta}`);
         this.#rotation = next;
         this.#rezoom(undefined);
+        // A half turn keeps every page's size, so no layer hears of it from a resize.
+        this.#text?.refresh();
+        this.#highlights.refresh();
+        this.#links?.refresh();
+    }
+    /**
+     * Draws the pages in `appearance` (Sepia, Dark, High contrast or their own colours), keeping the
+     * scroll position: pages in view paint again, a quick pass then sharp tiles, and none of their
+     * old pixels is kept; other pages give their canvas back and paint when they come into view.
+     * The thumbnails follow.
+     */
+    setAppearance(appearance) {
+        if (appearanceKey(appearance) === appearanceKey(this.#state.appearance))
+            return;
+        const { first, last } = this.#state.visibleRange;
+        for (const view of [...this.#pages.values()]) {
+            this.#abort(view);
+            view.tiles.clear();
+            view.detail?.tiles.clear();
+            if (view.index >= first && view.index <= last) {
+                view.appearance = appearanceKey(appearance);
+                view.painted = "";
+            }
+            else {
+                // Its shell shows the new paper until it is seen (`#readyForAppearance`).
+                this.#releaseCanvas(view);
+            }
+        }
+        this.#setState({ appearance });
+        this.#schedule();
     }
     /** The document point at viewport position (`x`, `y`) in CSS px. */
     pointAt(x, y) {
@@ -201,6 +383,7 @@ export class Viewer {
             canvases: this.#pool.inUse,
             peakCanvases: this.#pool.peak,
             maxCanvases: this.#pool.max,
+            detailCanvases: this.#detailPool.inUse,
             drawsOnUnmounted: this.#drawsOnUnmounted,
             dropped: this.#dropped,
             aborted: this.#aborted,
@@ -216,17 +399,118 @@ export class Viewer {
         clearTimeout(this.#settling);
         this.#unmountAll();
         this.#cache.clear();
+        this.find.reset();
+        this.#text?.destroy();
+        this.#links?.destroy();
         for (const f of this.#cleanup.splice(0))
             f();
         this.#root.remove();
     }
     // --- internals ---
+    /** The link layer, added to every page, unless `links` is `false`. */
+    #linkLayer(links) {
+        if (links === false)
+            return undefined;
+        const layer = new LinkLayer({
+            root: this.#root,
+            client: this.#client,
+            points: (page) => this.#sizes[page],
+            rotation: () => this.#rotation,
+            pageCount: () => this.#sizes.length,
+            goTo: (target) => this.jumpToDestination(target),
+            goToPage: (page) => this.jumpToPage(page),
+        }, links === true || links === undefined ? {} : links);
+        this.addLayer(layer);
+        return layer;
+    }
+    /**
+     * Where the view is, for the history: the document point a gap below the viewport's top-left (so
+     * a page that `goToPage` put at the top, half a gap down, is the one named), and the zoom.
+     */
+    #place() {
+        const layout = this.#layout;
+        if (layout === undefined || layout.pageCount === 0)
+            return undefined;
+        return { point: pointAt(layout, this.#root.clientWidth, this.#scroll(), { x: 0, y: this.#gap }), zoom: this.#zoom };
+    }
+    /** Puts the view back at a history `place`: its zoom, then its point a gap below the viewport's top-left. */
+    #show(place) {
+        this.#touch.stopMomentum();
+        if (place.zoom !== this.#zoom) {
+            this.#zoom = place.zoom;
+            this.#rezoom(undefined);
+        }
+        const layout = this.#layout;
+        if (layout === undefined || place.point.page >= layout.pageCount)
+            return;
+        const at = contentPosition(layout, this.#root.clientWidth, place.point);
+        this.#root.scrollTop = Math.max(0, at.y - this.#gap);
+        this.#root.scrollLeft = Math.max(0, at.x);
+        this.#schedule();
+    }
+    /**
+     * Scrolls so that `quads` (a find match, in page `page`'s points) are in view: nothing moves
+     * when they already are, else they come to the viewport's centre.
+     */
+    #reveal(page, quads) {
+        const layout = this.#layout;
+        const size = this.#sizes[page];
+        if (layout === undefined || size === undefined || page >= layout.pageCount || quads.length < 8)
+            return;
+        this.#touch.stopMomentum();
+        // The corners as fractions of the page, turned with the view (clockwise).
+        const turn = (fx, fy) => ({ 0: [fx, fy], 90: [1 - fy, fx], 180: [1 - fx, 1 - fy], 270: [fy, 1 - fx] })[this.#rotation];
+        const xs = [];
+        const ys = [];
+        for (let at = 0; at + 1 < quads.length; at += 2) {
+            const [x, y] = turn((quads[at] ?? 0) / size.width, (quads[at + 1] ?? 0) / size.height);
+            xs.push(x);
+            ys.push(y);
+        }
+        const viewportWidth = this.#root.clientWidth;
+        const pageLeft = layout.leftOf(page, viewportWidth);
+        const pageTop = layout.offsetOf(page);
+        const width = layout.widths[page] ?? 0;
+        const height = layout.heights[page] ?? 0;
+        const left = pageLeft + Math.min(...xs) * width;
+        const right = pageLeft + Math.max(...xs) * width;
+        const top = pageTop + Math.min(...ys) * height;
+        const bottom = pageTop + Math.max(...ys) * height;
+        const view = this.#scroll();
+        const viewportHeight = this.#root.clientHeight;
+        if (top < view.top || bottom > view.top + viewportHeight) {
+            this.#root.scrollTop = Math.max(0, (top + bottom) / 2 - viewportHeight / 2);
+        }
+        if (left < view.left || right > view.left + viewportWidth) {
+            this.#root.scrollLeft = Math.max(0, (left + right) / 2 - viewportWidth / 2);
+        }
+        this.#schedule();
+    }
     #scroll() {
         return { left: this.#root.scrollLeft, top: this.#root.scrollTop };
     }
     #viewport() {
         return { width: this.#root.clientWidth || 800, height: this.#root.clientHeight || 600 };
     }
+    /** The text layer `option` asks for, or none (`false`); it reports the selection as an event too. */
+    #textLayer(option) {
+        if (option === false)
+            return undefined;
+        const host = {
+            root: this.#root,
+            client: this.#client,
+            rotation: () => this.#rotation,
+            keepMounted: (pages) => this.keepMounted(pages),
+        };
+        const textOptions = option === true || option === undefined ? {} : option;
+        return new TextLayer(host, {
+            ...textOptions,
+            onSelection: (selection) => {
+                textOptions.onSelection?.(selection);
+                this.#emit("selectionchange", { selection });
+            },
+        });
+    }
     #emit(event, data) {
         for (const l of this.#events.get(event) ?? [])
             l(data);
@@ -286,6 +570,8 @@ export class Viewer {
         let unsharpened = false;
         for (const view of this.#pages.values()) {
             this.#abort(view);
+            // The new geometry needs other canvases: a page that waited for one tries again.
+            view.waiting = false;
             if (view.state === "error")
                 view.state = "placeholder";
             if (view.state === "sharp") {
@@ -327,6 +613,7 @@ export class Viewer {
         const frame = {
             layout,
             top: this.#root.scrollTop,
+            left: this.#root.scrollLeft,
             width: this.#root.clientWidth,
             height: this.#root.clientHeight,
         };
@@ -334,6 +621,7 @@ export class Viewer {
         const [first, last] = this.#mountRange(frame);
         // Writes.
         this.#placeShells(frame, first, last);
+        this.#focusJumpTarget();
         this.#setState({
             currentPage: layout.pageAt(frame.top + frame.height / 2),
             scrollTop: frame.top,
@@ -344,13 +632,17 @@ export class Viewer {
             this.#paintRange(frame, visible, first, last);
         this.#emit("renderstats", this.stats());
     }
-    /** Unmounts the shells outside `first..last`, mounts the missing ones and positions them all. */
+    /**
+     * Unmounts the shells outside `first..last` (but the pinned ones), mounts the missing ones and
+     * positions them all.
+     */
     #placeShells(frame, first, last) {
         const { layout, width } = frame;
+        const pinned = [...this.#pinned].filter((i) => i >= 0 && i < layout.pageCount && (i < first || i > last));
         for (const [i, view] of this.#pages)
-            if (i < first || i > last)
+            if ((i < first || i > last) && !this.#pinned.has(i))
                 this.#unmount(view);
-        for (let i = first; i <= last; i++) {
+        for (const i of [...pinned, ...range(first, last)]) {
             const view = this.#pages.get(i) ?? this.#mount(i);
             const w = layout.widths[i];
             const h = layout.heights[i];
@@ -366,6 +658,24 @@ export class Viewer {
         if (this.#pages.size > this.#peakMounted)
             this.#peakMounted = this.#pages.size;
     }
+    #jumpKeepingFocus(go) {
+        this.#keepFocus = true;
+        try {
+            this.history.jump(go);
+        }
+        finally {
+            this.#keepFocus = false;
+        }
+    }
+    /** Focuses the page the last jump landed on, once it is mounted, keeping the scroll where it is. */
+    #focusJumpTarget() {
+        const target = this.#focusTarget;
+        const view = target === undefined ? undefined : this.#pages.get(target);
+        if (view === undefined)
+            return;
+        this.#focusTarget = undefined;
+        view.shell.focus({ preventScroll: true });
+    }
     #notifyResize(view, width, height) {
         for (const layer of this.#layers)
             layer.onZoom?.(view.index, this.#slot(view, layer.name), { width, height });
@@ -383,7 +693,17 @@ export class Viewer {
         const shell = document.createElement("div");
         shell.className = "lamina-page";
         shell.dataset.pageIndex = String(index);
-        Object.assign(shell.style, { position: "absolute", contain: "strict", background: "#fff" });
+        // A region for assistive technology, and a place focus can land after a jump.
+        shell.setAttribute("role", "region");
+        shell.setAttribute("aria-roledescription", this.#regions.roleDescription ?? "page");
+        shell.setAttribute("aria-label", this.#pageName(index));
+        shell.tabIndex = -1;
+        // The paper shows before the page is drawn: white, or the page appearance's (--lamina-page-paper).
+        Object.assign(shell.style, {
+            position: "absolute",
+            contain: "strict",
+            background: "var(--lamina-page-paper, #fff)",
+        });
         this.#spacer.append(shell);
         const view = {
             index,
@@ -393,7 +713,10 @@ export class Viewer {
             controller: new AbortController(),
             state: "placeholder",
             painted: "",
+            appearance: appearanceKey(this.#state.appearance),
+            scale: 0,
             tiles: new Set(),
+            detail: undefined,
             busy: false,
             waiting: false,
             pass: 0,
@@ -412,6 +735,14 @@ export class Viewer {
             slot = document.createElement("div");
             slot.className = `lamina-layer-${name}`;
             Object.assign(slot.style, { position: "absolute", inset: "0" });
+            // The slots above the text cover the whole page: taking the pointer, they would sit between
+            // every press and the spans, and no drag could select text. Nor are they part of a selection:
+            // each element the viewer adds that holds nothing to select sets `none` itself, never an
+            // ancestor of the spans (user-select.ts).
+            if (name !== "text") {
+                slot.style.pointerEvents = "none";
+                setUserSelect(slot, "none");
+            }
             view.slots.set(name, slot);
             view.shell.append(slot);
         }
@@ -424,6 +755,10 @@ export class Viewer {
         view.pass++;
         view.busy = false;
     }
+    #pageName(index) {
+        const count = this.#sizes.length;
+        return this.#regions.name?.(index, count) ?? `Page ${index + 1} of ${count}`;
+    }
     #unmount(view) {
         this.#abort(view);
         for (const layer of this.#layers)
@@ -437,6 +772,7 @@ export class Viewer {
             this.#unmount(view);
     }
     #releaseCanvas(view) {
+        this.#releaseDetail(view);
         if (view.canvas !== undefined)
             this.#pool.release(view.canvas);
         view.canvas = undefined;
@@ -449,45 +785,112 @@ export class Viewer {
             other.waiting = false;
         this.#schedule();
     }
-    /** The sharp tiles of page `index` in view in `frame`, with their render requests and keys. */
-    #tilesInView(index, frame, ratio) {
-        const { layout, top, height } = frame;
-        const documentId = this.#document?.id ?? 0;
+    /** The part of page `index` in view in `frame`, in CSS px from the page's top-left. */
+    #inView(index, frame) {
+        const { layout, top, left, width, height } = frame;
         const cssW = layout.widths[index];
         const cssH = layout.heights[index];
         const pageTop = layout.offsetOf(index);
+        const pageLeft = layout.leftOf(index, width);
+        const x0 = Math.max(0, left - pageLeft);
+        const x1 = Math.min(cssW, left + width - pageLeft);
         const y0 = Math.max(0, top - pageTop);
         const y1 = Math.min(cssH, top + height - pageTop);
-        const inView = { x: 0, y: y0, width: cssW, height: Math.max(0, y1 - y0) };
-        return tilesFor(inView, { width: cssW, height: cssH }, ratio).map((clip) => {
-            const request = { page: index, scale: layout.scale * ratio, rotation: layout.rotation, clip };
-            return { clip, request, key: renderKey(request, documentId) };
-        });
+        return { x: x0, y: y0, width: Math.max(0, x1 - x0), height: Math.max(0, y1 - y0) };
+    }
+    /**
+     * The sharp tiles of page `index` over `area` (CSS px from the page's top-left) at `scale` (device
+     * px per pt), with their render requests and keys. They lie inside the page as the renderer sizes
+     * it at that scale.
+     */
+    #tiles(index, layout, scale, area) {
+        const page = pagePixels(this.#sizes[index], scale, layout.rotation);
+        return tilesFor(area, page, scale / layout.scale).map((clip) => this.#tile(index, layout, scale, clip));
+    }
+    /** Page `index` whole at `scale`, as one tile. */
+    #wholePage(index, layout, scale) {
+        const page = pagePixels(this.#sizes[index], scale, layout.rotation);
+        return this.#tile(index, layout, scale, { x: 0, y: 0, ...page });
+    }
+    /** The tile `clip` of page `index` at `scale`: its render request and cache key. */
+    #tile(index, layout, scale, clip) {
+        const request = { page: index, scale, rotation: layout.rotation, clip, ...appearanceField(this.#state.appearance) };
+        return { clip, request, key: renderKey(request, this.#document?.id ?? 0) };
+    }
+    /** The device px per pt of a sharp tile: the layout's scale × the device pixel ratio. */
+    #fullScale(layout) {
+        return layout.scale * this.#dpr();
+    }
+    /** Whether `view`'s canvas is below the full pixel ratio, so the part in view needs a detail canvas. */
+    #needsDetail(view, layout) {
+        return view.scale < this.#fullScale(layout) * (1 - 1e-9);
+    }
+    /** Every sharp tile now in view is drawn: into the detail canvas, or else into the page canvas. */
+    #sharpInView(view, frame) {
+        const { layout } = frame;
+        const area = this.#inView(view.index, frame);
+        if (!this.#needsDetail(view, layout)) {
+            return this.#tiles(view.index, layout, view.scale, area).every((t) => view.tiles.has(t.key));
+        }
+        const tiles = this.#tiles(view.index, layout, this.#fullScale(layout), area);
+        // Nothing of the page in view (off to one side, or only the gap below it): nothing to
+        // sharpen, and its detail canvas goes back to the pool for a page that has.
+        if (tiles.length === 0) {
+            this.#releaseDetail(view);
+            return true;
+        }
+        const detail = view.detail;
+        if (detail === undefined || detail.geometry !== geometryOf(layout))
+            return false;
+        return tiles.every((t) => detail.tiles.has(t.key));
+    }
+    /**
+     * Whether `view` may paint now, catching it up with the appearance: a page out of view when the
+     * appearance changed waits until it is seen (`prefetch` doesn't paint it), then starts afresh.
+     */
+    #readyForAppearance(view, priority) {
+        const appearance = appearanceKey(this.#state.appearance);
+        if (view.appearance === appearance)
+            return true;
+        if (priority === "prefetch")
+            return false;
+        view.appearance = appearance;
+        view.painted = "";
+        return true;
+    }
+    /**
+     * Whether `view`'s canvas needs nothing for `frame`: painted at its geometry and, in view, with
+     * every tile in view drawn (then it is sharp). A margin page painted at its geometry waits.
+     */
+    #upToDate(view, priority, frame) {
+        if (view.painted !== geometryOf(frame.layout))
+            return false;
+        if (priority === "prefetch")
+            return true;
+        // Sharp means every tile now in view is drawn: scrolling down a tall page sharpens the rest.
+        if (view.scale > 0 && this.#sharpInView(view, frame)) {
+            if (view.state !== "sharp") {
+                view.state = "sharp";
+                this.#emit("renderstats", this.stats());
+            }
+            return true;
+        }
+        // Tiles in view are missing (the page scrolled): it is no longer sharp until they are drawn.
+        if (view.state === "sharp")
+            view.state = "low";
+        return false;
     }
     /** Starts page `index`'s pass if it isn't busy and its canvas isn't done for `frame` yet. */
     #paint(index, priority, frame) {
         const view = this.#pages.get(index);
+        // A page in the margin gives its detail canvas back for the pages in view.
+        if (view !== undefined && priority === "prefetch")
+            this.#releaseDetail(view);
         if (view === undefined || this.#document === undefined || view.busy || view.waiting || view.state === "error") {
             return;
         }
-        const { layout } = frame;
-        if (view.painted === geometryOf(layout)) {
-            if (priority === "prefetch")
-                return;
-            const canvas = view.canvas;
-            const ratio = canvas === undefined ? 0 : canvas.width / layout.widths[index];
-            // Sharp means every tile now in view is drawn: scrolling down a tall page sharpens the rest.
-            if (ratio > 0 && this.#tilesInView(index, frame, ratio).every((t) => view.tiles.has(t.key))) {
-                if (view.state !== "sharp") {
-                    view.state = "sharp";
-                    this.#emit("renderstats", this.stats());
-                }
-                return;
-            }
-            // Tiles in view are missing (the page scrolled): it is no longer sharp until they are drawn.
-            if (view.state === "sharp")
-                view.state = "low";
-        }
+        if (!this.#readyForAppearance(view, priority) || this.#upToDate(view, priority, frame))
+            return;
         view.busy = true;
         const pass = view.pass;
         void this.#pass(view, pass, priority, frame)
@@ -524,7 +927,15 @@ export class Viewer {
             return;
         if (priority === "prefetch")
             return;
-        await this.#paintTiles(pass_, frame);
+        if (!this.#needsDetail(view, layout)) {
+            this.#releaseDetail(view);
+            await this.#paintTiles(pass_, this.#tiles(index, layout, view.scale, this.#inView(index, frame)));
+            return;
+        }
+        // The part in view first, sharp; then the whole backdrop in one render (it is capped at
+        // BACKDROP_MAX_PIXELS, below the renderer's limit), for what scrolls into view next.
+        await this.#paintDetail(pass_, frame);
+        await this.#paintTiles(pass_, [this.#wholePage(index, layout, view.scale)]);
     }
     /** The blurry pass: resizes the canvas and stretches a low-resolution page over it. */
     async #paintLow(pass) {
@@ -534,7 +945,12 @@ export class Viewer {
         const cssW = layout.widths[index];
         const cssH = layout.heights[index];
         const shown = rotated(this.#sizes[index], layout.rotation);
-        const request = { page: index, scale: lowScale(layout.scale * dpr, shown.width), rotation: layout.rotation };
+        const request = {
+            page: index,
+            scale: lowScale(layout.scale * dpr, shown.width),
+            rotation: layout.rotation,
+            ...appearanceField(this.#state.appearance),
+        };
         const low = await this.#bitmap(request, renderKey(request, this.#document?.id ?? 0), priority, signal);
         if (!live()) {
             this.#drop(low);
@@ -546,22 +962,65 @@ export class Viewer {
             this.#drop(low, false);
             return false;
         }
-        const { width, height } = this.#pool.fit(canvas, cssW * dpr, cssH * dpr);
+        // The canvas's scale: the device pixel ratio, unless the backdrop's pixel cap or the pool's fit
+        // lowers it (then a detail canvas takes the part in view). The canvas is the page at that scale
+        // exactly as the renderer sizes it, so every tile fits inside.
+        const css = { width: cssW, height: cssH };
+        const ratio = backdropRatio(dpr, css, this.#backdropMaxPixels);
+        // The pool is asked for the page in whole pixels, as the renderer sizes it at that ratio.
+        const wanted = pagePixels(this.#sizes[index], layout.scale * ratio, layout.rotation);
+        const fitted = this.#pool.fit(canvas, wanted.width, wanted.height);
+        const scale = sharpScale(layout.scale, ratio, css, fitted, wanted);
+        const { width, height } = pagePixels(this.#sizes[index], scale, layout.rotation);
+        // What the canvas shows now, if it is this page in this orientation at another zoom: drawn back
+        // at the new size, so a re-zoom never trades sharp pixels for blurry ones.
+        const before = await this.#snapshot(view, layout, width, height);
+        if (!live()) {
+            before?.close();
+            this.#drop(low);
+            return false;
+        }
         // Resizing clears the canvas: it happens only now, with the new pixels ready (no white flash).
         canvas.width = width;
         canvas.height = height;
-        const drawn = this.#draw(view, low.bitmap, 0, 0, width, height);
+        // The old pixels cover the whole page, so the low pass is drawn only when there are none.
+        const drawn = this.#draw(view, canvas, before ?? low.bitmap, 0, 0, width, height);
+        before?.close();
         this.#release(low);
         // Not drawn (evicted meanwhile): the canvas stays unpainted, and the next frame tries again.
         if (!drawn)
             return false;
         view.painted = geometryOf(layout);
+        view.scale = scale;
         view.tiles.clear();
         view.state = "low";
-        this.#pruneOtherGeometries(index, layout, new Set([request.scale, layout.scale * (width / cssW)]));
+        this.#pruneOtherGeometries(index, layout, new Set([request.scale, scale, layout.scale * dpr]));
         this.#emit("renderstats", this.stats());
         return true;
     }
+    /**
+     * A copy of `view`'s page canvas when it holds the page in `layout`'s rotation at another zoom (the
+     * pixels the user sees stretched), no larger than the new `width` × `height`, for #paintLow to
+     * draw back at the new size; else undefined.
+     */
+    async #snapshot(view, layout, width, height) {
+        const canvas = view.canvas;
+        if (canvas === undefined || view.painted === "" || rotationOf(view.painted) !== layout.rotation)
+            return undefined;
+        try {
+            // No larger than the new canvas: zooming out shrinks the copy rather than doubling the memory.
+            if (width >= canvas.width && height >= canvas.height)
+                return await createImageBitmap(canvas);
+            return await createImageBitmap(canvas, {
+                resizeWidth: Math.min(width, canvas.width),
+                resizeHeight: Math.min(height, canvas.height),
+            });
+        }
+        catch {
+            // No copy (out of memory, or a browser without resize options): the low pass stands in.
+            return undefined;
+        }
+    }
     /** Frees page `index`'s bitmaps of other scales or rotations at once, rather than at the budget. */
     #pruneOtherGeometries(index, layout, scales) {
         this.#cache.prune(index, (key) => {
@@ -569,13 +1028,13 @@ export class Viewer {
             return scales.has(scale) && rotation === layout.rotation;
         });
     }
-    /** Sharp tiles over the part in view, at the canvas's own pixel ratio (the pool may cap it). */
-    async #paintTiles(pass, frame) {
-        const { view, layout, priority, signal, live } = pass;
+    /** `tiles` (at the canvas's scale) into the page's canvas. */
+    async #paintTiles(pass, tiles) {
+        const { view, priority, signal, live } = pass;
         const canvas = view.canvas;
         if (canvas === undefined)
             return;
-        for (const tile of this.#tilesInView(view.index, frame, canvas.width / layout.widths[view.index])) {
+        for (const tile of tiles) {
             if (view.tiles.has(tile.key))
                 continue;
             const got = await this.#bitmap(tile.request, tile.key, priority, signal);
@@ -583,12 +1042,115 @@ export class Viewer {
                 this.#drop(got);
                 return;
             }
-            const drawn = this.#draw(view, got.bitmap, tile.clip.x, tile.clip.y);
+            const drawn = this.#draw(view, canvas, got.bitmap, tile.clip.x, tile.clip.y);
             this.#release(got);
             if (drawn)
                 view.tiles.add(tile.key);
         }
     }
+    /**
+     * Sharp tiles over the part in view at the full pixel ratio, into the detail canvas: placed (or
+     * moved) to cover them, its cached tiles drawn at once so it never shows empty, then the rest.
+     */
+    async #paintDetail(pass, frame) {
+        const { view, layout, priority, signal, live } = pass;
+        const tiles = this.#tiles(view.index, layout, this.#fullScale(layout), this.#inView(view.index, frame));
+        const rect = bounds(tiles.map((t) => t.clip));
+        if (rect === undefined) {
+            this.#releaseDetail(view);
+            return;
+        }
+        const detail = this.#placeDetail(view, layout, rect);
+        if (detail === undefined) {
+            // No detail canvas to be had: the page shows its backdrop and waits until one is released,
+            // rather than try again every frame.
+            this.#releaseDetail(view);
+            view.waiting = true;
+            return;
+        }
+        const missing = tiles.filter((tile) => {
+            if (detail.tiles.has(tile.key))
+                return false;
+            const cached = this.#cache.get(tile.key);
+            if (cached === undefined || !this.#drawDetail(view, detail, cached, tile.clip))
+                return true;
+            detail.tiles.add(tile.key);
+            return false;
+        });
+        for (const tile of missing) {
+            const got = await this.#bitmap(tile.request, tile.key, priority, signal);
+            if (!live() || view.detail !== detail) {
+                this.#drop(got);
+                return;
+            }
+            const drawn = this.#drawDetail(view, detail, got.bitmap, tile.clip);
+            this.#release(got);
+            if (drawn)
+                detail.tiles.add(tile.key);
+        }
+    }
+    /**
+     * `view`'s detail canvas covering `rect` (device px at the full scale): the one it has, if it
+     * already covers it at this geometry, else one sized and placed for `rect`. Undefined when the
+     * detail pool has no canvas or not the pixels (the page then shows its backdrop).
+     */
+    #placeDetail(view, layout, rect) {
+        const scale = this.#fullScale(layout);
+        const geometry = geometryOf(layout);
+        const old = view.detail;
+        if (old !== undefined && old.geometry === geometry && old.scale === scale && contains(old.rect, rect))
+            return old;
+        // Past the device's cap for one canvas (a large tablet's viewport), the page keeps its backdrop.
+        if (rect.width * rect.height > this.#canvasMaxPixels)
+            return undefined;
+        const canvas = old?.canvas ?? this.#detailPool.acquire();
+        if (canvas === undefined)
+            return undefined;
+        const fitted = this.#detailPool.fit(canvas, rect.width, rect.height);
+        if (fitted.width < rect.width || fitted.height < rect.height) {
+            if (old === undefined)
+                this.#detailPool.release(canvas);
+            return undefined;
+        }
+        // Resizing clears it: #paintDetail draws the cached tiles back before the next frame.
+        canvas.width = rect.width;
+        canvas.height = rect.height;
+        // In percentages of the shell, so it stretches with the page while a zoom gesture runs.
+        const page = pagePixels(this.#sizes[view.index], scale, layout.rotation);
+        const percent = (n, of) => `${(100 * n) / of}%`;
+        Object.assign(canvas.style, {
+            position: "absolute",
+            left: percent(rect.x, page.width),
+            top: percent(rect.y, page.height),
+            width: percent(rect.width, page.width),
+            height: percent(rect.height, page.height),
+        });
+        if (old === undefined) {
+            canvas.className = "lamina-page-detail";
+            setUserSelect(canvas, "none");
+            if (view.canvas === undefined)
+                view.shell.prepend(canvas);
+            else
+                view.canvas.after(canvas);
+        }
+        const detail = { canvas, rect, scale, geometry, tiles: new Set() };
+        view.detail = detail;
+        return detail;
+    }
+    #releaseDetail(view) {
+        if (view.detail === undefined)
+            return;
+        this.#detailPool.release(view.detail.canvas);
+        view.detail = undefined;
+        // A detail canvas is free again: pages that waited for one try now.
+        for (const other of this.#pages.values())
+            other.waiting = false;
+        this.#schedule();
+    }
+    /** Draws a sharp tile at `clip` (device px of the page) into `detail`, offset by its rectangle. */
+    #drawDetail(view, detail, bitmap, clip) {
+        return this.#draw(view, detail.canvas, bitmap, clip.x - detail.rect.x, clip.y - detail.rect.y);
+    }
     /**
      * A bitmap for `request`, from the cache or the worker. `owned` is true when the cache didn't
      * keep it, so the caller closes it after drawing. A cached bitmap another page's pass evicted
@@ -612,9 +1174,9 @@ export class Viewer {
         if (got.owned)
             got.bitmap.close();
     }
-    /** The one place pixels reach a canvas: it counts a draw onto a shell out of the DOM. */
-    #draw(view, bitmap, x, y, width, height) {
-        const ctx = view.canvas?.getContext("2d");
+    /** The one place pixels reach a canvas of `view`: it counts a draw onto a shell out of the DOM. */
+    #draw(view, canvas, bitmap, x, y, width, height) {
+        const ctx = canvas.getContext("2d");
         // A bitmap another pass's cache write evicted (closed) after it was fetched: not drawn.
         if (ctx === undefined || ctx === null || isClosed(bitmap))
             return false;
@@ -655,6 +1217,7 @@ export class Viewer {
         if (canvas === undefined)
             return undefined;
         canvas.className = "lamina-page-canvas";
+        setUserSelect(canvas, "none");
         Object.assign(canvas.style, { position: "absolute", inset: "0", width: "100%", height: "100%" });
         view.shell.prepend(canvas);
         view.canvas = canvas;
@@ -675,13 +1238,14 @@ export class Viewer {
         this.#on("scroll", () => this.#schedule(), { passive: true });
         this.#listenWheel();
         this.#listenKeys();
-        this.#listenTouchPinch();
+        this.#listenTouch();
         this.#listenGestures();
         this.#listenResize();
     }
     /** Ctrl/cmd+wheel and trackpad pinch (which browsers send as ctrl+wheel): zoom at the cursor. */
     #listenWheel() {
         this.#on("wheel", (e) => {
+            this.#touch.stopMomentum();
             if (!e.ctrlKey && !e.metaKey)
                 return;
             e.preventDefault();
@@ -693,6 +1257,7 @@ export class Viewer {
     /** `+` and `-` zoom by a quarter, `0` goes to actual size. */
     #listenKeys() {
         this.#on("keydown", (e) => {
+            this.#touch.stopMomentum();
             if (e.altKey)
                 return;
             const p = this.#state.percent;
@@ -707,42 +1272,39 @@ export class Viewer {
             e.preventDefault();
         });
     }
-    /** Touch pinch: two pointers; the zoom follows their distance, anchored at their midpoint. */
-    #listenTouchPinch() {
-        const pointers = new Map();
-        let pinch;
-        const spread = () => {
-            const [a, b] = [...pointers.values()];
-            return a === undefined || b === undefined
-                ? undefined
-                : { d: Math.hypot(a.x - b.x, a.y - b.y), x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
-        };
-        this.#on("pointerdown", (e) => {
-            if (e.pointerType !== "touch")
-                return;
-            pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
-            const s = spread();
-            if (s !== undefined)
-                pinch = { distance: s.d, percent: this.#state.percent };
-        });
-        this.#on("pointermove", (e) => {
-            if (!pointers.has(e.pointerId))
-                return;
-            pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
-            const s = spread();
-            if (s === undefined || pinch === undefined || pinch.distance === 0)
-                return;
-            this.setZoom(pinch.percent * (s.d / pinch.distance), { anchor: this.#anchorAt(s.x, s.y) });
-        });
-        const up = (e) => {
-            pointers.delete(e.pointerId);
-            if (pointers.size < 2)
-                pinch = undefined;
+    /** Touch and pen: pan with momentum, pinch around the fingers, double-tap zoom (view/touch.ts). */
+    #listenTouch() {
+        const gestures = this.#touch;
+        this.#on("pointerdown", (e) => gestures.down(e));
+        this.#on("pointermove", (e) => gestures.move(e));
+        for (const end of ["pointerup", "pointercancel", "lostpointercapture"]) {
+            this.#on(end, (e) => gestures.up(e));
+        }
+        this.#cleanup.push(() => gestures.stop());
+    }
+    /** The gestures' view of this viewer; it reads the root when called, so it may be made before the root. */
+    #touchHost() {
+        return {
+            percent: () => this.#state.percent,
+            fitsWidth: () => this.#zoom === "fit-width",
+            zoom: (to, anchor) => this.setZoom(to, { anchor }),
+            pointAt: (at) => this.pointAt(at.x, at.y),
+            positionOf: (point) => this.positionOf(point),
+            scrollBy: (dx, dy) => this.#root.scrollBy({ left: dx, top: dy, behavior: "instant" }),
+            local: (e) => this.#anchorAt(e.clientX, e.clientY),
+            frame: (callback) => requestAnimationFrame(callback),
+            cancelFrame: (id) => cancelAnimationFrame(id),
+            capture: (id) => {
+                try {
+                    this.#root.setPointerCapture(id);
+                }
+                catch {
+                    // The pointer is already up: nothing to keep.
+                }
+            },
         };
-        this.#on("pointerup", up);
-        this.#on("pointercancel", up);
     }
-    /** Safari's trackpad pinch: gesture events with a scale. */
+    /** Safari's trackpad pinch: gesture events with a scale (and iOS's touch pinch, which the touch gestures take). */
     #listenGestures() {
         let gesture;
         this.#on("gesturestart", (e) => {
@@ -753,6 +1315,9 @@ export class Viewer {
             if (gesture === undefined)
                 return;
             e.preventDefault();
+            // iOS sends these for a two-finger touch pinch too: the touch gestures zoom it then.
+            if (this.#touch.pinching())
+                return;
             const ge = e;
             this.setZoom(gesture * ge.scale, { anchor: this.#anchorAt(ge.clientX, ge.clientY) });
         });