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

package/dist/api/layout.d.ts

@@ -1,8 +1,7 @@
-import { ContainerElement } from "../elements/container-element.js";
-import { RowElement } from "../elements/row-element.js";
-import { RectangleElement } from "../elements/rectangle-element.js";
 import { ExpandedElement } from "../elements/layout/expanded-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
 import { PositionedElement, PositionedInsets } from "../elements/layout/positioned-element.js";
 import { LinkElement } from "../elements/layout/link-element.js";
 import { BookmarkElement } from "../elements/layout/bookmark-element.js";
@@ -28,13 +27,28 @@ export interface StackOptions {
      *  axis (`height: "50%"` only resolves where the parent bounds the height). */
     width?: SizeInput;
     height?: SizeInput;
+    /** Start this stack on a fresh page (CSS `break-before: page`, react-pdf's `break`). Ignored at the
+     *  top of a page. */
+    breakBefore?: boolean;
+    /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
+    /** Try to keep this stack on one page (CSS `break-inside: avoid`). If it does not fit here but would
+     *  fit on a fresh page, it moves there whole; if it is taller than a whole page, it splits anyway. */
+    keepTogether?: boolean;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
-export declare function Column(children: PDFElement[]): ContainerElement;
-export declare function Column(opts: StackOptions, children: PDFElement[]): ContainerElement;
+export declare function Column(children: PDFElement[]): PDFElement;
+export declare function Column(opts: StackOptions, children: PDFElement[]): PDFElement;
 /** A horizontal stack. `Row(children)` or `Row(opts, children)`. */
-export declare function Row(children: PDFElement[]): RowElement;
-export declare function Row(opts: StackOptions, children: PDFElement[]): RowElement;
+export declare function Row(children: PDFElement[]): PDFElement;
+export declare function Row(opts: StackOptions, children: PDFElement[]): PDFElement;
+/**
+ * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
+ * children in a `Column` and refuses to split them across a page break - unless they do not fit on a
+ * fresh page at all, in which case they split anyway (so pagination always terminates). Equivalent to
+ * the `keepTogether` prop on `Box`/`Column`/`Row`.
+ */
+export declare function keepTogether(children: PDFElement[]): KeepTogetherElement;
 /** A bordered / filled box that wraps its children (locked §4). */
 export interface BoxOptions {
     /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
@@ -65,22 +79,35 @@ export interface BoxOptions {
     /** `"hidden"` crops children to the box (rounded corners included); `"visible"` (default) lets a
      *  `Positioned` child spill over the edge. */
     overflow?: "hidden" | "visible";
+    /** Start this box on a fresh page (CSS `break-before: page`, react-pdf's `break`). Ignored at the top
+     *  of a page. */
+    breakBefore?: boolean;
+    /** Start everything after this box on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
+    /** Try to keep this box on one page (CSS `break-inside: avoid`). Moves whole to a fresh page if it
+     *  would fit there; splits anyway if it is taller than a whole page. */
+    keepTogether?: boolean;
 }
 /**
  * A box: maps to a `RectangleElement` (fill + border + radius) whose children are stacked
  * inside it, optionally inset by `padding` (a `PaddingElement` wrapping a `Column` of the
  * children). With no `border`/`borderWidth` the box has no outline (`borderWidth` 0).
  */
-export declare function Box(children: PDFElement[]): RectangleElement;
-export declare function Box(opts: BoxOptions, children: PDFElement[]): RectangleElement;
+export declare function Box(children: PDFElement[]): PDFElement;
+export declare function Box(opts: BoxOptions, children: PDFElement[]): PDFElement;
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export declare function Padding(padding: Insets, child: PDFElement): PaddingElement;
 /**
- * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Two ways, pick per
- * axis: pin to EDGES - `Positioned({ top, left, right, bottom }, child)`, where a negative value
- * pokes into / out of the corner (a badge, a tab, a ribbon) and pinning both sides stretches; or
- * ANCHOR + nudge - `Positioned({ h: "center", v: "end", x: -10, y: -8 }, child)`, i.e. centered /
- * end-aligned with a pixel offset. An edge wins over an anchor on the same axis.
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box - or, with none, to
+ * the page's content box. Two ways, pick per axis: pin to EDGES - `Positioned({ top, left, right,
+ * bottom }, child)`, where a negative value pokes into / out of the corner (a badge, a tab, a
+ * ribbon) and pinning both sides stretches; or ANCHOR + nudge - `Positioned({ h: "center", v: "end",
+ * x: -10, y: -8 }, child)`, i.e. centered / end-aligned with a pixel offset. An edge wins over an
+ * anchor on the same axis.
+ *
+ * A `Positioned` in a `Page`'s `header` or `footer` repeats on EVERY page and takes no space in the
+ * band, which is how you draw a watermark, a draft stamp or a corner ribbon across a document. It
+ * anchors to the page, not to the band, so `bottom: 0` is the foot of the page.
  */
 export declare function Positioned(opts: PositionedInsets, child: PDFElement): PositionedElement;
 /**
@@ -137,6 +164,12 @@ export declare function RotatedBox(opts: {
  * and `b` to the edges. `flex` weights it against other flex children (default 1).
  */
 export declare function Spacer(flex?: number): ExpandedElement;
+/**
+ * A forced page break. Put it in a `Column` (or any vertical flow) and everything AFTER it starts on
+ * a fresh page, no matter how much space is left: `Column([intro, PageBreak(), chapterTwo])`. It takes
+ * no space and draws nothing. Works nested, and a break wins over `keepTogether`.
+ */
+export declare function PageBreak(): PageBreakElement;
 export interface ExpandedOptions {
     /** Share of the leftover space vs other flex children (default 1). */
     flex?: number;

package/dist/api/layout.js

@@ -3,6 +3,8 @@ import { RowElement } from "../elements/row-element.js";
 import { RectangleElement } from "../elements/rectangle-element.js";
 import { ExpandedElement } from "../elements/layout/expanded-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
 import { PositionedElement } from "../elements/layout/positioned-element.js";
 import { LinkElement } from "../elements/layout/link-element.js";
 import { BookmarkElement } from "../elements/layout/bookmark-element.js";
@@ -24,25 +26,44 @@ function stackSize(opts) {
 const DEFAULT_CROSS = "start";
 export function Column(a, b) {
     const { opts, children } = splitArgs(a, b);
-    return new ContainerElement({
+    return maybeKeepTogether(opts, new ContainerElement({
         x: 0,
         y: 0,
         children,
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
         cross: opts.align ?? DEFAULT_CROSS,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
         ...stackSize(opts),
-    });
+    }));
 }
 export function Row(a, b) {
     const { opts, children } = splitArgs(a, b);
-    return new RowElement({
+    return maybeKeepTogether(opts, new RowElement({
         children,
         gap: opts.gap,
         main: opts.justify,
         cross: opts.align ?? DEFAULT_CROSS,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
         ...stackSize(opts),
-    });
+    }));
+}
+/** Wraps `element` in a `keepTogether` group when the `keepTogether` option is set; otherwise returns it
+ *  unchanged (byte-identical). Shared by the `Box`/`Column`/`Row` prop shortcut. */
+function maybeKeepTogether(opts, element) {
+    return opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+}
+/**
+ * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
+ * children in a `Column` and refuses to split them across a page break - unless they do not fit on a
+ * fresh page at all, in which case they split anyway (so pagination always terminates). Equivalent to
+ * the `keepTogether` prop on `Box`/`Column`/`Row`.
+ */
+export function keepTogether(children) {
+    const child = children.length === 1 ? children[0] : Column(children);
+    return new KeepTogetherElement({ child });
 }
 export function Box(a, b) {
     const { opts, children } = splitArgs(a, b);
@@ -66,7 +87,7 @@ export function Box(a, b) {
     // A point size fills `width`/`height`; a percentage fills `widthFactor`/`heightFactor`.
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
-    return new RectangleElement({
+    return maybeKeepTogether(opts, new RectangleElement({
         x: 0,
         y: 0,
         children: content,
@@ -88,18 +109,25 @@ export function Box(a, b) {
             : undefined,
         relative: opts.relative,
         overflow: opts.overflow,
-    });
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
+    }));
 }
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export function Padding(padding, child) {
     return new PaddingElement({ margin: toEdges(padding), child });
 }
 /**
- * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Two ways, pick per
- * axis: pin to EDGES - `Positioned({ top, left, right, bottom }, child)`, where a negative value
- * pokes into / out of the corner (a badge, a tab, a ribbon) and pinning both sides stretches; or
- * ANCHOR + nudge - `Positioned({ h: "center", v: "end", x: -10, y: -8 }, child)`, i.e. centered /
- * end-aligned with a pixel offset. An edge wins over an anchor on the same axis.
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box - or, with none, to
+ * the page's content box. Two ways, pick per axis: pin to EDGES - `Positioned({ top, left, right,
+ * bottom }, child)`, where a negative value pokes into / out of the corner (a badge, a tab, a
+ * ribbon) and pinning both sides stretches; or ANCHOR + nudge - `Positioned({ h: "center", v: "end",
+ * x: -10, y: -8 }, child)`, i.e. centered / end-aligned with a pixel offset. An edge wins over an
+ * anchor on the same axis.
+ *
+ * A `Positioned` in a `Page`'s `header` or `footer` repeats on EVERY page and takes no space in the
+ * band, which is how you draw a watermark, a draft stamp or a corner ribbon across a document. It
+ * anchors to the page, not to the band, so `bottom: 0` is the foot of the page.
  */
 export function Positioned(opts, child) {
     return new PositionedElement({ child, ...opts });
@@ -161,6 +189,14 @@ export function RotatedBox(opts, child) {
 export function Spacer(flex = 1) {
     return new ExpandedElement({ flex, child: Column([]) });
 }
+/**
+ * A forced page break. Put it in a `Column` (or any vertical flow) and everything AFTER it starts on
+ * a fresh page, no matter how much space is left: `Column([intro, PageBreak(), chapterTwo])`. It takes
+ * no space and draws nothing. Works nested, and a break wins over `keepTogether`.
+ */
+export function PageBreak() {
+    return new PageBreakElement();
+}
 export function Expanded(a, b) {
     const isOptsForm = b !== undefined;
     const opts = (isOptsForm ? a : {});

package/dist/api/structure.d.ts

@@ -132,6 +132,17 @@ export interface RenderOptions {
     standardFonts?: boolean;
     /** FlateDecode-compress the streams (default true). Set false for a greppable, uncompressed PDF. */
     compress?: boolean;
+    /** Kern the text - ON by default (still labelled experimental while we validate against react-pdf).
+     *  Emits `TJ` adjustments from the font's own pairs: standard-14 (AFM), embedded `kern` table, and
+     *  embedded `GPOS` Type 2, so every font path kerns. Set `false` to opt out (byte-identical to the
+     *  pre-kerning output). Verified against headless Chrome and measured == drawn to the thousandth. */
+    kerning?: boolean;
+    /** Bake a form field's VALUE into its own appearance stream (`/AP`) - ON by default. Baked values
+     *  render identically in every viewer and in print, and are what flattening (later) draws from. Set
+     *  `false` to leave text and choice values to the viewer instead (`/NeedAppearances`, what
+     *  react-pdf/pdfkit always do). Checkboxes, radios, buttons and signature boxes always carry their
+     *  own appearance either way - there is no value to defer. Only meaningful with form fields present. */
+    fieldAppearances?: boolean;
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;

package/dist/api/structure.js

@@ -137,6 +137,8 @@ export async function renderPdf(doc, options) {
             const om = this.objectManager;
             om.setCompress(options?.compress !== false); // FlateDecode streams by default
             om.setOverflowPolicy(options?.onOverflow ?? "error");
+            om.setKerning(options?.kerning !== false); // on by default (experimental); `kerning:false` opts out
+            om.acroform.setBakeAppearances(options?.fieldAppearances !== false); // baked unless opted out
             for (const [name, value] of Object.entries(fonts)) {
                 if (isFontBytes(value)) {
                     om.registerCustomFont(name, value);

package/dist/api/text.d.ts

@@ -11,6 +11,17 @@ export interface TextStyle {
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
+    /** Draw a line under the text. Its position and thickness come from the font, not from a guess.
+     *  A `Link` is NOT underlined automatically - say so if you want it. */
+    underline?: boolean;
+    /** Draw a line through the text, at half its x-height (where a browser puts it). */
+    strikethrough?: boolean;
+    /** Let the underline step around descenders, like a browser (`text-decoration-skip-ink`). Needs an
+     *  EMBEDDED font - the standard-14 outlines live in the viewer, so we cannot see where their ink
+     *  is. Asking for it with a standard font is an error, not a silent no-op. */
+    skipInk?: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Negative tightens. Default 0. */
+    letterSpacing?: number;
     /** External URL - makes this run an inline hyperlink (a /Link annotation over its glyphs). On a
      *  `span` it links just that run; on a whole `Text` (plain string) it links the whole text. */
     href?: string;
@@ -26,8 +37,9 @@ export interface TextOptions extends TextStyle {
     maxLines?: number;
     /** What happens past `maxLines`: `"clip"` (default) cuts hard, `"ellipsis"` ends with "…". */
     overflow?: TextOverflow;
-    /** Line-height multiplier (default `1`). `1.4` gives roomier body copy; each line is
-     *  `size * lineHeight` tall. */
+    /** Line-height multiplier: each line is `size * lineHeight` tall. Unset means the font's own
+     *  natural line height (`ascent + descent + lineGap`), like CSS `line-height: normal` - which is
+     *  what you want for body copy. `1` gives exactly one em, which most faces overflow slightly. */
     lineHeight?: number;
     /** Accessibility role for the tagged structure tree (only when rendered with `accessible`): a heading
      *  level `"h1"`..`"h6"` or `"p"` (default). Purely semantic - it does not change the visual style. */
@@ -56,6 +68,10 @@ export interface TextDefaults {
     color?: ColorInput;
     align?: "left" | "center" | "right";
     lineHeight?: number;
+    underline?: boolean;
+    strikethrough?: boolean;
+    skipInk?: boolean;
+    letterSpacing?: number;
 }
 /** Maps the `Text`-style option names onto a partial engine `ResolvedTextStyle` (only the set
  *  fields), for seeding the inheritance cascade. */

package/dist/api/text.js

@@ -50,6 +50,9 @@ export function span(text, style = {}) {
             ? toFontStyle(style.bold, style.italic)
             : undefined,
         fontColor: style.color !== undefined ? toColor(style.color) : undefined,
+        underline: style.underline,
+        strikethrough: style.strikethrough,
+        letterSpacing: style.letterSpacing,
         href: style.href,
         dest: style.to,
     };
@@ -79,6 +82,10 @@ export function Text(content, opts = {}) {
         maxLines: opts.maxLines,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
+        underline: opts.underline,
+        strikethrough: opts.strikethrough,
+        skipInk: opts.skipInk,
+        letterSpacing: opts.letterSpacing,
         role: opts.role,
     });
 }
@@ -103,5 +110,13 @@ export function toTextStyleOverride(opts) {
         style.textAlignment = ALIGN[opts.align];
     if (opts.lineHeight !== undefined)
         style.lineHeight = opts.lineHeight;
+    if (opts.underline !== undefined)
+        style.underline = opts.underline;
+    if (opts.strikethrough !== undefined)
+        style.strikethrough = opts.strikethrough;
+    if (opts.skipInk !== undefined)
+        style.skipInk = opts.skipInk;
+    if (opts.letterSpacing !== undefined)
+        style.letterSpacing = opts.letterSpacing;
     return style;
 }

package/dist/crypto/legacy-handler.d.ts

@@ -0,0 +1,43 @@
+import type { SecurityHandler } from "./security-handler.js";
+/** RC4. Not available in WebCrypto - for good reasons - so it is written out here, for reading only. */
+declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
+/** What the `/Encrypt` dictionary tells us, already parsed by the reader. */
+export interface LegacyEncryptInfo {
+    revision: number;
+    /** `/Length` in BITS (default 40). */
+    keyBits: number;
+    o: Uint8Array;
+    u: Uint8Array;
+    /** `/P`, the permission flags, as the signed 32-bit value the algorithm feeds in. */
+    permissions: number;
+    /** The first string of the document `/ID`. */
+    id: Uint8Array;
+    encryptMetadata: boolean;
+    /** True when the crypt filter is AESV2 rather than RC4. */
+    aes: boolean;
+}
+export declare class StandardLegacy implements SecurityHandler {
+    private readonly fileKey;
+    private readonly aes;
+    private constructor();
+    readonly canEncrypt = false;
+    encryptDict(): string;
+    encrypt(): Promise<Uint8Array>;
+    decrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+    /**
+     * Algorithm 1: every object is enciphered with its own key, derived from the file key plus the
+     * object's number and generation. Miss this and every single object decrypts to noise.
+     */
+    private objectKey;
+    /**
+     * Open a legacy-encrypted document: derive the file key from the password (algorithm 2), then CHECK it
+     * against `/U` (algorithm 6) so a wrong password is rejected rather than silently producing noise.
+     */
+    static open(password: string, info: LegacyEncryptInfo): SecurityHandler;
+    /** Algorithm 6: rebuild what `/U` must look like for this key and compare. */
+    private static passwordMatches;
+}
+export { rc4 };

package/dist/crypto/legacy-handler.js

@@ -0,0 +1,145 @@
+import { aesCbcDecrypt } from "./webcrypto.js";
+import { md5 } from "../utils/md5.js";
+/**
+ * The OLDER standard security handlers, for READING only: R2 and R3 (RC4, 40 and 128 bit) and R4
+ * (RC4 or AES-128).
+ *
+ * Read-only is a deliberate asymmetry, not an omission. RC4 is broken - biased keystream, and R2 uses a
+ * 40-bit key that is brute-forced in minutes - and PDF 2.0 removed it outright. But it is what PDFKit,
+ * react-pdf and Ghostscript still produce BY DEFAULT when you ask them for a password, so refusing to
+ * open such a file means refusing most of the encrypted PDFs anyone actually has. Writing one would be
+ * a different matter: offering a user "protection" we know to be broken helps nobody, so `encrypt`
+ * here throws.
+ *
+ * Two things distinguish these revisions from the modern R6:
+ * - the file key comes from MD5 over the password, `/O`, `/P` and the first `/ID` string (algorithm 2);
+ * - every object gets its OWN key, derived from the file key plus its number and generation
+ *   (algorithm 1). That is why `SecurityHandler.encrypt/decrypt` take a `ref`.
+ */
+/** The padding every legacy revision prepends to a password (algorithm 2, step a). */
+const PAD = new Uint8Array([
+    0x28, 0xbf, 0x4e, 0x5e, 0x4e, 0x75, 0x8a, 0x41, 0x64, 0x00, 0x4e, 0x56, 0xff, 0xfa, 0x01, 0x08,
+    0x2e, 0x2e, 0x00, 0xb6, 0xd0, 0x68, 0x3e, 0x80, 0x2f, 0x0c, 0xa9, 0xfe, 0x64, 0x53, 0x69, 0x7a,
+]);
+/** A password padded (or truncated) to the 32 bytes the algorithm wants. */
+function padPassword(password) {
+    const pw = new Uint8Array(32);
+    // Latin-1: the legacy handlers predate unicode passwords entirely.
+    const raw = Uint8Array.from(password, (c) => c.charCodeAt(0) & 0xff);
+    const take = Math.min(raw.length, 32);
+    pw.set(raw.subarray(0, take), 0);
+    pw.set(PAD.subarray(0, 32 - take), take);
+    return pw;
+}
+/** RC4. Not available in WebCrypto - for good reasons - so it is written out here, for reading only. */
+function rc4(key, data) {
+    const s = new Uint8Array(256);
+    for (let i = 0; i < 256; i++)
+        s[i] = i;
+    for (let i = 0, j = 0; i < 256; i++) {
+        j = (j + s[i] + key[i % key.length]) & 0xff;
+        [s[i], s[j]] = [s[j], s[i]];
+    }
+    const out = new Uint8Array(data.length);
+    for (let k = 0, i = 0, j = 0; k < data.length; k++) {
+        i = (i + 1) & 0xff;
+        j = (j + s[i]) & 0xff;
+        [s[i], s[j]] = [s[j], s[i]];
+        out[k] = data[k] ^ s[(s[i] + s[j]) & 0xff];
+    }
+    return out;
+}
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+};
+export class StandardLegacy {
+    constructor(fileKey, aes) {
+        this.fileKey = fileKey;
+        this.aes = aes;
+        this.canEncrypt = false;
+    }
+    encryptDict() {
+        throw new Error("@jasy/pdf: this handler only READS legacy encryption; jasy writes AES-256 (R6) exclusively");
+    }
+    async encrypt() {
+        throw new Error("@jasy/pdf: refusing to write RC4 or AES-128 - they are obsolete; jasy writes AES-256 (R6)");
+    }
+    async decrypt(data, ref) {
+        const key = this.objectKey(ref);
+        if (!this.aes)
+            return rc4(key, data);
+        if (data.length <= 16)
+            return new Uint8Array(0); // an IV and nothing else
+        return aesCbcDecrypt(key, data.subarray(0, 16), data.subarray(16));
+    }
+    /**
+     * Algorithm 1: every object is enciphered with its own key, derived from the file key plus the
+     * object's number and generation. Miss this and every single object decrypts to noise.
+     */
+    objectKey(ref) {
+        const num = ref?.num ?? 0;
+        const gen = ref?.gen ?? 0;
+        const extra = new Uint8Array(this.aes ? 9 : 5);
+        extra[0] = num & 0xff;
+        extra[1] = (num >> 8) & 0xff;
+        extra[2] = (num >> 16) & 0xff;
+        extra[3] = gen & 0xff;
+        extra[4] = (gen >> 8) & 0xff;
+        // AES adds the literal "sAlT" - the spec really does spell it that way.
+        if (this.aes)
+            extra.set([0x73, 0x41, 0x6c, 0x54], 5);
+        const digest = md5(concat(this.fileKey, extra));
+        return digest.subarray(0, Math.min(this.fileKey.length + 5, 16));
+    }
+    /**
+     * Open a legacy-encrypted document: derive the file key from the password (algorithm 2), then CHECK it
+     * against `/U` (algorithm 6) so a wrong password is rejected rather than silently producing noise.
+     */
+    static open(password, info) {
+        const keyLength = info.revision === 2 ? 5 : Math.max(5, Math.floor(info.keyBits / 8));
+        const p = new Uint8Array(4);
+        new DataView(p.buffer).setInt32(0, info.permissions, true); // little-endian, signed
+        let input = concat(padPassword(password), info.o.subarray(0, 32), p, info.id);
+        // R4 with /EncryptMetadata false folds in four 0xFF bytes.
+        if (info.revision >= 4 && !info.encryptMetadata) {
+            input = concat(input, new Uint8Array([0xff, 0xff, 0xff, 0xff]));
+        }
+        let key = md5(input);
+        if (info.revision >= 3) {
+            // 50 further rounds over the first keyLength bytes only.
+            for (let i = 0; i < 50; i++)
+                key = md5(key.subarray(0, keyLength));
+        }
+        key = key.subarray(0, keyLength);
+        if (!StandardLegacy.passwordMatches(key, info)) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        return new StandardLegacy(key, info.aes);
+    }
+    /** Algorithm 6: rebuild what `/U` must look like for this key and compare. */
+    static passwordMatches(key, info) {
+        if (info.revision === 2) {
+            const expect = rc4(key, PAD);
+            return expect.every((b, i) => b === info.u[i]);
+        }
+        // R3+ : MD5 over the padding and the /ID, then 20 rounds of RC4 with the key XORed by the round.
+        let x = md5(concat(PAD, info.id));
+        x = rc4(key, x);
+        for (let round = 1; round <= 19; round++) {
+            const rk = Uint8Array.from(key, (b) => b ^ round);
+            x = rc4(rk, x);
+        }
+        // Only the first 16 bytes are meaningful; the rest of /U is arbitrary padding.
+        for (let i = 0; i < 16; i++)
+            if (x[i] !== info.u[i])
+                return false;
+        return true;
+    }
+}
+export { rc4 };

package/dist/crypto/security-handler.d.ts

@@ -1,5 +1,8 @@
 /** A handler encrypts/decrypts the strings + streams of a document and describes itself as an `/Encrypt` dict. */
 export interface SecurityHandler {
+    /** Whether this scheme may be WRITTEN. False for the legacy revisions: we open them as a service to
+     *  files that already exist, but handing a user protection known to be broken is not one. */
+    readonly canEncrypt: boolean;
     /** The `/Encrypt` dictionary body (between `<<` and `>>`). Its own strings are never encrypted. */
     encryptDict(): string;
     /** Encrypt one string/stream. `ref` is unused for V5/R6 (one file key) but kept for future per-object schemes. */
@@ -33,6 +36,7 @@ declare class StandardAes256 implements SecurityHandler {
     private readonly dict;
     private constructor();
     static create(opts: EncryptOptions): Promise<StandardAes256>;
+    readonly canEncrypt = true;
     encryptDict(): string;
     encrypt(data: Uint8Array): Promise<Uint8Array>;
     decrypt(data: Uint8Array): Promise<Uint8Array>;
@@ -40,6 +44,18 @@ declare class StandardAes256 implements SecurityHandler {
      *  password is rejected, not silently turned into a garbage key), then decrypt /UE. The groundwork the
      *  future "open/edit existing PDF" path reuses. Throws on a wrong password. */
     static recoverFileKey(userPassword: string, u: Uint8Array, ue: Uint8Array): Promise<Uint8Array>;
+    /**
+     * A handler for READING an existing file: recover its key from the password, then decrypt with it.
+     * The `/Encrypt` dictionary is the file's own, so this handler never has to describe one.
+     *
+     * `revision` 6 is the standard (ISO 32000-2). Revision **5** is Adobe's withdrawn 2008 extension and
+     * differs in ONE respect: the key is a plain SHA-256 of password + salt, without the iterated
+     * procedure of algorithm 2.B. The cipher is the same AES-256, which is why supporting it costs almost
+     * nothing - and it matters, because PDFKit and react-pdf both emit R5 when asked for AES.
+     */
+    static forReading(userPassword: string, u: Uint8Array, ue: Uint8Array, revision?: 5 | 6): Promise<SecurityHandler>;
+    /** Revision 5: validate against /U with a single SHA-256, then unwrap /UE the same way R6 does. */
+    private static recoverFileKeyR5;
 }
 /** The factory = the seam. Today it always returns the AES-256 handler. */
 export declare function createSecurityHandler(opts: EncryptOptions): Promise<SecurityHandler>;

package/dist/crypto/security-handler.js

@@ -59,6 +59,7 @@ class StandardAes256 {
     constructor(fileKey, dict) {
         this.fileKey = fileKey;
         this.dict = dict;
+        this.canEncrypt = true;
     }
     static async create(opts) {
         const user = utf8(opts.userPassword);
@@ -118,6 +119,31 @@ class StandardAes256 {
         const intermediate = await hash2B(pw, u.subarray(40, 48), new Uint8Array(0));
         return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
     }
+    /**
+     * A handler for READING an existing file: recover its key from the password, then decrypt with it.
+     * The `/Encrypt` dictionary is the file's own, so this handler never has to describe one.
+     *
+     * `revision` 6 is the standard (ISO 32000-2). Revision **5** is Adobe's withdrawn 2008 extension and
+     * differs in ONE respect: the key is a plain SHA-256 of password + salt, without the iterated
+     * procedure of algorithm 2.B. The cipher is the same AES-256, which is why supporting it costs almost
+     * nothing - and it matters, because PDFKit and react-pdf both emit R5 when asked for AES.
+     */
+    static async forReading(userPassword, u, ue, revision = 6) {
+        const key = revision === 6
+            ? await StandardAes256.recoverFileKey(userPassword, u, ue)
+            : await StandardAes256.recoverFileKeyR5(userPassword, u, ue);
+        return new StandardAes256(key, "");
+    }
+    /** Revision 5: validate against /U with a single SHA-256, then unwrap /UE the same way R6 does. */
+    static async recoverFileKeyR5(userPassword, u, ue) {
+        const pw = utf8(userPassword);
+        const check = await sha(256, concat(pw, u.subarray(32, 40)));
+        if (!bytesEqual(check, u.subarray(0, 32))) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        const intermediate = await sha(256, concat(pw, u.subarray(40, 48)));
+        return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
+    }
 }
 /** The factory = the seam. Today it always returns the AES-256 handler. */
 export async function createSecurityHandler(opts) {

package/dist/edit/acroform-reader.d.ts

@@ -0,0 +1,70 @@
+import { type PdfDocument } from "./document.js";
+/**
+ * Reads an existing document's `/AcroForm` into a flat list of fields.
+ *
+ * The field tree is the part every producer lays out differently, and where a naive reader goes wrong:
+ *
+ * - **A field and its widget need not be the same object.** pdf-lib splits them (the field carries
+ *   `/T`, `/FT` and `/V`; its `/Kids` are bare widget annotations); PDFKit and our own writer merge
+ *   them into one. Both are legal, so the walk must cope with either.
+ * - **Attributes are inherited.** `/FT`, `/Ff`, `/V` and `/MaxLen` all pass down the tree, so a child may
+ *   state none of them and still have a type, flags and a value (ISO 32000-1 table 220).
+ * - **Names are hierarchical.** The name you address a field by is the `/T` values along the path,
+ *   joined with dots - `address.street`, not `street`.
+ * - **A field may own several widgets** (a radio group, or one field shown on several pages). It is
+ *   still ONE field with one value.
+ */
+/** One field found in an existing document, in the terms a caller thinks in. */
+export interface ReadField {
+    /** The fully qualified name: the `/T` values from the root down, joined with dots. */
+    name: string;
+    /** `Tx` text · `Btn` button (check box, radio, push button) · `Ch` choice · `Sig` signature. */
+    type: "Tx" | "Btn" | "Ch" | "Sig";
+    /** The current value as text, if it has one. A button's value is a name (`Yes`, `Off`). */
+    value?: string;
+    /** A multi-select choice field's values. */
+    values?: string[];
+    /** The `/Ff` field flags, already merged with anything inherited. */
+    flags: number;
+    /** `/MaxLen`: the longest text the field accepts, in characters. Inherited like the type. */
+    maxLen?: number;
+    /** The selectable options of a choice field, as `[export, label]`. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** For a check box or radio group: every export name its widgets can take, besides `Off`. */
+    onValues?: string[];
+    /** The object number of the FIELD dictionary - where `/V` lives, and what an update rewrites. */
+    objNum?: number;
+    /** The widgets that display this field. A radio group has one per button, and each knows only its
+     *  OWN export name, which is what its `/AS` has to be set to. */
+    widgets: ReadWidget[];
+    /** True when no widget carries an appearance stream - filling it means generating one. */
+    needsAppearance: boolean;
+}
+/** One widget annotation belonging to a field. */
+export interface ReadWidget {
+    num?: number;
+    /** The export names this particular widget can show (its `/AP /N` keys, minus `Off`). */
+    onValues: string[];
+    hasAppearance: boolean;
+}
+/** What a document says about its form as a whole. */
+export interface ReadForm {
+    fields: ReadField[];
+    /** The form asks viewers to regenerate every appearance. */
+    needAppearances: boolean;
+    /**
+     * The document carries an XFA packet beside the AcroForm (a "hybrid" form). Filling only the AcroForm
+     * side can be ignored by a viewer that prefers XFA, so this is reported rather than glossed over.
+     */
+    hasXfa: boolean;
+    /** True when the cross-reference table had to be rebuilt to read the file at all. */
+    recovered: boolean;
+}
+/**
+ * Read the form of a loaded document. Returns `undefined` when there is no `/AcroForm` at all - that is
+ * a plain PDF, not an error.
+ */
+export declare function readAcroForm(doc: PdfDocument): ReadForm | undefined;