web-doc 0.6.2 → 0.7.0

package/dist/edit/pdf/engine/compact.js

@@ -0,0 +1,442 @@
+import { ViewerError } from "../../../errors.js";
+export class PdfCompactionError extends ViewerError {
+    constructor(message) {
+        super("edit-failed", `The full save could not be compacted: ${message}`, {
+            details: { stage: "materialize", reason: "pdf-compaction" },
+        });
+    }
+}
+/** The reachable objects of `bytes` with a fresh cross-reference table. */
+export function compactPdf(bytes) {
+    const { objects, trailer, trailerReferences, headerEnd } = parseFile(bytes);
+    const byNumber = new Map(objects.map((object) => [object.number, object]));
+    const reachable = new Set();
+    const queue = [...trailerReferences];
+    while (queue.length > 0) {
+        const number = queue.pop();
+        if (reachable.has(number))
+            continue;
+        const object = byNumber.get(number);
+        if (!object)
+            continue;
+        reachable.add(number);
+        queue.push(...object.references);
+    }
+    const kept = objects.filter((object) => reachable.has(object.number));
+    const parts = [bytes.subarray(0, headerEnd)];
+    const offsets = new Map();
+    let position = headerEnd;
+    for (const object of kept) {
+        offsets.set(object.number, position);
+        const slice = bytes.subarray(object.start, object.end);
+        parts.push(slice, NEWLINE);
+        position += slice.byteLength + 1;
+    }
+    // One subsection per run of consecutive numbers, as PDFium writes it, so
+    // sparse numbering does not cost twenty bytes per gap.
+    const numbers = kept.map((object) => object.number).sort((a, b) => a - b);
+    const size = (numbers.at(-1) ?? 0) + 1;
+    let xref = "xref\n0 1\n0000000000 65535 f \n";
+    for (let index = 0; index < numbers.length;) {
+        let count = 1;
+        while (numbers[index + count] === numbers[index] + count)
+            count += 1;
+        xref += `${numbers[index]} ${count}\n`;
+        for (const number of numbers.slice(index, index + count))
+            xref += `${String(offsets.get(number)).padStart(10, "0")} ${String(byNumber.get(number).generation).padStart(5, "0")} n \n`;
+        index += count;
+    }
+    const dictionary = trailer.replace(/\/Size\s+\d+/, `/Size ${size}`);
+    parts.push(ascii(`${xref}trailer\n${dictionary}\nstartxref\n${position}\n%%EOF\n`));
+    return concat(parts);
+}
+function parseFile(bytes) {
+    const lexer = new Lexer(bytes);
+    const objects = [];
+    let trailer;
+    let trailerReferences = [];
+    let headerEnd;
+    // Two integers followed by `obj` open an object; a dangling pair is kept
+    // until the next token tells what it is.
+    let pending = [];
+    for (;;) {
+        const token = lexer.next();
+        if (token.kind === "end")
+            break;
+        if (token.kind === "number") {
+            pending.push(token);
+            if (pending.length > 2)
+                pending.shift();
+            continue;
+        }
+        if (token.kind === "keyword" && token.value === "obj") {
+            const [first, second] = pending;
+            if (pending.length !== 2 ||
+                first.kind !== "number" ||
+                second.kind !== "number")
+                throw new PdfCompactionError("an object header is malformed");
+            // The object starts at its number: the cross-reference offset must
+            // point there, not at the whitespace before it.
+            const object = parseObject(lexer, bytes, first.value, second.value, first.start);
+            headerEnd ??= object.start;
+            objects.push(object);
+            pending = [];
+            continue;
+        }
+        pending = [];
+        if (token.kind === "keyword" && token.value === "trailer") {
+            const dictionaryStart = lexer.skipWhitespace();
+            const references = [];
+            const dictionaryEnd = skipValue(lexer, references);
+            trailer = latin1(bytes.subarray(dictionaryStart, dictionaryEnd));
+            trailerReferences = references;
+            continue;
+        }
+        if (token.kind === "keyword" && token.value === "xref") {
+            // A classic table: `xref`, subsections of `start count` and entries.
+            // PDFium always writes one; its entries are skipped as plain tokens.
+            continue;
+        }
+        if (token.kind === "keyword" && token.value === "startxref") {
+            lexer.next();
+            continue;
+        }
+        if (token.kind === "delimiter" && token.value === "<<")
+            // A dictionary outside any object: an xref stream's or a stray one.
+            throw new PdfCompactionError("the file uses a cross-reference stream instead of a trailer");
+    }
+    if (trailer === undefined)
+        throw new PdfCompactionError("the file has no trailer dictionary");
+    if (headerEnd === undefined)
+        throw new PdfCompactionError("the file has no objects");
+    // Indirect stream lengths were resolved while parsing where the length
+    // object came first; the rest were measured from `endstream`.
+    return { objects, trailer, trailerReferences, headerEnd };
+}
+function parseObject(lexer, bytes, number, generation, start) {
+    const references = [];
+    let integer;
+    let lengthValue;
+    let lengthReference;
+    // The object's value: a dictionary, an array, a scalar or nothing.
+    const first = lexer.peek();
+    if (first.kind === "number") {
+        lexer.next();
+        const second = lexer.peek();
+        if (second.kind === "number") {
+            lexer.next();
+            const third = lexer.peek();
+            if (third.kind === "keyword" && third.value === "R") {
+                lexer.next();
+                references.push(first.value);
+            }
+        }
+        else
+            integer = first.value;
+    }
+    else if (first.kind !== "keyword" || first.value !== "endobj") {
+        const dictionaryStart = lexer.position;
+        const dictionaryEnd = skipValue(lexer, references);
+        if (first.kind === "delimiter" && first.value === "<<") {
+            const length = findLength(bytes, dictionaryStart, dictionaryEnd);
+            lengthValue = length?.value;
+            lengthReference = length?.reference;
+        }
+    }
+    let next = lexer.next();
+    if (next.kind === "keyword" && next.value === "stream") {
+        let dataStart = next.end;
+        if (bytes[dataStart] === CR)
+            dataStart += 1;
+        if (bytes[dataStart] === LF)
+            dataStart += 1;
+        let dataEnd;
+        if (lengthValue !== undefined)
+            dataEnd = dataStart + lengthValue;
+        else if (lengthReference !== undefined) {
+            const known = lexer.integerObjects.get(lengthReference);
+            if (known !== undefined)
+                dataEnd = dataStart + known;
+        }
+        if (dataEnd === undefined ||
+            dataEnd > bytes.length ||
+            !followedByEndstream(bytes, dataEnd)) {
+            // Length unknown or wrong: measure to the `endstream` that closes the
+            // object. Stream data that spells "endstream" would mislead this, but
+            // a wrong direct length is the more common fault.
+            dataEnd = findEndstream(bytes, dataStart);
+            if (dataEnd === undefined)
+                throw new PdfCompactionError(`object ${number} has no endstream`);
+        }
+        lexer.seek(dataEnd);
+        const endstream = lexer.next();
+        if (endstream.kind !== "keyword" || endstream.value !== "endstream")
+            throw new PdfCompactionError(`object ${number} is not terminated`);
+        next = lexer.next();
+    }
+    if (next.kind !== "keyword" || next.value !== "endobj")
+        throw new PdfCompactionError(`object ${number} has no endobj`);
+    if (integer !== undefined)
+        lexer.integerObjects.set(number, integer);
+    return {
+        number,
+        generation,
+        start,
+        end: next.end,
+        references,
+        ...(integer === undefined ? {} : { integer }),
+    };
+}
+/** Skips one value (dictionary, array, scalar), collecting `n g R` references. */
+function skipValue(lexer, references) {
+    let depth = 0;
+    let numbers = [];
+    let end = lexer.position;
+    do {
+        const token = lexer.next();
+        end = token.end;
+        switch (token.kind) {
+            case "end":
+                throw new PdfCompactionError("a value is not terminated");
+            case "delimiter":
+                if (token.value === "<<" || token.value === "[")
+                    depth += 1;
+                else if (token.value === ">>" || token.value === "]")
+                    depth -= 1;
+                numbers = [];
+                break;
+            case "number":
+                numbers.push(token.value);
+                if (numbers.length > 2)
+                    numbers.shift();
+                break;
+            case "keyword":
+                if (token.value === "R" && numbers.length === 2)
+                    references.push(numbers[0]);
+                else if (depth === 0 && !SCALAR_KEYWORDS.has(token.value))
+                    throw new PdfCompactionError(`unexpected keyword ${token.value}`);
+                numbers = [];
+                break;
+            default:
+                numbers = [];
+        }
+        if (depth < 0)
+            throw new PdfCompactionError("unbalanced delimiters");
+    } while (depth > 0);
+    return end;
+}
+/** `/Length` of a dictionary's bytes: a direct integer or an indirect reference. */
+function findLength(bytes, start, end) {
+    const lexer = new Lexer(bytes.subarray(start, end));
+    for (;;) {
+        const token = lexer.next();
+        if (token.kind === "end")
+            return undefined;
+        if (token.kind !== "name" || !lexer.lastNameIs("Length"))
+            continue;
+        const value = lexer.next();
+        if (value.kind !== "number")
+            return undefined;
+        const generation = lexer.peek();
+        if (generation.kind !== "number")
+            return { value: value.value };
+        lexer.next();
+        const reference = lexer.peek();
+        if (reference.kind === "keyword" && reference.value === "R")
+            return { reference: value.value };
+        return { value: value.value };
+    }
+}
+function followedByEndstream(bytes, at) {
+    let index = at;
+    while (index < bytes.length && isWhitespace(bytes[index]))
+        index += 1;
+    return matchesAscii(bytes, index, "endstream");
+}
+function findEndstream(bytes, from) {
+    for (let index = from; index <= bytes.length - 9; index += 1) {
+        if (bytes[index] !== 0x65 || !matchesAscii(bytes, index, "endstream"))
+            continue;
+        const after = index + 9;
+        if (after < bytes.length && !isWhitespace(bytes[after]))
+            continue;
+        // Trim the end-of-line that precedes `endstream`.
+        let end = index;
+        if (end > from && bytes[end - 1] === LF)
+            end -= 1;
+        if (end > from && bytes[end - 1] === CR)
+            end -= 1;
+        return end;
+    }
+    return undefined;
+}
+/** A PDF tokenizer that skips comments, strings and names as units. */
+class Lexer {
+    #bytes;
+    #position = 0;
+    #lastName = "";
+    /** Objects whose value is a bare integer, as seen so far: indirect lengths. */
+    integerObjects = new Map();
+    constructor(bytes) {
+        this.#bytes = bytes;
+    }
+    get position() {
+        return this.#position;
+    }
+    seek(position) {
+        this.#position = position;
+    }
+    lastNameIs(name) {
+        return this.#lastName === name;
+    }
+    peek() {
+        const position = this.#position;
+        const token = this.next();
+        this.#position = position;
+        return token;
+    }
+    /** Skips whitespace and comments; returns where the next token starts. */
+    skipWhitespace() {
+        const bytes = this.#bytes;
+        for (;;) {
+            while (this.#position < bytes.length &&
+                isWhitespace(bytes[this.#position]))
+                this.#position += 1;
+            if (bytes[this.#position] !== 0x25)
+                return this.#position; // %
+            while (this.#position < bytes.length &&
+                bytes[this.#position] !== LF &&
+                bytes[this.#position] !== CR)
+                this.#position += 1;
+        }
+    }
+    next() {
+        const bytes = this.#bytes;
+        const start = this.skipWhitespace();
+        if (start >= bytes.length)
+            return { kind: "end", start, end: start };
+        const byte = bytes[start];
+        if (byte === 0x28) {
+            // ( literal string with nesting and escapes
+            let depth = 0;
+            let index = start;
+            for (; index < bytes.length; index += 1) {
+                const current = bytes[index];
+                if (current === 0x5c)
+                    index += 1; // backslash escapes the next byte
+                else if (current === 0x28)
+                    depth += 1;
+                else if (current === 0x29 && --depth === 0)
+                    break;
+            }
+            this.#position = Math.min(index + 1, bytes.length);
+            return { kind: "string", start, end: this.#position };
+        }
+        if (byte === 0x3c) {
+            if (bytes[start + 1] === 0x3c) {
+                this.#position = start + 2;
+                return {
+                    kind: "delimiter",
+                    value: "<<",
+                    start,
+                    end: this.#position,
+                };
+            }
+            let index = start + 1;
+            while (index < bytes.length && bytes[index] !== 0x3e)
+                index += 1;
+            this.#position = Math.min(index + 1, bytes.length);
+            return { kind: "string", start, end: this.#position };
+        }
+        if (byte === 0x3e && bytes[start + 1] === 0x3e) {
+            this.#position = start + 2;
+            return {
+                kind: "delimiter",
+                value: ">>",
+                start,
+                end: this.#position,
+            };
+        }
+        if (byte === 0x5b || byte === 0x5d || byte === 0x7b || byte === 0x7d) {
+            this.#position = start + 1;
+            return {
+                kind: "delimiter",
+                value: String.fromCharCode(byte),
+                start,
+                end: this.#position,
+            };
+        }
+        if (byte === 0x2f) {
+            let index = start + 1;
+            while (index < bytes.length && isRegular(bytes[index]))
+                index += 1;
+            this.#position = index;
+            this.#lastName = latin1(bytes.subarray(start + 1, index));
+            return { kind: "name", start, end: index };
+        }
+        let index = start;
+        while (index < bytes.length && isRegular(bytes[index]))
+            index += 1;
+        if (index === start)
+            index += 1; // a stray delimiter byte
+        this.#position = index;
+        const text = latin1(bytes.subarray(start, index));
+        const value = Number(text);
+        if (/^[+-]?(\d+\.?\d*|\.\d+)$/.test(text) && Number.isFinite(value))
+            return { kind: "number", value, start, end: index };
+        return { kind: "keyword", value: text, start, end: index };
+    }
+}
+/** Keywords that are whole values on their own: `null`, `true`, `false`. */
+const SCALAR_KEYWORDS = new Set(["null", "true", "false"]);
+const CR = 0x0d;
+const LF = 0x0a;
+const NEWLINE = Uint8Array.of(LF);
+function isWhitespace(byte) {
+    return (byte === 0x20 ||
+        byte === LF ||
+        byte === CR ||
+        byte === 0x09 ||
+        byte === 0x0c ||
+        byte === 0x00);
+}
+/** Regular characters: anything but whitespace and the delimiters. */
+function isRegular(byte) {
+    return (!isWhitespace(byte) &&
+        byte !== 0x28 &&
+        byte !== 0x29 &&
+        byte !== 0x3c &&
+        byte !== 0x3e &&
+        byte !== 0x5b &&
+        byte !== 0x5d &&
+        byte !== 0x7b &&
+        byte !== 0x7d &&
+        byte !== 0x2f &&
+        byte !== 0x25);
+}
+function matchesAscii(bytes, at, text) {
+    if (at + text.length > bytes.length)
+        return false;
+    for (let index = 0; index < text.length; index += 1)
+        if (bytes[at + index] !== text.charCodeAt(index))
+            return false;
+    return true;
+}
+function latin1(bytes) {
+    let text = "";
+    for (let offset = 0; offset < bytes.length; offset += 0x8000)
+        text += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    return text;
+}
+function ascii(text) {
+    return Uint8Array.from(text, (character) => character.charCodeAt(0) & 0xff);
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}

package/dist/edit/pdf/engine/document.d.ts

@@ -0,0 +1,95 @@
+import type { EngineBatch, EngineChange, MaterializedDocument, RestoreTarget } from "../../engine.js";
+import type { EditFindOptions, EditOperation, ElementQuery, OperationIssue, PagePoint, PageRect, TextPosition, TextRange, TextTarget } from "../../types.js";
+import type { PageLayout, PdfElement, PdfOperation, TextLayout } from "../types.js";
+import type { EditWorkerBitmap } from "../../../worker-protocol.js";
+import { FontLibrary } from "./fonts.js";
+import { ImageCache } from "./images.js";
+import { type AssetSource } from "../../assets.js";
+import type { ResourceLimits } from "../../../contracts.js";
+import type { Pdfium } from "./pdfium.js";
+/**
+ * The working copy of one PDF: a PDFium document rebuilt from the original
+ * bytes plus the applied batches, with a stable id for every page and object.
+ * Everything a query answers comes from PDFium; the model only remembers
+ * identities and caches.
+ */
+/** Batches arrive as plain JSON; unknown operations are reported, not typed away. */
+type PdfOrUnknownOperation = PdfOperation | EditOperation;
+/** Properties of the original that a change invalidates or leaves behind. */
+export type DocumentFeature = "docmdp" | "tagged" | "pdfa";
+export declare class PdfEditDocument {
+    #private;
+    readonly images: ImageCache;
+    constructor(pdfium: Pdfium, original: Uint8Array, fonts?: FontLibrary, limits?: ResourceLimits, assets?: AssetSource, compact?: (bytes: Uint8Array) => Uint8Array);
+    /** Features of the original a change affects, see `DocumentFeature`. */
+    get features(): readonly DocumentFeature[];
+    /** Signature fields in the document. */
+    get signatureCount(): number;
+    /**
+     * The families and texts a batch will draw, so the fonts can be fetched
+     * before the synchronous validation and application run.
+     */
+    fontRequests(operations: readonly PdfOrUnknownOperation[]): {
+        readonly family: string;
+        readonly text: string;
+    }[];
+    get pageCount(): number;
+    get pdfium(): Pdfium;
+    /**
+     * Checks a batch against the current document. Operations are checked one
+     * after another against the state before the batch, which is exact for
+     * everything but a page count another operation of the batch changes.
+     */
+    validate(operations: readonly PdfOrUnknownOperation[]): OperationIssue[];
+    /**
+     * Applies a batch. Plain operation arrays, as the unit tests pass them, get
+     * the next batch number as their state id.
+     */
+    apply(input: readonly PdfOrUnknownOperation[] | EngineBatch): EngineChange;
+    /**
+     * Bytes of the current state. The viewer reopens the incremental form,
+     * which is cheap to produce and read. A save defaults to a full rewrite —
+     * compacted, so deleted content is gone and the bytes do not depend on
+     * which pages were read — unless the file is signed, where the incremental
+     * form keeps the signed revision intact. Without changes either form is
+     * the bytes the document was opened from.
+     */
+    materialize(purpose?: "show" | "save", mode?: "incremental" | "full"): Uint8Array;
+    /**
+     * The bytes of the current state. A full save goes through the compaction
+     * pass; when the pass cannot read PDFium's output, the uncompacted full
+     * save stands in — silently for the display copy, with a
+     * `privacy-not-guaranteed` warning for a save, since deleted content may
+     * then remain recoverable in the file (decided 2026-10-02). Signed files
+     * take the incremental form for both purposes so the signed revision
+     * stays intact in every base the session may restore from.
+     */
+    materializeDocument(purpose?: "show" | "save", mode?: "incremental" | "full"): MaterializedDocument;
+    /**
+     * Rebuilds a state from its base (the original, or a checkpoint) and the
+     * batches after it. Plain arrays of batches, as the unit tests pass them,
+     * get state ids 1, 2, 3…
+     */
+    restore(input: readonly (readonly PdfOrUnknownOperation[])[] | RestoreTarget): void;
+    getElements(query: ElementQuery): PdfElement[];
+    getElement(id: string): PdfElement | undefined;
+    /** Elements under a point, top-most (drawn last) first. */
+    elementsAt(pageIndex: number, point: PagePoint): PdfElement[];
+    findText(query: string, options: EditFindOptions): TextTarget[];
+    /** Lines, glyph boxes and styles of a text, text box or table element. */
+    textLayout(elementId: string): TextLayout | undefined;
+    /** The layouts of every text element on a page, with the page's displayed size. */
+    pageLayout(pageIndex: number): PageLayout | undefined;
+    /** The caret position nearest to a page-space point; none on a page without text. */
+    positionAt(pageIndex: number, point: PagePoint): TextPosition | undefined;
+    /**
+     * Renders a page with the listed elements inactive, as RGBA over white at
+     * `scale` device pixels per point. The objects are reactivated before the
+     * call returns, so nothing about the document changes.
+     */
+    renderPageWithout(pageIndex: number, elementIds: readonly string[], scale: number): EditWorkerBitmap;
+    /** The rectangles a range covers, one per line fragment, in reading order. */
+    rangeRects(range: TextRange): PageRect[];
+    dispose(): void;
+}
+export {};