@2018kguo/recto 0.0.0-stage → 0.3.0

package/dist/document.js

@@ -0,0 +1,405 @@
+// One open PDF. Every coordinate this returns is in the viewer's frame: PDF points, top-left
+// origin, with /Rotate and the crop box applied.
+import { PdfError } from "./errors.js";
+/** `PdfPageText.flags` bit: a space or line break the engine inferred; not in the content stream. */
+export const CHAR_GENERATED = 1;
+/** `PdfPageText.flags` bit: the glyph has no Unicode mapping, so its text is unreadable. */
+export const CHAR_UNMAPPED = 2;
+/** Entry `i` of a `boxes` column. */
+export function boxAt(boxes, i) {
+    return {
+        x: boxes[4 * i] ?? 0,
+        y: boxes[4 * i + 1] ?? 0,
+        width: boxes[4 * i + 2] ?? 0,
+        height: boxes[4 * i + 3] ?? 0,
+    };
+}
+/** The text of chars `first..last` (inclusive). */
+export function charsText(page, first, last) {
+    let out = "";
+    for (let i = first; i <= last; i++) {
+        out += String.fromCodePoint(page.codepoints[i] ?? 0xff_fd);
+    }
+    return out;
+}
+/** Segment kinds, in the low bits of `PdfPathSegments.kinds`. */
+export const SEGMENT_LINE = 0;
+export const SEGMENT_BEZIER = 1;
+export const SEGMENT_MOVE = 2;
+/** `PdfPathSegments.kinds` bit: the segment closes its subpath. */
+export const SEGMENT_CLOSE = 4;
+/**
+ * `PdfPathSegments.kinds` bit on a move: its subpath is a rectangle drawn by
+ * `re` (pdf.js counts only those as rectangles).
+ */
+export const SEGMENT_RECT = 8;
+/** `paths.flags` bits. */
+export const PATH_FILL = 1;
+export const PATH_STROKE = 2;
+export const ANNOT_SUBTYPE = {
+    text: 1,
+    link: 2,
+    freeText: 3,
+    stamp: 13,
+    widget: 20,
+};
+const DEFAULT_MAX_HEIGHT = 4096;
+const MAX_DIMENSION = 16_384;
+/** What a call into the instance threw, as what the caller should see. */
+export function engineFailure(instance, error) {
+    if (error instanceof PdfError) {
+        return error;
+    }
+    // An exhausted call stack in WebAssembly is a RangeError, and leaves the instance in the
+    // same unknown state as a trap. The argument checks that throw RangeError run before any call.
+    if (error instanceof WebAssembly.RuntimeError || error instanceof RangeError) {
+        instance.dead = true;
+        return new PdfError("crash", `the engine crashed: ${error.message}`, error);
+    }
+    const code = error?.code;
+    if (typeof code === "string") {
+        return new PdfError(code, error.message);
+    }
+    return error;
+}
+/** Runs `read` over an object wasm-bindgen allocated, freeing it even if `read` throws. */
+function consume(owned, read) {
+    try {
+        return read(owned);
+    }
+    finally {
+        owned.free();
+    }
+}
+function toText(t) {
+    return consume(t, () => {
+        const fontFlags = t.fontFlags;
+        const fontWeights = t.fontWeights;
+        const fontEmbedded = t.fontEmbedded;
+        const fontAscents = t.fontAscents;
+        const fontDescents = t.fontDescents;
+        const fonts = t.fontNames.map((name, i) => ({
+            name,
+            flags: fontFlags[i] ?? 0,
+            weight: fontWeights[i] ?? 0,
+            embedded: fontEmbedded[i] === 1,
+            ascent: fontAscents[i] ?? 0,
+            descent: fontDescents[i] ?? 0,
+        }));
+        const wordFirstChar = t.wordFirstChar;
+        const runEms = t.runEms;
+        return {
+            text: t.text,
+            count: t.count,
+            codepoints: t.codepoints,
+            boxes: t.boxes,
+            fontSizes: t.fontSizes,
+            tfSizes: t.tfSizes,
+            truncated: t.truncated,
+            angles: t.angles,
+            fills: t.fills,
+            fontIds: t.fontIds,
+            flags: t.flags,
+            fonts,
+            words: {
+                count: wordFirstChar.length,
+                firstChar: wordFirstChar,
+                lastChar: t.wordLastChar,
+                boxes: t.wordBoxes,
+            },
+            runIds: t.runIds,
+            runs: { count: runEms.length, origins: t.runOrigins, ems: runEms },
+        };
+    });
+}
+function toObjects(o) {
+    return consume(o, () => {
+        const imageBoxes = o.imageBoxes;
+        const pathFlags = o.pathFlags;
+        const segmentKinds = o.segmentKinds;
+        return {
+            textObjects: o.textObjects,
+            truncated: o.truncated,
+            images: {
+                count: imageBoxes.length / 4,
+                boxes: imageBoxes,
+                pixels: o.imagePixels,
+            },
+            paths: {
+                count: pathFlags.length,
+                boxes: o.pathBoxes,
+                flags: pathFlags,
+                start: o.pathStart,
+            },
+            segments: {
+                count: segmentKinds.length,
+                points: o.segmentPoints,
+                kinds: segmentKinds,
+            },
+        };
+    });
+}
+function toAnnotations(a) {
+    return consume(a, () => {
+        const subtypes = a.subtypes;
+        const boxes = a.boxes;
+        const contents = a.contents;
+        const hasField = a.hasField;
+        const fieldTypes = a.fieldTypes;
+        const fieldValues = a.fieldValues;
+        const objects = a.appearanceObjects;
+        const textObjects = a.appearanceTextObjects;
+        const text = a.appearanceText;
+        const out = [];
+        for (let i = 0; i < a.count; i++) {
+            out.push({
+                subtype: subtypes[i] ?? 0,
+                box: boxAt(boxes, i),
+                contents: contents[i] ?? "",
+                field: hasField[i] === 1
+                    ? { type: fieldTypes[i] ?? "", value: fieldValues[i] ?? "" }
+                    : null,
+                appearanceObjects: objects[i] ?? 0,
+                appearanceTextObjects: textObjects[i] ?? 0,
+                appearanceText: text[i] ?? "",
+            });
+        }
+        return out;
+    });
+}
+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, 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) {
+            throw new PdfError("closed", "this document is closed");
+        }
+        if (!(Number.isInteger(index) && index >= 0 && index < this.pageCount)) {
+            throw new RangeError(`page ${index} is out of range (0..${this.pageCount - 1})`);
+        }
+        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");
+        }
+    }
+    #call(fn) {
+        let result;
+        try {
+            result = fn();
+        }
+        catch (error) {
+            // A failed fetch or asset surfaces inside the engine as some other error.
+            const failure = this.#instance.failure ?? this.#fetchFailure();
+            if (failure && !(error instanceof WebAssembly.RuntimeError)) {
+                throw failure;
+            }
+            throw engineFailure(this.#instance, error);
+        }
+        // Or as a page that reads short: blank text must not pass for the page's text.
+        const failure = this.#instance.failure ?? this.#fetchFailure();
+        if (failure) {
+            throw failure;
+        }
+        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(() => {
+            const [width = 0, height = 0, rotation = 0] = this.#doc.pageInfo(index);
+            return { width, height, rotation: rotation };
+        });
+    }
+    text(index) {
+        this.#check(index);
+        return this.#call(() => toText(this.#doc.pageText(index)));
+    }
+    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.
+            const open = [];
+            for (const [title, url, level, page] of this.#doc.outline()) {
+                const item = { title, page, url: url || null, children: [] };
+                (level === 0 ? top : (open[level - 1]?.children ?? top)).push(item);
+                open[level] = item;
+            }
+            return top;
+        });
+    }
+    annotations(index) {
+        this.#check(index);
+        return this.#call(() => toAnnotations(this.#doc.annotations(index)));
+    }
+    scan(index) {
+        this.#check(index);
+        this.#needsRender();
+        return this.#call(() => consume(this.#doc.scan(index), (scan) => ({
+            text: toText(scan.takeText()),
+            objects: toObjects(scan.takeObjects()),
+            annotations: toAnnotations(scan.takeAnnotations()),
+        })));
+    }
+    textAndAnnotations(index) {
+        this.#check(index);
+        return this.#call(() => consume(this.#doc.textAndAnnotations(index), (scan) => ({
+            text: toText(scan.takeText()),
+            annotations: toAnnotations(scan.takeAnnotations()),
+        })));
+    }
+    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`);
+        }
+        this.#needsRender();
+        return this.#call(() => consume(this.#doc.render(index, options.width, maxHeight), (page) => ({
+            width: page.width,
+            height: page.height,
+            truncated: page.truncated,
+            rgba: page.takeRgba(),
+        })));
+    }
+    async renderAsync(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`);
+        }
+        this.#needsRender();
+        const instance = this.#instance;
+        const sliceMs = options.sliceMs ?? DEFAULT_SLICE_MS;
+        const task = this.#call(() => this.#doc.renderTask(index, options.width, maxHeight));
+        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) => ({
+                width: page.width,
+                height: page.height,
+                truncated: page.truncated,
+                rgba: page.takeRgba(),
+            })));
+        }
+        finally {
+            if (!instance.dead && !instance.abandoned) {
+                task.free();
+            }
+        }
+    }
+    close() {
+        if (this.#closed) {
+            return;
+        }
+        this.#closed = true;
+        this.#instance.openDocuments -= 1;
+        this.#instance.documents.open -= 1;
+        if (!this.#instance.dead && !this.#instance.abandoned) {
+            this.#doc.free();
+        }
+        this.#instance.onClose?.();
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+// A browser without Symbol.dispose yet: tools that lower `using` look for this one instead.
+Object.defineProperty(RectoDocument.prototype, Symbol.for("Symbol.dispose"), {
+    value: RectoDocument.prototype.close,
+});

package/dist/engine.d.ts

@@ -0,0 +1,62 @@
+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 = {
+    /**
+     * The directory holding the package's wasm/ files, for setups that move the package
+     * without them (a bundler that does not rewrite `new URL`, a CDN). A URL in a browser; a
+     * 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. 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;
+    /**
+     * 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?: (AssetName | "cmaps.brotli" | "fonts.bin")[];
+};
+export type PdfOpenOptions = {
+    password?: string;
+    /** Checked before the open. */
+    signal?: AbortSignal;
+};
+export type PdfEngineStats = {
+    heapBytes: number;
+    /** Increments every time the instance is replaced. heapBytes is 0 while there is none. */
+    generation: number;
+    openDocuments: number;
+};
+/** One instance per thread is enough; several documents can be open on it. */
+export interface PdfEngine {
+    /**
+     * Opens a PDF held in memory. The bytes are copied before this returns its promise, so the
+     * caller may reuse, change or transfer its buffer straight away, without waiting for it.
+     */
+    open(bytes: Uint8Array | ArrayBuffer, options?: PdfOpenOptions): Promise<PdfDocument>;
+    /**
+     * Opens a PDF read by byte range, fetching only what the engine parses. Every read of it
+     * can block this thread for a network round trip; see `timeoutMs`.
+     */
+    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:
+ *
+ *   await using doc = await openPdf(bytes);
+ *   doc.pageCount; doc.text(0); doc.render(0, { width: 1024 });
+ */
+export declare function openPdf(bytes: Uint8Array | ArrayBuffer, options?: PdfOpenOptions): Promise<PdfDocument>;