@2018kguo/recto 0.0.0-stage → 0.3.0

package/dist/ranged.js

@@ -0,0 +1,497 @@
+// Ranged open: the engine parses a buffer of the file's whole length, and asks for each
+// chunk the first time the parser reads it. The engine's calls are synchronous, so a fetch
+// has to finish before it returns: in Node it runs on a small fetcher thread while this
+// thread waits on a SharedArrayBuffer (Atomics.wait), and in a Web Worker it is a synchronous
+// XMLHttpRequest. The engine therefore parses the document once and sees exactly the bytes
+// a whole-file open sees: no reopen, no retry, no zero-filled reads on the success path.
+//
+// The thread that reads a ranged document blocks while a fetch is in flight (bounded by
+// `timeoutMs`), so run it on a worker thread of its own, never on a server's main loop.
+//
+// Fetched bytes are kept as fixed-size chunks indexed by chunk number, so a read costs
+// O(chunks it spans), whatever the number of fetches so far. The first fetch reads the head
+// (and learns the size); a file it does not cover gets its tail next, since an ordinary
+// file's cross-reference table is at its end. A miss that continues the previous fetch (a
+// long xref table or page run read front to back) doubles the read-ahead, so a sequential
+// scan of n chunks costs O(log n) round trips.
+import { PdfError } from "./errors.js";
+const DEFAULT_CHUNK_BYTES = 64 * 1024;
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_READ_AHEAD_BYTES = 8 * 1024 * 1024;
+/**
+ * The first read. It covers a small file whole in one request, and a linearized file's
+ * first-page cross-reference section.
+ */
+const HEAD_CHUNKS = 4;
+/**
+ * A ranged open reserves the file's length of linear memory: fresh pages, committed only where
+ * fetched, so memory use follows the bytes fetched and not the length (measured in
+ * docs/how-it-works.md). wasm32 has 4 GiB of addresses, and this leaves 512 MiB for everything else.
+ * The parser's zero-copy objects are slices of that one buffer, and its offsets are 32-bit there.
+ */
+const MAX_FILE_BYTES = 3584 * 1024 * 1024;
+/** Fetched chunks of one file and the policy for fetching more. */
+class RangeLoader {
+    length = 0;
+    chunkBytes;
+    /** Fetched chunks by chunk number (a flat array, sized once the length is known). */
+    #chunks = [];
+    /** Set once a fetch failed; every later read fails and every call throws it. */
+    failure = null;
+    #bytesFetched = 0;
+    #requests = 0;
+    #rounds = 0;
+    #reads = 0;
+    #readBytes = 0;
+    #lastFetchEnd = -1;
+    #readAhead;
+    #etag = null;
+    #fetch;
+    #maxBytes;
+    #timeoutMs;
+    #totalTimeoutMs;
+    #deadline;
+    #signal;
+    constructor(fetch, options) {
+        this.#fetch = fetch;
+        this.chunkBytes = options.chunkBytes;
+        this.#readAhead = options.chunkBytes;
+        this.#maxBytes = options.maxBytes;
+        this.#timeoutMs = options.timeoutMs;
+        this.#totalTimeoutMs = options.totalTimeoutMs;
+        this.#deadline = performance.now() + options.totalTimeoutMs;
+        this.#signal = options.signal;
+    }
+    stats() {
+        return {
+            bytesFetched: this.#bytesFetched,
+            requests: this.#requests,
+            rounds: this.#rounds,
+            reads: this.#reads,
+            readBytes: this.#readBytes,
+            fileBytes: this.length,
+        };
+    }
+    /** Fetches chunks `firstChunk..endChunk`, keeping only those not held yet. */
+    fetchChunks(firstChunk, endChunk) {
+        const runs = [];
+        let wanted = 0;
+        for (let chunk = firstChunk; chunk < endChunk; chunk++) {
+            if (this.#chunks[chunk]) {
+                continue;
+            }
+            const start = chunk * this.chunkBytes;
+            const end = this.length > 0
+                ? Math.min(this.length, start + this.chunkBytes)
+                : start + this.chunkBytes;
+            const last = runs.at(-1);
+            if (last && last.end === start) {
+                last.end = end;
+            }
+            else {
+                runs.push({ start, end });
+            }
+            wanted += end - start;
+        }
+        if (runs.length === 0) {
+            return;
+        }
+        if (this.#signal?.aborted) {
+            throw new PdfError("aborted", "the signal was aborted", this.#signal.reason);
+        }
+        // Before the length is known the head's size is a guess, and the file may be far smaller;
+        // the fetch itself stops at the budget.
+        if (this.length > 0 && this.#bytesFetched + wanted > this.#maxBytes) {
+            throw tooLarge(this.#maxBytes);
+        }
+        const passedTotal = `the ranged read passed its ${this.#totalTimeoutMs} ms (totalTimeoutMs)`;
+        const left = this.#deadline - performance.now();
+        if (left <= 0) {
+            throw new PdfError("timeout", passedTotal);
+        }
+        this.#rounds += 1;
+        const passesTotal = left < this.#timeoutMs;
+        let answers;
+        try {
+            answers = this.#fetch(runs, passesTotal ? Math.ceil(left) : this.#timeoutMs, this.#maxBytes - this.#bytesFetched);
+        }
+        catch (error) {
+            if (passesTotal && error.code === "timeout") {
+                throw new PdfError("timeout", passedTotal, error);
+            }
+            throw error;
+        }
+        for (const answer of answers) {
+            this.#requests += 1;
+            this.#bytesFetched += answer.bytes.byteLength;
+            if (this.length > 0 && answer.length !== this.length) {
+                throw new PdfError("fetch-failed", `the file changed size during the ranged read (${this.length} bytes, now ${answer.length})`, undefined, answer.status);
+            }
+            // Before anything is sized from it: the total is whatever the server said.
+            if (answer.length > MAX_FILE_BYTES) {
+                throw new PdfError("too-large", `a ranged read holds files up to ${MAX_FILE_BYTES} bytes (this one is ${answer.length}); use open() or a smaller file`);
+            }
+            if (this.#etag && answer.etag && answer.etag !== this.#etag) {
+                throw new PdfError("fetch-failed", "the file was replaced during the ranged read (its ETag changed)", undefined, answer.status);
+            }
+            this.#etag ??= answer.etag;
+            this.length = answer.length;
+            this.#store(answer);
+        }
+    }
+    #store(answer) {
+        // Answers start on a chunk boundary (we asked for one). Views, not copies.
+        const { bytes } = answer;
+        if (this.#chunks.length === 0) {
+            this.#chunks = Array.from({
+                length: Math.ceil(answer.length / this.chunkBytes),
+            });
+        }
+        for (let at = 0; at < bytes.byteLength; at += this.chunkBytes) {
+            const chunk = (answer.start + at) / this.chunkBytes;
+            this.#chunks[chunk] ??= bytes.subarray(at, Math.min(bytes.byteLength, at + this.chunkBytes));
+        }
+    }
+    /**
+     * The `startxref` offset in the fetched last chunk, if it names one. Null for a linearized
+     * file, whose trailer points at the first-page section near the head.
+     */
+    startxref() {
+        const first = this.#chunks[0];
+        const last = this.#chunks.at(-1);
+        if (!first ||
+            !last ||
+            new TextDecoder("latin1").decode(first.subarray(0, 1024)).includes("/Linearized")) {
+            return null;
+        }
+        const tail = new TextDecoder("latin1").decode(last.subarray(-1024));
+        const match = /startxref\s+(\d+)\s+%%EOF\s*$/u.exec(tail);
+        const offset = match ? Number(match[1]) : Number.NaN;
+        return offset >= 0 && offset < this.length ? offset : null;
+    }
+    /** The chunk window to fetch for a miss at `chunk`, with read-ahead. */
+    #window(chunk, lastNeeded) {
+        const start = chunk * this.chunkBytes;
+        const sequential = this.#lastFetchEnd >= 0 &&
+            start >= this.#lastFetchEnd - this.chunkBytes &&
+            start <= this.#lastFetchEnd + this.chunkBytes;
+        this.#readAhead = sequential
+            ? Math.min(MAX_READ_AHEAD_BYTES, this.#readAhead * 2)
+            : this.chunkBytes;
+        const totalChunks = Math.ceil(this.length / this.chunkBytes);
+        const end = Math.min(totalChunks, Math.max(lastNeeded + 1, chunk + this.#readAhead / this.chunkBytes));
+        this.#lastFetchEnd = end * this.chunkBytes;
+        return [chunk, end];
+    }
+    /**
+     * Copies [offset, offset + out.length) into `out`, fetching what is missing first. On a
+     * failed fetch it records the failure and fails the read; the call that made it then
+     * throws the failure.
+     */
+    read(offset, out) {
+        this.#reads += 1;
+        this.#readBytes += out.byteLength;
+        const end = offset + out.byteLength;
+        if (this.failure || end > this.length || offset < 0) {
+            return false;
+        }
+        if (out.byteLength === 0) {
+            return true;
+        }
+        const first = Math.floor(offset / this.chunkBytes);
+        const last = Math.floor((end - 1) / this.chunkBytes);
+        for (let chunk = first; chunk <= last; chunk++) {
+            if (!this.#chunks[chunk]) {
+                try {
+                    this.fetchChunks(...this.#window(chunk, last));
+                }
+                catch (error) {
+                    this.failure =
+                        error instanceof PdfError
+                            ? error
+                            : new PdfError("fetch-failed", String(error), error);
+                    return false;
+                }
+                break;
+            }
+        }
+        let at = offset;
+        for (let chunk = first; chunk <= last; chunk++) {
+            const bytes = this.#chunks[chunk];
+            if (!bytes) {
+                return false;
+            }
+            const from = at - chunk * this.chunkBytes;
+            const take = Math.min(bytes.byteLength - from, end - at);
+            out.set(bytes.subarray(from, from + take), at - offset);
+            at += take;
+        }
+        return true;
+    }
+}
+/**
+ * Starts a ranged read of `source`: the head, then (for a larger file) the tail and its last
+ * cross-reference section. Blocks while it fetches.
+ */
+export function startRangeLoader(source, options = {}) {
+    const positive = (name, value) => {
+        if (value !== undefined && !(typeof value === "number" && value > 0)) {
+            throw new RangeError(`${name} must be above 0 (got ${value})`);
+        }
+    };
+    positive("chunkBytes", options.chunkBytes);
+    positive("maxBytes", options.maxBytes);
+    positive("timeoutMs", options.timeoutMs);
+    positive("totalTimeoutMs", options.totalTimeoutMs);
+    if (options.chunkBytes !== undefined && !Number.isSafeInteger(options.chunkBytes)) {
+        throw new RangeError(`chunkBytes must be a whole number (got ${options.chunkBytes})`);
+    }
+    if (options.signal?.aborted) {
+        throw new PdfError("aborted", "the signal was aborted", options.signal.reason);
+    }
+    const chunkBytes = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;
+    const loader = new RangeLoader(fetcherFor(source), {
+        chunkBytes,
+        maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        totalTimeoutMs: options.totalTimeoutMs ?? Number.POSITIVE_INFINITY,
+        signal: options.signal,
+    });
+    loader.fetchChunks(0, HEAD_CHUNKS);
+    if (loader.length <= 0) {
+        throw new PdfError("invalid-file", "the file is empty");
+    }
+    // A file the head covered is read whole; any other one gets its tail.
+    const totalChunks = Math.ceil(loader.length / chunkBytes);
+    if (totalChunks > HEAD_CHUNKS) {
+        loader.fetchChunks(Math.max(HEAD_CHUNKS, totalChunks - 1), totalChunks);
+        // The tail names the last cross-reference section (`startxref`). Fetch all of it in one
+        // round, rather than letting the parser discover it a chunk at a time.
+        const xrefAt = loader.startxref();
+        if (xrefAt !== null && loader.length - xrefAt <= MAX_READ_AHEAD_BYTES) {
+            loader.fetchChunks(Math.floor(xrefAt / chunkBytes), totalChunks);
+        }
+    }
+    return loader;
+}
+/**
+ * The caller's source in a form that stays valid across an await: bytes copied, a URL as an
+ * absolute http(s) string. Runs before anything asynchronous.
+ */
+export function ownedSource(source) {
+    if (ArrayBuffer.isView(source)) {
+        return new Uint8Array(source.buffer, source.byteOffset, source.byteLength).slice();
+    }
+    if (typeof source !== "string" && !(source instanceof URL)) {
+        throw new TypeError("expected an http(s) URL or the PDF's bytes as a Uint8Array");
+    }
+    const base = globalThis.location?.href;
+    const url = URL.parse(source, base);
+    if (url?.protocol !== "http:" && url?.protocol !== "https:") {
+        // Not the URL itself: it may hold a credential.
+        throw new TypeError("expected an absolute http(s) URL; use open() for a file on disk");
+    }
+    return url.href;
+}
+function fetcherFor(source) {
+    if (typeof source !== "string") {
+        const bytes = source;
+        return (ranges) => ranges.map(({ start, end }) => ({
+            start,
+            bytes: bytes.subarray(start, Math.min(end, bytes.byteLength)),
+            length: bytes.byteLength,
+            etag: null,
+            status: 206,
+        }));
+    }
+    const url = source;
+    // Node's fetch cannot run under a blocked thread; in a browser worker a synchronous
+    // XMLHttpRequest needs no second thread.
+    return globalThis.process?.getBuiltinModule?.("node:worker_threads")
+        ? (ranges, timeoutMs, limit) => fetchOverThread(url, ranges, timeoutMs, limit)
+        : (ranges, timeoutMs, limit) => fetchOverXhr(url, ranges, timeoutMs, limit);
+}
+function tooLarge(maxBytes) {
+    return new PdfError("too-large", `the ranged read would pass ${maxBytes} bytes (maxBytes); raise it or fetch the file whole`);
+}
+/**
+ * A server's answer as chunks to store, or a clear failure. Messages never carry the URL: a
+ * presigned query is a credential.
+ */
+function answerOf(range, status, contentRange, etag, bytes, limit) {
+    if (status === 200) {
+        // The server ignored Range and sent the whole file: use it, while the budget allows.
+        if (bytes.byteLength > limit) {
+            throw new PdfError("too-large", `the server does not answer Range requests, and the whole file is past the ${limit} bytes left of maxBytes`);
+        }
+        return { start: 0, bytes, length: bytes.byteLength, etag, status };
+    }
+    if (status !== 206) {
+        throw new PdfError("fetch-failed", `the ranged read failed (HTTP ${status})`, undefined, status);
+    }
+    const match = /^bytes (\d+)-\d+\/(\d+)$/u.exec(contentRange?.trim() ?? "");
+    if (!match) {
+        throw new PdfError("fetch-failed", "the server's 206 answer has no usable Content-Range (with a total length). " +
+            "A cross-origin server must also send Access-Control-Expose-Headers: Content-Range.", undefined, status);
+    }
+    const start = Number(match[1]);
+    const length = Number(match[2]);
+    // A short or shifted answer (a proxy capping ranges) would store a partial chunk.
+    if (start !== range.start || bytes.byteLength !== Math.min(range.end, length) - range.start) {
+        throw new PdfError("fetch-failed", `the server answered a different range than asked (asked ${range.start}-${range.end - 1}, got ${bytes.byteLength} bytes from ${start})`, undefined, status);
+    }
+    return { start, bytes, length, etag, status };
+}
+const NO_ANSWER = "the ranged read failed: the network, or a cross-origin server that does not allow it";
+function fetchOverXhr(url, ranges, timeoutMs, limit) {
+    const deadline = performance.now() + timeoutMs;
+    return ranges.map((range) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("GET", url, false);
+        xhr.responseType = "arraybuffer";
+        xhr.timeout = Math.max(1, deadline - performance.now());
+        xhr.setRequestHeader("Range", `bytes=${range.start}-${range.end - 1}`);
+        try {
+            xhr.send();
+        }
+        catch (error) {
+            const timedOut = error.name === "TimeoutError";
+            throw new PdfError(timedOut ? "timeout" : "fetch-failed", timedOut
+                ? `the ranged read timed out after ${timeoutMs} ms`
+                : NO_ANSWER, error);
+        }
+        // Firefox reports a refused cross-origin read as status 0, not a throw.
+        if (xhr.status === 0) {
+            throw new PdfError("fetch-failed", NO_ANSWER);
+        }
+        return answerOf(range, xhr.status, xhr.getResponseHeader("Content-Range"), xhr.getResponseHeader("ETag"), new Uint8Array(xhr.response), limit);
+    });
+}
+// The fetcher thread: plain JS (eval), so it needs no loader or bundler entry. It answers
+// each request on the port, then bumps `flag` so the waiting thread wakes. The body is read
+// up to `limit`, for a server that answers a small range with a huge whole file.
+const FETCHER_SOURCE = `
+const { workerData } = require("node:worker_threads");
+const { port, flag } = workerData;
+const controllers = new Map();
+async function get(m, signal) {
+  const response = await fetch(m.url, {
+    headers: { Range: "bytes=" + m.start + "-" + (m.end - 1), "Accept-Encoding": "identity" },
+    signal,
+  });
+  const reply = {
+    status: response.status,
+    contentRange: response.headers.get("content-range"),
+    etag: response.headers.get("etag"),
+  };
+  if (!response.ok) {
+    if (response.body) await response.body.cancel();
+    return { ...reply, bytes: new ArrayBuffer(0) };
+  }
+  const parts = [];
+  let size = 0;
+  for await (const part of response.body ?? []) {
+    size += part.byteLength;
+    if (size > m.limit) return { ...reply, overLimit: true, bytes: new ArrayBuffer(0) };
+    parts.push(part);
+  }
+  const { buffer, byteOffset, byteLength } = Buffer.concat(parts);
+  return { ...reply, bytes: buffer.slice(byteOffset, byteOffset + byteLength) };
+}
+port.on("message", async (m) => {
+  if (m.abort) { const c = controllers.get(m.id); if (c) c.abort(); return; }
+  const controller = new AbortController();
+  controllers.set(m.id, controller);
+  let reply;
+  try {
+    reply = await get(m, controller.signal);
+    // Done reading, so a request cut short at the limit stops downloading too.
+    controller.abort();
+  } catch (error) {
+    // A code, never the message: fetch quotes the URL in some of them.
+    reply = { failed: (error && error.cause && error.cause.code) || (error && error.name) || "error" };
+  }
+  controllers.delete(m.id);
+  reply.id = m.id;
+  port.postMessage(reply, reply.bytes ? [reply.bytes] : []);
+  Atomics.add(flag, 0, 1);
+  Atomics.notify(flag, 0);
+});
+`;
+let fetcher = null;
+function workerThreads() {
+    return globalThis.process.getBuiltinModule("node:worker_threads");
+}
+function startFetcher() {
+    const { MessageChannel, Worker } = workerThreads();
+    const flag = new Int32Array(new SharedArrayBuffer(4));
+    const { port1, port2 } = new MessageChannel();
+    const worker = new Worker(FETCHER_SOURCE, {
+        eval: true,
+        name: "recto-range-fetcher",
+        workerData: { port: port2, flag },
+        transferList: [port2],
+    });
+    worker.unref();
+    port1.unref();
+    worker.on("exit", () => {
+        fetcher = null;
+    });
+    return { port: port1, flag, nextId: 0 };
+}
+/** Fetches `ranges` in parallel on the fetcher thread; blocks until all answer. */
+function fetchOverThread(url, ranges, timeoutMs, limit) {
+    const current = (fetcher ??= startFetcher());
+    const deadline = performance.now() + timeoutMs;
+    const pending = new Map();
+    for (const range of ranges) {
+        const id = current.nextId++;
+        pending.set(id, range);
+        current.port.postMessage({ id, url, start: range.start, end: range.end, limit });
+    }
+    const answers = [];
+    let failure = null;
+    let seen = Atomics.load(current.flag, 0);
+    while (pending.size > 0) {
+        for (;;) {
+            const received = workerThreads().receiveMessageOnPort(current.port);
+            if (!received) {
+                break;
+            }
+            const reply = received.message;
+            const range = pending.get(reply.id);
+            if (!range) {
+                continue; // a reply to a request that already timed out
+            }
+            pending.delete(reply.id);
+            try {
+                if (reply.failed !== undefined) {
+                    throw new PdfError("fetch-failed", `the ranged read failed: ${reply.failed}`);
+                }
+                if (reply.overLimit) {
+                    throw tooLarge(limit);
+                }
+                answers.push(answerOf(range, reply.status, reply.contentRange, reply.etag, new Uint8Array(reply.bytes), limit));
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (pending.size === 0) {
+            break;
+        }
+        const remaining = deadline - performance.now();
+        if (remaining <= 0 || Atomics.wait(current.flag, 0, seen, remaining) === "timed-out") {
+            for (const id of pending.keys()) {
+                current.port.postMessage({ id, abort: true });
+            }
+            throw new PdfError("timeout", `the ranged read timed out after ${timeoutMs} ms. This thread is blocked while it waits, so a server running on the same thread can never answer; run the read on a worker thread.`);
+        }
+        seen = Atomics.load(current.flag, 0);
+    }
+    if (failure) {
+        throw failure;
+    }
+    return answers;
+}

package/dist/reading-order.d.ts

@@ -0,0 +1,14 @@
+import { type PdfPageInfo, type PdfPageText } from "./document.ts";
+export declare const BREAK_NONE = 0;
+export declare const BREAK_SPACE = 1;
+export declare const BREAK_LINE = 2;
+export type ReadingOrder = {
+    /** Char indices in reading order: real chars only (no generated chars, no CR/LF). */
+    order: Uint32Array<ArrayBuffer>;
+    /** BREAK_NONE | BREAK_SPACE | BREAK_LINE before `order[k]`. */
+    breaks: Uint8Array<ArrayBuffer>;
+    length: number;
+};
+/** Break hints without a visible glyph, even when the font supplies bounds. */
+export declare function isInvisibleCodepoint(code: number): boolean;
+export declare function readingOrder(page: Pick<PdfPageText, "count" | "codepoints" | "flags" | "boxes" | "angles">, info: Pick<PdfPageInfo, "width" | "height" | "rotation">): ReadingOrder;

package/dist/reading-order.js

@@ -0,0 +1,173 @@
+// The order a page's chars are read in, and where the word and line breaks
+// fall, as flat arrays over the page's char columns.
+//
+// On an upright page the order is the content stream's, and generated chars
+// (a space at a gap, CR LF at a new line) mark the breaks. On a page displayed
+// with /Rotate 90, 180 or 270, content order can split words and lines along
+// the wrong axis and reverse runs on a 180 page. There the chars are laid out again in the frame
+// the text reads in: each char's box is turned back by the page rotation
+// less its own angle, clustered into lines across that frame, sorted along
+// it, and a space marked where a gap is wider than a word gap.
+//
+// Data-oriented: the plan is two typed columns (`order`, `breaks`) over
+// char indices; the reflow sorts an index array, never char objects.
+import { CHAR_GENERATED } from "./document.js";
+export const BREAK_NONE = 0;
+export const BREAK_SPACE = 1;
+export const BREAK_LINE = 2;
+const LF = 0x0a;
+const CR = 0x0d;
+const SPACE = 0x20;
+/** Break hints without a visible glyph, even when the font supplies bounds. */
+export function isInvisibleCodepoint(code) {
+    return (code === 0xad || code === 0x20_0b || code === 0x20_60 || code === 0xfe_ff);
+}
+/** A gap wider than this share of the font height is a word break (pdf.js's TRACKING_SPACE_FACTOR band starts at 0.102). */
+const WORD_GAP_RATIO = 0.15;
+/** Chars whose centres are within this share of their height across the reading axis share a line. */
+const LINE_TOLERANCE_RATIO = 0.5;
+/** Content order, with its generated chars turned into breaks. */
+function streamOrder(page) {
+    const { count, codepoints, flags } = page;
+    const order = new Uint32Array(count);
+    const breaks = new Uint8Array(count);
+    let length = 0;
+    let pending = BREAK_NONE;
+    for (let i = 0; i < count; i++) {
+        const code = codepoints[i] ?? 0;
+        if (isInvisibleCodepoint(code)) {
+            continue;
+        }
+        if ((flags[i] ?? 0) & CHAR_GENERATED) {
+            pending = Math.max(pending, code === LF ? BREAK_LINE : code === SPACE ? BREAK_SPACE : BREAK_NONE);
+            continue;
+        }
+        if (code === CR || code === LF) {
+            pending = BREAK_LINE;
+            continue;
+        }
+        order[length] = i;
+        breaks[length] = length === 0 ? BREAK_NONE : pending;
+        pending = BREAK_NONE;
+        length += 1;
+    }
+    return { order, breaks, length };
+}
+/**
+ * A char's quarter turn in the viewer frame: the page's clockwise /Rotate
+ * less the char's own counter-clockwise angle, snapped to 0, 90, 180, 270.
+ */
+function viewerTurn(rotation, angle) {
+    const degrees = rotation - (angle * 180) / Math.PI;
+    return ((Math.round(degrees / 90) % 4) + 4) % 4;
+}
+/**
+ * Reflow for a rotated page. Each char's box centre and extent go into the
+ * frame its text reads in (x along the line, y down the page), then lines
+ * are clustered by y and read by x.
+ */
+function reflowedOrder(page, info) {
+    const { count, codepoints, flags, boxes, angles } = page;
+    // Real, visible chars and their reading-frame geometry, as columns.
+    const ids = new Uint32Array(count);
+    const along = new Float64Array(count);
+    const across = new Float64Array(count);
+    const start = new Float64Array(count);
+    const end = new Float64Array(count);
+    const size = new Float64Array(count);
+    const turnOf = new Uint8Array(count);
+    const generatedBreaks = new Uint32Array(count + 1);
+    let n = 0;
+    for (let i = 0; i < count; i++) {
+        const code = codepoints[i] ?? 0;
+        const generated = ((flags[i] ?? 0) & CHAR_GENERATED) !== 0;
+        generatedBreaks[i + 1] =
+            (generatedBreaks[i] ?? 0) +
+                (generated && (code === SPACE || code === CR || code === LF) ? 1 : 0);
+        if (generated || isInvisibleCodepoint(code) || code === CR || code === LF) {
+            continue;
+        }
+        const x = boxes[4 * i] ?? 0;
+        const y = boxes[4 * i + 1] ?? 0;
+        const w = boxes[4 * i + 2] ?? 0;
+        const h = boxes[4 * i + 3] ?? 0;
+        const turn = viewerTurn(info.rotation, angles[i] ?? 0);
+        // (along, across) of the box's two corners in the reading frame.
+        let a0;
+        let a1;
+        let c0;
+        let c1;
+        if (turn === 0) {
+            [a0, a1, c0, c1] = [x, x + w, y, y + h];
+        }
+        else if (turn === 1) {
+            // Reads down the viewer frame; later lines further left.
+            [a0, a1, c0, c1] = [y, y + h, info.width - (x + w), info.width - x];
+        }
+        else if (turn === 2) {
+            [a0, a1, c0, c1] = [
+                info.width - (x + w),
+                info.width - x,
+                info.height - (y + h),
+                info.height - y,
+            ];
+        }
+        else {
+            [a0, a1, c0, c1] = [info.height - (y + h), info.height - y, x, x + w];
+        }
+        ids[n] = i;
+        turnOf[n] = turn;
+        start[n] = a0;
+        end[n] = a1;
+        along[n] = (a0 + a1) / 2;
+        across[n] = (c0 + c1) / 2;
+        size[n] = Math.max(c1 - c0, 0.01);
+        n += 1;
+    }
+    // Lines: sort by turn, then across; a new line starts where the centre
+    // moves past the tolerance. Native traversal within a line is independent
+    // of the page rotation.
+    const byLine = Array.from({ length: n }, (_, k) => k).toSorted((p, q) => (turnOf[p] ?? 0) - (turnOf[q] ?? 0) || (across[p] ?? 0) - (across[q] ?? 0));
+    const lineOf = new Uint32Array(n);
+    let line = 0;
+    for (let k = 1; k < byLine.length; k++) {
+        const p = byLine[k - 1] ?? 0;
+        const q = byLine[k] ?? 0;
+        if (turnOf[p] !== turnOf[q] ||
+            (across[q] ?? 0) - (across[p] ?? 0) >
+                LINE_TOLERANCE_RATIO * Math.max(size[p] ?? 0, size[q] ?? 0)) {
+            line += 1;
+        }
+        lineOf[q] = line;
+    }
+    const reading = byLine.toSorted((p, q) => (lineOf[p] ?? 0) - (lineOf[q] ?? 0) || (ids[p] ?? 0) - (ids[q] ?? 0));
+    const order = new Uint32Array(n);
+    const breaks = new Uint8Array(n);
+    for (let k = 0; k < reading.length; k++) {
+        const q = reading[k] ?? 0;
+        order[k] = ids[q] ?? 0;
+        if (k === 0) {
+            continue;
+        }
+        const p = reading[k - 1] ?? 0;
+        if (lineOf[p] !== lineOf[q]) {
+            breaks[k] = BREAK_LINE;
+        }
+        else {
+            const first = Math.min(ids[p] ?? 0, ids[q] ?? 0);
+            const last = Math.max(ids[p] ?? 0, ids[q] ?? 0);
+            const hasBreak = (generatedBreaks[last] ?? 0) > (generatedBreaks[first + 1] ?? 0);
+            const gap = Math.max((start[q] ?? 0) - (end[p] ?? 0), (start[p] ?? 0) - (end[q] ?? 0));
+            // Native rotation can generate a break inside a word. Conversely,
+            // loose CJK boxes can have a gap without a word boundary at all.
+            if (hasBreak &&
+                gap > WORD_GAP_RATIO * Math.max(size[p] ?? 0, size[q] ?? 0)) {
+                breaks[k] = BREAK_SPACE;
+            }
+        }
+    }
+    return { order, breaks, length: n };
+}
+export function readingOrder(page, info) {
+    return info.rotation === 0 ? streamOrder(page) : reflowedOrder(page, info);
+}

package/dist/sha256.d.ts

@@ -0,0 +1 @@
+export declare function sha256Hex(bytes: Uint8Array): string;