@2018kguo/recto 0.1.0 → 0.3.0

package/dist/assets.d.ts

@@ -1,14 +1,19 @@
 import { PINS } from "../wasm/pins.mjs";
 export type AssetName = keyof typeof PINS;
+export type WasmName = "recto.wasm" | "recto-render.wasm" | "recto-more.wasm" | "recto-rare.wasm";
+/** The standard fonts, in the order the wasm asks for them (`font_index` in crates/recto/src/assets.rs). */
+export declare const STANDARD_FONTS: readonly ["FoxitFixed.pfb", "FoxitFixedBold.pfb", "FoxitFixedBoldItalic.pfb", "FoxitFixedItalic.pfb", "FoxitSans.pfb", "FoxitSansBold.pfb", "FoxitSansBoldItalic.pfb", "FoxitSansItalic.pfb", "FoxitSerif.pfb", "FoxitSerifBold.pfb", "FoxitSerifBoldItalic.pfb", "FoxitSerifItalic.pfb", "FoxitSymbol.pfb", "FoxitDingbats.pfb"];
 /** Whether an asset can be read at the moment the engine asks for it. */
 export declare function canReadSync(): boolean;
 /** `assetBase` as a directory URL, or null for the package's own files. */
 export declare function assetBaseUrl(base: string | URL | undefined): URL | null;
-/** The wasm's bytes, for compiling. Asynchronous where it can be. */
-export declare function loadWasm(base: URL | null): Promise<Uint8Array<ArrayBuffer>>;
-/** Fetches assets ahead of time, for a thread that can't read them when they're needed. */
+/** A hash to use where there is no native one to call synchronously. A live instance's is quicker than this file's. */
+export type SyncHash = (bytes: Uint8Array) => string | null;
+/** The wasm, verified and then compiled. */
+export declare function compileWasm(name: WasmName, base: URL | null): Promise<WebAssembly.Module>;
+/** Fetches and verifies assets ahead of time; a thread that can't read them when needed has to. */
 export declare function preloadAssets(base: URL | null, names: AssetName[]): Promise<void>;
 /** An asset, read synchronously. Throws a PdfError rather than returning nothing. */
-export declare function loadAssetSync(name: AssetName, base: URL | null): Uint8Array;
-/** Entry `index` of fonts.bin: u32 count, u32 offsets[count + 1], bytes (little-endian). */
-export declare function fontFromBundle(bundle: Uint8Array, index: number): Uint8Array;
+export declare function loadAssetSync(name: AssetName, base: URL | null, hash?: SyncHash): Uint8Array;
+/** A file, read now and hashed before it's returned, and not kept: a part is compiled once. */
+export declare function readCheckedSync(name: AssetName, base: URL | null, hash?: SyncHash): Uint8Array;

package/dist/assets.js

@@ -8,21 +8,72 @@
 // are written out as `new URL("literal", import.meta.url)` because that is the form
 // bundlers recognise and rewrite, emitting the file.
 //
-// Each file is pinned by SHA-256: the engine reads its tables as trusted, and a dev server's
-// HTML fallback page must not read as a font. pins.mjs is written by the build.
+// Each file is pinned by SHA-256 and hashed here, every byte, before it's used: the engine reads
+// its tables as trusted, and a dev server's HTML fallback page must not read as a font. Nothing is
+// left to `fetch`'s `integrity`, which a wrapper around `fetch` can drop, and which buffers the
+// body anyway. pins.mjs is written by the build.
 import { PINS } from "../wasm/pins.mjs";
 import { PdfError } from "./errors.js";
 import { sha256Hex } from "./sha256.js";
+/** The standard fonts, in the order the wasm asks for them (`font_index` in crates/recto/src/assets.rs). */
+export const STANDARD_FONTS = [
+    "FoxitFixed.pfb",
+    "FoxitFixedBold.pfb",
+    "FoxitFixedBoldItalic.pfb",
+    "FoxitFixedItalic.pfb",
+    "FoxitSans.pfb",
+    "FoxitSansBold.pfb",
+    "FoxitSansBoldItalic.pfb",
+    "FoxitSansItalic.pfb",
+    "FoxitSerif.pfb",
+    "FoxitSerifBold.pfb",
+    "FoxitSerifBoldItalic.pfb",
+    "FoxitSerifItalic.pfb",
+    "FoxitSymbol.pfb",
+    "FoxitDingbats.pfb",
+];
 function packagedUrl(name) {
     switch (name) {
         case "recto.wasm":
             return new URL("../wasm/recto.wasm", import.meta.url);
-        case "fonts.bin":
-            return new URL("../wasm/fonts.bin", import.meta.url);
+        case "recto-render.wasm":
+            return new URL("../wasm/recto-render.wasm", import.meta.url);
+        case "recto-more.wasm":
+            return new URL("../wasm/recto-more.wasm", import.meta.url);
+        case "recto-rare.wasm":
+            return new URL("../wasm/recto-rare.wasm", import.meta.url);
+        case "FoxitFixed.pfb":
+            return new URL("../wasm/FoxitFixed.pfb", import.meta.url);
+        case "FoxitFixedBold.pfb":
+            return new URL("../wasm/FoxitFixedBold.pfb", import.meta.url);
+        case "FoxitFixedBoldItalic.pfb":
+            return new URL("../wasm/FoxitFixedBoldItalic.pfb", import.meta.url);
+        case "FoxitFixedItalic.pfb":
+            return new URL("../wasm/FoxitFixedItalic.pfb", import.meta.url);
+        case "FoxitSans.pfb":
+            return new URL("../wasm/FoxitSans.pfb", import.meta.url);
+        case "FoxitSansBold.pfb":
+            return new URL("../wasm/FoxitSansBold.pfb", import.meta.url);
+        case "FoxitSansBoldItalic.pfb":
+            return new URL("../wasm/FoxitSansBoldItalic.pfb", import.meta.url);
+        case "FoxitSansItalic.pfb":
+            return new URL("../wasm/FoxitSansItalic.pfb", import.meta.url);
+        case "FoxitSerif.pfb":
+            return new URL("../wasm/FoxitSerif.pfb", import.meta.url);
+        case "FoxitSerifBold.pfb":
+            return new URL("../wasm/FoxitSerifBold.pfb", import.meta.url);
+        case "FoxitSerifBoldItalic.pfb":
+            return new URL("../wasm/FoxitSerifBoldItalic.pfb", import.meta.url);
+        case "FoxitSerifItalic.pfb":
+            return new URL("../wasm/FoxitSerifItalic.pfb", import.meta.url);
+        case "FoxitSymbol.pfb":
+            return new URL("../wasm/FoxitSymbol.pfb", import.meta.url);
+        case "FoxitDingbats.pfb":
+            return new URL("../wasm/FoxitDingbats.pfb", import.meta.url);
         case "cjk-fallback.ttf":
             return new URL("../wasm/cjk-fallback.ttf", import.meta.url);
-        case "cmaps.brotli":
-            return new URL("../wasm/cmaps.brotli", import.meta.url);
+        case "cmaps.deflate":
+            return new URL("../wasm/cmaps.deflate", import.meta.url);
     }
 }
 /** A stalled server must not block the thread for ever; the largest asset is 5 MB. */
@@ -71,11 +122,16 @@ function loadFailure(name, url, reason, cause) {
     return new PdfError("missing-asset", `recto could not load ${name}${url ? ` from ${url.href}` : ""}: ${reason}. It ships in the package's wasm/ ` +
         "directory. If a bundler or dev server moved the package without its files, copy them " +
         "somewhere it serves and pass that directory as `assetBase` (with Vite's dev server, add " +
-        'optimizeDeps: { exclude: ["@2018kguo/recto"] } instead).', cause);
+        'optimizeDeps: { exclude: ["@2018kguo/recto"] } instead; a server bundle should keep the package external).', cause);
 }
-function checked(name, url, bytes) {
-    if (sha256Hex(bytes) !== PINS[name]) {
-        throw loadFailure(name, url, `the ${bytes.byteLength} bytes there are not this build's file (a server's fallback page, or a different version of the package)`);
+function notThisBuild(name, url, bytes) {
+    return loadFailure(name, url, `the ${bytes.byteLength} bytes there are not this build's file (a server's fallback page, or a different version of the package)`);
+}
+function checked(name, url, bytes, hash) {
+    const crypto = globalThis.process?.getBuiltinModule?.("node:crypto");
+    const hex = crypto ? crypto.createHash("sha256").update(bytes).digest("hex") : (hash?.(bytes) ?? sha256Hex(bytes));
+    if (hex !== PINS[name]) {
+        throw notThisBuild(name, url, bytes);
     }
     return bytes;
 }
@@ -93,32 +149,52 @@ function readSync(url) {
     }
     return new Uint8Array(xhr.response);
 }
-/** The wasm's bytes, for compiling. Asynchronous where it can be. */
-export async function loadWasm(base) {
+/** `crypto.subtle` is only there in a secure context; a plain-http page hashes here. */
+async function hashOf(bytes) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        return sha256Hex(bytes);
+    }
+    const digest = new Uint8Array(await subtle.digest("SHA-256", bytes));
+    return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The only way bytes get here from a network without blocking: whole, and hashed before they're used. */
+async function fetchBytes(name, url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if ((await hashOf(bytes)) !== PINS[name]) {
+        throw notThisBuild(name, url, bytes);
+    }
+    return bytes;
+}
+/** The wasm, verified and then compiled. */
+export async function compileWasm(name, base) {
     let url = null;
     let bytes;
     try {
         // Inside the try: under a blob: worker `import.meta.url` is no base for a URL.
-        url = assetUrl("recto.wasm", base);
-        if (nodeFs()) {
-            bytes = readFromDisk(url);
-        }
-        else {
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
-            }
-            bytes = new Uint8Array(await response.arrayBuffer());
-        }
+        url = assetUrl(name, base);
+        bytes = (nodeFs() ? checked(name, url, readFromDisk(url)) : await fetchBytes(name, url));
     }
     catch (error) {
-        throw loadFailure("recto.wasm", url, error instanceof Error ? error.message : String(error), error);
+        if (error instanceof PdfError) {
+            throw error;
+        }
+        throw loadFailure(name, url, error instanceof Error ? error.message : String(error), error);
     }
-    return checked("recto.wasm", url, bytes);
+    return await compiling(name, WebAssembly.compile(bytes));
+}
+function compiling(name, module) {
+    return module.catch((error) => {
+        throw new PdfError("missing-asset", `recto could not compile ${name}: ${String(error)}. A Content-Security-Policy must allow 'wasm-unsafe-eval'.`, error);
+    });
 }
 /** Verified assets by URL: hash and read each once per thread. */
 const loaded = new Map();
-/** Fetches assets ahead of time, for a thread that can't read them when they're needed. */
+/** Fetches and verifies assets ahead of time; a thread that can't read them when needed has to. */
 export async function preloadAssets(base, names) {
     await Promise.all(names.map(async (name) => {
         let url = null;
@@ -128,28 +204,40 @@ export async function preloadAssets(base, names) {
             if (loaded.has(url.href)) {
                 return;
             }
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
-            }
-            bytes = new Uint8Array(await response.arrayBuffer());
+            bytes = nodeFs() ? checked(name, url, readFromDisk(url)) : await fetchBytes(name, url);
         }
         catch (error) {
+            if (error instanceof PdfError) {
+                throw error;
+            }
             throw loadFailure(name, url, error instanceof Error ? error.message : String(error), error);
         }
-        loaded.set(url.href, checked(name, url, bytes));
+        loaded.set(url.href, bytes);
     }));
 }
 /** An asset, read synchronously. Throws a PdfError rather than returning nothing. */
-export function loadAssetSync(name, base) {
+export function loadAssetSync(name, base, hash) {
     let url = null;
-    let bytes;
     try {
         url = assetUrl(name, base);
         const cached = loaded.get(url.href);
         if (cached) {
             return cached;
         }
+    }
+    catch (error) {
+        throw loadFailure(name, url, error instanceof Error ? error.message : String(error), error);
+    }
+    const bytes = readCheckedSync(name, base, hash);
+    loaded.set(url.href, bytes);
+    return bytes;
+}
+/** A file, read now and hashed before it's returned, and not kept: a part is compiled once. */
+export function readCheckedSync(name, base, hash) {
+    let url = null;
+    let bytes;
+    try {
+        url = assetUrl(name, base);
         if (!canReadSync()) {
             throw new Error("this thread can only use assets fetched up front, and it was left out of preloadAssets");
         }
@@ -158,12 +246,5 @@ export function loadAssetSync(name, base) {
     catch (error) {
         throw loadFailure(name, url, error instanceof Error ? error.message : String(error), error);
     }
-    loaded.set(url.href, checked(name, url, bytes));
-    return bytes;
-}
-/** Entry `index` of fonts.bin: u32 count, u32 offsets[count + 1], bytes (little-endian). */
-export function fontFromBundle(bundle, index) {
-    const view = new DataView(bundle.buffer, bundle.byteOffset, bundle.byteLength);
-    const base = 4 + (view.getUint32(0, true) + 1) * 4;
-    return bundle.subarray(base + view.getUint32(4 + index * 4, true), base + view.getUint32(8 + index * 4, true));
+    return checked(name, url, bytes, hash);
 }

package/dist/document.d.ts

@@ -171,6 +171,12 @@ export type PdfRenderOptions = {
     /** Default 4096. May be Infinity, to fit the width alone. A render is capped at 16,384 px a side and 64 Mpx. */
     maxHeight?: number;
 };
+export type PdfRenderAsyncOptions = PdfRenderOptions & {
+    /** Stops the render at the next pause: `aborted`, with the document still usable. */
+    signal?: AbortSignal;
+    /** About how long it runs before giving the thread back. Default 8. */
+    sliceMs?: number;
+};
 export type PdfBitmap = {
     width: number;
     height: number;
@@ -204,6 +210,18 @@ export interface PdfDocument {
     readonly pageCount: number;
     /** The document's bookmarks; empty if it has none. */
     outline(): PdfOutlineItem[];
+    /** What each page is called, one string per page ("iv", "A-5"), or null if the file doesn't say. */
+    pageLabels(): string[] | null;
+    /**
+     * Which of the document's trees were cut short: `pages` means `pageCount` may be short, by a limit or
+     * because a damaged tree left no pages (an honestly empty document says false). `pageLabels` and `outline`
+     * mean those passed a limit, and may be wrong or incomplete. A page's own limits are `truncated` on its results.
+     */
+    structureTruncated(): {
+        pages: boolean;
+        pageLabels: boolean;
+        outline: boolean;
+    };
     pageInfo(index: number): PdfPageInfo;
     text(index: number): PdfPageText;
     /** `text`, `objects` and `annotations` from one interpretation of the page. */
@@ -220,16 +238,34 @@ export interface PdfDocument {
     objects(index: number): PdfPageObjects;
     annotations(index: number): PdfAnnotation[];
     render(index: number, options: PdfRenderOptions): PdfBitmap;
+    /**
+     * The same pixels as `render`, giving the thread back between slices, and stoppable with a
+     * signal. The last step, rasterizing, is one piece: about a third of a heavy page's time.
+     */
+    renderAsync(index: number, options: PdfRenderAsyncOptions): Promise<PdfBitmap>;
     close(): void;
     [Symbol.dispose](): void;
 }
 export type Instance = {
     glue: ReturnType<typeof createGlue>;
+    /** Loads a part of the wasm, hashed first, or throws `missing-asset` having changed nothing. */
+    loadPart(name: "recto-render.wasm" | "recto-more.wasm" | "recto-rare.wasm"): void;
     memory: WebAssembly.Memory;
+    /** Its memory when it was made: past this, something used it, and dropping it gives memory back. */
+    startBytes: number;
     generation: number;
     openDocuments: number;
-    /** Set once the instance trapped or an asset failed; nothing may call it again. */
+    /** The engine's count of documents open, on any of its instances. */
+    documents: {
+        open: number;
+    };
+    /** Set once the instance trapped; nothing may call it again. */
     dead: boolean;
+    /**
+     * Set once a part or asset failed to load inside a call. Nothing more runs on it, but a document's
+     * file is still whole there, so it reopens on another instance at its next call.
+     */
+    abandoned: boolean;
     /** An asset's load failure, rethrown by the call that needed the asset. */
     failure: PdfError | undefined;
     /** Called when a document on this instance closes. */
@@ -240,10 +276,19 @@ export declare function engineFailure(instance: Instance, error: unknown): unkno
 export declare class RectoDocument implements PdfDocument {
     #private;
     readonly pageCount: number;
-    constructor(instance: Instance, doc: Glue.Document, fetchFailure?: () => PdfError | null);
+    constructor(instance: Instance, doc: Glue.Document, reopen: (doc: Glue.Document, instance: Instance) => {
+        instance: Instance;
+        doc: Glue.Document;
+    }, fetchFailure?: () => PdfError | null);
     pageInfo(index: number): PdfPageInfo;
     text(index: number): PdfPageText;
     objects(index: number): PdfPageObjects;
+    pageLabels(): string[] | null;
+    structureTruncated(): {
+        pages: boolean;
+        pageLabels: boolean;
+        outline: boolean;
+    };
     outline(): PdfOutlineItem[];
     annotations(index: number): PdfAnnotation[];
     scan(index: number): {
@@ -256,6 +301,7 @@ export declare class RectoDocument implements PdfDocument {
         annotations: PdfAnnotation[];
     };
     render(index: number, options: PdfRenderOptions): PdfBitmap;
+    renderAsync(index: number, options: PdfRenderAsyncOptions): Promise<PdfBitmap>;
     close(): void;
     [Symbol.dispose](): void;
 }

package/dist/document.js

@@ -167,19 +167,35 @@ function toAnnotations(a) {
         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, 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 +204,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 +234,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 +267,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.
@@ -252,6 +308,7 @@ export class RectoDocument {
     }
     scan(index) {
         this.#check(index);
+        this.#needsRender();
         return this.#call(() => consume(this.#doc.scan(index), (scan) => ({
             text: toText(scan.takeText()),
             objects: toObjects(scan.takeObjects()),
@@ -272,6 +329,7 @@ export class RectoDocument {
             !(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,
@@ -279,13 +337,60 @@ export class RectoDocument {
             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;
-        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,22 @@ 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.
+     * 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 +50,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: