@2018kguo/recto 0.1.0 → 0.5.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

@@ -170,6 +170,29 @@ export type PdfRenderOptions = {
     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;
+    /**
+     * Draws only this part of the page: x, y, width, height in points in the viewer frame, as text and
+     * annotation boxes are (top-left origin, `/Rotate` and the crop box applied). The bitmap holds the
+     * pixels of the whole page's bitmap at the scale `width` and `maxHeight` give that this covers,
+     * grown out to whole pixels and cut to the page, and says where they are. With a region the limits
+     * are on the region's bitmap, not the page's, and `width` may be up to 262,144.
+     */
+    region?: PdfBox;
+};
+/** A render of a region: where its pixels are in the whole page's bitmap at that scale. */
+export type PdfRegionBitmap = PdfBitmap & {
+    /** The bitmap's top-left pixel, in the whole page's bitmap. */
+    x: number;
+    y: number;
+    /** The whole page's bitmap's size at this scale: what `render` without a region and its limits would give. */
+    pageWidth: number;
+    pageHeight: 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;
@@ -182,6 +205,67 @@ export type PdfBitmap = {
      */
     truncated: boolean;
 };
+/** Where a link in this file goes: a page, and the place on it in that page's viewer frame. */
+export type PdfDestination = {
+    /** The page's index, or -1 if it goes nowhere in this file. */
+    page: number;
+    /**
+     * How to show the page, as the file names it: "XYZ", "Fit", "FitH", "FitV", "FitR", "FitB", "FitBH",
+     * "FitBV"; null if it names none.
+     */
+    view: string | null;
+    /**
+     * The point to bring to the window's top-left, in points in the target page's viewer frame
+     * (top-left origin, its `/Rotate` and crop box applied). null for a coordinate the destination leaves
+     * as it was; under a quarter turn, the page's `left` is the viewer's `y`.
+     */
+    x: number | null;
+    y: number | null;
+    /** "XYZ"'s zoom, 1 for 100%; null to leave it as it was. */
+    zoom: number | null;
+    /** "FitR"'s rectangle, in the target page's viewer frame; null for any other view. */
+    box: PdfBox | null;
+};
+/** What a link does. Another file or a program is reported, never followed. */
+export type PdfLinkTarget = {
+    kind: "uri";
+    uri: string;
+}
+/** A `GoTo` action or the link's `/Dest`, named destinations resolved. */
+ | {
+    kind: "page";
+    destination: PdfDestination;
+}
+/** `GoToR`: a destination in another file, by name or by page number there. */
+ | {
+    kind: "remote";
+    file: string;
+    name: string | null;
+    page: number | null;
+}
+/** `Launch`: a file or program. */
+ | {
+    kind: "launch";
+    file: string;
+}
+/** Any other action by its `/S` ("JavaScript", "SubmitForm", ...); a `Named` action's `/N` ("NextPage", ...) is `name`. */
+ | {
+    kind: "action";
+    action: string;
+    name: string | null;
+}
+/** No action and no destination. */
+ | {
+    kind: "none";
+};
+/** A `/Link` annotation and where it goes. */
+export type PdfLink = {
+    /** Its index in what `annotations` returns for the page. */
+    annotation: number;
+    /** Its `/Rect` in the viewer frame, as its annotation's `box`. */
+    box: PdfBox;
+    target: PdfLinkTarget;
+};
 export declare const ANNOT_SUBTYPE: {
     readonly text: 1;
     readonly link: 2;
@@ -204,6 +288,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. */
@@ -219,17 +315,46 @@ export interface PdfDocument {
     };
     objects(index: number): PdfPageObjects;
     annotations(index: number): PdfAnnotation[];
+    /**
+     * The page's links, in the order `annotations` lists them, and where each goes. Loads drawing's
+     * part of the wasm, as `objects` does.
+     */
+    links(index: number): PdfLink[];
+    render(index: number, options: PdfRenderOptions & {
+        region: PdfBox;
+    }): PdfRegionBitmap;
     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 & {
+        region: PdfBox;
+    }): Promise<PdfRegionBitmap>;
+    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,12 +365,22 @@ 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[];
+    links(index: number): PdfLink[];
     scan(index: number): {
         text: PdfPageText;
         objects: PdfPageObjects;
@@ -255,7 +390,14 @@ export declare class RectoDocument implements PdfDocument {
         text: PdfPageText;
         annotations: PdfAnnotation[];
     };
+    render(index: number, options: PdfRenderOptions & {
+        region: PdfBox;
+    }): PdfRegionBitmap;
     render(index: number, options: PdfRenderOptions): PdfBitmap;
+    renderAsync(index: number, options: PdfRenderAsyncOptions & {
+        region: PdfBox;
+    }): Promise<PdfRegionBitmap>;
+    renderAsync(index: number, options: PdfRenderAsyncOptions): Promise<PdfBitmap>;
     close(): void;
     [Symbol.dispose](): void;
 }