@laminapdf/viewer 0.2.0-alpha.4 → 0.2.0-alpha.6

package/dist/view/viewer.js

@@ -11,17 +11,21 @@
 import { pagePixels } from "@laminapdf/render";
 import { BitmapCache } from "../canvas/cache.js";
 import { CanvasPool } from "../canvas/pool.js";
+import { EditSession } from "../edit/session.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 { isRotation, keptTop, PageLayout, rotated } from "../layout/page-layout.js";
 import { range } from "../layout/range.js";
-import { renderKey, renderKeyFields } from "../protocol.js";
+import { appearanceField, appearanceKey, renderKeyFields, viewKey, } 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). */
@@ -29,6 +33,19 @@ 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}`;
@@ -64,18 +81,48 @@ export class Viewer {
     /** The text layer, unless `text: false`. */
     #text;
     #highlights;
+    /** The link layer, unless `links: false`. */
+    #links;
+    /** The link previews' pictures, loaded with their code on the first preview (not at startup). */
+    #previews;
+    #loadingPreviews;
     /** 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;
+    /**
+     * The open document's edit session: its history, and edits, undo, redo and going to a step,
+     * each redrawing the pages it touched. One call runs at a time, in the order they were made.
+     */
+    edits;
     /** 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 = [];
-    #document;
+    /** The open document's ID (renders name it), or undefined before one opens. */
+    #documentId;
+    /** Counts `open`s: an edit answered for a document since replaced redraws nothing. */
+    #opens = 0;
     #sizes = [];
+    /** Each edited page's revision (`invalidate` bumps it), part of its bitmaps' cache keys. */
+    #revisions = new Map();
     #layout;
     #zoom;
     #rotation = 0;
+    /**
+     * Where the view goes once it has a size, when it was opened or restored without one (a hidden
+     * host ignores scrolling): the top of a new document, or a kept position.
+     */
+    #pending;
     #state;
     #frame;
     #settling;
@@ -114,31 +161,28 @@ export class Viewer {
         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();
-        if (options.text !== false) {
-            const host = {
-                root: this.#root,
-                client: this.#client,
-                rotation: () => this.#rotation,
-                keepMounted: (pages) => this.keepMounted(pages),
-            };
-            this.#text = new TextLayer(host, options.text === true || options.text === undefined ? {} : options.text);
+        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,
-            reveal: (page, quads) => this.#reveal(page, quads),
+            // 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({
@@ -147,6 +191,28 @@ export class Viewer {
             rotation: () => this.#rotation,
         });
         this.addLayer(this.#highlights);
+        this.#links = this.#linkLayer(options.links);
+        this.edits = this.#editSession();
+    }
+    /**
+     * The edit session over this view's calls, which follows a restarted worker: its replay tells
+     * the session its history (`edit`), and lost edits leave it empty.
+     */
+    #editSession() {
+        const edits = new EditSession({
+            applyEdit: (ops, call) => this.applyEdit(ops, call),
+            undoEdit: () => this.#editCall(() => this.#client.undoEdit()),
+            redoEdit: () => this.#editCall(() => this.#client.redoEdit()),
+            goToStep: (position) => this.#editCall(() => this.#client.goToStep(position)),
+            editHistory: () => this.#client.editHistory(),
+        });
+        this.#cleanup.push(this.#client.on("restarted", ({ reopened, edits: replay }) => {
+            if (reopened)
+                this.#reopened();
+            if (replay === "lost")
+                edits.reset(this.#client.document);
+        }), this.#client.on("edit", ({ history }) => edits.follow(history)));
+        return edits;
     }
     /** The scroll container (append it, or use {@link mount}). */
     get element() {
@@ -161,14 +227,22 @@ export class Viewer {
     open(document) {
         this.#unmountAll();
         this.#cache.clear();
-        this.#document = document;
+        this.#previews?.clear();
+        this.#documentId = document.id;
+        this.#opens++;
+        this.#revisions = new Map();
         this.#pinned = new Set();
+        this.#focusTarget = undefined;
         this.find.reset();
-        this.#text?.open(document);
+        this.history.reset();
+        this.edits.reset(document);
+        this.#text?.open();
         this.#sizes = document.pages.map((p) => ({ width: p.width, height: p.height }));
         this.#layout = undefined;
         this.#root.scrollTop = 0;
         this.#root.scrollLeft = 0;
+        // A hidden view keeps its old scroll: the new document starts at its top once it shows.
+        this.#pending = this.#sized() ? undefined : "top";
         this.#relayout(this.#viewport());
         this.#schedule();
     }
@@ -192,6 +266,23 @@ 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
@@ -253,6 +344,14 @@ export class Viewer {
             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.
@@ -275,6 +374,177 @@ export class Viewer {
         // 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.#previews?.clear();
+        this.#setState({ appearance });
+        this.#schedule();
+    }
+    /**
+     * Where `target` goes, as a picture for a link preview (R07): one render of the region around its
+     * point (or the top of its page) through the document worker, and the text of the lines it shows.
+     * The viewer keeps the last few (`PREVIEW_CACHE`) and closes them on a zoom, rotation or
+     * appearance change and when the document closes, so draw the bitmap at once and never close it.
+     * Rejects with `AbortError` when `signal` aborts or the pictures are cleared while it draws.
+     */
+    preview(target, options = {}) {
+        return this.#linkPreviews().then((previews) => previews.picture(target, options.signal ?? new AbortController().signal));
+    }
+    /** The pointer is over the link preview (`true`) or has left it: a hovered preview stays (WCAG 1.4.13). */
+    holdLinkPreview(held) {
+        this.#links?.hold(held);
+    }
+    /** Escape or Close on the link preview: it goes, and stays hidden until its link is left. */
+    dismissLinkPreview() {
+        this.#links?.dismiss();
+    }
+    /** Whether a link is previewed or focused, so {@link followLinkPreview} has one (`nav.follow-link`). */
+    canFollowLink() {
+        return this.#links?.canFollow() ?? false;
+    }
+    /** Follows the previewed link, else the focused one (`nav.follow-link`); `false` when there is neither. */
+    followLinkPreview() {
+        return this.#links?.follow() ?? false;
+    }
+    /**
+     * Draws `pages` again: an edit changed them. Their bitmaps go, here and in a thumbnail strip,
+     * and their layers read their text and links again; every other page keeps what it drew.
+     * `sizes` gives the pages whose displayed size in points changed (a quarter turn swaps width and
+     * height): the layout takes them, and the page at the top of the viewport stays there. A page in
+     * view keeps its old pixels until the new ones are drawn over them.
+     */
+    invalidate(pages, sizes) {
+        const count = this.#sizes.length;
+        const changed = new Set([...pages, ...(sizes?.keys() ?? [])].filter((p) => Number.isInteger(p) && p >= 0 && p < count));
+        if (changed.size === 0)
+            return;
+        const resized = new Set();
+        for (const [page, size] of sizes ?? []) {
+            const old = this.#sizes[page];
+            if (old === undefined || (old.width === size.width && old.height === size.height))
+                continue;
+            this.#sizes[page] = { width: size.width, height: size.height };
+            resized.add(page);
+        }
+        for (const page of changed) {
+            this.#revisions.set(page, (this.#revisions.get(page) ?? 0) + 1);
+            this.#cache.prune(page, () => false);
+        }
+        if (resized.size > 0)
+            this.#resize();
+        const { first, last } = this.#state.visibleRange;
+        for (const page of changed) {
+            const view = this.#pages.get(page);
+            if (view === undefined)
+                continue;
+            this.#redraw(view, resized.has(page) || page < first || page > last);
+            this.#remountLayers(view);
+        }
+        this.find.refresh([...changed]);
+        const list = [...changed].sort((a, b) => a - b);
+        this.#emit("invalidate", { pages: list.map((index) => ({ index, ...this.#sizes[index] })) });
+        this.#emit("renderstats", this.stats());
+        this.#schedule();
+    }
+    /**
+     * Applies `ops` to the open document through the client (`ViewerClient.applyEdit`) and redraws
+     * the pages they touched ({@link invalidate}): an edit on screen in one call. A failed edit
+     * changes nothing and redraws nothing.
+     */
+    applyEdit(ops, options) {
+        return this.#editCall(() => this.#client.applyEdit(ops, options));
+    }
+    /** Runs an edit session call and redraws the pages it touched, unless another document opened meanwhile. */
+    async #editCall(call) {
+        const opens = this.#opens;
+        const result = await call();
+        // Another document opened meanwhile: these pages aren't its pages.
+        if (this.#opens === opens) {
+            this.invalidate(result.pages.map((page) => page.index), new Map(result.pages.map((page) => [page.index, page])));
+        }
+        return result;
+    }
+    /**
+     * Every page's displayed size in points, as the view lays it out: the sizes the document opened
+     * with, and those edits gave since (`invalidate`). A thumbnail strip lays its pages out from it.
+     * With `documentId`, empty unless the view shows that document: a page count alone can't tell two
+     * documents apart.
+     */
+    pageSizes(documentId) {
+        if (documentId !== undefined && documentId !== this.#documentId)
+            return [];
+        return this.#sizes;
+    }
+    /**
+     * Where the reader is: the document point a gap below the viewport's top-left, the zoom and the
+     * rotation; `undefined` without a document. {@link restore} puts the view back there.
+     */
+    viewPosition() {
+        const pending = this.#pending;
+        if (pending === "top" && this.#sizes.length > 0) {
+            return { point: { page: 0, x: 0, y: 0 }, zoom: this.#zoom, rotation: this.#rotation };
+        }
+        if (pending !== undefined && pending !== "top")
+            return pending;
+        const place = this.#place();
+        return place === undefined ? undefined : { ...place, rotation: this.#rotation };
+    }
+    /**
+     * Puts the view at `position` (a {@link viewPosition} kept from an earlier visit), as a history
+     * jump from where the view is, so Back returns there. Its page is clamped to the document's and
+     * its point to the page. Called in the task that opened the document, before the next frame, it
+     * paints no other page first.
+     */
+    restore(position) {
+        if (this.#layout === undefined || this.#sizes.length === 0)
+            return;
+        // Hidden: it takes place once the view has a size (`#listenResize`).
+        if (!this.#sized()) {
+            const page = Math.min(this.#sizes.length - 1, Math.max(0, Math.trunc(position.point.page) || 0));
+            this.#pending = { ...position, point: { ...position.point, page } };
+            return;
+        }
+        this.#pending = undefined;
+        this.history.jump(() => {
+            const turned = isRotation(position.rotation) && position.rotation !== this.#rotation;
+            if (turned)
+                this.#rotation = position.rotation;
+            const clamp = (v) => (Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0);
+            const page = Math.min(this.#sizes.length - 1, Math.max(0, Math.trunc(position.point.page) || 0));
+            // The zoom is set before the scroll: #show only rezooms when the zoom changes.
+            this.#zoom = position.zoom;
+            this.#rezoom(undefined);
+            this.#show({ point: { page, x: clamp(position.point.x), y: clamp(position.point.y) }, zoom: position.zoom });
+            // As rotate() does: the layers follow once the pages are laid out for the new rotation.
+            if (turned) {
+                this.#text?.refresh();
+                this.#highlights.refresh();
+                this.#links?.refresh();
+            }
+        });
     }
     /** The document point at viewport position (`x`, `y`) in CSS px. */
     pointAt(x, y) {
@@ -308,6 +578,7 @@ export class Viewer {
             dropped: this.#dropped,
             aborted: this.#aborted,
             cacheBytes: this.#cache.bytes,
+            previewBitmaps: this.#previews?.size ?? 0,
             pages,
         };
     }
@@ -319,13 +590,76 @@ export class Viewer {
         clearTimeout(this.#settling);
         this.#unmountAll();
         this.#cache.clear();
+        this.#previews?.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 previews' pictures, drawn at this viewer's zoom, rotation and appearance. Their code
+     * loads on the first preview, so the reader's startup script doesn't carry it.
+     */
+    #linkPreviews() {
+        this.#loadingPreviews ??= import("./previews.js").then(({ LinkPreviews }) => {
+            this.#previews = new LinkPreviews({
+                client: this.#client,
+                size: (page) => this.#sizes[page],
+                rotation: () => this.#rotation,
+                percent: () => this.#state.percent,
+                appearance: () => this.#state.appearance,
+                dpr: () => this.#dpr(),
+            });
+            return this.#previews;
+        });
+        return this.#loadingPreviews;
+    }
+    /** 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),
+            preview: (request) => this.#emit("linkpreview", request),
+            previewEnd: (anchor) => this.#emit("linkpreviewend", { anchor }),
+        }, 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.
@@ -364,12 +698,124 @@ export class Viewer {
         }
         this.#schedule();
     }
+    /**
+     * The worker restarted and opened the file again as it was, without the edits: the edited pages
+     * take their sizes from it and draw again (at a new revision, so no bitmap of theirs is reused).
+     */
+    #reopened() {
+        const document = this.#client.document;
+        if (document === undefined || document.pages.length !== this.#sizes.length)
+            return;
+        this.#documentId = document.id;
+        const edited = [...this.#revisions.keys()];
+        const sizes = new Map(edited.map((index) => [index, document.pages[index]]));
+        this.invalidate(edited, sizes);
+    }
+    /**
+     * Lays the pages out again after some changed size, keeping the page at the viewport's top where
+     * it is (scaled into its new height, if it is one that changed). A fixed zoom stays; a fit mode
+     * fits again, since a page turned a quarter can be wider than the window at the old scale.
+     */
+    #resize() {
+        const before = this.#layout;
+        if (before === undefined)
+            return;
+        const viewport = this.#viewport();
+        const scale = typeof this.#zoom === "string"
+            ? scaleFor(this.#zoom, this.#reference(), this.#rotation, viewport, this.#gap)
+            : before.scale;
+        const after = new PageLayout(this.#sizes, { scale, rotation: before.rotation, gap: this.#gap });
+        if (after.height > MAX_HEIGHT) {
+            // Past what browsers can scroll: the zoom is capped again.
+            this.#rezoom(undefined);
+            return;
+        }
+        const top = keptTop(before, after, this.#root.scrollTop);
+        this.#layout = after;
+        this.#spacer.style.height = `${after.height}px`;
+        this.#spacer.style.width = `${after.contentWidth(viewport.width)}px`;
+        this.#root.scrollTop = top;
+        if (scale !== before.scale) {
+            const percent = percentOfScale(scale);
+            this.#setState({ zoom: this.#zoom, percent });
+            this.#emit("zoomchange", { zoom: this.#zoom, percent });
+            this.#staleRenders();
+        }
+    }
+    /**
+     * Makes `view` draw its page again: its renders aborted (a late one is dropped), its tiles
+     * forgotten. A page in view at its old size keeps its pixels, and sharp tiles replace them; a
+     * page that changed size, or one outside the view, paints its quick pass first.
+     */
+    #redraw(view, repaint) {
+        this.#abort(view);
+        view.waiting = false;
+        view.tiles.clear();
+        // A page whose render failed tries again from the start.
+        if (repaint || view.state === "error") {
+            this.#releaseDetail(view);
+            view.painted = "";
+            view.state = "placeholder";
+        }
+        else {
+            view.detail?.tiles.clear();
+            if (view.state !== "placeholder")
+                view.state = "low";
+        }
+    }
+    /** Mounts `view`'s layers again, so they read its text and links again, at its size now. */
+    #remountLayers(view) {
+        const size = { width: this.#layout?.widths[view.index] ?? 0, height: this.#layout?.heights[view.index] ?? 0 };
+        for (const layer of this.#layers) {
+            const slot = this.#slot(view, layer.name);
+            layer.onUnmount?.(view.index, slot);
+            layer.onMount?.(view.index, slot);
+            layer.onZoom?.(view.index, slot, size);
+        }
+    }
     #scroll() {
         return { left: this.#root.scrollLeft, top: this.#root.scrollTop };
     }
     #viewport() {
         return { width: this.#root.clientWidth || 800, height: this.#root.clientHeight || 600 };
     }
+    /** Whether the view has a size (it is in a shown container), so it can scroll. */
+    #sized() {
+        return this.#root.clientWidth > 0 && this.#root.clientHeight > 0;
+    }
+    /** Puts a view that just got its size where it was opened or restored to. */
+    #showPending(pending) {
+        this.#pending = undefined;
+        this.#relayout(this.#viewport());
+        // The scroll kept while hidden is the last document's: the top first, so a restore's history
+        // jump leaves from page 1.
+        this.#root.scrollTop = 0;
+        this.#root.scrollLeft = 0;
+        if (pending === "top")
+            this.#schedule();
+        else
+            this.restore(pending);
+    }
+    /** 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,
+            points: (page) => this.#sizes[page],
+            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);
@@ -404,6 +850,8 @@ export class Viewer {
         this.#spacer.style.height = `${layout.height}px`;
         this.#spacer.style.width = `${layout.contentWidth(viewport.width)}px`;
         if (zoomed) {
+            // Pictures drawn at the old zoom or rotation would show the wrong size or turn.
+            this.#previews?.clear();
             const percent = percentOfScale(layout.scale);
             this.#setState({ pageCount: layout.pageCount, zoom: this.#zoom, percent, rotation: this.#rotation });
             this.#emit("zoomchange", { zoom: this.#zoom, percent });
@@ -424,8 +872,13 @@ export class Viewer {
         const scroll = scrollToPoint(after, viewport.width, point, at);
         this.#root.scrollTop = scroll.top;
         this.#root.scrollLeft = scroll.left;
-        // Renders for the old geometry are stale: abort them (a page that failed gets another try);
-        // the canvases stretch until the gesture settles and the new pass paints, so no page is sharp.
+        this.#staleRenders();
+    }
+    /**
+     * Renders for the old geometry are stale: abort them (a page that failed gets another try); the
+     * canvases stretch until the zoom settles and the new pass paints, so no page is sharp.
+     */
+    #staleRenders() {
         let unsharpened = false;
         for (const view of this.#pages.values()) {
             this.#abort(view);
@@ -452,7 +905,9 @@ export class Viewer {
             return;
         this.#frame = requestAnimationFrame(() => {
             this.#frame = undefined;
-            this.#update();
+            // A view waiting for its size has only an old scroll to go by: it draws once it is placed.
+            if (this.#pending === undefined)
+                this.#update();
         });
     }
     /** The mounted range: visible ± margin pages, and at least a viewport above and below. */
@@ -480,6 +935,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,
@@ -516,6 +972,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 });
@@ -533,7 +1007,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,
@@ -543,6 +1027,7 @@ export class Viewer {
             controller: new AbortController(),
             state: "placeholder",
             painted: "",
+            appearance: appearanceKey(this.#state.appearance),
             scale: 0,
             tiles: new Set(),
             detail: undefined,
@@ -565,9 +1050,13 @@ export class Viewer {
             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.
-            if (name !== "text")
+            // 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);
         }
@@ -580,6 +1069,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)
@@ -635,8 +1128,12 @@ export class Viewer {
     }
     /** 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 };
-        return { clip, request, key: renderKey(request, this.#document?.id ?? 0) };
+        const request = { page: index, scale, rotation: layout.rotation, clip, ...appearanceField(this.#state.appearance) };
+        return { clip, request, key: this.#key(request) };
+    }
+    /** `request`'s cache key: the render key with its page's revision. */
+    #key(request) {
+        return viewKey(request, this.#documentId ?? 0, this.#revisions.get(request.page) ?? 0);
     }
     /** The device px per pt of a sharp tile: the layout's scale × the device pixel ratio. */
     #fullScale(layout) {
@@ -665,31 +1162,53 @@ export class Viewer {
             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") {
+        if (view === undefined || this.#documentId === undefined || view.busy || view.waiting || view.state === "error") {
             return;
         }
-        const { layout } = frame;
-        if (view.painted === geometryOf(layout)) {
-            if (priority === "prefetch")
-                return;
-            // 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;
-            }
-            // 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)
@@ -744,8 +1263,13 @@ 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 low = await this.#bitmap(request, renderKey(request, this.#document?.id ?? 0), priority, signal);
+        const request = {
+            page: index,
+            scale: lowScale(layout.scale * dpr, shown.width),
+            rotation: layout.rotation,
+            ...appearanceField(this.#state.appearance),
+        };
+        const low = await this.#bitmap(request, this.#key(request), priority, signal);
         if (!live()) {
             this.#drop(low);
             return false;
@@ -921,6 +1445,7 @@ export class Viewer {
         });
         if (old === undefined) {
             canvas.className = "lamina-page-detail";
+            setUserSelect(canvas, "none");
             if (view.canvas === undefined)
                 view.shell.prepend(canvas);
             else
@@ -953,7 +1478,17 @@ export class Viewer {
         const cached = this.#cache.get(key);
         if (cached !== undefined && !isClosed(cached))
             return { bitmap: cached, owned: false };
+        const revision = this.#revisions.get(request.page) ?? 0;
         const { bitmap } = await this.#client.render(request, { priority, signal });
+        // The page was edited while this render waited: its pixels may be the old file's, and its key
+        // names a revision nothing asks for again. The worker runs one call at a time and `invalidate`
+        // runs only once the edit has answered, so an answer that comes after it, at the same
+        // revision, drew the edited file; the worker's coalescing key needs no revision for the same
+        // reason (no render can run across an edit).
+        if ((this.#revisions.get(request.page) ?? 0) !== revision) {
+            bitmap.close();
+            throw new DOMException("the page changed while it rendered", "AbortError");
+        }
         const kept = this.#cache.set(key, request.page, bitmap, this.#state.currentPage);
         return { bitmap, owned: !kept };
     }
@@ -1010,6 +1545,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;
@@ -1122,6 +1658,10 @@ export class Viewer {
         const resize = new ResizeObserver(() => {
             if (this.#layout === undefined)
                 return;
+            if (this.#pending !== undefined && this.#sized()) {
+                this.#showPending(this.#pending);
+                return;
+            }
             if (typeof this.#zoom === "string")
                 this.#rezoom(undefined);
             else