@2018kguo/recto 0.0.0-stage → 0.1.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,14 @@
+import { PINS } from "../wasm/pins.mjs";
+export type AssetName = keyof typeof PINS;
+/** 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. */
+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;

package/dist/assets.js

@@ -0,0 +1,169 @@
+// 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: 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.
+import { PINS } from "../wasm/pins.mjs";
+import { PdfError } from "./errors.js";
+import { sha256Hex } from "./sha256.js";
+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 "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);
+    }
+}
+/** 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).', 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)`);
+    }
+    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);
+}
+/** The wasm's bytes, for compiling. Asynchronous where it can be. */
+export async function loadWasm(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());
+        }
+    }
+    catch (error) {
+        throw loadFailure("recto.wasm", url, error instanceof Error ? error.message : String(error), error);
+    }
+    return checked("recto.wasm", url, bytes);
+}
+/** 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. */
+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;
+            }
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            bytes = new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            throw loadFailure(name, url, error instanceof Error ? error.message : String(error), error);
+        }
+        loaded.set(url.href, checked(name, url, bytes));
+    }));
+}
+/** An asset, read synchronously. Throws a PdfError rather than returning nothing. */
+export function loadAssetSync(name, base) {
+    let url = null;
+    let bytes;
+    try {
+        url = assetUrl(name, base);
+        const cached = loaded.get(url.href);
+        if (cached) {
+            return cached;
+        }
+        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);
+    }
+    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));
+}

package/dist/document.d.ts

@@ -0,0 +1,261 @@
+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 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[];
+    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;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+export type Instance = {
+    glue: ReturnType<typeof createGlue>;
+    memory: WebAssembly.Memory;
+    generation: number;
+    openDocuments: number;
+    /** Set once the instance trapped or an asset failed; nothing may call it again. */
+    dead: 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, fetchFailure?: () => PdfError | null);
+    pageInfo(index: number): PdfPageInfo;
+    text(index: number): PdfPageText;
+    objects(index: number): PdfPageObjects;
+    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;
+    close(): void;
+    [Symbol.dispose](): void;
+}