@2018kguo/recto 0.1.0 → 0.5.0

package/dist/document.js

@@ -45,6 +45,37 @@ export const ANNOT_SUBTYPE = {
 };
 const DEFAULT_MAX_HEIGHT = 4096;
 const MAX_DIMENSION = 16_384;
+/** With a region, the whole page's bitmap may be up to this wide. */
+const MAX_REGION_DIMENSION = 262_144;
+/** `width`, `maxHeight` and the region as the engine takes them (NaNs for none), or a RangeError. */
+function renderArgs(options) {
+    const maxHeight = options.maxHeight ?? DEFAULT_MAX_HEIGHT;
+    const { region } = options;
+    const most = region ? MAX_REGION_DIMENSION : MAX_DIMENSION;
+    if (!(options.width > 0 && options.width <= most) || !(maxHeight > 0)) {
+        throw new RangeError(region
+            ? `with a region, render width must be in 1..${MAX_REGION_DIMENSION} and maxHeight above 0`
+            : `render width must be in 1..${MAX_DIMENSION} and maxHeight above 0`);
+    }
+    if (!region) {
+        return [options.width, maxHeight, Number.NaN, Number.NaN, Number.NaN, Number.NaN];
+    }
+    const { x, y, width, height } = region;
+    if (![x, y, width, height].every((v) => typeof v === "number" && Number.isFinite(v)) || !(width > 0 && height > 0)) {
+        throw new RangeError("a render's region needs finite x and y, and width and height above 0");
+    }
+    return [options.width, maxHeight, x, y, width, height];
+}
+/** A rendered page as `render` returns it: with a region, where it is on the page. */
+function bitmapOf(page, region) {
+    const bitmap = {
+        width: page.width,
+        height: page.height,
+        truncated: page.truncated,
+        rgba: page.takeRgba(),
+    };
+    return region ? { ...bitmap, x: page.x, y: page.y, pageWidth: page.pageWidth, pageHeight: page.pageHeight } : bitmap;
+}
 /** What a call into the instance threw, as what the caller should see. */
 export function engineFailure(instance, error) {
     if (error instanceof PdfError) {
@@ -167,19 +198,60 @@ function toAnnotations(a) {
         return out;
     });
 }
+function toLink([annotation, x, y, width, height, kind, text, page, view, destX, destY, zoom, rx, ry, rw, rh, name]) {
+    const number = (v) => (Number.isNaN(v) ? null : v);
+    const target = kind === "uri"
+        ? { kind, uri: text }
+        : kind === "page"
+            ? {
+                kind,
+                destination: {
+                    page,
+                    view,
+                    x: number(destX),
+                    y: number(destY),
+                    zoom: number(zoom),
+                    box: Number.isNaN(rx) ? null : { x: rx, y: ry, width: rw, height: rh },
+                },
+            }
+            : kind === "remote"
+                ? { kind, file: text, name, page: page < 0 ? null : page }
+                : kind === "launch"
+                    ? { kind, file: text }
+                    : kind === "action"
+                        ? { kind, action: text, name }
+                        : { kind: "none" };
+    return { annotation, box: { x, y, width, height }, target };
+}
+const DEFAULT_SLICE_MS = 8;
+/** Back to the event loop, without the 4 ms a nested timer waits in a browser. */
+function nextTask() {
+    return new Promise((resolve) => {
+        const { port1, port2 } = new MessageChannel();
+        port1.onmessage = () => {
+            port1.close();
+            resolve();
+        };
+        port2.postMessage(0);
+    });
+}
 export class RectoDocument {
     pageCount;
     #closed = false;
     #doc;
     #instance;
+    /** The same file on another instance. */
+    #reopen;
     /** A ranged read's failure, thrown by the call whose fetch it failed. */
     #fetchFailure;
-    constructor(instance, doc, fetchFailure = () => null) {
+    constructor(instance, doc, reopen, fetchFailure = () => null) {
         this.#instance = instance;
         this.#doc = doc;
+        this.#reopen = reopen;
         this.#fetchFailure = fetchFailure;
         this.pageCount = doc.pageCount;
         instance.openDocuments += 1;
+        instance.documents.open += 1;
     }
     #check(index) {
         if (this.#closed) {
@@ -188,8 +260,11 @@ export class RectoDocument {
         if (!(Number.isInteger(index) && index >= 0 && index < this.pageCount)) {
             throw new RangeError(`page ${index} is out of range (0..${this.pageCount - 1})`);
         }
-        if (this.#instance.failure) {
-            throw this.#instance.failure;
+        this.#checkInstance();
+    }
+    #checkInstance() {
+        if (this.#instance.abandoned) {
+            this.#moveOffAbandoned();
         }
         if (this.#instance.dead) {
             throw new PdfError("crash", "the engine crashed earlier on this thread; open the document again");
@@ -215,6 +290,26 @@ export class RectoDocument {
         }
         return result;
     }
+    /** The call that failed told the caller; this one is a fresh start. */
+    #moveOffAbandoned() {
+        const old = this.#instance;
+        let moved;
+        try {
+            moved = this.#reopen(this.#doc, old);
+        }
+        catch (error) {
+            throw engineFailure(old, error);
+        }
+        old.openDocuments -= 1;
+        old.onClose?.();
+        this.#instance = moved.instance;
+        this.#doc = moved.doc;
+        moved.instance.openDocuments += 1;
+    }
+    /** Loaded ahead of the call, so that failing to get it leaves nothing half-done. */
+    #needsRender() {
+        this.#call(() => this.#instance.loadPart("recto-render.wasm"));
+    }
     pageInfo(index) {
         this.#check(index);
         return this.#call(() => {
@@ -228,12 +323,29 @@ export class RectoDocument {
     }
     objects(index) {
         this.#check(index);
+        this.#needsRender();
         return this.#call(() => toObjects(this.#doc.objects(index)));
     }
+    pageLabels() {
+        if (this.#closed) {
+            throw new PdfError("closed", "this document is closed");
+        }
+        this.#checkInstance();
+        return this.#call(() => this.#doc.pageLabels());
+    }
+    structureTruncated() {
+        if (this.#closed) {
+            throw new PdfError("closed", "this document is closed");
+        }
+        this.#checkInstance();
+        const [pages, pageLabels, outline] = this.#call(() => this.#doc.structureTruncated());
+        return { pages: pages === 1, pageLabels: pageLabels === 1, outline: outline === 1 };
+    }
     outline() {
         if (this.#closed) {
             throw new PdfError("closed", "this document is closed");
         }
+        this.#checkInstance();
         return this.#call(() => {
             const top = [];
             // The open item at each level; an item's parent is the last one a level up.
@@ -250,8 +362,15 @@ export class RectoDocument {
         this.#check(index);
         return this.#call(() => toAnnotations(this.#doc.annotations(index)));
     }
+    links(index) {
+        this.#check(index);
+        // A viewer's call: its code is in drawing's part, so text alone downloads none of it.
+        this.#needsRender();
+        return this.#call(() => this.#doc.links(index).map(toLink));
+    }
     scan(index) {
         this.#check(index);
+        this.#needsRender();
         return this.#call(() => consume(this.#doc.scan(index), (scan) => ({
             text: toText(scan.takeText()),
             objects: toObjects(scan.takeObjects()),
@@ -267,17 +386,46 @@ export class RectoDocument {
     }
     render(index, options) {
         this.#check(index);
-        const maxHeight = options.maxHeight ?? DEFAULT_MAX_HEIGHT;
-        if (!(options.width > 0 && options.width <= MAX_DIMENSION) ||
-            !(maxHeight > 0)) {
-            throw new RangeError(`render width must be in 1..${MAX_DIMENSION} and maxHeight above 0`);
+        const args = renderArgs(options);
+        this.#needsRender();
+        return this.#call(() => consume(this.#doc.render(index, ...args), (page) => bitmapOf(page, options.region !== undefined)));
+    }
+    async renderAsync(index, options) {
+        this.#check(index);
+        const args = renderArgs(options);
+        this.#needsRender();
+        const instance = this.#instance;
+        const sliceMs = options.sliceMs ?? DEFAULT_SLICE_MS;
+        const task = this.#call(() => this.#doc.renderTask(index, ...args));
+        const stopIfAsked = () => {
+            if (options.signal?.aborted) {
+                throw new PdfError("aborted", "the signal was aborted", options.signal.reason);
+            }
+            if (this.#closed) {
+                throw new PdfError("closed", "this document is closed");
+            }
+            if (instance.dead) {
+                throw new PdfError("crash", "the engine crashed while this render was paused; open the document again");
+            }
+            if (instance.abandoned) {
+                throw instance.failure ?? new PdfError("missing-asset", "a file the engine needed failed to load while this render was paused; render again");
+            }
+        };
+        try {
+            stopIfAsked();
+            while (!this.#call(() => task.step(sliceMs))) {
+                await nextTask();
+                stopIfAsked();
+            }
+            await nextTask();
+            stopIfAsked();
+            return this.#call(() => consume(task.finish(), (page) => bitmapOf(page, options.region !== undefined)));
+        }
+        finally {
+            if (!instance.dead && !instance.abandoned) {
+                task.free();
+            }
         }
-        return this.#call(() => consume(this.#doc.render(index, options.width, maxHeight), (page) => ({
-            width: page.width,
-            height: page.height,
-            truncated: page.truncated,
-            rgba: page.takeRgba(),
-        })));
     }
     close() {
         if (this.#closed) {
@@ -285,7 +433,8 @@ export class RectoDocument {
         }
         this.#closed = true;
         this.#instance.openDocuments -= 1;
-        if (!this.#instance.dead) {
+        this.#instance.documents.open -= 1;
+        if (!this.#instance.dead && !this.#instance.abandoned) {
             this.#doc.free();
         }
         this.#instance.onClose?.();

package/dist/engine.d.ts

@@ -1,5 +1,5 @@
-import { type AssetName } from "./assets.ts";
-import { type PdfDocument } from "./document.ts";
+import { type AssetName, type SyncHash } from "./assets.ts";
+import { type Instance, type PdfDocument } from "./document.ts";
 import { type PdfRangedDocument, type PdfRangedOpenOptions, type PdfRangeSource } from "./ranged.ts";
 export type PdfEngineOptions = {
     /**
@@ -8,16 +8,29 @@ export type PdfEngineOptions = {
      * path or file: URL in Node. Defaults to the package's own wasm/ directory.
      */
     assetBase?: string | URL;
-    /** Past this much linear memory, the instance is dropped when its last document closes, or
-     * replaced at the next open if one is still open. Default 512 MiB. */
+    /**
+     * Past this much linear memory, the instance is dropped when its last document closes, or replaced
+     * at the next open if one is still open. By default it's dropped a second after the last close, once
+     * anything has used it, and an open before then reuses it; past 512 MiB, at the close; and past 64 MiB
+     * with a document still open, the next open gets a new one.
+     */
     recycleAboveBytes?: number;
     /**
-     * Where a thread can't read a file synchronously (a page's main thread, a service worker), the
-     * assets are fetched while the engine is created: by default all of them, 5.6 MB. Name fewer to
-     * fetch less, and a document that needs one you left out fails with `missing-asset`. Ignored
-     * where assets can be read when needed.
+     * The most bytes one stream may decode to, and one image hold at a byte a component. Past it, that
+     * stream or image is left out and the page's results say `truncated`, so a few bytes that inflate to
+     * gigabytes can't take the instance's memory. Default 768 MiB (a 600 dpi gray scan of an A0 page is
+     * 558 MB); `Infinity` for none.
+     */
+    maxDecodedBytes?: number;
+    /**
+     * Files to fetch and verify while the engine is created, so that a missing one fails here and no later
+     * call waits for it. `recto-render.wasm` saves the first `render` that wait; all three parts check the
+     * whole engine at startup. The default is none, except where a thread can't read a file when it's needed
+     * (a page's main thread, a service worker): there it's all of them, about 9.6 MB. Name fewer to fetch less, and
+     * a call that needs a font or CMaps you left out fails with `missing-asset`. The parts are fetched there
+     * whatever you name, so it can always draw.
      */
-    preloadAssets?: Exclude<AssetName, "recto.wasm">[];
+    preloadAssets?: (AssetName | "cmaps.brotli" | "fonts.bin")[];
 };
 export type PdfOpenOptions = {
     password?: string;
@@ -44,6 +57,8 @@ export interface PdfEngine {
     openRanged(source: PdfRangeSource, options?: PdfRangedOpenOptions): Promise<PdfRangedDocument>;
     stats(): PdfEngineStats;
 }
+/** An instance's own SHA-256, for an asset it needs: faster than JavaScript's in a cold browser. */
+export declare function hashOn(instance: Pick<Instance, "dead" | "glue">): SyncHash;
 export declare function createPdfEngine(options?: PdfEngineOptions): Promise<PdfEngine>;
 /**
  * Opens a PDF on this thread's shared engine: