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

package/dist/api/layout.d.ts

@@ -11,10 +11,11 @@ import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
 import { ColorInput } from "./color.js";
+import { type GradientInput } from "./gradient.js";
 import { Insets } from "./insets.js";
-import { SizeInput } from "./dimension.js";
+import { BoundsInput, SizeInput, RadiusInput } from "./dimension.js";
 /** Options shared by the `Column` and `Row` stacks (locked §4). */
-export interface StackOptions {
+export interface StackOptions extends BoundsInput {
     /** Space inserted between children, in points. */
     gap?: number;
     /** Distribution along the main axis (CSS `justify-content`): start (default) · center · end ·
@@ -35,6 +36,13 @@ export interface StackOptions {
     /** 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;
+    /** Lay the children out backwards along the axis (CSS `row-reverse` / `column-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap: wrap`). The `gap`
+     *  is used BETWEEN the lines as well as between the items. */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). Default `start`. */
+    alignContent?: MainAlign;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
 export declare function Column(children: PDFElement[]): PDFElement;
@@ -50,7 +58,7 @@ export declare function Row(opts: StackOptions, children: PDFElement[]): PDFElem
  */
 export declare function keepTogether(children: PDFElement[]): KeepTogetherElement;
 /** A bordered / filled box that wraps its children (locked §4). */
-export interface BoxOptions {
+export interface BoxOptions extends BoundsInput {
     /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
     border?: ColorInput;
     /** Per-side border colors - override/add to `border`. Any of these makes the box draw
@@ -62,8 +70,8 @@ export interface BoxOptions {
     borderLeft?: ColorInput;
     /** Border thickness in points (default 1 when a border is present). */
     borderWidth?: number;
-    /** Background fill color. */
-    bg?: ColorInput;
+    /** Background: a colour, or a gradient from `linearGradient()` / `radialGradient()`. */
+    bg?: ColorInput | GradientInput;
     /** Inner padding between the border and the children. */
     padding?: Insets;
     /** Size on each axis: a number of points (fixed) or a percentage string like `"50%"` (a fraction
@@ -72,7 +80,7 @@ export interface BoxOptions {
     width?: SizeInput;
     height?: SizeInput;
     /** Corner radius in points. */
-    radius?: number;
+    radius?: RadiusInput;
     /** Make this box a positioning frame: `Positioned` children placed inside it resolve their
      *  offsets against this box (CSS `position: relative`). */
     relative?: boolean;
@@ -173,6 +181,12 @@ export declare function PageBreak(): PageBreakElement;
 export interface ExpandedOptions {
     /** Share of the leftover space vs other flex children (default 1). */
     flex?: number;
+    /**
+     * Main-axis size reserved BEFORE the leftover is shared out (CSS `flex-basis`): points, or a
+     * percentage of what the line offers its items. The child ends up with `basis + its share of the
+     * rest`, so `flexBasis: 120` with `flex: 0` is simply a fixed 120pt slot. Default 0.
+     */
+    flexBasis?: SizeInput;
 }
 /**
  * Makes a child fill the leftover space along the stack's main axis (height in a Column,

package/dist/api/layout.js

@@ -12,14 +12,21 @@ import { AnchorElement } from "../elements/layout/anchor-element.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
 import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
 import { toColor } from "./color.js";
+import { isGradientInput } from "./gradient.js";
 import { toEdges } from "./insets.js";
-import { toDimension } from "./dimension.js";
+import { toBounds, toDimension, toRadius, } from "./dimension.js";
 import { splitArgs } from "./args.js";
 /** Splits `StackOptions` width/height into the fixed points + fraction the stack elements expect. */
 function stackSize(opts) {
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
-    return { width: w?.points, height: h?.points, widthFactor: w?.factor, heightFactor: h?.factor };
+    return {
+        width: w?.points,
+        height: h?.points,
+        widthFactor: w?.factor,
+        heightFactor: h?.factor,
+        ...toBounds(opts),
+    };
 }
 // The public default for `cross` is `start` (locked §5) - i.e. don't stretch a child unless
 // asked. The engine default is `stretch`; the factory sets the friendlier public one.
@@ -33,6 +40,9 @@ export function Column(a, b) {
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
         cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
         breakBefore: opts.breakBefore,
         breakAfter: opts.breakAfter,
         ...stackSize(opts),
@@ -45,6 +55,9 @@ export function Row(a, b) {
         gap: opts.gap,
         main: opts.justify,
         cross: opts.align ?? DEFAULT_CROSS,
+        reverse: opts.reverse,
+        wrap: opts.wrap,
+        alignContent: opts.alignContent,
         breakBefore: opts.breakBefore,
         breakAfter: opts.breakAfter,
         ...stackSize(opts),
@@ -53,7 +66,12 @@ export function Row(a, b) {
 /** 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;
+    // alignSelf and order go on the OUTERMOST element - that is the one the surrounding stack places.
+    const wrapped = opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+    return wrapped
+        .withAlignSelf(opts.alignSelf)
+        .withOrder(opts.order)
+        .withFlexShrink(opts.flexShrink);
 }
 /**
  * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
@@ -92,13 +110,14 @@ export function Box(a, b) {
         y: 0,
         children: content,
         color: opts.border !== undefined ? toColor(opts.border) : undefined,
-        backgroundColor: opts.bg !== undefined ? toColor(opts.bg) : undefined,
+        backgroundColor: opts.bg === undefined ? undefined : isGradientInput(opts.bg) ? opts.bg : toColor(opts.bg),
         borderWidth: hasBorder ? (opts.borderWidth ?? 1) : 0,
         width: w?.points,
         height: h?.points,
         widthFactor: w?.factor,
         heightFactor: h?.factor,
-        radius: opts.radius,
+        ...toBounds(opts),
+        radius: opts.radius !== undefined ? toRadius(opts.radius) : undefined,
         sideBorders: hasPerSide
             ? {
                 top: side(opts.borderTop),
@@ -201,5 +220,11 @@ export function Expanded(a, b) {
     const isOptsForm = b !== undefined;
     const opts = (isOptsForm ? a : {});
     const child = (isOptsForm ? b : a);
-    return new ExpandedElement({ flex: opts.flex ?? 1, child });
+    const basis = opts.flexBasis !== undefined ? toDimension(opts.flexBasis) : undefined;
+    return new ExpandedElement({
+        flex: opts.flex ?? 1,
+        basis: basis?.points,
+        basisFactor: basis?.factor,
+        child,
+    });
 }

package/dist/api/page-builder.d.ts

@@ -16,6 +16,10 @@ export type { PageInfo };
  * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
  * `pageCount` is the document total; `pageSize` is the media box in points.
  *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
  * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
@@ -30,3 +34,7 @@ export interface PageNumberOptions extends TextOptions {
 export declare function PageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
 /** The document's total page count as text. Sugar for `PageBuilder`. */
 export declare function PageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export declare function SubPageNumber({ offset, ...style }?: PageNumberOptions): PageBuilderElement;
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export declare function SubPageCount({ offset, ...style }?: PageNumberOptions): PageBuilderElement;

package/dist/api/page-builder.js

@@ -14,6 +14,10 @@ import { Text } from "./text.js";
  * `pageNumber` is 1-based and counts PHYSICAL pages (an overflowing `Page` contributes several);
  * `pageCount` is the document total; `pageSize` is the media box in points.
  *
+ * `subPageNumber` / `subPageTotalPages` are the same counts WITHIN one logical `Page` element - what you
+ * want when a document is several sections and the footer should say "Attachment, page 1 of 4" beside
+ * "sheet 4 of 7". With a single `Page` they are identical to the document counts.
+ *
  * The numbers themselves are always exact. Two sizing caveats, both from the same chicken-and-egg (the
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
@@ -30,3 +34,11 @@ export function PageNumber({ offset = 0, ...style } = {}) {
 export function PageCount({ offset = 0, ...style } = {}) {
     return PageBuilder(({ pageCount }) => Text(String(pageCount + offset), style));
 }
+/** The page number WITHIN its logical `Page` (a section), as text. Sugar for `PageBuilder`. */
+export function SubPageNumber({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageNumber }) => Text(String(subPageNumber + offset), style));
+}
+/** How many pages the surrounding logical `Page` produced, as text. Sugar for `PageBuilder`. */
+export function SubPageCount({ offset = 0, ...style } = {}) {
+    return PageBuilder(({ subPageTotalPages }) => Text(String(subPageTotalPages + offset), style));
+}

package/dist/api/structure.d.ts

@@ -7,6 +7,7 @@ import { PageSize } from "../constants/page-sizes.js";
 import { type EncryptOptions } from "../crypto/security-handler.js";
 export type { EncryptOptions, Permissions } from "../crypto/security-handler.js";
 import { StackOptions } from "./layout.js";
+import { type UrlFontSource } from "./font-url.js";
 import { Insets } from "./insets.js";
 import { TextDefaults } from "./text.js";
 /** A custom page size. Use the `mm()` helper for millimetres, or pass points directly. */
@@ -78,6 +79,10 @@ export interface JasyDocument extends PDFDocumentElement {
      *  path (read now, on Node), raw bytes, or a styled family. Re-adding a name overwrites it.
      *  A registered font that no `Text` actually uses is dropped at render and costs nothing. */
     addFont(name: string, source: FontSource): this;
+    /** The same, from a URL. Async because the fetch happens NOW, exactly as `addFont` reads a path
+     *  now - so a broken link fails where you asked for the font, not inside a later render.
+     *  `await doc.addFontFromUrl("Inter", "https://…/Inter-Regular.ttf")`, or a styled family of URLs. */
+    addFontFromUrl(name: string, source: UrlFontSource): Promise<this>;
     /** The names of the registered fonts. */
     getFonts(): string[];
     /** Whether a font is registered under `name`. */

package/dist/api/structure.js

@@ -2,7 +2,8 @@ import { readFileBytes } from "../platform/node-fs.js";
 import { PDFDocumentElement } from "../elements/pdf-document-element.js";
 import { PageElement } from "../elements/page-element.js";
 import { DefaultTextStyleElement } from "../elements/layout/default-text-style-element.js";
-import { PageSize } from "../constants/page-sizes.js";
+import { PageSize, pageFormats } from "../constants/page-sizes.js";
+import { resolveEdges } from "../layout/insets.js";
 import { Orientation } from "../renderer/pdf-config.js";
 import { PDFDocument } from "../renderer/pdf-document-class.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
@@ -10,6 +11,7 @@ import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
 import { createSecurityHandler } from "../crypto/security-handler.js";
 import { uaXmp } from "../utils/ua-xmp.js";
 import { Column } from "./layout.js";
+import { loadFontFromUrl } from "./font-url.js";
 import { toEdges } from "./insets.js";
 import { toTextStyleOverride } from "./text.js";
 const MM_TO_PT = 72 / 25.4; // 1 mm in PDF points
@@ -38,10 +40,16 @@ export function Page(a, b) {
     const isOpts = !Array.isArray(a);
     const opts = (isOpts ? a : {});
     const children = (isOpts ? (b ?? []) : a);
-    const [top, right, bottom, left] = toEdges(opts.margin ?? DEFAULT_MARGIN);
+    const size = resolveSize(opts.size);
+    const landscape = opts.orientation === "landscape";
+    // A percentage margin resolves against the page WIDTH (see `Insets`), which is known right here -
+    // the page is the one box whose geometry does not depend on a parent.
+    const [w, h] = size.customSize ?? pageFormats[size.pageSize ?? PageSize.A4];
+    const pageWidth = landscape ? h : w;
+    const [top, right, bottom, left] = resolveEdges(toEdges(opts.margin ?? DEFAULT_MARGIN), pageWidth);
     const config = {
-        ...resolveSize(opts.size),
-        orientation: opts.orientation === "landscape" ? Orientation.landscape : Orientation.portrait,
+        ...size,
+        orientation: landscape ? Orientation.landscape : Orientation.portrait,
         margin: { top, right, bottom, left },
     };
     return new PageElement({
@@ -93,6 +101,10 @@ export function Document(a, b) {
         registry.set(name, resolveFontSource(source));
         return doc;
     };
+    doc.addFontFromUrl = async (name, source) => {
+        registry.set(name, await loadFontFromUrl(source));
+        return doc;
+    };
     doc.getFonts = () => [...registry.keys()];
     doc.hasFont = (name) => registry.has(name);
     return doc;

package/dist/api/text.d.ts

@@ -1,13 +1,16 @@
-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 };
 /** 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 +25,19 @@ 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;
+    /** 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;
@@ -31,10 +47,18 @@ export interface TextStyle {
 }
 export interface TextOptions extends TextStyle {
     /** 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 +86,28 @@ 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;
 }
 /** 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,26 @@ 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,
         role: opts.role,
     });
 }
@@ -99,8 +113,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 +134,13 @@ 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;
     return style;
 }

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 {
 }