@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.3

package/dist/source/http.js

@@ -0,0 +1,211 @@
+// httpRangeSource: a remote PDF read with HTTP Range requests. Errors never carry the URL
+// (ADR 0026 §4): it may hold tokens.
+import { packageError } from "../errors.js";
+import { WHOLE } from "./range.js";
+/** `bytes start-end/size` → its numbers. */
+function contentRange(header) {
+    const m = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(header?.trim() ?? "");
+    if (m === null)
+        return undefined;
+    return { start: Number(m[1]), end: Number(m[2]), size: Number(m[3]) };
+}
+function failed(reason, status, cause) {
+    const e = packageError("fetch-failed", "fetching a range of the remote file failed", {
+        data: status === undefined ? { reason } : { reason, status },
+    });
+    if (cause !== undefined)
+        Object.defineProperty(e, "cause", { value: cause });
+    return e;
+}
+function changed() {
+    return packageError("source-changed", "the remote file changed while it was being read");
+}
+/**
+ * A {@link RangeSource} over a URL, for `Document.openRange`. The first request asks for the
+ * last `tail` bytes, which gives the size and the part of the file a reader needs first (the
+ * xref is at the end). Every later request sends `If-Range` with the first strong `ETag` (else
+ * its `Last-Modified`); a response whose `ETag`, `Last-Modified` or total size differs fails
+ * with `source-changed`. A server that ignores
+ * `Range` (it answers `200`) is read with that one full download.
+ *
+ * The server must allow `Range` (across origins: `Access-Control-Allow-Headers: Range` and
+ * `Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`) and must not compress
+ * the response.
+ *
+ * @param url - the file.
+ * @param options - headers, credentials, signal, block size.
+ * @returns the source, once the first request has answered.
+ * @throws {@link LaminaPdfError} `fetch-failed` (with `data.status`), `source-changed`.
+ */
+export async function httpRangeSource(url, options = {}) {
+    // A whole number of bytes, at least 1 (a fraction would make a malformed Range header).
+    const tail = Number.isFinite(options.tail) ? Math.max(1, Math.floor(options.tail ?? 0)) : 65_536;
+    const request = rangeRequester(url, options);
+    const first = await request(`bytes=-${tail}`, options.signal);
+    if (first.status === 200) {
+        // No range support: this response is the whole file.
+        const whole = new Uint8Array(await first.arrayBuffer());
+        // Tagged, so Document.openRange opens these bytes directly instead of copying them again.
+        return {
+            size: whole.length,
+            read: async (offset, length) => whole.slice(offset, offset + length),
+            [WHOLE]: whole,
+        };
+    }
+    if (first.status === 416 && /^bytes \*\/0$/.test(first.headers.get("Content-Range")?.trim() ?? "")) {
+        // An empty file has no last bytes to send: open it as empty (Lamina PDF then says what it is).
+        await first.body?.cancel();
+        return { size: 0, read: async () => new Uint8Array() };
+    }
+    const file = new RangedFile(request, await readProbe(first));
+    return {
+        size: file.size,
+        read: (offset, length, opts) => file.read(offset, length, opts?.signal),
+        blockSize: options.blockSize ?? 16_384,
+    };
+}
+/** Cancels `res`'s body (nothing will read it) and rejects with `error`. */
+async function discard(res, error) {
+    await res.body?.cancel();
+    throw error;
+}
+function rangeRequester(url, options) {
+    const doFetch = options.fetch ?? fetch;
+    return async (range, signal, ifRange) => {
+        const headers = new Headers(options.headers);
+        headers.set("Range", range);
+        if (ifRange !== undefined)
+            headers.set("If-Range", ifRange);
+        try {
+            return await doFetch(url, {
+                headers,
+                ...(options.credentials === undefined ? {} : { credentials: options.credentials }),
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw signal.reason;
+            throw failed("network", undefined, e);
+        }
+    };
+}
+/** Checks the first answer is a `206` with the file's last bytes, and reads them. */
+async function readProbe(first) {
+    if (first.status !== 206) {
+        return discard(first, failed("status", first.status));
+    }
+    const range = contentRange(first.headers.get("Content-Range"));
+    if (range === undefined || range.end !== range.size - 1) {
+        return discard(first, failed("content-range", 206));
+    }
+    const tailBytes = new Uint8Array(await first.arrayBuffer());
+    if (tailBytes.length !== range.size - range.start)
+        throw failed("content-range", 206);
+    return {
+        size: range.size,
+        tailStart: range.start,
+        tailBytes,
+        etag: first.headers.get("ETag") ?? undefined,
+        lastModified: first.headers.get("Last-Modified") ?? undefined,
+    };
+}
+/** The reads after the probe: from its tail, by ranged requests, or from one whole download. */
+class RangedFile {
+    #request;
+    #probe;
+    // If-Range needs a strong ETag, else a Last-Modified date; a weak ETag is only compared.
+    #ifRange;
+    // Set once a ranged request is answered 200: the whole file, downloaded once and shared by
+    // every read (reads already in flight cancel their own bodies and wait for it).
+    #whole;
+    constructor(request, probe) {
+        this.#request = request;
+        this.#probe = probe;
+        const { etag, lastModified } = probe;
+        this.#ifRange = etag !== undefined && !etag.startsWith("W/") ? etag : lastModified;
+    }
+    get size() {
+        return this.#probe.size;
+    }
+    async read(offset, length, signal) {
+        const { tailStart, tailBytes } = this.#probe;
+        const end = offset + length;
+        if (offset >= tailStart)
+            return tailBytes.slice(offset - tailStart, end - tailStart);
+        if (end <= tailStart)
+            return this.#fetchRange(offset, end, signal);
+        // Straddles the tail the probe brought: fetch only the part before it.
+        const out = new Uint8Array(length);
+        out.set(await this.#fetchRange(offset, tailStart, signal));
+        out.set(tailBytes.subarray(0, end - tailStart), tailStart - offset);
+        return out;
+    }
+    /** Whether `res` shows a different version than the first response (ETag, then Last-Modified). */
+    #differs(res) {
+        const { etag, lastModified } = this.#probe;
+        const tag = res.headers.get("ETag") ?? undefined;
+        if (etag !== undefined && tag !== undefined)
+            return tag !== etag;
+        const modified = res.headers.get("Last-Modified") ?? undefined;
+        return lastModified !== undefined && modified !== undefined && modified !== lastModified;
+    }
+    /** The bytes `offset..end` from the network (or from the whole file, once there is one). */
+    async #fetchRange(offset, end, signal) {
+        if (this.#whole !== undefined)
+            return (await this.#whole).slice(offset, end);
+        const res = await this.#request(`bytes=${offset}-${end - 1}`, signal, this.#ifRange);
+        if (this.#differs(res)) {
+            return discard(res, changed());
+        }
+        if (res.status === 200)
+            return this.#fromWhole(res, offset, end);
+        return this.#fromPartial(res, offset, end);
+    }
+    /** The server ignored Range (or If-Range found the file changed and sent it whole). */
+    async #fromWhole(res, offset, end) {
+        if (this.#probe.etag !== undefined && res.headers.get("ETag") === null) {
+            return discard(res, changed());
+        }
+        let whole = this.#whole;
+        if (whole === undefined)
+            whole = this.#download(res);
+        else
+            await res.body?.cancel();
+        return (await whole).slice(offset, end);
+    }
+    #download(res) {
+        const download = res.arrayBuffer().then((buffer) => {
+            const bytes = new Uint8Array(buffer);
+            if (bytes.length !== this.#probe.size)
+                throw changed();
+            return bytes;
+        });
+        this.#whole = download;
+        // A failed or aborted download (its read's signal) must not stick: the next read that
+        // gets a 200 starts a new one.
+        download.catch(() => {
+            if (this.#whole === download)
+                this.#whole = undefined;
+        });
+        return download;
+    }
+    /** A `206` with exactly the bytes asked for, from the same file. */
+    async #fromPartial(res, offset, end) {
+        if (res.status !== 206) {
+            return discard(res, failed("status", res.status));
+        }
+        const got = contentRange(res.headers.get("Content-Range"));
+        if (got !== undefined && got.size !== this.#probe.size) {
+            return discard(res, changed());
+        }
+        if (got === undefined || got.start !== offset || got.end !== end - 1) {
+            return discard(res, failed("content-range", 206));
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (bytes.length !== end - offset)
+            throw failed("content-range", 206);
+        return bytes;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/source/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/source/http.ts"],"names":[],"mappings":"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"}

package/dist/source/range.d.ts

@@ -0,0 +1,75 @@
+import type { WasmSparseSource } from "@laminapdf/wasm/base";
+import type { BaseGlue } from "../init.js";
+import type { Instance } from "../internal/instance.js";
+/** A byte range of the input. */
+export interface ByteRange {
+    /** First byte. */
+    readonly offset: number;
+    /** Number of bytes. */
+    readonly length: number;
+}
+/**
+ * Random access to a file whose bytes are fetched on demand (a remote file, a `Blob`, a file
+ * handle). `@laminapdf/viewer`'s document worker reads a `Blob` through it too.
+ */
+export interface RangeSource {
+    /** The file's size in bytes. */
+    readonly size: number;
+    /**
+     * The `length` bytes at `offset` (exactly that many: the file is at least `offset + length`
+     * long). Rejects when `signal` aborts.
+     */
+    read(offset: number, length: number, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    /** The block size this source prefers fetches aligned to (HTTP: fewer, larger requests). */
+    readonly blockSize?: number;
+}
+/** How a range document fetches. */
+export interface RangeOptions {
+    /** Aborts the open's fetches: it rejects with the signal's reason. Later calls take their own
+     * signal ({@link Document.ensure}). */
+    readonly signal?: AbortSignal;
+    /** Fetches are widened to whole blocks of this many bytes (default: the source's, else 4096). */
+    readonly blockSize?: number;
+    /** Extra bytes fetched after each range (default 0). */
+    readonly readahead?: number;
+    /** Rounds of fetches per call before giving up with the last `data-pending` (default 1024). */
+    readonly maxRounds?: number;
+    /** The most bytes the document may hold (default: no limit); more is `source-budget-exceeded`. */
+    readonly budget?: number;
+}
+/**
+ * A {@link RangeSource} over a caller's read function (a `Blob.slice`, a file handle, an IPC call).
+ *
+ * @param size - the file's size in bytes.
+ * @param read - returns the `length` bytes at `offset`.
+ */
+export declare function callbackSource(size: number, read: (offset: number, length: number, signal?: AbortSignal) => Promise<Uint8Array>): RangeSource;
+/** @internal Marks a source whose bytes are all in memory already (`httpRangeSource` after a `200`). */
+export declare const WHOLE: unique symbol;
+/** @internal The whole file, when `source` already has it in memory. */
+export declare function wholeBytes(source: RangeSource): Uint8Array | undefined;
+/** @internal What a range document keeps to fetch more: never the password or a signal. */
+export interface RangeState {
+    /** The instance the sparse source lives in, and its generation then. */
+    readonly instance: Instance<BaseGlue>;
+    readonly generation: number;
+    readonly sparse: WasmSparseSource;
+    readonly source: RangeSource;
+    readonly blockSize: number;
+    readonly readahead: number;
+    readonly maxRounds: number;
+}
+/**
+ * Runs `call` until it stops throwing (or rejecting with) `data-pending`: fetches the ranges
+ * asked for (widened to blocks, minus what the source holds), supplies them and calls again.
+ * Gives up with the last `data-pending` after `maxRounds`, or when a round asks again for
+ * exactly what the round before asked (no progress). The fetches of a round share one abort
+ * controller: `signal` aborts them all, and the first failure aborts the others; the round waits
+ * for every fetch before it throws, so nothing is supplied after it returns.
+ *
+ * @internal
+ */
+export declare function settle<T>(state: RangeState, call: () => T | Promise<T>, signal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=range.d.ts.map

package/dist/source/range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range.d.ts","sourceRoot":"","sources":["../../src/source/range.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,iCAAiC;AACjC,MAAM,WAAW,SAAS;IACxB,kBAAkB;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvG,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC3B;2CACuC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,iGAAiG;IACjG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,GAClF,WAAW,CAEb;AAOD,wGAAwG;AACxG,eAAO,MAAM,KAAK,EAAE,OAAO,MAAoC,CAAC;AAEhE,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,CAGtE;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAuB/G"}

package/dist/source/range.js

@@ -0,0 +1,100 @@
+import { isLaminaPdfError, packageError } from "../errors.js";
+/**
+ * A {@link RangeSource} over a caller's read function (a `Blob.slice`, a file handle, an IPC call).
+ *
+ * @param size - the file's size in bytes.
+ * @param read - returns the `length` bytes at `offset`.
+ */
+export function callbackSource(size, read) {
+    return { size, read: (offset, length, options) => read(offset, length, options?.signal) };
+}
+/** The ranges of a `data-pending` error. */
+function rangesOf(e) {
+    return e.ranges ?? [];
+}
+/** @internal Marks a source whose bytes are all in memory already (`httpRangeSource` after a `200`). */
+export const WHOLE = Symbol("lamina.wholeBytes");
+/** @internal The whole file, when `source` already has it in memory. */
+export function wholeBytes(source) {
+    const bytes = source[WHOLE];
+    return bytes instanceof Uint8Array ? bytes : undefined;
+}
+/**
+ * Runs `call` until it stops throwing (or rejecting with) `data-pending`: fetches the ranges
+ * asked for (widened to blocks, minus what the source holds), supplies them and calls again.
+ * Gives up with the last `data-pending` after `maxRounds`, or when a round asks again for
+ * exactly what the round before asked (no progress). The fetches of a round share one abort
+ * controller: `signal` aborts them all, and the first failure aborts the others; the round waits
+ * for every fetch before it throws, so nothing is supplied after it returns.
+ *
+ * @internal
+ */
+export async function settle(state, call, signal) {
+    const { instance, generation, sparse, blockSize, readahead, maxRounds } = state;
+    let previous;
+    for (let round = 0;; round++) {
+        let error;
+        try {
+            return await call();
+        }
+        catch (e) {
+            if (!isLaminaPdfError(e, "data-pending"))
+                throw e;
+            error = e;
+        }
+        const asked = rangesOf(error);
+        const key = JSON.stringify(asked);
+        const flat = new Float64Array(asked.flatMap((r) => [r.offset, r.offset + r.length]));
+        // The planning is laminapdf-source's (`SparseSource::to_fetch`), shared with the Rust loop.
+        // The fetches await: a reset() or a trap may have replaced the sparse source's instance.
+        instance.check(generation, "Document");
+        const todo = instance.call(() => sparse.toFetch(flat, blockSize, readahead));
+        if (round >= maxRounds || todo.length === 0 || key === previous)
+            throw error;
+        signal?.throwIfAborted();
+        await fetchRound(state, todo, signal);
+        previous = key;
+    }
+}
+/** Fetches and supplies the flat `[start, end, …]` ranges of one round. */
+async function fetchRound(state, todo, signal) {
+    const { instance, generation, sparse, source } = state;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal?.reason);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    let failure;
+    const fetches = [];
+    for (let i = 0; i + 1 < todo.length; i += 2) {
+        const start = todo[i] ?? 0;
+        const end = todo[i + 1] ?? 0;
+        fetches.push(source
+            .read(start, end - start, { signal: controller.signal })
+            .then((bytes) => {
+            if (bytes.length !== end - start) {
+                throw packageError("fetch-failed", "a range source returned a different number of bytes than asked for", {
+                    data: { reason: "length", expected: end - start, got: bytes.length },
+                });
+            }
+            if (controller.signal.aborted)
+                return;
+            instance.check(generation, "Document");
+            instance.call(() => sparse.supply(start, bytes));
+        })
+            .catch((e) => {
+            // The first failure wins; the aborts it causes in the other fetches don't replace it.
+            failure ??= { reason: e };
+            controller.abort(e);
+        }));
+    }
+    try {
+        await Promise.all(fetches);
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+    }
+    if (signal?.aborted)
+        throw signal.reason;
+    if (failure !== undefined)
+        throw failure.reason;
+}
+//# sourceMappingURL=range.js.map

package/dist/source/range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"range.js","sourceRoot":"","sources":["../../src/source/range.ts"],"names":[],"mappings":"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"}

package/dist/text.d.ts

@@ -0,0 +1,90 @@
+import type { PageTextJs, TextRunJs } from "@laminapdf/wasm/extract";
+/** Options for {@link PageRef.text}. */
+export interface TextOptions {
+    /** Leave out text drawn invisibly (rendering modes 3 and 7: OCR layers, hidden text). */
+    readonly skipInvisible?: boolean;
+}
+/** A point in page space (ADR 0027: top-left of the displayed CropBox, y down, points). */
+export interface QuadPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** A glyph's quad: its four corners, in drawing order (bottom-left, bottom-right, top-right, top-left of the glyph box). */
+export type GlyphQuad = readonly [QuadPoint, QuadPoint, QuadPoint, QuadPoint];
+/** One glyph of a run. */
+export interface TextGlyph {
+    /** The glyph's text (document text; U+FFFD when its Unicode is unknown). */
+    readonly text: string;
+    /** Its quad in page space. */
+    readonly quad: GlyphQuad;
+}
+/** A run: glyphs of one font, size, direction and marked content on one baseline, in logical order. */
+export declare class PageTextRun {
+    #private;
+    /** @internal */
+    constructor(page: PageText, run: TextRunJs);
+    /** The run's text in logical order (document text). */
+    get text(): string;
+    /** The font's `/BaseFont` (document text). */
+    get font(): string;
+    /** Font size, the text matrix applied. */
+    get size(): number;
+    /** Vertical writing. */
+    get vertical(): boolean;
+    /** The marked-content ID the run is in, if any (structure tree links). */
+    get mcid(): number | undefined;
+    /** The text comes from an `/ActualText` span. */
+    get actualText(): boolean;
+    /** Drawn invisibly (`Tr` 3 or 7: an OCR layer, hidden text). */
+    get invisible(): boolean;
+    /** The bounds of its glyph quads in page space: `{ x, y, width, height }`. */
+    get bounds(): {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /** The `[start, end)` range of its glyphs in the page's glyph arrays ({@link PageText.buffers}). */
+    get glyphRange(): readonly [number, number];
+    /** Its glyphs, with their quads (built on each call). */
+    glyphs(): TextGlyph[];
+}
+/** @internal The raw arrays of a PageText (the worker client sends them). */
+export declare let rawOf: (text: PageText) => PageTextJs;
+/** A page's extracted text: lines in reading order, and runs with their glyphs' quads. */
+export declare class PageText {
+    #private;
+    /** @internal */
+    constructor(raw: PageTextJs);
+    /** The text by line (runs on one baseline joined, trimmed), in content order. */
+    get lines(): readonly string[];
+    /** The page's text: its lines joined with `\n`. */
+    text(): string;
+    /** The runs, in content order (made on first use). */
+    get runs(): readonly PageTextRun[];
+    /** Glyphs whose Unicode is unknown (shown as U+FFFD). */
+    get unmapped(): number;
+    /** The number of glyphs. */
+    readonly glyphCount: number;
+    /**
+     * Glyph `i`'s text and quad.
+     *
+     * @throws `RangeError` for an index outside `0 … glyphCount - 1`; `TypeError` once
+     *   {@link PageText.buffers}' arrays were transferred to another thread.
+     */
+    glyph(i: number): TextGlyph;
+    /**
+     * The arrays as the WASM returned them: `quads` (8 numbers per glyph), `glyphText` and
+     * `glyphOffsets` (glyph i is `glyphText.slice(glyphOffsets[i], glyphOffsets[i + 1])`). Post
+     * `quads.buffer` and `glyphOffsets.buffer` as transferables to move them to another thread;
+     * that detaches them here, and this PageText's `glyph()` and `glyphs()` then throw (`lines`
+     * and `runs` keep working). They are this PageText's own arrays, not copies: writing to them
+     * changes what `glyph()` returns.
+     */
+    get buffers(): {
+        readonly quads: Float32Array;
+        readonly glyphText: string;
+        readonly glyphOffsets: Uint32Array;
+    };
+}
+//# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAErE,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4HAA4H;AAC5H,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE9E,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,uGAAuG;AACvG,qBAAa,WAAW;;IAMtB,gBAAgB;IAChB,YAAY,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAIzC;IAED,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,8CAA8C;IAC9C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wBAAwB;IACxB,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,0EAA0E;IAC1E,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED,iDAAiD;IACjD,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,gEAAgE;IAChE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,8EAA8E;IAC9E,IAAI,MAAM,IAAI;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAGxG;IAED,oGAAoG;IACpG,IAAI,UAAU,IAAI,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAE1C;IAED,yDAAyD;IACzD,MAAM,IAAI,SAAS,EAAE,CAKpB;CACF;AAED,6EAA6E;AAC7E,eAAO,IAAI,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,UAAU,CAAC;AAEjD,0FAA0F;AAC1F,qBAAa,QAAQ;;IAUnB,gBAAgB;IAChB,YAAY,GAAG,EAAE,UAAU,EAK1B;IAED,iFAAiF;IACjF,IAAI,KAAK,IAAI,SAAS,MAAM,EAAE,CAE7B;IAED,mDAAmD;IACnD,IAAI,IAAI,MAAM,CAEb;IAED,sDAAsD;IACtD,IAAI,IAAI,IAAI,SAAS,WAAW,EAAE,CAGjC;IAED,yDAAyD;IACzD,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAc1B;IAED;;;;;;;OAOG;IACH,IAAI,OAAO,IAAI;QAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAA;KAAE,CAE9G;CACF"}

package/dist/text.js

@@ -0,0 +1,127 @@
+/** A run: glyphs of one font, size, direction and marked content on one baseline, in logical order. */
+export class PageTextRun {
+    #page;
+    #run;
+    #range;
+    /** @internal */
+    constructor(page, run) {
+        this.#page = page;
+        this.#run = run;
+        this.#range = Object.freeze([run.glyphs[0], run.glyphs[1]]);
+    }
+    /** The run's text in logical order (document text). */
+    get text() {
+        return this.#run.text;
+    }
+    /** The font's `/BaseFont` (document text). */
+    get font() {
+        return this.#run.font;
+    }
+    /** Font size, the text matrix applied. */
+    get size() {
+        return this.#run.size;
+    }
+    /** Vertical writing. */
+    get vertical() {
+        return this.#run.vertical;
+    }
+    /** The marked-content ID the run is in, if any (structure tree links). */
+    get mcid() {
+        return this.#run.mcid;
+    }
+    /** The text comes from an `/ActualText` span. */
+    get actualText() {
+        return this.#run.actualText;
+    }
+    /** Drawn invisibly (`Tr` 3 or 7: an OCR layer, hidden text). */
+    get invisible() {
+        return this.#run.invisible;
+    }
+    /** The bounds of its glyph quads in page space: `{ x, y, width, height }`. */
+    get bounds() {
+        const [x, y, width, height] = this.#run.bounds;
+        return { x, y, width, height };
+    }
+    /** The `[start, end)` range of its glyphs in the page's glyph arrays ({@link PageText.buffers}). */
+    get glyphRange() {
+        return this.#range;
+    }
+    /** Its glyphs, with their quads (built on each call). */
+    glyphs() {
+        const [start, end] = this.#run.glyphs;
+        const out = [];
+        for (let i = start; i < end; i++)
+            out.push(this.#page.glyph(i));
+        return out;
+    }
+}
+/** @internal The raw arrays of a PageText (the worker client sends them). */
+export let rawOf;
+/** A page's extracted text: lines in reading order, and runs with their glyphs' quads. */
+export class PageText {
+    #raw;
+    #runs;
+    static {
+        rawOf = (text) => text.#raw;
+    }
+    #lines;
+    /** @internal */
+    constructor(raw) {
+        this.#raw = raw;
+        this.#lines = Object.freeze([...raw.lines]);
+        // Kept from the start: transferring the buffers detaches glyphOffsets.
+        this.glyphCount = Math.max(0, raw.glyphOffsets.length - 1);
+    }
+    /** The text by line (runs on one baseline joined, trimmed), in content order. */
+    get lines() {
+        return this.#lines;
+    }
+    /** The page's text: its lines joined with `\n`. */
+    text() {
+        return this.#lines.join("\n");
+    }
+    /** The runs, in content order (made on first use). */
+    get runs() {
+        this.#runs ??= this.#raw.runs.map((r) => new PageTextRun(this, r));
+        return this.#runs;
+    }
+    /** Glyphs whose Unicode is unknown (shown as U+FFFD). */
+    get unmapped() {
+        return this.#raw.unmapped;
+    }
+    /** The number of glyphs. */
+    glyphCount;
+    /**
+     * Glyph `i`'s text and quad.
+     *
+     * @throws `RangeError` for an index outside `0 … glyphCount - 1`; `TypeError` once
+     *   {@link PageText.buffers}' arrays were transferred to another thread.
+     */
+    glyph(i) {
+        if (!Number.isInteger(i) || i < 0 || i >= this.glyphCount) {
+            throw new RangeError(`glyph index ${i} is outside 0..${this.glyphCount - 1}`);
+        }
+        const q = this.#raw.quads;
+        if (q.length < (i + 1) * 8 || this.#raw.glyphOffsets.length <= i + 1) {
+            throw new TypeError("the glyph arrays were transferred (buffers): this PageText no longer holds them");
+        }
+        const o = i * 8;
+        const point = (k) => ({ x: q[o + 2 * k] ?? 0, y: q[o + 2 * k + 1] ?? 0 });
+        return {
+            text: this.#raw.glyphText.slice(this.#raw.glyphOffsets[i] ?? 0, this.#raw.glyphOffsets[i + 1] ?? 0),
+            quad: [point(0), point(1), point(2), point(3)],
+        };
+    }
+    /**
+     * The arrays as the WASM returned them: `quads` (8 numbers per glyph), `glyphText` and
+     * `glyphOffsets` (glyph i is `glyphText.slice(glyphOffsets[i], glyphOffsets[i + 1])`). Post
+     * `quads.buffer` and `glyphOffsets.buffer` as transferables to move them to another thread;
+     * that detaches them here, and this PageText's `glyph()` and `glyphs()` then throw (`lines`
+     * and `runs` keep working). They are this PageText's own arrays, not copies: writing to them
+     * changes what `glyph()` returns.
+     */
+    get buffers() {
+        return { quads: this.#raw.quads, glyphText: this.#raw.glyphText, glyphOffsets: this.#raw.glyphOffsets };
+    }
+}
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"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"}