@laminapdf/viewer 0.2.0-alpha.5 → 0.2.0

package/dist/view/viewer.js

@@ -11,14 +11,15 @@
 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 { 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 { appearanceField, appearanceKey, 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";
@@ -82,6 +83,9 @@ export class Viewer {
     #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;
     /**
@@ -89,6 +93,11 @@ export class Viewer {
      * `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;
@@ -99,11 +108,21 @@ export class Viewer {
     #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;
@@ -173,6 +192,30 @@ export class Viewer {
         });
         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(),
+            planSave: (options) => this.#client.planSave(options),
+            copyEdits: (options) => this.#client.copyEdits(options),
+            adoptEdits: (token) => this.#client.adoptEdits(token),
+        });
+        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() {
@@ -187,16 +230,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.history.reset();
-        this.#text?.open(document);
+        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();
     }
@@ -353,9 +402,153 @@ export class Viewer {
                 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) {
         const layout = this.#layout;
@@ -388,6 +581,7 @@ export class Viewer {
             dropped: this.#dropped,
             aborted: this.#aborted,
             cacheBytes: this.#cache.bytes,
+            previewBitmaps: this.#previews?.size ?? 0,
             pages,
         };
     }
@@ -399,6 +593,7 @@ export class Viewer {
         clearTimeout(this.#settling);
         this.#unmountAll();
         this.#cache.clear();
+        this.#previews?.clear();
         this.find.reset();
         this.#text?.destroy();
         this.#links?.destroy();
@@ -407,6 +602,24 @@ export class Viewer {
         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)
@@ -419,6 +632,8 @@ export class Viewer {
             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;
@@ -486,12 +701,104 @@ 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)
@@ -500,6 +807,7 @@ export class Viewer {
             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;
@@ -545,6 +853,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 });
@@ -565,8 +875,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);
@@ -593,7 +908,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. */
@@ -815,7 +1132,11 @@ 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, ...appearanceField(this.#state.appearance) };
-        return { clip, request, key: renderKey(request, this.#document?.id ?? 0) };
+        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) {
@@ -886,7 +1207,7 @@ export class Viewer {
         // 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;
         }
         if (!this.#readyForAppearance(view, priority) || this.#upToDate(view, priority, frame))
@@ -951,7 +1272,7 @@ export class Viewer {
             rotation: layout.rotation,
             ...appearanceField(this.#state.appearance),
         };
-        const low = await this.#bitmap(request, renderKey(request, this.#document?.id ?? 0), priority, signal);
+        const low = await this.#bitmap(request, this.#key(request), priority, signal);
         if (!live()) {
             this.#drop(low);
             return false;
@@ -1160,7 +1481,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 };
     }
@@ -1330,6 +1661,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