@2018kguo/recto 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Kevin Guo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+vendor/ holds patched copies of the hayro crates, MIT or Apache-2.0 licensed by
+their authors; see vendor/README.md and each crate's licence files. The shipped
+fonts and CMaps have their own licences, gathered in js/wasm/THIRD_PARTY_NOTICES
+by the build.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @2018kguo/recto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A PDF engine for JavaScript: text with positions, page objects and rendering, in Rust compiled
+to WebAssembly. No runtime dependencies and no install scripts; the built wasm ships in this
+package, so you don't need Rust.
+
+```js
+import { readFile } from "node:fs/promises";
+import { openPdf } from "@2018kguo/recto";
+
+const bytes = await readFile("report.pdf");
+await using doc = await openPdf(bytes);
+doc.pageCount;
+doc.text(0).text;
+const { width, height, rgba } = doc.render(0, { width: 1024 });
+```
+
+Calls run synchronously on the calling thread, so put heavy work on a `worker_threads` worker. In
+a browser, use a dedicated Web Worker: `import` it there and call `openPdf`. Nothing else is
+needed. It also runs on a page's main thread and in a service worker, where it fetches its assets
+up front, but a main thread freezes for the length of each call.
+
+[Documentation](https://github.com/2018kguo/recto#readme) ·
+[Reference](https://github.com/2018kguo/recto/blob/main/docs/reference.md)
+
+MIT. The bundled fonts and CMaps have their own licences: see `wasm/THIRD_PARTY_NOTICES`.

package/dist/assets.d.ts

@@ -0,0 +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;
+/** 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, 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

@@ -0,0 +1,250 @@
+// The files in ../wasm: where they are, how to read them, and the check that they are the
+// ones this build was made with.
+//
+// The engine asks for a font or CMap from inside a synchronous call, the first time a
+// document needs one, so reading must be synchronous too: fs in Node, a synchronous
+// XMLHttpRequest in a Web Worker. A page's main thread may not fetch bytes synchronously, and a
+// service worker has no XMLHttpRequest, so there they are fetched up front instead. The URLs
+// 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 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 "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.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. */
+const ASSET_TIMEOUT_MS = 60_000;
+/** Node's fs when there is one. `getBuiltinModule` keeps bundlers from following it. */
+function nodeFs() {
+    return globalThis.process?.getBuiltinModule?.("node:fs");
+}
+/** Whether an asset can be read at the moment the engine asks for it. */
+export function canReadSync() {
+    if (nodeFs()) {
+        return true;
+    }
+    return typeof document === "undefined" && typeof XMLHttpRequest !== "undefined";
+}
+/** `assetBase` as a directory URL, or null for the package's own files. */
+export function assetBaseUrl(base) {
+    if (base === undefined) {
+        return null;
+    }
+    let url;
+    if (base instanceof URL) {
+        url = new URL(base);
+    }
+    else if (/^[a-z][a-z0-9+.-]+:/iu.test(base)) {
+        url = new URL(base);
+    }
+    else if (nodeFs()) {
+        url = globalThis.process.getBuiltinModule("node:url").pathToFileURL(base);
+    }
+    else {
+        url = new URL(base, location.href);
+    }
+    if (!url.pathname.endsWith("/")) {
+        url.pathname += "/";
+    }
+    if (nodeFs() && url.protocol !== "file:") {
+        throw new TypeError("In Node, assetBase must be a directory path or a file: URL: the engine reads fonts synchronously.");
+    }
+    return url;
+}
+function assetUrl(name, base) {
+    return base ? new URL(name, base) : packagedUrl(name);
+}
+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; a server bundle should keep the package external).', cause);
+}
+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;
+}
+function readFromDisk(url) {
+    return nodeFs().readFileSync(url);
+}
+function readSync(url) {
+    const xhr = new XMLHttpRequest();
+    xhr.open("GET", url.href, false);
+    xhr.responseType = "arraybuffer";
+    xhr.timeout = ASSET_TIMEOUT_MS;
+    xhr.send();
+    if (xhr.status !== 200) {
+        throw new Error(`HTTP ${xhr.status}`);
+    }
+    return new Uint8Array(xhr.response);
+}
+/** `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(name, base);
+        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);
+    }
+    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 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;
+        let bytes;
+        try {
+            url = assetUrl(name, base);
+            if (loaded.has(url.href)) {
+                return;
+            }
+            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, bytes);
+    }));
+}
+/** An asset, read synchronously. Throws a PdfError rather than returning nothing. */
+export function loadAssetSync(name, base, hash) {
+    let url = null;
+    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");
+        }
+        bytes = nodeFs() ? readFromDisk(url) : readSync(url);
+    }
+    catch (error) {
+        throw loadFailure(name, url, error instanceof Error ? error.message : String(error), error);
+    }
+    return checked(name, url, bytes, hash);
+}

package/dist/document.d.ts

@@ -0,0 +1,307 @@
+import type { createGlue } from "../wasm/recto.gen.mjs";
+import type * as Glue from "../wasm/recto.types.mjs";
+import { PdfError } from "./errors.ts";
+export type PdfBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type PdfPageInfo = {
+    width: number;
+    height: number;
+    rotation: 0 | 90 | 180 | 270;
+};
+export type PdfFont = {
+    name: string;
+    /** PDF font descriptor flags (fixed pitch, serif, symbolic, italic, ...). */
+    flags: number;
+    /** 100 to 900 as the file states it, or as its name says; 0 where it says nothing. */
+    weight: number;
+    embedded: boolean;
+    /** Top of this font's char boxes, in ems above the baseline: the descriptor's, or 0.8. */
+    ascent: number;
+    /** Bottom of this font's char boxes, in ems (negative): the descriptor's, or -0.2. */
+    descent: number;
+};
+/** `PdfPageText.flags` bit: a space or line break the engine inferred; not in the content stream. */
+export declare const CHAR_GENERATED = 1;
+/** `PdfPageText.flags` bit: the glyph has no Unicode mapping, so its text is unreadable. */
+export declare const CHAR_UNMAPPED = 2;
+/**
+ * A page's characters as columns (structure of arrays): char `i` is entry
+ * `i` of every column, and entries `4i..4i+3` of `boxes`. Typed arrays, so
+ * a page crosses a thread boundary by transfer, not by copying objects.
+ */
+export type PdfPageText = {
+    /** The whole page's text, generated spaces included. */
+    text: string;
+    count: number;
+    /** Unicode code points (U+FFFD where a glyph's code is no scalar value). */
+    codepoints: Uint32Array<ArrayBuffer>;
+    /** x, y, width, height per char: the advance by the font's ascent and descent, not glyph ink. */
+    boxes: Float32Array<ArrayBuffer>;
+    /** The size each char is drawn at, in points: `Tf` scaled by the text and page matrices. */
+    fontSizes: Float32Array<ArrayBuffer>;
+    /** The `Tf` operand each char was shown with, unscaled. */
+    tfSizes: Float32Array<ArrayBuffer>;
+    /** Radians, counter-clockwise. */
+    angles: Float32Array<ArrayBuffer>;
+    /** Fill colour as 0xRRGGBBAA. */
+    fills: Uint32Array<ArrayBuffer>;
+    /** Index into `fonts`; -1 for characters the engine generated. */
+    fontIds: Int32Array<ArrayBuffer>;
+    /** CHAR_GENERATED | CHAR_UNMAPPED. */
+    flags: Uint8Array<ArrayBuffer>;
+    /** One per font dictionary used on the page. */
+    fonts: PdfFont[];
+    /** The page showed more glyphs than one page may collect (2^19); the rest aren't here. */
+    truncated: boolean;
+    /** Runs of non-space chars in content order, as char ranges and boxes. */
+    words: PdfWords;
+    /**
+     * Index into `runs` per char: the text object (one show-text operator)
+     * the char was drawn by; -1 for chars the engine generated.
+     */
+    runIds: Int32Array<ArrayBuffer>;
+    runs: PdfTextRuns;
+};
+/**
+ * One entry per text object, in the order its chars first appear: where
+ * its text starts and how large it is drawn. Every char of a run sits on
+ * the run's baseline (a rise or a new line starts a new text object).
+ */
+export type PdfTextRuns = {
+    count: number;
+    /** x, y per run: the text origin on the baseline, in the viewer frame. */
+    origins: Float32Array<ArrayBuffer>;
+    /** The font size as drawn, in points (Tf scaled by the text and current matrices). */
+    ems: Float32Array<ArrayBuffer>;
+};
+export type PdfWords = {
+    count: number;
+    /** First and last char index of each word, inclusive. */
+    firstChar: Uint32Array<ArrayBuffer>;
+    lastChar: Uint32Array<ArrayBuffer>;
+    /** x, y, width, height per word: the union of its char boxes. */
+    boxes: Float32Array<ArrayBuffer>;
+};
+/** Entry `i` of a `boxes` column. */
+export declare function boxAt(boxes: Float32Array, i: number): PdfBox;
+/** The text of chars `first..last` (inclusive). */
+export declare function charsText(page: Pick<PdfPageText, "codepoints">, first: number, last: number): string;
+/** Segment kinds, in the low bits of `PdfPathSegments.kinds`. */
+export declare const SEGMENT_LINE = 0;
+export declare const SEGMENT_BEZIER = 1;
+export declare const SEGMENT_MOVE = 2;
+/** `PdfPathSegments.kinds` bit: the segment closes its subpath. */
+export declare 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 declare const SEGMENT_RECT = 8;
+/** `paths.flags` bits. */
+export declare const PATH_FILL = 1;
+export declare const PATH_STROKE = 2;
+/** All paths' segments end to end; path `i` owns `start[i]..start[i+1]`. */
+export type PdfPathSegments = {
+    count: number;
+    /** x, y per segment end point, in the viewer frame. */
+    points: Float32Array<ArrayBuffer>;
+    /** SEGMENT_LINE | SEGMENT_BEZIER | SEGMENT_MOVE, plus SEGMENT_CLOSE and SEGMENT_RECT. */
+    kinds: Uint8Array<ArrayBuffer>;
+};
+/**
+ * A page's images and paths as columns. Form XObjects are flattened, their
+ * transforms applied; every box and point is in the viewer frame.
+ */
+export type PdfPageObjects = {
+    textObjects: number;
+    /** The page held more than one page may collect (2^21 path segments, 2^19 images); the rest aren't here. */
+    truncated: boolean;
+    images: {
+        count: number;
+        /** x, y, width, height per image. */
+        boxes: Float32Array<ArrayBuffer>;
+        /** Pixel width, height per image (0, 0 when the engine cannot say). */
+        pixels: Uint32Array<ArrayBuffer>;
+    };
+    paths: {
+        count: number;
+        /** x, y, width, height per path. */
+        boxes: Float32Array<ArrayBuffer>;
+        /** PATH_FILL | PATH_STROKE. */
+        flags: Uint8Array<ArrayBuffer>;
+        /** count + 1 offsets into `segments`. */
+        start: Uint32Array<ArrayBuffer>;
+    };
+    segments: PdfPathSegments;
+};
+export type PdfAnnotation = {
+    subtype: number;
+    box: PdfBox;
+    /** /Contents (a FreeText's text; a note for most other kinds); "" when absent. */
+    contents: string;
+    /**
+     * A widget's form field: its type (/FT: "Tx", "Ch", "Btn", "Sig") and
+     * value (/V, both inherited through /Parent); null for other annotations.
+     * A multi-select choice field's /V array reads as "".
+     */
+    field: {
+        type: string;
+        value: string;
+    } | null;
+    /**
+     * Objects in the annotation's normal appearance, and how many of them are
+     * text: a stamp that paints words has text objects. 0 without an
+     * appearance.
+     */
+    appearanceObjects: number;
+    appearanceTextObjects: number;
+    /**
+     * The text the appearance's text objects paint, one object a line (a
+     * stamp's words, a list box's options), each line trimmed.
+     */
+    appearanceText: string;
+};
+export type PdfRenderOptions = {
+    /** Target width in pixels; the scale also keeps height within `maxHeight`. */
+    width: number;
+    /** 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;
+    /** Opaque RGBA on a white background, four bytes a pixel. */
+    rgba: Uint8Array<ArrayBuffer>;
+    /**
+     * The page passed a limit on what one render may do (more than 32 groups that need the page
+     * redrawn under them), so past that those groups are drawn as if isolated.
+     */
+    truncated: boolean;
+};
+export declare const ANNOT_SUBTYPE: {
+    readonly text: 1;
+    readonly link: 2;
+    readonly freeText: 3;
+    readonly stamp: 13;
+    readonly widget: 20;
+};
+/**
+ * An open PDF. Every call is synchronous CPU work on this thread. Closing is idempotent, and
+ * every other method throws a PdfError with code "closed" afterwards.
+ */
+/** A bookmark. `page` is -1 if it goes nowhere in this file; `url` is set if it links out. */
+export type PdfOutlineItem = {
+    title: string;
+    page: number;
+    url: string | null;
+    children: PdfOutlineItem[];
+};
+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. */
+    scan(index: number): {
+        text: PdfPageText;
+        objects: PdfPageObjects;
+        annotations: PdfAnnotation[];
+    };
+    /** `text` and `annotations` from one interpretation of the page. */
+    textAndAnnotations(index: number): {
+        text: PdfPageText;
+        annotations: PdfAnnotation[];
+    };
+    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;
+    /** 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. */
+    onClose?: () => void;
+};
+/** What a call into the instance threw, as what the caller should see. */
+export declare function engineFailure(instance: Instance, error: unknown): unknown;
+export declare class RectoDocument implements PdfDocument {
+    #private;
+    readonly pageCount: number;
+    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): {
+        text: PdfPageText;
+        objects: PdfPageObjects;
+        annotations: PdfAnnotation[];
+    };
+    textAndAnnotations(index: number): {
+        text: PdfPageText;
+        annotations: PdfAnnotation[];
+    };
+    render(index: number, options: PdfRenderOptions): PdfBitmap;
+    renderAsync(index: number, options: PdfRenderAsyncOptions): Promise<PdfBitmap>;
+    close(): void;
+    [Symbol.dispose](): void;
+}