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

package/dist/edit/fill.js

@@ -1,9 +1,10 @@
 import { PdfDocument } from "./document.js";
 import { readAcroForm } from "./acroform-reader.js";
-import { IncrementalWriter, serialize } from "./writer.js";
+import { carryStrings, IncrementalWriter, serialize } from "./writer.js";
 import { bakeAppearance, bakeButtonStates, fontMetrics, readLook } from "./appearance.js";
+import { flattenInto } from "./flatten.js";
 import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
-import { get, isDict, isRef, isString, } from "./objects.js";
+import { get, isDict, isRef } from "./objects.js";
 /** Field flags we have to honour when filling (see `forms/acroform.ts` for the writer's side). */
 const FF_READ_ONLY = 1 << 0;
 const FF_MULTI_SELECT = 1 << 21;
@@ -65,19 +66,6 @@ function withEntries(dict, changes, cipher) {
     return `<< ${parts.join(" ")} >>`;
 }
 /** Every string reachable inside an object, so a dictionary can be re-enciphered 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 (isDict(o))
-        for (const v of o.map.values())
-            stringsIn(v, out, depth + 1);
-    return out;
-}
 /**
  * Draw the field again for its NEW value and append the XObject, returning its object number. Falls back
  * to `undefined` when the widget does not say enough about itself to draw it - then the caller drops the
@@ -117,7 +105,24 @@ async function bakeStatesFor(doc, writer, field, widgetNum, state) {
             data: (await doc.encryptForWrite(encoded)) ?? encoded,
         });
     };
-    return `<< /N << /${escName(on)} ${await write(faces.on)} 0 R /Off ${await write(faces.off)} 0 R >> >>`;
+    // The object numbers come back too: a flatten in the same pass stamps one of these two states.
+    const onNum = await write(faces.on);
+    const offNum = await write(faces.off);
+    return {
+        ap: `<< /N << /${escName(on)} ${onNum} 0 R /Off ${offNum} 0 R >> >>`,
+        states: new Map([
+            [on, onNum],
+            ["Off", offNum],
+        ]),
+    };
+}
+/** The appearance a widget ALREADY carries for one of its states, from `/AP /N /<state>`. */
+function stateAppearance(doc, widgetNum, state) {
+    const states = doc.resolve(get(doc.resolve(get(doc.getObject(widgetNum), "AP")), "N"));
+    if (states === undefined || !isDict(states))
+        return undefined;
+    const chosen = states.map.get(state);
+    return isRef(chosen) ? chosen : undefined;
 }
 class FillError extends Error {
 }
@@ -237,9 +242,22 @@ function plan(field, value, enciphered) {
  * @param values field name -> value. Names are the fully qualified ones `readAcroForm` reports.
  */
 export async function fillForm(bytes, values, options = {}) {
+    // Two option combinations describe a document nobody wants. Refused before the file is opened, since
+    // the answer does not depend on it.
+    if (options.fieldAppearances === false && options.needAppearances === false) {
+        throw new FillError("fieldAppearances and needAppearances are both false, which leaves the values invisible: nothing " +
+            "is drawn by jasy and the viewer is not asked to draw anything either. Turn one of them on");
+    }
+    if (options.flatten === true && options.fieldAppearances === false) {
+        throw new FillError("flatten needs fieldAppearances: flattening freezes the picture a field shows, and with " +
+            "fieldAppearances false there is no picture of the new value to freeze");
+    }
     // Async because an encrypted document has to be deciphered before its field names mean anything, and
     // because the values written back have to be enciphered again with the same file key.
-    const doc = await PdfDocument.open(bytes, { password: options.password });
+    const doc = await PdfDocument.open(bytes, {
+        password: options.password,
+        maxStreamSize: options.maxStreamSize,
+    });
     if (!doc.canReEncrypt) {
         throw new FillError("this PDF is encrypted with RC4 or AES-128; jasy can open it but writes only AES-256, so filling it " +
             "would have to downgrade its protection - refused");
@@ -279,6 +297,8 @@ export async function fillForm(bytes, values, options = {}) {
     const bake = options.fieldAppearances !== false;
     // One metrics instance for the whole fill, not one per field and not one at module scope.
     const metrics = bake ? fontMetrics() : undefined;
+    // Only collected when a flatten follows in this same pass; see `FreshAppearances` for why it exists.
+    const fresh = options.flatten ? new Map() : undefined;
     // A widget we could not draw has no picture at all, so the viewer must be asked after all.
     let someBakeFailed = false;
     const filled = [];
@@ -323,6 +343,8 @@ export async function fillForm(bytes, values, options = {}) {
                 if (bake && baked === undefined)
                     someBakeFailed = true;
                 editsFor(w.num).AP = baked !== undefined ? `<< /N ${baked} 0 R >>` : undefined;
+                if (baked !== undefined)
+                    fresh?.set(w.num, { kind: "ref", num: baked, gen: 0 });
             }
         }
         for (const [widgetNum, state] of change.as ?? []) {
@@ -330,9 +352,20 @@ export async function fillForm(bytes, values, options = {}) {
             // A button whose widget ships NO state pictures (PDFKit, react-pdf write none) stays an empty box
             // in anything that does not redraw - and cannot be flattened at all. Draw the two states once.
             if (bake && !field.widgets.find((w) => w.num === widgetNum)?.hasAppearance) {
-                const ap = await bakeStatesFor(doc, writer, field, widgetNum, state);
-                if (ap !== undefined)
-                    editsFor(widgetNum).AP = ap;
+                const drawn = await bakeStatesFor(doc, writer, field, widgetNum, state);
+                if (drawn !== undefined) {
+                    editsFor(widgetNum).AP = drawn.ap;
+                    const num = drawn.states.get(state);
+                    if (num !== undefined)
+                        fresh?.set(widgetNum, { kind: "ref", num, gen: 0 });
+                }
+            }
+            else {
+                // The widget keeps its own pictures and only /AS moves, so the state to stamp is the NEW one -
+                // reading /AS back out of the document would give the state before this fill.
+                const ref = stateAppearance(doc, widgetNum, state);
+                if (ref !== undefined)
+                    fresh?.set(widgetNum, ref);
             }
         }
         for (const [objNum, changes] of edits) {
@@ -355,18 +388,7 @@ export async function fillForm(bytes, values, options = {}) {
     const alsoRewritten = bake || options.needAppearances !== false ? [acro, catalog] : [];
     // One pass over every string that will be carried over unchanged. Without this a preserved tooltip or
     // a /DA would be written back in the clear, into a file where nothing else is.
-    const carried = new Map();
-    if (doc.isEncrypted) {
-        for (const target of [...pending.map((p) => p.target), ...alsoRewritten]) {
-            for (const str of stringsIn(target)) {
-                if (carried.has(str))
-                    continue;
-                const cipher = await doc.encryptForWrite(str.bytes);
-                if (cipher)
-                    carried.set(str, hex(cipher));
-            }
-        }
-    }
+    const carried = await carryStrings(doc, [...pending.map((p) => p.target), ...alsoRewritten]);
     for (const { objNum, target, changes } of pending) {
         writer.update(objNum, withEntries(target, changes, carried));
     }
@@ -374,8 +396,10 @@ export async function fillForm(bytes, values, options = {}) {
     // When we DID draw, the flag has to go: a form that still asks for regeneration gets it, and the
     // viewer throws our drawing away and redraws from /DA - which is how PDFKit's forms kept asking for a
     // ZapfDingbats they do not ship.
+    // With a flatten following there is nothing left to answer it for, and that pass rewrites the same
+    // /AcroForm dictionary anyway.
     const needAppearances = bake && !someBakeFailed ? "false" : "true";
-    if (bake || options.needAppearances !== false) {
+    if (!options.flatten && (bake || options.needAppearances !== false)) {
         if (acro !== undefined && isDict(acro)) {
             if (isRef(acroRef)) {
                 writer.update(acroRef.num, withEntries(acro, { NeedAppearances: needAppearances }, carried));
@@ -390,6 +414,11 @@ export async function fillForm(bytes, values, options = {}) {
             }
         }
     }
-    return { bytes: writer.save(), warnings, filled };
+    // Same writer, so the whole operation stays one incremental update. Last, because it freezes the
+    // pictures drawn above.
+    const flattened = options.flatten
+        ? await flattenInto(doc, writer, form.fields, carried, fresh)
+        : [];
+    return { bytes: writer.save(), warnings, filled, flattened };
 }
 export { FillError };

package/dist/edit/flatten.d.ts

@@ -1,6 +1,7 @@
 import { PdfDocument } from "./document.js";
 import { type ReadField } from "./acroform-reader.js";
 import { IncrementalWriter, type StringCipher } from "./writer.js";
+import { type PdfRef } from "./objects.js";
 /**
  * Flattening a form: the values stop being editable fields and become part of the page.
  *
@@ -21,6 +22,8 @@ import { IncrementalWriter, type StringCipher } from "./writer.js";
 export interface FlattenOptions {
     /** The user password, for a document that is encrypted. */
     password?: string;
+    /** Ceiling on what ONE stream may inflate to, in bytes (default 64 MB) - the zip-bomb guard. */
+    maxStreamSize?: number;
     /** Flatten only these fields (fully qualified names). Omit for all of them. */
     fields?: string[];
 }
@@ -33,10 +36,19 @@ export interface FlattenResult {
 export declare class FlattenError extends Error {
     constructor(message: string);
 }
+/**
+ * The appearance streams a fill has just written, keyed by widget object number.
+ *
+ * Flattening reads the picture a widget shows out of the DOCUMENT, but mid-pass the new one is still in
+ * the writer - without this map a filled-and-flattened form freezes the value from before the fill.
+ * Both widget kinds go stale, for different reasons: a text field's `/AP` is replaced, a button's `/AP`
+ * keeps every state and only `/AS` moves.
+ */
+export type FreshAppearances = ReadonlyMap<number, PdfRef>;
 /**
  * Stamp the fields into their pages and take the widgets away. Shared by `flattenForm` and
  * `fillForm(..., { flatten: true })`, so filling and flattening produce ONE incremental update.
  */
-export declare function flattenInto(doc: PdfDocument, writer: IncrementalWriter, fields: ReadField[], cipher?: StringCipher): Promise<string[]>;
+export declare function flattenInto(doc: PdfDocument, writer: IncrementalWriter, fields: ReadField[], carriedIn?: StringCipher, fresh?: FreshAppearances): Promise<string[]>;
 /** Flatten an existing form: its values become page content and stop being editable. */
 export declare function flattenForm(bytes: Uint8Array, options?: FlattenOptions): Promise<FlattenResult>;

package/dist/edit/flatten.js

@@ -3,7 +3,7 @@ import { readAcroForm } from "./acroform-reader.js";
 import { bakeAppearance, bakeButtonStates, readLook } from "./appearance.js";
 import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
 import { latin1FromBytes } from "../utils/bytes.js";
-import { IncrementalWriter, serialize } from "./writer.js";
+import { carryStrings, IncrementalWriter, serialize } from "./writer.js";
 import { get, isDict, isRef, isStream, nameOf, } from "./objects.js";
 export class FlattenError extends Error {
     constructor(message) {
@@ -104,8 +104,11 @@ function appearanceOf(doc, widget) {
  * Collect what has to happen. A widget that ships NO appearance gets one drawn now, from its own style
  * and current value - the same drawing the fill path bakes. Without that, flattening a form from a
  * producer that writes no appearances (PDFKit, react-pdf) could only ever refuse.
+ *
+ * `fresh` overrides where a widget's picture comes from. It is empty for a plain `flattenForm`, and
+ * carries the just-baked appearances when a fill flattens in the same pass - see `FreshAppearances`.
  */
-async function planStamps(doc, writer, fields) {
+async function planStamps(doc, writer, fields, fresh) {
     const pages = widgetPages(doc);
     const stamps = [];
     // Widgets that leave the page without leaving a picture: a push button with no face of its own. It
@@ -119,7 +122,9 @@ async function planStamps(doc, writer, fields) {
             if (w.num === undefined)
                 continue;
             const widget = doc.getObject(w.num);
-            let appearance = appearanceOf(doc, widget);
+            // A picture written during THIS pass wins: it lives in the writer, not in `doc`, so reading the
+            // document would freeze the value the field had BEFORE the fill.
+            let appearance = fresh?.get(w.num) ?? appearanceOf(doc, widget);
             if (appearance === undefined) {
                 const drawnNum = await drawMissing(doc, writer, field, w.num);
                 if (drawnNum === undefined) {
@@ -277,14 +282,19 @@ function withEntries(dict, changes, cipher) {
  * Stamp the fields into their pages and take the widgets away. Shared by `flattenForm` and
  * `fillForm(..., { flatten: true })`, so filling and flattening produce ONE incremental update.
  */
-export async function flattenInto(doc, writer, fields, cipher) {
+export async function flattenInto(doc, writer, fields, carriedIn, fresh) {
     if (fields.length === 0)
         return [];
-    const { stamps, removeOnly } = await planStamps(doc, writer, fields);
+    const { stamps, removeOnly } = await planStamps(doc, writer, fields, fresh);
     // Group by page: one appended content stream per page, not one per widget.
     const byPage = new Map();
     for (const s of stamps)
         (byPage.get(s.pageNum) ?? byPage.set(s.pageNum, []).get(s.pageNum)).push(s);
+    // Strings in the objects rewritten below have to be enciphered again; the caller's map is the seed.
+    // Untested because unreachable today: we can only flatten our own R6 files, and our page dictionaries
+    // hold no strings. It bites the moment a producer inlines an annotation (/Contents, /URI).
+    const acroDict = doc.resolve(get(doc.catalog, "AcroForm"));
+    const cipher = await carryStrings(doc, [...[...byPage.keys()].map((n) => doc.getObject(n)), acroDict, doc.catalog], new Map(carriedIn ?? []));
     for (const [pageNum, pageStamps] of byPage) {
         const page = doc.getObject(pageNum);
         if (page === undefined || !isDict(page))
@@ -353,10 +363,21 @@ export async function flattenInto(doc, writer, fields, cipher) {
         const gone = new Set(fields.map((f) => f.objNum).filter((n) => n !== undefined));
         // A flattened field may hang in a PARENT's /Kids rather than in the form's /Fields. Dropping it only
         // from the root leaves it reachable, so `readAcroForm` still reports a field with no widget left.
-        pruneKids(doc, writer, get(acro, "Fields"), gone, cipher);
+        // Planned first, written after: a surviving parent is rewritten whole, carrying its own /T, /TU
+        // and /DA, and enciphering those needs an await the sync walk cannot do.
+        const prunes = pruneKids(doc, get(acro, "Fields"), gone);
+        await carryStrings(doc, prunes.map((p) => p.node), cipher);
+        for (const p of prunes) {
+            writer.update(p.num, withEntries(p.node, { Kids: `[${p.kept.map((k) => serialize(k, cipher)).join(" ")}]` }, cipher));
+        }
         const roots = doc.resolve(get(acro, "Fields"));
         const kept = Array.isArray(roots) ? roots.filter((r) => !(isRef(r) && gone.has(r.num))) : [];
-        const newAcro = withEntries(acro, { Fields: `[${kept.map((r) => serialize(r, cipher)).join(" ")}]` }, cipher);
+        const newAcro = withEntries(acro, {
+            Fields: `[${kept.map((r) => serialize(r, cipher)).join(" ")}]`,
+            // A form with nothing left in it asking a viewer to regenerate appearances is a document
+            // contradicting itself, so the flag goes with the last field.
+            ...(kept.length === 0 ? { NeedAppearances: undefined } : {}),
+        }, cipher);
         if (isRef(acroRef)) {
             writer.update(acroRef.num, newAcro);
         }
@@ -377,12 +398,12 @@ export async function flattenInto(doc, writer, fields, cipher) {
  * Walk the field tree and rewrite every `/Kids` that still points at a flattened field. A branch left
  * with no children at all is added to `gone` so its own owner drops it too.
  */
-function pruneKids(doc, writer, list, gone, cipher, depth = 0) {
+function pruneKids(doc, list, gone, out = [], depth = 0) {
     if (depth > 32)
-        return;
+        return out;
     const entries = doc.resolve(list);
     if (!Array.isArray(entries))
-        return;
+        return out;
     for (const ref of entries) {
         if (!isRef(ref) || gone.has(ref.num))
             continue;
@@ -392,7 +413,7 @@ function pruneKids(doc, writer, list, gone, cipher, depth = 0) {
         const kids = get(node, "Kids");
         if (kids === undefined)
             continue;
-        pruneKids(doc, writer, kids, gone, cipher, depth + 1);
+        pruneKids(doc, kids, gone, out, depth + 1);
         const resolved = doc.resolve(kids);
         if (!Array.isArray(resolved))
             continue;
@@ -403,12 +424,16 @@ function pruneKids(doc, writer, list, gone, cipher, depth = 0) {
             gone.add(ref.num); // an empty branch is a field with nothing left to show
             continue;
         }
-        writer.update(ref.num, withEntries(node, { Kids: `[${kept.map((k) => serialize(k, cipher)).join(" ")}]` }, cipher));
+        out.push({ num: ref.num, node, kept });
     }
+    return out;
 }
 /** Flatten an existing form: its values become page content and stop being editable. */
 export async function flattenForm(bytes, options = {}) {
-    const doc = await PdfDocument.open(bytes, { password: options.password });
+    const doc = await PdfDocument.open(bytes, {
+        password: options.password,
+        maxStreamSize: options.maxStreamSize,
+    });
     if (!doc.canReEncrypt) {
         throw new FlattenError("this PDF is encrypted with RC4 or AES-128; jasy can open it but writes only AES-256, so " +
             "flattening it would have to downgrade its protection - refused");

package/dist/edit/index.d.ts

@@ -15,4 +15,6 @@ export { flattenForm, FlattenError } from "./flatten.js";
 export type { FlattenOptions, FlattenResult } from "./flatten.js";
 export type { FieldValue, FillOptions, FillResult } from "./fill.js";
 export { PdfDocument, PdfEncryptedError } from "./document.js";
+export type { LoadOptions, OpenOptions } from "./document.js";
+export { DEFAULT_MAX_STREAM_SIZE, PdfStreamTooLargeError } from "../utils/inflate.js";
 export type { PdfDict, PdfName, PdfObject, PdfRef, PdfStream, PdfString } from "./objects.js";

package/dist/edit/index.js

@@ -12,5 +12,7 @@ export { readAcroForm } from "./acroform-reader.js";
 export { fillForm, FillError } from "./fill.js";
 export { flattenForm, FlattenError } from "./flatten.js";
 // The document itself, for callers who want to look further than the form.
-// PdfEncryptedError is what a caller catches to tell "wrong password" apart from a broken file.
+// PdfEncryptedError is what a caller catches to tell "wrong password" apart from a broken file;
+// PdfStreamTooLargeError tells "this file is attacking me" apart from both.
 export { PdfDocument, PdfEncryptedError } from "./document.js";
+export { DEFAULT_MAX_STREAM_SIZE, PdfStreamTooLargeError } from "../utils/inflate.js";

package/dist/edit/objects.d.ts

@@ -61,3 +61,8 @@ export declare const numberOf: (o: PdfObject | undefined) => number | undefined;
  * which agrees with Latin-1 for everything a field name realistically holds.
  */
 export declare function textOf(o: PdfObject | undefined): string | undefined;
+/**
+ * Every string inside an object, however deep. Both sides of the crypto seam use it: strings are
+ * deciphered on open and must be enciphered again before an object is written back.
+ */
+export declare function stringsIn(o: PdfObject | undefined, out?: PdfString[], depth?: number): PdfString[];

package/dist/edit/objects.js

@@ -54,3 +54,30 @@ export function textOf(o) {
     // value round-trippable, which is what a reader that may write the string back needs.
     return latin1FromBytes(b);
 }
+/**
+ * Every string inside an object, however deep. Both sides of the crypto seam use it: strings are
+ * deciphered on open and must be enciphered again before an object is written back.
+ */
+export function stringsIn(o, out = [], depth = 0) {
+    if (o === undefined || o === null)
+        return out;
+    // Throws rather than returning a short list: a missed string is one written back in the clear.
+    // Bounded at all only because the walk does not follow references, just inline containers.
+    if (depth > MAX_NESTING) {
+        throw new Error(`@jasy/pdf: this PDF nests objects more than ${MAX_NESTING} deep, which no legitimate producer ` +
+            `does; refusing to walk it`);
+    }
+    if (isString(o))
+        out.push(o);
+    else if (Array.isArray(o))
+        for (const e of o)
+            stringsIn(e, out, depth + 1);
+    // The dictionary only - a stream's DATA is covered by the stream's own encryption.
+    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;
+}
+const MAX_NESTING = 64;

package/dist/edit/writer.d.ts

@@ -51,3 +51,10 @@ export declare class IncrementalWriter {
     /** The offset the ORIGINAL file's `startxref` pointed at - our `/Prev`. */
     private previousStartXref;
 }
+/**
+ * Encipher every string the given objects carry, into the cipher map `serialize` consults.
+ *
+ * Not optional on an encrypted document: `serialize` writes any string missing from the map as
+ * PLAINTEXT, so an object rewritten without this pass leaks whatever it holds.
+ */
+export declare function carryStrings(doc: PdfDocument, objects: Array<PdfObject | undefined>, into?: Map<PdfString, string>): Promise<StringCipher>;

package/dist/edit/writer.js

@@ -1,4 +1,4 @@
-import { isDict, isRef, isStream, isString } from "./objects.js";
+import { isDict, isRef, isStream, isString, stringsIn, } from "./objects.js";
 /**
  * Writing changes back into an existing PDF, as an **incremental update**.
  *
@@ -259,3 +259,25 @@ export class IncrementalWriter {
         return m ? Number(m[1]) : undefined;
     }
 }
+/** Bytes as an enciphered PDF hex string, the form every rewritten string takes in an encrypted file. */
+const hexString = (b) => `<${Array.from(b, (x) => x.toString(16).padStart(2, "0").toUpperCase()).join("")}>`;
+/**
+ * Encipher every string the given objects carry, into the cipher map `serialize` consults.
+ *
+ * Not optional on an encrypted document: `serialize` writes any string missing from the map as
+ * PLAINTEXT, so an object rewritten without this pass leaks whatever it holds.
+ */
+export async function carryStrings(doc, objects, into = new Map()) {
+    if (!doc.isEncrypted)
+        return into;
+    for (const o of objects) {
+        for (const str of stringsIn(o)) {
+            if (into.has(str))
+                continue;
+            const cipher = await doc.encryptForWrite(str.bytes);
+            if (cipher)
+                into.set(str, hexString(cipher));
+        }
+    }
+    return into;
+}

package/dist/elements/container-element.d.ts

@@ -9,9 +9,26 @@ interface ContainerElementParams extends SizedElement, WithChildren {
     main?: MainAlign;
     /** Horizontal alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Lay the children out backwards along the main axis (CSS `row-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap`). */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). */
+    alignContent?: MainAlign;
     /** Width/height as a fraction (0..1) of the offered box instead of `width`/`height` (relative sizing). */
     widthFactor?: number;
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: number;
     /** Start this stack on a fresh page (CSS `break-before: page`). */
     breakBefore?: boolean;
     /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
@@ -22,10 +39,13 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
     private gap;
     private main;
     private cross;
+    private reverse;
+    private wrap;
+    private alignContent?;
     private breakBefore;
     private breakAfter;
     private requested;
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }: ContainerElementParams);
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }: ContainerElementParams);
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     /**

package/dist/elements/container-element.js

@@ -1,15 +1,18 @@
 import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
-import { resolveExtent } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
 import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 export class ContainerElement extends SizedPDFElement {
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }) {
         super({ x, y, width, height });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
-        this.requested = { width, height, widthFactor, heightFactor };
+        this.reverse = reverse ?? false;
+        this.wrap = wrap ?? false;
+        this.alignContent = alignContent;
+        this.requested = { ...sizing, width, height };
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
     }
@@ -62,6 +65,9 @@ export class ContainerElement extends SizedPDFElement {
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            reverse: this.reverse,
+            wrap: this.wrap,
+            alignContent: this.alignContent,
             breakAfter,
         });
     }
@@ -93,17 +99,19 @@ export class ContainerElement extends SizedPDFElement {
         // Relative sizing: a pinned extent (fixed points or a fraction of the offered box, clamped into
         // the constraints) wins; else fill a bounded axis; else stay `undefined` and shrink-wrap below.
         // A Column nested in a Row gets unbounded width - passing 0 there would collapse children to 0.
-        const explicitWidth = resolveExtent(this.requested.width, this.requested.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        const explicitHeight = resolveExtent(this.requested.height, this.requested.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const specs = extentSpecs(this.requested);
+        const resolved = resolveSize(specs.width, specs.height, this.requested.aspectRatio, constraints);
+        const { width: explicitWidth, height: explicitHeight, constraints: bounds } = resolved;
+        // Fill-or-shrink-wrap is decided by the constraints we were GIVEN; a min/max only caps the result.
         const boundedWidth = explicitWidth !== undefined
-            ? constraints.constrainWidth(explicitWidth)
+            ? bounds.constrainWidth(explicitWidth)
             : constraints.hasBoundedWidth
-                ? constraints.maxWidth
+                ? bounds.maxWidth
                 : undefined;
         const boundedHeight = explicitHeight !== undefined
-            ? constraints.constrainHeight(explicitHeight)
+            ? bounds.constrainHeight(explicitHeight)
             : constraints.hasBoundedHeight
-                ? constraints.maxHeight
+                ? bounds.maxHeight
                 : undefined;
         // Vertical stack: cross = width (children fill it), main = height (the stacking extent).
         const crossAvail = boundedWidth ?? Infinity;
@@ -113,7 +121,14 @@ export class ContainerElement extends SizedPDFElement {
             // Vertical flex stack (main = height, cross = width). The shared helper measures
             // fixed children, distributes the leftover to flex children, and places everything
             // in source order.
-            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
+            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, {
+                gap: this.gap,
+                main: this.main,
+                cross: this.cross,
+                reverse: this.reverse,
+                wrap: this.wrap,
+                alignContent: this.alignContent,
+            }, ctx);
         }
         // Pinned/bounded axis takes that extent; an unbounded one shrink-wraps to the children (height =
         // the stack, width = the widest child). Top-left coordinates; the container draws nothing, and

package/dist/elements/image-element.d.ts

@@ -1,3 +1,4 @@
+import type { Radii } from "../ir/display-list.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
 export declare enum BoxFit {
@@ -55,9 +56,20 @@ interface ImageElementParams {
     widthFactor?: number;
     /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; overrides the image's OWN ratio (CSS `aspect-ratio`), `fit` then places it. */
+    aspectRatio?: number;
     fit?: BoxFit;
-    /** Corner radius in points; rounds the image box (0 = sharp, default). */
-    radius?: number;
+    /** Corner radius in points - one number or per corner; rounds the image box (0 = sharp, default). */
+    radius?: number | Radii;
     /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
     alt?: string;
 }
@@ -69,8 +81,10 @@ export declare class ImageElement extends SizedPDFElement {
     private radius;
     private readonly alt?;
     private requested;
+    /** min/max/aspectRatio, kept as given so every layout pass re-resolves them. */
+    private sizing;
     private intrinsic?;
-    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, }: ImageElementParams);
+    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, ...sizing }: ImageElementParams);
     /**
      * Loads the image and records its intrinsic pixel size. Runs in the async pre-layout pass (layout
      * itself is synchronous and cannot await jimp) so `calculateLayout` can turn a width-only image
@@ -87,7 +101,7 @@ export declare class ImageElement extends SizedPDFElement {
         height: number | undefined;
         image: CustomImage;
         fit: BoxFit;
-        radius: number;
+        radius: number | Radii;
         alt: string | undefined;
     };
 }