@jasy/pdf 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/edit/flatten.js

@@ -0,0 +1,437 @@
+import { PdfDocument } from "./document.js";
+import { readAcroForm } from "./acroform-reader.js";
+import { bakeAppearance, bakeButtonStates, readLook } from "./appearance.js";
+import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
+import { latin1FromBytes } from "../utils/bytes.js";
+import { IncrementalWriter, serialize } from "./writer.js";
+import { get, isDict, isRef, isStream, nameOf, } from "./objects.js";
+export class FlattenError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+// Field flags we have to read here (see `forms/acroform.ts` for the writer's side).
+const FF_PUSHBUTTON = 1 << 16;
+const FF_RADIO = 1 << 15;
+const numbers = (o, n) => {
+    if (!Array.isArray(o) || o.length < n)
+        return undefined;
+    const out = o.slice(0, n).map((x) => (typeof x === "number" ? x : NaN));
+    return out.some(Number.isNaN) ? undefined : out;
+};
+/**
+ * Where a form XObject has to be placed so its box lands on the annotation's rectangle (PDF 12.5.5).
+ *
+ * Not just a translation: the appearance declares its own `/BBox` and an optional `/Matrix`, and the
+ * result has to be mapped onto `/Rect`. For everything we and pdf-lib produce the BBox starts at the
+ * origin and matches the rect, so this collapses to a plain shift - but a foreign file may differ, and
+ * then a plain shift puts the drawing in the wrong place at the wrong size.
+ */
+function placement(stamp) {
+    const [bx0, by0, bx1, by1] = stamp.bbox;
+    const m = stamp.matrix ?? [1, 0, 0, 1, 0, 0];
+    // The four corners of the BBox through /Matrix, then their bounding box.
+    const xs = [];
+    const ys = [];
+    for (const [x, y] of [
+        [bx0, by0],
+        [bx1, by0],
+        [bx1, by1],
+        [bx0, by1],
+    ]) {
+        xs.push(m[0] * x + m[2] * y + m[4]);
+        ys.push(m[1] * x + m[3] * y + m[5]);
+    }
+    const tx0 = Math.min(...xs);
+    const ty0 = Math.min(...ys);
+    const tw = Math.max(...xs) - tx0;
+    const th = Math.max(...ys) - ty0;
+    const [rx0, ry0, rx1, ry1] = stamp.rect;
+    const rw = Math.abs(rx1 - rx0);
+    const rh = Math.abs(ry1 - ry0);
+    const sx = tw === 0 ? 1 : rw / tw;
+    const sy = th === 0 ? 1 : rh / th;
+    return [sx, 0, 0, sy, Math.min(rx0, rx1) - tx0 * sx, Math.min(ry0, ry1) - ty0 * sy];
+}
+const fmt = (n) => (Number.isInteger(n) ? String(n) : String(Number(n.toFixed(6))));
+/** Map every widget object number to the page that lists it in `/Annots`. */
+function widgetPages(doc) {
+    const out = new Map();
+    const visit = (node, depth) => {
+        if (depth > 64)
+            return;
+        const dict = doc.resolve(node);
+        if (dict === undefined || !isDict(dict))
+            return;
+        const kids = doc.lookup(dict, "Kids");
+        if (Array.isArray(kids)) {
+            for (const k of kids)
+                visit(k, depth + 1);
+            return;
+        }
+        const pageNum = isRef(node) ? node.num : undefined;
+        if (pageNum === undefined)
+            return;
+        const annots = doc.lookup(dict, "Annots");
+        if (!Array.isArray(annots))
+            return;
+        for (const a of annots)
+            if (isRef(a))
+                out.set(a.num, pageNum);
+    };
+    visit(doc.trailer.map.get("Root") && get(doc.catalog, "Pages"), 0);
+    return out;
+}
+/**
+ * The appearance to stamp for one widget. A button's `/AP /N` is a dictionary of STATES (`/Yes`, `/Off`)
+ * and the one to keep is whichever `/AS` currently shows - flattening a check box has to freeze what the
+ * reader sees, not some other state.
+ */
+function appearanceOf(doc, widget) {
+    const n = get(doc.resolve(get(widget, "AP")), "N");
+    if (isRef(n)) {
+        const target = doc.resolve(n);
+        return isStream(target) ? n : undefined;
+    }
+    const states = doc.resolve(n);
+    if (states === undefined || !isDict(states))
+        return undefined;
+    const as = nameOf(doc.lookup(widget, "AS"));
+    const chosen = as !== undefined ? states.map.get(as) : undefined;
+    return isRef(chosen) ? chosen : undefined;
+}
+/**
+ * Collect what has to happen. A widget that ships NO appearance gets one drawn now, from its own style
+ * and current value - the same drawing the fill path bakes. Without that, flattening a form from a
+ * producer that writes no appearances (PDFKit, react-pdf) could only ever refuse.
+ */
+async function planStamps(doc, writer, fields) {
+    const pages = widgetPages(doc);
+    const stamps = [];
+    // Widgets that leave the page without leaving a picture: a push button with no face of its own. It
+    // draws nothing and holds no value, and after flattening it could not do anything anyway, so keeping
+    // it would leave a dead control on a document that is no longer a form.
+    const removeOnly = new Map();
+    const missing = [];
+    const offPage = [];
+    for (const field of fields) {
+        for (const w of field.widgets) {
+            if (w.num === undefined)
+                continue;
+            const widget = doc.getObject(w.num);
+            let appearance = appearanceOf(doc, widget);
+            if (appearance === undefined) {
+                const drawnNum = await drawMissing(doc, writer, field, w.num);
+                if (drawnNum === undefined) {
+                    const page = pages.get(w.num);
+                    if ((field.flags & FF_PUSHBUTTON) !== 0 && page !== undefined) {
+                        removeOnly.set(w.num, page);
+                    }
+                    else if (!missing.includes(field.name)) {
+                        missing.push(field.name);
+                    }
+                    continue;
+                }
+                appearance = { kind: "ref", num: drawnNum, gen: 0 };
+            }
+            const pageNum = pages.get(w.num);
+            if (pageNum === undefined) {
+                if (!offPage.includes(field.name))
+                    offPage.push(field.name);
+                continue;
+            }
+            const rect = numbers(doc.lookup(widget, "Rect"), 4);
+            const stream = doc.resolve(appearance);
+            const bbox = numbers(doc.lookup(stream, "BBox"), 4) ?? [
+                0,
+                0,
+                rect ? Math.abs(rect[2] - rect[0]) : 0,
+                rect ? Math.abs(rect[3] - rect[1]) : 0,
+            ];
+            if (rect === undefined || bbox === undefined) {
+                if (!missing.includes(field.name))
+                    missing.push(field.name);
+                continue;
+            }
+            stamps.push({
+                pageNum,
+                appearance,
+                rect: rect,
+                bbox: bbox,
+                matrix: numbers(doc.lookup(stream, "Matrix"), 6),
+                widget: { kind: "ref", num: w.num, gen: 0 },
+            });
+        }
+    }
+    if (missing.length > 0) {
+        throw new FlattenError(`these fields could not be drawn, so flattening them would leave an empty box: ` +
+            `${missing.map((n) => `"${n}"`).join(", ")}. A widget needs a /Rect and a kind we can draw`);
+    }
+    if (offPage.length > 0) {
+        throw new FlattenError(`these fields have a widget that no page lists in /Annots, so there is nowhere to stamp it: ` +
+            offPage.map((n) => `"${n}"`).join(", "));
+    }
+    return { stamps, removeOnly };
+}
+/** The page's existing content, decoded, or undefined when it cannot be read. */
+function existingContent(doc, contents) {
+    const resolved = doc.resolve(contents);
+    const parts = Array.isArray(resolved) ? resolved : [contents];
+    let out = "";
+    for (const p of parts) {
+        const stream = doc.resolve(p);
+        if (stream === undefined || !isStream(stream))
+            return undefined;
+        out += latin1FromBytes(doc.streamData(stream)) + "\n";
+    }
+    return out;
+}
+/** Draw a widget that has no appearance, and return the object number of the new XObject. */
+async function drawMissing(doc, writer, field, widgetNum) {
+    const widget = doc.getObject(widgetNum);
+    const look = readLook(doc, widget, field);
+    if (look === undefined || look.width <= 0 || look.height <= 0)
+        return undefined;
+    let content;
+    let bbox;
+    if (field.type === "Btn") {
+        // A PUSH button has no on/off states and no value - it is a control, not a picture of anything. It
+        // carries whatever face its author drew, and if there is none there is nothing to freeze.
+        if ((field.flags & FF_PUSHBUTTON) !== 0)
+            return undefined;
+        // Freeze the state the widget is CURRENTLY showing - flattening captures what the reader sees.
+        const as = nameOf(doc.lookup(widget, "AS")) ?? field.value ?? "Off";
+        const radio = (field.flags & FF_RADIO) !== 0;
+        const faces = bakeButtonStates(look, as === "Off" ? (field.onValues?.[0] ?? "Yes") : as, radio);
+        content = as === "Off" ? faces.off : faces.on;
+        bbox = faces.bbox;
+    }
+    else {
+        const face = bakeAppearance(look, field, field.value, field.values);
+        if (face === undefined)
+            return undefined;
+        content = face.content;
+        bbox = face.bbox;
+    }
+    const encoded = new Uint8Array(getArrayBuffer(content));
+    return writer.add({
+        dict: `/Type /XObject /Subtype /Form /BBox [${bbox.map((n) => Number(n.toFixed(2))).join(" ")}] ` +
+            `/Resources << /Font << /Helv ${writer.helv()} 0 R >> >>`,
+        data: (await doc.encryptForWrite(encoded)) ?? encoded,
+    });
+}
+/**
+ * Does the page's own content leave the graphics state changed?
+ *
+ * When `/Contents` holds several streams the spec treats them as ONE - so whatever the existing content
+ * leaves in effect applies to anything appended. That is not a bug in the producer: nothing follows a
+ * page, so nothing has to be restored. But PDFKit and react-pdf both open with `1 0 0 -1 0 <h> cm`,
+ * flipping the page to a top-left origin and never undoing it, and our stamps would land upside down.
+ *
+ * Answered CONSERVATIVELY: only a stream we can prove to be state-neutral - balanced `q`/`Q` and no
+ * state operator outside them - is left alone. Anything else, including anything we cannot scan
+ * reliably, gets wrapped.
+ */
+function leavesStateDirty(content) {
+    // Strings can contain anything, including something that looks like an operator.
+    const code = content.replace(/\((?:\\.|[^\\)])*\)/g, " ").replace(/<[0-9A-Fa-f\s]*>/g, " ");
+    if (/\bBI\b/.test(code))
+        return true; // an inline image swallows arbitrary bytes - do not guess
+    let depth = 0;
+    for (const token of code.split(/\s+/)) {
+        if (token === "q")
+            depth++;
+        else if (token === "Q") {
+            if (--depth < 0)
+                return true;
+        }
+        else if (depth === 0 && ["cm", "gs", "W", "W*", "cs", "CS", "sh"].includes(token)) {
+            return true;
+        }
+    }
+    return depth !== 0;
+}
+/** A resource name for the stamped XObject that does not collide with one the page already uses. */
+function freeName(taken, i) {
+    let name = `JasyFlat${i}`;
+    let n = i;
+    while (taken.has(name))
+        name = `JasyFlat${i}_${++n}`;
+    taken.add(name);
+    return name;
+}
+/** Rewrite a dictionary with entries replaced or dropped, like `fill.ts` does. */
+function withEntries(dict, changes, cipher) {
+    const parts = [];
+    for (const [k, v] of dict.map) {
+        if (Object.prototype.hasOwnProperty.call(changes, k))
+            continue;
+        parts.push(`/${k} ${serialize(v, cipher)}`);
+    }
+    for (const [k, v] of Object.entries(changes))
+        if (v !== undefined)
+            parts.push(`/${k} ${v}`);
+    return `<< ${parts.join(" ")} >>`;
+}
+/**
+ * Stamp the fields into their pages and take the widgets away. Shared by `flattenForm` and
+ * `fillForm(..., { flatten: true })`, so filling and flattening produce ONE incremental update.
+ */
+export async function flattenInto(doc, writer, fields, cipher) {
+    if (fields.length === 0)
+        return [];
+    const { stamps, removeOnly } = await planStamps(doc, writer, fields);
+    // Group by page: one appended content stream per page, not one per widget.
+    const byPage = new Map();
+    for (const s of stamps)
+        (byPage.get(s.pageNum) ?? byPage.set(s.pageNum, []).get(s.pageNum)).push(s);
+    for (const [pageNum, pageStamps] of byPage) {
+        const page = doc.getObject(pageNum);
+        if (page === undefined || !isDict(page))
+            continue;
+        // The XObject resources the page already has, so a new name cannot shadow one.
+        const resources = doc.resolve(get(page, "Resources"));
+        const xobjects = isDict(resources) ? doc.resolve(get(resources, "XObject")) : undefined;
+        const taken = new Set(isDict(xobjects) ? [...xobjects.map.keys()] : []);
+        let ops = "";
+        const added = [];
+        pageStamps.forEach((s, i) => {
+            const name = freeName(taken, i + 1);
+            added.push(`/${name} ${s.appearance.num} ${s.appearance.gen} R`);
+            const m = placement(s).map(fmt).join(" ");
+            ops += `q ${m} cm /${name} Do Q\n`;
+        });
+        // /Contents becomes an ARRAY with our stream appended - the existing one is never touched.
+        const contents = get(page, "Contents");
+        const existing = Array.isArray(doc.resolve(contents))
+            ? doc.resolve(contents).map((c) => serialize(c, cipher))
+            : contents !== undefined
+                ? [serialize(contents, cipher)]
+                : [];
+        // If the page leaves the graphics state changed, bracket its content in q/Q so our stamps start
+        // from the default state. Only then - a well-behaved page pays nothing.
+        const own = existingContent(doc, contents);
+        const wrap = own !== undefined && leavesStateDirty(own);
+        const front = [];
+        if (wrap) {
+            const q = new Uint8Array(getArrayBuffer("q\n"));
+            front.push(`${writer.add({ dict: "", data: (await doc.encryptForWrite(q)) ?? q })} 0 R`);
+        }
+        let newContents;
+        if (ops !== "") {
+            const body = (wrap ? "Q\n" : "") + ops;
+            const data = new Uint8Array(getArrayBuffer(body));
+            const streamNum = writer.add({ dict: "", data: (await doc.encryptForWrite(data)) ?? data });
+            newContents = `[${[...front, ...existing, `${streamNum} 0 R`].join(" ")}]`;
+        }
+        // The widgets we stamped leave /Annots; anything else on the page stays.
+        const flattenedRefs = new Set(pageStamps.map((s) => s.widget.num));
+        for (const [widget, page] of removeOnly)
+            if (page === pageNum)
+                flattenedRefs.add(widget);
+        const annots = doc.resolve(get(page, "Annots"));
+        const keptAnnots = Array.isArray(annots)
+            ? annots.filter((a) => !(isRef(a) && flattenedRefs.has(a.num)))
+            : [];
+        const newXObjects = isDict(xobjects)
+            ? `<< ${[...xobjects.map].map(([k, v]) => `/${k} ${serialize(v, cipher)}`).join(" ")} ${added.join(" ")} >>`
+            : `<< ${added.join(" ")} >>`;
+        const newResources = isDict(resources)
+            ? withEntries(resources, { XObject: newXObjects }, cipher)
+            : `<< /XObject ${newXObjects} >>`;
+        writer.update(pageNum, withEntries(page, {
+            ...(newContents !== undefined ? { Contents: newContents } : {}),
+            Annots: `[${keptAnnots.map((a) => serialize(a, cipher)).join(" ")}]`,
+            Resources: newResources,
+        }, cipher));
+    }
+    // The fields are gone from the form. Their objects stay in the file, simply unreferenced - an
+    // incremental update appends, it cannot delete.
+    const acroRef = get(doc.catalog, "AcroForm");
+    const acro = doc.resolve(acroRef);
+    if (acro !== undefined && isDict(acro)) {
+        const gone = new Set(fields.map((f) => f.objNum).filter((n) => n !== undefined));
+        // A flattened field may hang in a PARENT's /Kids rather than in the form's /Fields. Dropping it only
+        // from the root leaves it reachable, so `readAcroForm` still reports a field with no widget left.
+        pruneKids(doc, writer, get(acro, "Fields"), gone, cipher);
+        const roots = doc.resolve(get(acro, "Fields"));
+        const kept = Array.isArray(roots) ? roots.filter((r) => !(isRef(r) && gone.has(r.num))) : [];
+        const newAcro = withEntries(acro, { Fields: `[${kept.map((r) => serialize(r, cipher)).join(" ")}]` }, cipher);
+        if (isRef(acroRef)) {
+            writer.update(acroRef.num, newAcro);
+        }
+        else {
+            // The form dict can sit INLINE in the catalog - our own writer puts it there - and then the
+            // CATALOG is what has to be rewritten. Skipping it left every field listed in a form that no
+            // longer has any widgets: a document contradicting itself.
+            const rootRef = doc.trailer.map.get("Root");
+            const catalog = doc.catalog;
+            if (isRef(rootRef) && catalog !== undefined && isDict(catalog)) {
+                writer.update(rootRef.num, withEntries(catalog, { AcroForm: newAcro }, cipher));
+            }
+        }
+    }
+    return fields.map((f) => f.name);
+}
+/**
+ * Walk the field tree and rewrite every `/Kids` that still points at a flattened field. A branch left
+ * with no children at all is added to `gone` so its own owner drops it too.
+ */
+function pruneKids(doc, writer, list, gone, cipher, depth = 0) {
+    if (depth > 32)
+        return;
+    const entries = doc.resolve(list);
+    if (!Array.isArray(entries))
+        return;
+    for (const ref of entries) {
+        if (!isRef(ref) || gone.has(ref.num))
+            continue;
+        const node = doc.resolve(ref);
+        if (node === undefined || !isDict(node))
+            continue;
+        const kids = get(node, "Kids");
+        if (kids === undefined)
+            continue;
+        pruneKids(doc, writer, kids, gone, cipher, depth + 1);
+        const resolved = doc.resolve(kids);
+        if (!Array.isArray(resolved))
+            continue;
+        const kept = resolved.filter((k) => !(isRef(k) && gone.has(k.num)));
+        if (kept.length === resolved.length)
+            continue;
+        if (kept.length === 0) {
+            gone.add(ref.num); // an empty branch is a field with nothing left to show
+            continue;
+        }
+        writer.update(ref.num, withEntries(node, { Kids: `[${kept.map((k) => serialize(k, cipher)).join(" ")}]` }, cipher));
+    }
+}
+/** Flatten an existing form: its values become page content and stop being editable. */
+export async function flattenForm(bytes, options = {}) {
+    const doc = await PdfDocument.open(bytes, { password: options.password });
+    if (!doc.canReEncrypt) {
+        throw new FlattenError("this PDF is encrypted with RC4 or AES-128; jasy can open it but writes only AES-256, so " +
+            "flattening it would have to downgrade its protection - refused");
+    }
+    const form = readAcroForm(doc);
+    if (!form)
+        throw new FlattenError("this PDF has no AcroForm to flatten");
+    const warnings = [];
+    if (form.hasXfa) {
+        warnings.push("This document is an AcroForm/XFA hybrid; a viewer that prefers the XFA packet may still show " +
+            "editable fields.");
+    }
+    const byName = new Map(form.fields.map((f) => [f.name, f]));
+    const wanted = options.fields;
+    if (wanted) {
+        const unknown = wanted.filter((n) => !byName.has(n));
+        if (unknown.length > 0) {
+            throw new FlattenError(`no such field: ${unknown.map((n) => `"${n}"`).join(", ")}. This form has: ` +
+                form.fields.map((f) => `"${f.name}"`).join(", "));
+        }
+    }
+    const fields = wanted ? wanted.map((n) => byName.get(n)) : form.fields;
+    const writer = new IncrementalWriter(doc);
+    const flattened = await flattenInto(doc, writer, fields);
+    return { bytes: writer.save(), flattened, warnings };
+}

package/dist/edit/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@jasy/pdf/edit` - reading and filling the form of an EXISTING PDF.
+ *
+ * A separate entry point on purpose. Creating a document never needs the parser, and a browser bundle
+ * that only generates should not carry it - the same reason jimp is kept out of the text path. Importing
+ * `@jasy/pdf` alone pulls in none of this.
+ *
+ * The scope is deliberately narrow: AcroForm fields, and nothing else. This is not a PDF editor. What we
+ * do not understand, we leave untouched, and what we cannot do safely we refuse by name.
+ */
+export { readAcroForm } from "./acroform-reader.js";
+export type { ReadField, ReadForm, ReadWidget } from "./acroform-reader.js";
+export { fillForm, FillError } from "./fill.js";
+export { flattenForm, FlattenError } from "./flatten.js";
+export type { FlattenOptions, FlattenResult } from "./flatten.js";
+export type { FieldValue, FillOptions, FillResult } from "./fill.js";
+export { PdfDocument, PdfEncryptedError } from "./document.js";
+export type { PdfDict, PdfName, PdfObject, PdfRef, PdfStream, PdfString } from "./objects.js";

package/dist/edit/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@jasy/pdf/edit` - reading and filling the form of an EXISTING PDF.
+ *
+ * A separate entry point on purpose. Creating a document never needs the parser, and a browser bundle
+ * that only generates should not carry it - the same reason jimp is kept out of the text path. Importing
+ * `@jasy/pdf` alone pulls in none of this.
+ *
+ * The scope is deliberately narrow: AcroForm fields, and nothing else. This is not a PDF editor. What we
+ * do not understand, we leave untouched, and what we cannot do safely we refuse by name.
+ */
+export { readAcroForm } from "./acroform-reader.js";
+export { fillForm, FillError } from "./fill.js";
+export { flattenForm, FlattenError } from "./flatten.js";
+// The document itself, for callers who want to look further than the form.
+// PdfEncryptedError is what a caller catches to tell "wrong password" apart from a broken file.
+export { PdfDocument, PdfEncryptedError } from "./document.js";

package/dist/edit/lexer.d.ts

@@ -0,0 +1,30 @@
+import type { PdfObject } from "./objects.js";
+export declare class Lexer {
+    readonly bytes: Uint8Array;
+    pos: number;
+    constructor(bytes: Uint8Array, pos?: number);
+    /** Skip whitespace and comments (`%` to end of line). */
+    skip(): void;
+    /** The next bare token (a keyword like `obj`, `R`, `endstream`), without consuming delimiters. */
+    private word;
+    /** True when the bytes at the cursor spell `word` (after whitespace). Does not consume. */
+    peekWord(word: string): boolean;
+    /** Consume `word` if present; report whether it was. */
+    eatWord(word: string): boolean;
+    /**
+     * Parse one object at the cursor. Returns `undefined` at end of input or on a token this reader does
+     * not model - the caller treats that as "not something I can work with" rather than crashing.
+     */
+    parse(): PdfObject | undefined;
+    /** `/Name`, with `#XX` escapes decoded (a font or field name may hold `#20` for a space). */
+    private name;
+    /** `(text)`: balanced nested parens, backslash escapes, and the line continuation. */
+    private literalString;
+    /** `<48656C6C6F>`: hex digits, whitespace ignored, an odd final digit padded with 0. */
+    private hexString;
+    private array;
+    /** `<< … >>`, followed by `stream` when it is a stream object. */
+    private dictOrStream;
+    /** A number, or an indirect reference when the shape is `int int R`. */
+    private numberOrRef;
+}