@jasy/pdf 1.0.0-alpha.8 → 1.0.0-beta.1

package/dist/api/text.d.ts

@@ -1,13 +1,17 @@
-import { TextElement, TextRole, TextSegment } from "../elements/text-element.js";
+import { TextElement, TextRole, TextSegment, type VerticalTextAlign } from "../elements/text-element.js";
 import { TextOverflow } from "../text/line-breaker.js";
-import { ResolvedTextStyle } from "../text/text-style.js";
+import type { Direction } from "../text/bidi.js";
+import { ResolvedTextStyle, type TextTransform } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
-export type { TextOverflow };
+import type { Hyphenator } from "../text/word-splitting.js";
+export type { TextOverflow, Direction, TextTransform, Hyphenator };
 /** Text styling shared by `Text`, `Paragraph` and `span`. `bold`/`italic` are booleans
  *  (locked §7.3) and combine into one engine `FontStyle`. */
 export interface TextStyle {
     size?: number;
-    font?: string;
+    /** Font family, or a STACK: each code point is drawn by the first family in the list that has a
+     *  glyph for it, so `["Inter", "NotoSansCJK"]` sets mixed-script text without splitting it by hand. */
+    font?: string | string[];
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
@@ -22,6 +26,29 @@ export interface TextStyle {
     skipInk?: boolean;
     /** Extra space after every glyph, in points (CSS `letter-spacing`). Negative tightens. Default 0. */
     letterSpacing?: number;
+    /** Base writing direction (CSS `direction`): `"rtl"` starts the line on the right, for Hebrew or
+     *  Arabic. Mixed text is reordered per Unicode UAX #9 either way, so Hebrew inside an `ltr`
+     *  paragraph already comes out right - this decides where the LINE starts. */
+    direction?: Direction;
+    /** CSS `text-transform`: recase the text. `capitalize` upper-cases the first letter of each word. */
+    textTransform?: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
+    wordSpacing?: number;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent?: number;
+    /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
+     *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
+     *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
+    breakWord?: boolean;
+    /** The ligatures the font's designer drew (`fi`, `fl`, `ffi`). ON by default, like kerning -
+     *  `false` opts this text out. Embedded fonts only; the standard-14 have no GSUB. */
+    ligatures?: boolean;
+    /** Language-aware splitting: given a word, return its parts. A hyphen is drawn at the break.
+     *  Pluggable, so no pattern data ships here: pass `hyphen`, `hyphenopoly`, or your own. */
+    hyphenate?: Hyphenator;
+    /** CSS `vertical-align` for a SPAN: raises a footnote marker or lowers an index. It shifts the
+     *  baseline only - pass a smaller `size` too if you want the browser's `<sup>` look. */
+    verticalAlign?: VerticalTextAlign;
     /** 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;
@@ -29,12 +56,20 @@ export interface TextStyle {
      *  same-document /GoTo instead of a URL). Use for a clickable table of contents / cross-reference. */
     to?: string;
 }
-export interface TextOptions extends TextStyle {
+export interface TextOptions extends Omit<TextStyle, "verticalAlign"> {
     /** Text-internal alignment (left/center/right) - independent of a parent's `cross` (§5). */
-    align?: "left" | "center" | "right";
+    align?: "left" | "center" | "right" | "justify";
     /** Cap the number of wrapped lines (default: unlimited - the text grows down as far as it needs,
      *  paginating onto the next page). Needs a bounded width (a Column/Expanded/`Box({ width })`). */
     maxLines?: number;
+    /**
+     * Minimum lines that must stay behind at a page break (CSS `orphans`), and minimum that must carry
+     * over (CSS `widows`). Both default to 2, the CSS initial value: a single line stranded at the foot of
+     * a page - or alone at the top of the next - reads as a mistake. Set both to 1 to switch the protection
+     * off and let a paragraph break wherever the page ends.
+     */
+    orphans?: number;
+    widows?: number;
     /** What happens past `maxLines`: `"clip"` (default) cuts hard, `"ellipsis"` ends with "…". */
     overflow?: TextOverflow;
     /** Line-height multiplier: each line is `size * lineHeight` tall. Unset means the font's own
@@ -62,16 +97,38 @@ export declare function Paragraph(content: string | TextSegment[], opts?: TextOp
  *  Unset fields stay out so they keep inheriting. */
 export interface TextDefaults {
     size?: number;
-    font?: string;
+    /** Font family, or a STACK: each code point is drawn by the first family in the list that has a
+     *  glyph for it, so `["Inter", "NotoSansCJK"]` sets mixed-script text without splitting it by hand. */
+    font?: string | string[];
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
-    align?: "left" | "center" | "right";
+    align?: "left" | "center" | "right" | "justify";
     lineHeight?: number;
     underline?: boolean;
     strikethrough?: boolean;
     skipInk?: boolean;
     letterSpacing?: number;
+    /** Base writing direction (CSS `direction`): `"rtl"` starts the line on the right, for Hebrew or
+     *  Arabic. Mixed text is reordered per Unicode UAX #9 either way, so Hebrew inside an `ltr`
+     *  paragraph already comes out right - this decides where the LINE starts. */
+    direction?: Direction;
+    /** CSS `text-transform`: recase the text. `capitalize` upper-cases the first letter of each word. */
+    textTransform?: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
+    wordSpacing?: number;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent?: number;
+    /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
+     *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
+     *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
+    breakWord?: boolean;
+    /** The ligatures the font's designer drew (`fi`, `fl`, `ffi`). ON by default, like kerning -
+     *  `false` opts this text out. Embedded fonts only; the standard-14 have no GSUB. */
+    ligatures?: boolean;
+    /** Language-aware splitting: given a word, return its parts. A hyphen is drawn at the break.
+     *  Pluggable, so no pattern data ships here: pass `hyphen`, `hyphenopoly`, or your own. */
+    hyphenate?: Hyphenator;
 }
 /** 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

@@ -1,4 +1,4 @@
-import { TextElement } from "../elements/text-element.js";
+import { TextElement, } from "../elements/text-element.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { toColor } from "./color.js";
@@ -12,10 +12,15 @@ function toFontStyle(bold, italic) {
         return FontStyle.Italic;
     return FontStyle.Normal;
 }
+/** The family a run starts in - the first of a stack, or the single name given. */
+const primaryFont = (font) => Array.isArray(font) ? font[0] : font;
+/** The rest of the stack, tried in order for a code point the first family cannot draw. */
+const fallbackFonts = (font) => Array.isArray(font) ? font.slice(1) : undefined;
 const ALIGN = {
     left: HorizontalAlignment.left,
     center: HorizontalAlignment.center,
     right: HorizontalAlignment.right,
+    justify: HorizontalAlignment.justify,
 };
 /**
  * Validates a font `size` (a number of points). Rejects anything that would silently become a NaN
@@ -45,7 +50,8 @@ export function span(text, style = {}) {
     return {
         content: text,
         fontSize: toFontSize(style.size),
-        fontFamily: style.font,
+        fontFamily: primaryFont(style.font),
+        fontFallback: fallbackFonts(style.font),
         fontStyle: style.bold !== undefined || style.italic !== undefined
             ? toFontStyle(style.bold, style.italic)
             : undefined,
@@ -53,6 +59,7 @@ export function span(text, style = {}) {
         underline: style.underline,
         strikethrough: style.strikethrough,
         letterSpacing: style.letterSpacing,
+        verticalAlign: style.verticalAlign,
         href: style.href,
         dest: style.to,
     };
@@ -73,19 +80,29 @@ export function Text(content, opts = {}) {
     return new TextElement({
         content: body,
         fontSize: toFontSize(opts.size),
-        fontFamily: opts.font,
+        fontFamily: primaryFont(opts.font),
+        fontFallback: fallbackFonts(opts.font),
         fontStyle: opts.bold !== undefined || opts.italic !== undefined
             ? toFontStyle(opts.bold, opts.italic)
             : undefined,
         color: opts.color !== undefined ? toColor(opts.color) : undefined,
         textAlignment: opts.align ? ALIGN[opts.align] : undefined,
         maxLines: opts.maxLines,
+        orphans: opts.orphans,
+        widows: opts.widows,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
         underline: opts.underline,
         strikethrough: opts.strikethrough,
         skipInk: opts.skipInk,
         letterSpacing: opts.letterSpacing,
+        direction: opts.direction,
+        textTransform: opts.textTransform,
+        wordSpacing: opts.wordSpacing,
+        textIndent: opts.textIndent,
+        breakWord: opts.breakWord,
+        ligatures: opts.ligatures,
+        hyphenate: opts.hyphenate,
         role: opts.role,
     });
 }
@@ -99,8 +116,10 @@ export function toTextStyleOverride(opts) {
     const style = {};
     if (opts.size !== undefined)
         style.fontSize = toFontSize(opts.size);
-    if (opts.font !== undefined)
-        style.fontFamily = opts.font;
+    if (opts.font !== undefined) {
+        style.fontFamily = primaryFont(opts.font);
+        style.fontFallback = fallbackFonts(opts.font);
+    }
     if (opts.bold !== undefined || opts.italic !== undefined) {
         style.fontStyle = toFontStyle(opts.bold, opts.italic);
     }
@@ -118,5 +137,19 @@ export function toTextStyleOverride(opts) {
         style.skipInk = opts.skipInk;
     if (opts.letterSpacing !== undefined)
         style.letterSpacing = opts.letterSpacing;
+    if (opts.direction !== undefined)
+        style.direction = opts.direction;
+    if (opts.textTransform !== undefined)
+        style.textTransform = opts.textTransform;
+    if (opts.wordSpacing !== undefined)
+        style.wordSpacing = opts.wordSpacing;
+    if (opts.textIndent !== undefined)
+        style.textIndent = opts.textIndent;
+    if (opts.breakWord !== undefined)
+        style.breakWord = opts.breakWord;
+    if (opts.ligatures !== undefined)
+        style.ligatures = opts.ligatures;
+    if (opts.hyphenate !== undefined)
+        style.hyphenate = opts.hyphenate;
     return style;
 }

package/dist/canvas/painter.d.ts

@@ -0,0 +1,102 @@
+import { type ColorInput } from "../api/color.js";
+import { type GradientInput } from "../api/gradient.js";
+import type { IRNode, StrokeStyle } from "../ir/display-list.js";
+/**
+ * The imperative escape hatch: a box in the layout that you draw into yourself.
+ *
+ * It is the SECOND producer of the vector layer (SVG is the first), so it needs no new IR and no
+ * backend change - everything it draws is a `Path` node like any other, which means it tags, it
+ * paginates, and it works in the browser.
+ *
+ * Three deliberate departures from the PDFKit-shaped painters (react-pdf's included):
+ *
+ * 1. **Typed to the value.** `cap: "round"` autocompletes and a wrong one is a compile error, where
+ *    react-pdf's `paint` callback receives `painter: any` - no help on the one thing you use.
+ * 2. **No hidden state.** There is no `lineWidth(2)` that a later `stroke()` happens to pick up, and
+ *    no `save()`/`restore()` pair to forget: a transform or a clip is a SCOPE (`group`, `clipped`)
+ *    that closes itself.
+ * 3. **One coordinate system.** Top-left, y down, points - the same as every other element in jasy
+ *    and the same as SVG. The origin is the canvas box, so `0,0` is its own corner.
+ */
+/** Where a shape ends up. A gradient resolves against the shape's own bounding box, as in SVG. */
+export type PaintInput = ColorInput | GradientInput;
+export interface StrokeOptions {
+    /** Line width in points. Default 1. */
+    width?: number;
+    cap?: StrokeStyle["cap"];
+    join?: StrokeStyle["join"];
+    miterLimit?: number;
+    /** Dash lengths in points, plus the phase to start at. */
+    dash?: number[];
+    dashOffset?: number;
+}
+export interface FillOptions {
+    /** `evenodd` cuts a hole where subpaths overlap an odd number of times. Default `nonzero`. */
+    rule?: "nonzero" | "evenodd";
+}
+/** A transform applied for the duration of a `group`. Composed in this order: translate, rotate, scale. */
+export interface TransformOptions {
+    translate?: [number, number];
+    /** Degrees, clockwise on the page. */
+    rotate?: number;
+    /** One number scales both axes. */
+    scale?: number | [number, number];
+    /** The point `rotate` and `scale` happen around. Default `[0, 0]`. */
+    origin?: [number, number];
+}
+/** The size the callback was given, so a drawing can be written relative to its box. */
+export interface CanvasSize {
+    width: number;
+    height: number;
+}
+export declare class CanvasPainter {
+    readonly size: CanvasSize;
+    /** The nodes drawn so far, in order. */
+    private readonly nodes;
+    /** The path being built. Emptied by every painting call, so a shape cannot leak into the next. */
+    private current;
+    private cursor;
+    private start;
+    constructor(size: CanvasSize);
+    /** Everything drawn, for the renderer. */
+    drawn(): IRNode[];
+    move(x: number, y: number): this;
+    line(x: number, y: number): this;
+    /** A cubic Bézier - the curve PDF draws natively. */
+    curve(x1: number, y1: number, x2: number, y2: number, x: number, y: number): this;
+    /** A quadratic Bézier. PDF has no operator for one, so it is raised to a cubic exactly. */
+    quad(cx: number, cy: number, x: number, y: number): this;
+    close(): this;
+    rect(x: number, y: number, width: number, height: number): this;
+    circle(cx: number, cy: number, r: number): this;
+    /** Four cubics; the constant is the standard circle-to-Bézier one. */
+    ellipse(cx: number, cy: number, rx: number, ry: number): this;
+    polygon(points: readonly (readonly [number, number])[]): this;
+    /** SVG path data, through the same reader `Svg()` uses - arcs and shorthands included. */
+    path(d: string): this;
+    /** Fills the path built so far and starts a new one. Default black, as in SVG and PDF. */
+    fill(paint?: PaintInput, options?: FillOptions): this;
+    /** Strokes the path built so far and starts a new one. */
+    stroke(color?: ColorInput, options?: StrokeOptions): this;
+    fillAndStroke(paint: PaintInput, color: ColorInput, options?: StrokeOptions & FillOptions): this;
+    /**
+     * Draws inside a transform. It closes itself, so there is no `restore()` to forget - and a nested
+     * `group` composes, exactly like a `<g transform>` in SVG.
+     */
+    group(transform: TransformOptions, draw: (c: CanvasPainter) => void): this;
+    /**
+     * Draws clipped to a path. `build` draws the clip shape (nothing is painted from it), `draw` draws
+     * what the clip applies to.
+     */
+    clipped(build: (c: CanvasPainter) => void, draw: (c: CanvasPainter) => void, options?: FillOptions): this;
+    private paint;
+    /**
+     * A path may not cross the edge of a scope. It would be built in one coordinate space and painted
+     * in another, and the version that just dropped it made a shape vanish without a word - exactly
+     * the silence this codebase refuses everywhere else.
+     */
+    private assertNoPendingPath;
+    private resolve;
+    private strokeStyle;
+    private matrixOf;
+}

package/dist/canvas/painter.js

@@ -0,0 +1,183 @@
+import { toColor } from "../api/color.js";
+import { isGradientInput, resolveGradient } from "../api/gradient.js";
+import { pathData } from "../svg/shapes.js";
+import { boundsOf, quadToCubic } from "../vector/path.js";
+const DEGREES = Math.PI / 180;
+export class CanvasPainter {
+    constructor(size) {
+        this.size = size;
+        /** The nodes drawn so far, in order. */
+        this.nodes = [];
+        /** The path being built. Emptied by every painting call, so a shape cannot leak into the next. */
+        this.current = [];
+        this.cursor = [0, 0];
+        this.start = [0, 0];
+    }
+    /** Everything drawn, for the renderer. */
+    drawn() {
+        return this.nodes;
+    }
+    // --- building a path ---------------------------------------------------------------------------
+    move(x, y) {
+        this.current.push({ op: "m", x, y });
+        this.cursor = [x, y];
+        this.start = [x, y];
+        return this;
+    }
+    line(x, y) {
+        this.current.push({ op: "l", x, y });
+        this.cursor = [x, y];
+        return this;
+    }
+    /** A cubic Bézier - the curve PDF draws natively. */
+    curve(x1, y1, x2, y2, x, y) {
+        this.current.push({ op: "c", x1, y1, x2, y2, x, y });
+        this.cursor = [x, y];
+        return this;
+    }
+    /** A quadratic Bézier. PDF has no operator for one, so it is raised to a cubic exactly. */
+    quad(cx, cy, x, y) {
+        this.current.push(quadToCubic(this.cursor[0], this.cursor[1], cx, cy, x, y));
+        this.cursor = [x, y];
+        return this;
+    }
+    close() {
+        this.current.push({ op: "z" });
+        this.cursor = [...this.start];
+        return this;
+    }
+    rect(x, y, width, height) {
+        return this.move(x, y)
+            .line(x + width, y)
+            .line(x + width, y + height)
+            .line(x, y + height)
+            .close();
+    }
+    circle(cx, cy, r) {
+        return this.ellipse(cx, cy, r, r);
+    }
+    /** Four cubics; the constant is the standard circle-to-Bézier one. */
+    ellipse(cx, cy, rx, ry) {
+        const k = 0.5522847498307936;
+        const [ox, oy] = [rx * k, ry * k];
+        return this.move(cx - rx, cy)
+            .curve(cx - rx, cy - oy, cx - ox, cy - ry, cx, cy - ry)
+            .curve(cx + ox, cy - ry, cx + rx, cy - oy, cx + rx, cy)
+            .curve(cx + rx, cy + oy, cx + ox, cy + ry, cx, cy + ry)
+            .curve(cx - ox, cy + ry, cx - rx, cy + oy, cx - rx, cy)
+            .close();
+    }
+    polygon(points) {
+        if (points.length === 0)
+            return this;
+        this.move(points[0][0], points[0][1]);
+        for (const [x, y] of points.slice(1))
+            this.line(x, y);
+        return this.close();
+    }
+    /** SVG path data, through the same reader `Svg()` uses - arcs and shorthands included. */
+    path(d) {
+        const parsed = pathData(d);
+        this.current.push(...parsed);
+        // Where the pen ends up: after a `z` it is back at that subpath's `m`, not at the last point.
+        for (const cmd of parsed) {
+            if (cmd.op === "m")
+                this.start = [cmd.x, cmd.y];
+            this.cursor = cmd.op === "z" ? [...this.start] : [cmd.x, cmd.y];
+        }
+        return this;
+    }
+    // --- painting it -------------------------------------------------------------------------------
+    /** Fills the path built so far and starts a new one. Default black, as in SVG and PDF. */
+    fill(paint = "black", options = {}) {
+        return this.paint(this.resolve(paint), undefined, options.rule);
+    }
+    /** Strokes the path built so far and starts a new one. */
+    stroke(color = "black", options = {}) {
+        return this.paint(undefined, this.strokeStyle(color, options));
+    }
+    fillAndStroke(paint, color, options = {}) {
+        return this.paint(this.resolve(paint), this.strokeStyle(color, options), options.rule);
+    }
+    // --- scopes, instead of save/restore -----------------------------------------------------------
+    /**
+     * Draws inside a transform. It closes itself, so there is no `restore()` to forget - and a nested
+     * `group` composes, exactly like a `<g transform>` in SVG.
+     */
+    group(transform, draw) {
+        this.assertNoPendingPath("group");
+        const matrix = this.matrixOf(transform);
+        this.nodes.push({ type: "transform-push", matrix });
+        draw(this);
+        this.assertNoPendingPath("group");
+        this.nodes.push({ type: "transform-pop" });
+        return this;
+    }
+    /**
+     * Draws clipped to a path. `build` draws the clip shape (nothing is painted from it), `draw` draws
+     * what the clip applies to.
+     */
+    clipped(build, draw, options = {}) {
+        this.assertNoPendingPath("clipped");
+        build(this);
+        const commands = this.current;
+        this.current = [];
+        this.nodes.push({ type: "clip-path-push", commands, fillRule: options.rule });
+        draw(this);
+        this.assertNoPendingPath("clipped");
+        this.nodes.push({ type: "clip-pop" });
+        return this;
+    }
+    // --- internals ---------------------------------------------------------------------------------
+    paint(fill, stroke, rule) {
+        const commands = this.current;
+        this.current = [];
+        if (commands.length === 0)
+            return this;
+        this.nodes.push({ type: "path", commands, fill, fillRule: rule, stroke });
+        return this;
+    }
+    /**
+     * A path may not cross the edge of a scope. It would be built in one coordinate space and painted
+     * in another, and the version that just dropped it made a shape vanish without a word - exactly
+     * the silence this codebase refuses everywhere else.
+     */
+    assertNoPendingPath(scope) {
+        if (this.current.length === 0)
+            return;
+        this.current = [];
+        throw new Error(`@jasy/pdf: a Canvas path was built but never filled or stroked around \`${scope}()\`. ` +
+            `Paint it before the scope opens, or move the drawing inside it.`);
+    }
+    resolve(paint) {
+        if (isGradientInput(paint)) {
+            const box = boundsOf(this.current);
+            return resolveGradient(paint, box.x, box.y, box.width, box.height);
+        }
+        return toColor(paint);
+    }
+    strokeStyle(color, options) {
+        return {
+            color: toColor(color),
+            width: options.width ?? 1,
+            cap: options.cap,
+            join: options.join,
+            miterLimit: options.miterLimit,
+            dash: options.dash,
+            dashOffset: options.dashOffset,
+        };
+    }
+    matrixOf(t) {
+        const [ox, oy] = t.origin ?? [0, 0];
+        const [sx, sy] = Array.isArray(t.scale) ? t.scale : [t.scale ?? 1, t.scale ?? 1];
+        const theta = (t.rotate ?? 0) * DEGREES;
+        const [cos, sin] = [Math.cos(theta), Math.sin(theta)];
+        // T(translate) · T(origin) · R · S · T(-origin), written out as a PDF `cm` operand.
+        const [a, b, c, d] = [cos * sx, sin * sx, -sin * sy, cos * sy];
+        const [tx, ty] = t.translate ?? [0, 0];
+        // `-sin(0)` is -0, which is a surprising value to read back out of a matrix. It writes as
+        // "0.000" either way, so normalising costs nothing and keeps the number predictable.
+        const zero = (n) => (n === 0 ? 0 : n);
+        return [a, b, c, d, tx + ox - (a * ox + c * oy), ty + oy - (b * ox + d * oy)].map(zero);
+    }
+}

package/dist/edit/document.d.ts

@@ -1,5 +1,15 @@
 import { type PdfDict, type PdfObject, type PdfStream } from "./objects.js";
 declare const EMPTY: Uint8Array<ArrayBuffer>;
+/** What `PdfDocument.load` accepts. */
+export interface LoadOptions {
+    /** Ceiling on what ONE stream may inflate to, in bytes (default 64 MB). Raise it for a document that
+     *  is genuinely enormous; a stream past it throws `PdfStreamTooLargeError` rather than being read. */
+    maxStreamSize?: number;
+}
+/** What `PdfDocument.open` accepts - everything `load` takes, plus the password. */
+export interface OpenOptions extends LoadOptions {
+    password?: string;
+}
 /** 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 {
@@ -23,8 +33,10 @@ export declare class PdfDocument {
      *  update has to follow suit: mixing the two leaves readers that understand only one kind unable to
      *  walk the chain back. */
     usesXrefStream: boolean;
+    /** Ceiling on what one stream may inflate to; see `inflate.ts`. */
+    private maxStreamSize;
     private constructor();
-    static load(bytes: Uint8Array): PdfDocument;
+    static load(bytes: Uint8Array, opts?: LoadOptions): PdfDocument;
     /**
      * Open a document, decrypting it when it is password-protected.
      *
@@ -33,9 +45,7 @@ export declare class PdfDocument {
      * 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>;
+    static open(bytes: Uint8Array, opts?: OpenOptions): Promise<PdfDocument>;
     /**
      * Build the handler for this file's `/Encrypt` dictionary, or say precisely why we cannot.
      *

package/dist/edit/document.js

@@ -1,6 +1,6 @@
-import { unzlibSync } from "fflate";
 import { Lexer } from "./lexer.js";
-import { get, isDict, isRef, isStream, isString, nameOf, numberOf, } from "./objects.js";
+import { DEFAULT_MAX_STREAM_SIZE, inflateBounded, PdfStreamTooLargeError, } from "../utils/inflate.js";
+import { get, isDict, isRef, isStream, isString, nameOf, numberOf, stringsIn, } from "./objects.js";
 import { StandardAes256 } from "../crypto/security-handler.js";
 import { StandardLegacy } from "../crypto/legacy-handler.js";
 const EMPTY = new Uint8Array(0);
@@ -13,22 +13,6 @@ export class PdfEncryptedError extends Error {
 }
 /** The raw bytes of a `/Encrypt` entry that must be a string (`/U`, `/UE`). */
 const stringBytes = (o) => isString(o) ? o.bytes : undefined;
-/** Every string reachable inside an object, so the whole tree can be decrypted in one walk. */
-function stringsIn(o, out = [], depth = 0) {
-    if (o === undefined || o === null || depth > 64)
-        return out;
-    if (isString(o))
-        out.push(o);
-    else if (Array.isArray(o))
-        for (const e of o)
-            stringsIn(e, out, depth + 1);
-    else if (isStream(o))
-        stringsIn(o.dict, out, depth + 1);
-    else if (isDict(o))
-        for (const v of o.map.values())
-            stringsIn(v, out, depth + 1);
-    return out;
-}
 export class PdfDocument {
     constructor(bytes) {
         this.bytes = bytes;
@@ -46,9 +30,13 @@ export class PdfDocument {
          *  update has to follow suit: mixing the two leaves readers that understand only one kind unable to
          *  walk the chain back. */
         this.usesXrefStream = false;
+        /** Ceiling on what one stream may inflate to; see `inflate.ts`. */
+        this.maxStreamSize = DEFAULT_MAX_STREAM_SIZE;
     }
-    static load(bytes) {
+    static load(bytes, opts = {}) {
         const doc = new PdfDocument(bytes);
+        if (opts.maxStreamSize !== undefined)
+            doc.maxStreamSize = opts.maxStreamSize;
         try {
             doc.readXrefChain();
         }
@@ -70,7 +58,7 @@ export class PdfDocument {
      * before the synchronous constructor).
      */
     static async open(bytes, opts = {}) {
-        const doc = PdfDocument.load(bytes);
+        const doc = PdfDocument.load(bytes, opts);
         if (!doc.isEncrypted)
             return doc;
         doc.security = await doc.securityHandlerFor(opts.password);
@@ -577,9 +565,14 @@ export class PdfDocument {
         filters.forEach((filter, i) => {
             if (filter === "FlateDecode") {
                 try {
-                    data = unzlibSync(data);
+                    // Per pass, because /Filter is a list and [/FlateDecode /FlateDecode] is a legal nested bomb.
+                    data = inflateBounded(data, this.maxStreamSize);
                 }
-                catch {
+                catch (e) {
+                    // A stream that blew the ceiling is an attack, not a stream we failed to decode - swallowing
+                    // it here would hand back silent garbage.
+                    if (e instanceof PdfStreamTooLargeError)
+                        throw e;
                     return; // not our data to repair; hand back what we have
                 }
                 data = this.undoPredictor(data, this.resolve(parms[i]));

package/dist/edit/fill.d.ts

@@ -16,6 +16,8 @@ export type FieldValue = string | boolean | string[] | null;
 export interface FillOptions {
     /** The user password, for a document that is encrypted. Wrong or missing gives a named error. */
     password?: string;
+    /** Ceiling on what ONE stream may inflate to, in bytes (default 64 MB) - the zip-bomb guard. */
+    maxStreamSize?: number;
     /**
      * Draw the new value into the field's appearance (default `true`), the same way jasy bakes one when it
      * CREATES a field - so the value is visible in any viewer, not only in one that honours
@@ -23,10 +25,23 @@ export interface FillOptions {
      */
     fieldAppearances?: boolean;
     /**
-     * Leave the drawing of the values to the viewer by setting `/NeedAppearances`, instead of generating
-     * appearance streams. Default `true` today - baking them is the next step.
+     * Ask the viewer to draw the values itself, by setting `/NeedAppearances true` (default `true`).
+     *
+     * The two options answer the same question and exactly one of them ends up applying: when we DID
+     * bake, the flag is written as `false`, because a form that still asks for regeneration gets it and
+     * the viewer throws our drawing away. Turning BOTH off is refused - see `fillForm`.
      */
     needAppearances?: boolean;
+    /**
+     * Flatten the form after filling it (default `false`): the values become ordinary page content and
+     * the fields stop being editable. The whole form is flattened, not only the names in `values` - a
+     * document where some fields are frozen and others are not is the surprising outcome, and
+     * `flattenForm(bytes, { fields })` is there for anyone who wants that on purpose.
+     *
+     * Filling and flattening in one call produces ONE incremental update rather than two, so the file
+     * stays smaller than calling them in sequence - and the result is identical either way.
+     */
+    flatten?: boolean;
 }
 export interface FillResult {
     bytes: Uint8Array;
@@ -34,6 +49,8 @@ export interface FillResult {
     warnings: string[];
     /** The names actually written. */
     filled: string[];
+    /** The names turned into page content, when `flatten` was asked for. Empty otherwise. */
+    flattened: string[];
 }
 declare class FillError extends Error {
 }