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

package/dist/edit/appearance.js

@@ -0,0 +1,171 @@
+import { PDFObjectManager, FontStyle } from "../utils/pdf-object-manager.js";
+import { checkboxOff, checkboxOn, fieldDrawSize, listBoxFace, radioOff, radioOn, textFieldFace, wrapFieldValue, } from "../forms/appearance.js";
+import { Color } from "../common/color.js";
+import { get, isDict, isString, numberOf } from "./objects.js";
+import { latin1FromBytes } from "../utils/bytes.js";
+/**
+ * Re-drawing a field's appearance after its value changed.
+ *
+ * A widget's appearance is a picture of its value. Change the value and the picture is wrong - which is
+ * why filling used to DROP it and ask the viewer to redraw (`/NeedAppearances`). That works, but it hands
+ * control of how the value looks to whatever program opens the file, and it leaves the field invisible in
+ * anything that does not honour the flag. Baking it is what jasy does when it CREATES a field; there is
+ * no reason the edit side should be different.
+ *
+ * The face builders in `forms/appearance.ts` need nothing from the writer - plain numbers, a style and
+ * pre-measured lines - so the only pieces to bring are the font metrics and the widget's own style, and
+ * the latter is readable straight out of the file: `/DA` for size and colour, `/MK` for the border and
+ * background, `/Q` for alignment, `/Ff` for multiline.
+ */
+const FF_MULTILINE = 1 << 12;
+const FF_PASSWORD = 1 << 13;
+/**
+ * Font metrics for measuring. Created per call rather than kept in a module-level variable: jasy has no
+ * global object manager by design (a shared one caused the mixed-page-size bug), and a reader that holds
+ * mutable state at module scope would quietly reintroduce it.
+ */
+export function fontMetrics() {
+    const om = new PDFObjectManager();
+    om.registerFont("Helvetica", FontStyle.Normal, "Helvetica");
+    return om;
+}
+/** `[r g b]` in 0..1, as `/MK` writes colours. An empty array means "none". */
+function colorOf(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const n = raw.map((x) => (typeof x === "number" ? x : 0));
+    if (n.length === 1)
+        return new Color(n[0] * 255, n[0] * 255, n[0] * 255); // grey
+    if (n.length >= 3)
+        return new Color(n[0] * 255, n[1] * 255, n[2] * 255);
+    return undefined;
+}
+/**
+ * The bits of `/DA` we need: the font size and the fill colour.
+ *
+ * `/DA` is a content-stream fragment, not a dictionary - `"/Helv 12 Tf 0 0 0 rg"`. Size `0` is the PDF
+ * convention for "auto, fit the box", which is what a viewer would do; we resolve it the same way the
+ * writer does when it bakes.
+ */
+function fromDA(da) {
+    let size = 0;
+    let color = new Color(0, 0, 0);
+    if (da) {
+        const tf = /(-?[\d.]+)\s+Tf/.exec(da);
+        if (tf)
+            size = Number(tf[1]);
+        const rg = /(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s+rg/.exec(da);
+        const g = /(-?[\d.]+)\s+g\b/.exec(da);
+        if (rg)
+            color = new Color(Number(rg[1]) * 255, Number(rg[2]) * 255, Number(rg[3]) * 255);
+        else if (g)
+            color = new Color(Number(g[1]) * 255, Number(g[1]) * 255, Number(g[1]) * 255);
+    }
+    return { size, color };
+}
+export function readLook(doc, widget, field) {
+    const rect = doc.lookup(widget, "Rect");
+    if (!Array.isArray(rect) || rect.length < 4)
+        return undefined;
+    const n = rect.map((x) => (typeof x === "number" ? x : NaN));
+    if (n.some(Number.isNaN))
+        return undefined;
+    const width = Math.abs(n[2] - n[0]);
+    const height = Math.abs(n[3] - n[1]);
+    // /DA may be on the widget, the field, or the form - it is inheritable.
+    const daOf = (o) => {
+        const v = doc.lookup(o, "DA");
+        return isString(v) ? latin1FromBytes(v.bytes) : undefined;
+    };
+    const acro = doc.lookup(doc.catalog, "AcroForm");
+    const da = daOf(widget) ??
+        (field.objNum !== undefined ? daOf(doc.getObject(field.objNum)) : undefined) ??
+        daOf(acro);
+    const { size, color } = fromDA(da);
+    const mk = doc.resolve(get(widget, "MK"));
+    const border = isDict(mk) ? colorOf(doc.lookup(mk, "BC")) : undefined;
+    const background = isDict(mk) ? colorOf(doc.lookup(mk, "BG")) : undefined;
+    const bs = doc.resolve(get(widget, "BS"));
+    const borderWidth = border ? (numberOf(isDict(bs) ? doc.lookup(bs, "W") : undefined) ?? 1) : 0;
+    // /Q is inheritable in the same chain as /DA: widget, then field, then the form.
+    const q = numberOf(doc.lookup(widget, "Q")) ??
+        (field.objNum !== undefined
+            ? numberOf(doc.lookup(doc.getObject(field.objNum), "Q"))
+            : undefined) ??
+        numberOf(doc.lookup(acro, "Q")) ??
+        0;
+    return {
+        width,
+        height,
+        style: { border, background, color, fontSize: size, borderWidth },
+        align: q === 1 ? "center" : q === 2 ? "right" : "left",
+        multiline: (field.flags & FF_MULTILINE) !== 0,
+        password: (field.flags & FF_PASSWORD) !== 0,
+    };
+}
+/** The auto-size a viewer would pick: fit the cap height into the box, clamped to something readable. */
+function drawSize(look, capHeight) {
+    return fieldDrawSize(look.style.fontSize, look.height, look.style.borderWidth, capHeight);
+}
+/**
+ * The content stream for a text or choice field showing `value`, and the BBox it is drawn in.
+ * Returns `undefined` for a kind we do not draw (a button keeps its own state pictures).
+ */
+export function bakeAppearance(look, field, value, values, metrics) {
+    if (field.type !== "Tx" && field.type !== "Ch")
+        return undefined;
+    const om = metrics ?? fontMetrics();
+    const { capHeight } = om.getFontDecoration("Helvetica", FontStyle.Normal);
+    const size = drawSize(look, capHeight);
+    const innerWidth = Math.max(1, look.width - 2 * (2 + look.style.borderWidth));
+    const measure = (t) => ({
+        text: t,
+        width: om.getStringWidth(t, "Helvetica", size, FontStyle.Normal),
+    });
+    let content;
+    if (field.type === "Ch" && field.options && look.height > size * 2) {
+        // A list box draws every option, with the selected ones highlighted.
+        const chosen = new Set(values ?? (value !== undefined ? [value] : []));
+        const rows = field.options.map((o) => ({
+            ...measure(o.label),
+            selected: chosen.has(o.value),
+        }));
+        content = listBoxFace(look.width, look.height, look.style, rows, capHeight, size, "Helv");
+    }
+    else {
+        // A choice stores an EXPORT value but shows its label - "DE" in /V, "Germany" on screen.
+        const display = field.type === "Ch" ? (field.options?.find((o) => o.value === value)?.label ?? value) : value;
+        const shown = look.password ? "•".repeat([...(display ?? "")].length) : (display ?? "");
+        const lines = shown
+            ? wrapFieldValue(shown, "Helvetica", size, FontStyle.Normal, innerWidth, om, look.multiline).map(measure)
+            : [];
+        content = textFieldFace(look.width, look.height, look.style, lines, capHeight, size, "Helv", look.multiline, look.align);
+    }
+    return { content, bbox: [0, 0, look.width, look.height] };
+}
+/** The `/DR` a regenerated appearance refers to: our own Helvetica, added when the form has none. */
+export const HELV_FONT = "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>";
+/** True when the form's `/DR /Font` already offers a usable `/Helv`. */
+export function hasHelv(doc) {
+    const dr = doc.lookup(doc.lookup(doc.catalog, "AcroForm"), "DR");
+    const fonts = doc.lookup(dr, "Font");
+    return isDict(fonts) && fonts.map.has("Helv");
+}
+/**
+ * The two state pictures a check box or radio button needs, for a widget that ships none at all.
+ *
+ * A button's `/AP /N` is a dictionary of STATES, not a picture of a value, so an existing one stays
+ * valid however often the value changes - this is only for the producers that write none (PDFKit,
+ * react-pdf) and leave every box empty until a viewer redraws it. `on` is the export name the widget
+ * switches to.
+ */
+export function bakeButtonStates(look, on, radio) {
+    const w = look.width;
+    const h = look.height;
+    return {
+        on: radio ? radioOn(w, h, look.style) : checkboxOn(w, h, look.style),
+        off: radio ? radioOff(w, h, look.style) : checkboxOff(w, h, look.style),
+        bbox: [0, 0, w, h],
+        state: on,
+    };
+}

package/dist/edit/document.d.ts

@@ -0,0 +1,135 @@
+import { type PdfDict, type PdfObject, type PdfStream } from "./objects.js";
+declare const EMPTY: Uint8Array<ArrayBuffer>;
+/** Thrown when a file cannot be opened because of its encryption - always saying which of the reasons it
+ *  is: no password, wrong password, or a revision we do not implement. */
+export declare class PdfEncryptedError extends Error {
+    constructor(message: string);
+}
+export declare class PdfDocument {
+    readonly bytes: Uint8Array;
+    private readonly xref;
+    private readonly cache;
+    /** Object streams already unpacked, by their object number. */
+    private readonly objStmCache;
+    /** Set once an encrypted file has been opened with its password. */
+    private security?;
+    /** Decrypted stream payloads, keyed by the stream's data offset (unique per stream). */
+    private readonly plainStreams;
+    /** True when the cross-reference index was unusable and had to be rebuilt by scanning. Surfaced so
+     *  a caller can report it - a silently repaired file is exactly the kind of guess we avoid. */
+    recovered: boolean;
+    trailer: PdfDict;
+    /** Whether this file indexes itself with an xref STREAM rather than a classic table. An incremental
+     *  update has to follow suit: mixing the two leaves readers that understand only one kind unable to
+     *  walk the chain back. */
+    usesXrefStream: boolean;
+    private constructor();
+    static load(bytes: Uint8Array): PdfDocument;
+    /**
+     * Open a document, decrypting it when it is password-protected.
+     *
+     * Async because key derivation and AES are (WebCrypto), and because decryption happens ONCE here,
+     * eagerly, rather than at every read: that keeps `getObject`, `streamData` and the whole form layer
+     * above them synchronous, which is the same trade the writer makes (`structure.ts` builds the handler
+     * before the synchronous constructor).
+     */
+    static open(bytes: Uint8Array, opts?: {
+        password?: string;
+    }): Promise<PdfDocument>;
+    /**
+     * Build the handler for this file's `/Encrypt` dictionary, or say precisely why we cannot.
+     *
+     * Every refusal names its reason: no password given, wrong password, or an encryption revision we do
+     * not implement. "Cannot open this file" would be the unhelpful answer, and guessing would be worse.
+     */
+    private securityHandlerFor;
+    /**
+     * Which cipher and key length actually apply to the streams.
+     *
+     * For V4 the answer is NOT the top-level `/Length`: the document names a crypt filter in `/StmF` and
+     * that filter carries its own `/CFM` and `/Length` (in BYTES, where the top-level one is in bits).
+     * `/Identity` means the streams are not enciphered at all - decrypting them anyway would destroy them.
+     */
+    private streamCipher;
+    /**
+     * Decrypt every string and stream, once, in place.
+     *
+     * Three things are deliberately NOT decrypted, because they were never encrypted (ISO 32000-1 7.6.2):
+     * the `/Encrypt` dictionary's own strings, a cross-reference stream, and strings of objects that live
+     * inside an object stream - the object stream was enciphered as a whole, so its members come out in
+     * the clear already.
+     */
+    private decryptEverything;
+    /** The byte offset in the `startxref` trailer at the very end of the file. */
+    private findStartXref;
+    /** Read the index at `startxref`, then walk `/Prev` back through earlier revisions. Entries already
+     *  known win: the NEWEST revision is read first, and an older one must not overwrite it. */
+    private readXrefChain;
+    /** One index section, either format. Returns its trailer dictionary. */
+    private readXrefSection;
+    /** The classic table: `xref`, then `start count` subsections of 20-byte entries, then `trailer`. */
+    private readXrefTable;
+    /**
+     * An xref STREAM: fixed-width binary rows, widths in `/W`, object numbers from `/Index`. Row type 1
+     * is a plain byte offset, type 2 points into an object stream, type 0 is a free slot.
+     */
+    private readXrefStream;
+    /** Record an entry unless a NEWER revision already claimed that object number. */
+    private note;
+    /**
+     * Last resort: scan the whole file for `N G obj` headers and believe those. Used when the index is
+     * missing or does not lead anywhere - and flagged via `recovered`, never silently.
+     */
+    private rebuildByScanning;
+    /** The object with that number, or `undefined` when the file does not have it. */
+    getObject(num: number): PdfObject | undefined;
+    /** Parse `N G obj … endobj` at a byte offset, checking that it really is object `num`. */
+    private parseObjectAt;
+    /** Unpack an object stream once, then serve its members from the cache. */
+    private objectFromStream;
+    /** Follow indirect references until a direct object is reached. */
+    resolve(o: PdfObject | undefined): PdfObject | undefined;
+    /** A dictionary entry, with the reference already followed. */
+    lookup(o: PdfObject | undefined, key: string): PdfObject | undefined;
+    /**
+     * The file is password-protected. Every string and stream in it is enciphered, so anything read out
+     * of it is ciphertext until a decryption path exists - which is why the form layer refuses rather
+     * than handing back nonsense field names.
+     */
+    get isEncrypted(): boolean;
+    /** True once the password has been accepted and the contents decrypted, so what is read is plaintext.
+     *  Always true for a document that was never encrypted. */
+    get isReadable(): boolean;
+    /**
+     * Encipher a value that is about to be written back INTO this document, or `undefined` when the
+     * document is not encrypted and the value goes in as it is.
+     *
+     * Needed because we decrypt everything on open: a string we then hand back to the writer is plaintext
+     * in memory, and writing it into an encrypted file unchanged would both leak it and produce a document
+     * that contradicts its own /Encrypt declaration.
+     */
+    encryptForWrite(data: Uint8Array): Promise<Uint8Array | undefined>;
+    /**
+     * Whether values written back into this document can be enciphered again.
+     *
+     * False for a legacy-encrypted file: we can READ RC4 and AES-128, but writing one would downgrade the
+     * user's document to a broken cipher. Asked BEFORE any work is done - otherwise the refusal depends on
+     * a string happening to be present in whatever we rewrite, which is a guarantee by accident.
+     */
+    get canReEncrypt(): boolean;
+    /** The generation of an object as the file records it. Members of an object stream are always 0. */
+    generationOf(num: number): number;
+    get catalog(): PdfObject | undefined;
+    /** A stream's bytes as they sit in the file: sliced by `/Length`, still filtered and still encrypted. */
+    private rawStream;
+    /** A stream's DECODED bytes: deciphered if the document is encrypted, then run through its filters. */
+    streamData(stream: PdfStream): Uint8Array;
+    /**
+     * Undo a PNG predictor (`/Predictor` 10-15), which xref streams almost always use - the IRS form in
+     * our fixtures does. Each row is prefixed with its filter type and is decoded against the row above.
+     */
+    private undoPredictor;
+    /** Every object number the index knows, ascending - for walking a whole document. */
+    objectNumbers(): number[];
+}
+export { EMPTY };