@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/forms/acroform.js

@@ -1,5 +1,6 @@
+import { coverText } from "../text/glyph-coverage.js";
 import { NORMAL_STYLE, escName, num2, pdfColor } from "./pdf.js";
-import { checkboxOff, checkboxOn, listBoxFace, pushButtonFace, radioOff, radioOn, signatureFace, fieldDrawSize, textFieldFace, wrapFieldValue, } from "./appearance.js";
+import { HELV, checkboxOff, checkboxOn, listBoxFace, pushButtonFace, radioOff, radioOn, signatureFace, fieldDrawSize, textFieldFace, wrapFieldValue, } from "./appearance.js";
 // AcroForm field flags (/Ff), by 1-based bit position per the PDF spec.
 const FF_READ_ONLY = 1 << 0; // bit 1
 const FF_REQUIRED = 1 << 1; // bit 2: must be filled in before the form is submitted
@@ -28,8 +29,12 @@ function boxChrome(node, extraMK = "") {
         out += ` /BS << /W ${num2(style.borderWidth)} /S /S >>`;
     return out;
 }
-/** The annotation flags (/F). Bit 2 = Hidden, bit 3 = Print. A widget prints by default; `hidden`
- *  removes it from screen AND print, `print: false` keeps it on screen only. */
+/** A widget in the structure tree (accessible tagging) names its slot in the ParentTree. */
+function withStructParent(dict, structParent) {
+    return structParent === undefined
+        ? dict
+        : dict.replace(/^<< /, `<< /StructParent ${structParent} `);
+}
 function annotFlags(f) {
     if (f.hidden)
         return 2;
@@ -162,9 +167,9 @@ function actionDict(a, om) {
         case "submit":
             // /Flags 4 = ExportFormat: post the field values as HTML form data rather than FDF, which is what
             // an ordinary web endpoint expects.
-            return `/A << /S /SubmitForm /F << /FS /URL /F ${om.pdfString(a.url)} >> /Flags 4 >>`;
+            return `/A << /S /SubmitForm /F << /FS /URL /F ${om.pdfUri(a.url)} >> /Flags 4 >>`;
         case "url":
-            return `/A << /S /URI /URI ${om.pdfString(a.url)} >>`;
+            return `/A << /S /URI /URI ${om.pdfUri(a.url)} >>`;
     }
 }
 /**
@@ -196,27 +201,66 @@ export class AcroFormCollector {
     drawSize(style, height, capHeight) {
         return fieldDrawSize(style.fontSize, height, style.borderWidth, capHeight);
     }
+    /**
+     * The font a field's baked appearance draws its text in: the font the field inherits when it is
+     * EMBEDDED, else the standard Helvetica. PDF/A and PDF/UA require every font that draws to be
+     * embedded, and a document that embeds its fonts means that. The /DA keeps naming Helvetica - it is
+     * what a viewer redraws with once someone types, and a subset font could not draw the new characters.
+     * Measuring and drawing both take the font from here.
+     */
+    faceFont(node, om) {
+        const inherited = node.font;
+        if (inherited && om.isCustomFont(inherited.family, inherited.style)) {
+            const { family, style } = inherited;
+            const resource = om.getCustomFontResource(family, style);
+            return {
+                family,
+                style,
+                // Drawn SHAPED (ligatures, joining forms) - the shaping `getStringWidth` measures with.
+                face: {
+                    res: `F${resource.fontIndex}`,
+                    encode: (text) => `<${om.encodeCustomText(family, text, style)}>`,
+                },
+                resources: `/Font << /F${resource.fontIndex} ${resource.resourceIndex} 0 R >>`,
+                // A glyph the font lacks would draw as .notdef, which PDF/A forbids.
+                cover: (text) => {
+                    const { text: drawable, dropped } = coverText(text, family, style, om, false);
+                    if (dropped.length > 0)
+                        om.reportMissingGlyph?.(dropped);
+                    return drawable;
+                },
+            };
+        }
+        return {
+            family: "Helvetica",
+            style: NORMAL_STYLE,
+            face: HELV,
+            resources: `/Font << /Helv ${this.helv(om)} 0 R >>`,
+            cover: (text) => text,
+        };
+    }
     /** Measure one line for the appearance generator. */
-    line(om, text, size) {
-        return { text, width: om.getStringWidth(text, "Helvetica", size, NORMAL_STYLE) };
+    line(om, font, text, size) {
+        return { text, width: om.getStringWidth(text, font.family, size, font.style) };
     }
     /** Bake a text field's value into an appearance stream; returns the XObject number. */
     bakeText(node, om) {
         const f = node.field;
         if (f.kind !== "text")
             throw new Error("bakeText: not a text field");
-        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const font = this.faceFont(node, om);
+        const { capHeight } = om.getFontDecoration(font.family, font.style);
         const size = this.drawSize(node.style, node.height, capHeight);
         // A password field shows the mask, never the characters - the value still lives in /V.
-        const value = f.password ? "•".repeat([...(f.value ?? "")].length) : (f.value ?? "");
+        const value = font.cover(f.password ? "•".repeat([...(f.value ?? "")].length) : (f.value ?? ""));
         const innerWidth = Math.max(1, node.width - 2 * (2 + node.style.borderWidth));
         let lines = [];
         if (value) {
-            const texts = wrapFieldValue(value, "Helvetica", size, NORMAL_STYLE, innerWidth, om, f.multiline ?? false);
-            lines = texts.map((t) => this.line(om, t, size));
+            const texts = wrapFieldValue(value, font.family, size, font.style, innerWidth, om, f.multiline ?? false);
+            lines = texts.map((t) => this.line(om, font, t, size));
         }
-        const face = textFieldFace(node.width, node.height, node.style, lines, capHeight, size, "Helv", f.multiline ?? false, f.align);
-        return om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, `/Font << /Helv ${this.helv(om)} 0 R >>`);
+        const face = textFieldFace(node.width, node.height, node.style, lines, capHeight, size, font.face, f.multiline ?? false, f.align);
+        return om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, font.resources);
     }
     /** Bake a choice field: a combo shows its current value on one line, a list box shows its options
      *  with the selected rows highlighted. */
@@ -224,24 +268,27 @@ export class AcroFormCollector {
         const f = node.field;
         if (f.kind !== "choice")
             throw new Error("bakeChoice: not a choice");
-        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const font = this.faceFont(node, om);
+        const { capHeight } = om.getFontDecoration(font.family, font.style);
         const size = this.drawSize(node.style, node.height, capHeight);
         const shown = (v) => f.options.find((o) => o.value === v)?.label ?? v;
         const chosen = choiceSelection(f);
         const selected = new Set(chosen);
         let face;
         if (f.combo) {
-            const current = chosen.length ? [this.line(om, shown(chosen[0]), size)] : [];
-            face = textFieldFace(node.width, node.height, node.style, current, capHeight, size, "Helv", false, f.align);
+            const current = chosen.length
+                ? [this.line(om, font, font.cover(shown(chosen[0])), size)]
+                : [];
+            face = textFieldFace(node.width, node.height, node.style, current, capHeight, size, font.face, false, f.align);
         }
         else {
             const rows = f.options.map((o) => ({
-                ...this.line(om, o.label ?? o.value, size),
+                ...this.line(om, font, font.cover(o.label ?? o.value), size),
                 selected: selected.has(o.value),
             }));
-            face = listBoxFace(node.width, node.height, node.style, rows, capHeight, size, "Helv", f.align);
+            face = listBoxFace(node.width, node.height, node.style, rows, capHeight, size, font.face, f.align);
         }
-        return om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, `/Font << /Helv ${this.helv(om)} 0 R >>`);
+        return om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, font.resources);
     }
     get isEmpty() {
         return this.fieldRefs.length === 0;
@@ -278,9 +325,9 @@ export class AcroFormCollector {
     }
     /** Emit the widget object for one form-field IR node, register it as a field, and return its object
      *  number so the PageRenderer can add it to that page's /Annots. */
-    addField(node, om) {
+    addField(node, om, structParent) {
         if (node.field.kind === "radio")
-            return this.addRadio(node, om);
+            return this.addRadio(node, om, structParent);
         this.claimName(node.field.name, node.field.kind);
         let dict;
         if (node.field.kind === "checkbox") {
@@ -307,7 +354,7 @@ export class AcroFormCollector {
             if (!this.bake)
                 this.needAppearances = true;
         }
-        const objNum = om.addObject(dict);
+        const objNum = om.addObject(withStructParent(dict, structParent));
         this.fieldRefs.push(objNum);
         return objNum;
     }
@@ -318,13 +365,15 @@ export class AcroFormCollector {
         const f = node.field;
         if (f.kind !== "pushbutton")
             throw new Error("buildPushButtonWidget: not a push button");
-        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const font = this.faceFont(node, om);
+        const { capHeight } = om.getFontDecoration(font.family, font.style);
         // `fontSize: 0` means auto-size, here as everywhere: resolve it before measuring or drawing.
         const size = this.drawSize(node.style, node.height, capHeight);
-        const width = om.getStringWidth(f.label, "Helvetica", size, NORMAL_STYLE);
-        const fontNum = this.helv(om);
-        const face = pushButtonFace(node.width, node.height, node.style, f.label, width, capHeight, "Helv", size);
-        const apRef = om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, `/Font << /Helv ${fontNum} 0 R >>`);
+        const caption = font.cover(f.label);
+        const width = om.getStringWidth(caption, font.family, size, font.style);
+        this.helv(om); // the /DA below names it
+        const face = pushButtonFace(node.width, node.height, node.style, caption, width, capHeight, font.face, size);
+        const apRef = om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, font.resources);
         const parts = [`/Type /Annot /Subtype /Widget /FT /Btn`, `/T ${om.pdfString(f.name)}`];
         if (f.tooltip !== undefined)
             parts.push(`/TU ${om.pdfString(f.tooltip)}`);
@@ -343,7 +392,7 @@ export class AcroFormCollector {
     /** A radio button: one KID widget of its group's shared field. The group field is reserved on first
      *  sight (and added to /Fields); each button adds itself to that field's /Kids. Returns the kid widget
      *  number, which goes into the PAGE /Annots (the parent field does not). */
-    addRadio(node, om) {
+    addRadio(node, om, structParent) {
         const f = node.field;
         if (f.kind !== "radio")
             throw new Error("addRadio: not a radio");
@@ -375,7 +424,7 @@ export class AcroFormCollector {
             `/AS /${escName(as)}`,
             `/DA ${om.pdfString(`/ZaDb 0 Tf ${pdfColor(node.style.color)} rg`)}`,
         ];
-        const kidNum = om.addObject(`<< ${parts.join(" ")}${boxChrome(node)} >>`);
+        const kidNum = om.addObject(withStructParent(`<< ${parts.join(" ")}${boxChrome(node)} >>`, structParent));
         g.kids.push(kidNum);
         return kidNum;
     }
@@ -386,12 +435,12 @@ export class AcroFormCollector {
         if (f.kind !== "signature")
             throw new Error("buildSignatureWidget: not a signature");
         this.hasSignature = true;
-        const label = f.label ?? "";
-        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const font = this.faceFont(node, om);
+        const label = font.cover(f.label ?? "");
+        const { capHeight } = om.getFontDecoration(font.family, font.style);
         const size = this.drawSize(node.style, node.height, capHeight);
-        const labelWidth = label ? om.getStringWidth(label, "Helvetica", size, NORMAL_STYLE) : 0;
-        const fontNum = this.helv(om);
-        const apRef = om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, signatureFace(node.width, node.height, node.style, label, labelWidth, "Helv", size), `/Font << /Helv ${fontNum} 0 R >>`);
+        const labelWidth = label ? om.getStringWidth(label, font.family, size, font.style) : 0;
+        const apRef = om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, signatureFace(node.width, node.height, node.style, label, labelWidth, font.face, size), font.resources);
         const parts = [`/Type /Annot /Subtype /Widget /FT /Sig`, `/T ${om.pdfString(f.name)}`];
         if (f.tooltip !== undefined)
             parts.push(`/TU ${om.pdfString(f.tooltip)}`);

package/dist/forms/appearance.d.ts

@@ -1,6 +1,17 @@
 import type { FieldAlign, FieldStyle } from "./field.js";
 import type { FontMetrics } from "../utils/font-metrics.js";
 import type { FontStyle } from "../utils/pdf-object-manager.js";
+/**
+ * The font an appearance draws its text in: its resource name inside the appearance stream's own
+ * /Resources, and how a string becomes a `Tj` operand in it. One object, so the caller that picks the
+ * font also decides its encoding - a WinAnsi literal for Helvetica, glyph ids for an embedded font.
+ */
+export interface FaceFont {
+    res: string;
+    encode(text: string): string;
+}
+/** The standard Helvetica (`/Helv`) a field's /DA names: WinAnsi literal strings. */
+export declare const HELV: FaceFont;
 /** The unchecked appearance: just the box. */
 export declare function checkboxOff(w: number, h: number, style: FieldStyle): string;
 /** The checked appearance: the box plus a vector checkmark (font-free, so it renders everywhere). */
@@ -12,16 +23,16 @@ export declare function radioOn(w: number, h: number, style: FieldStyle): string
 /**
  * A push button's face: the box plus its caption, centred. The caller measures the caption (this module
  * stays free of font metrics and the writer) and passes `captionWidth` in points and `capHeight` as an em
- * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `fontRes` is
- * the font's resource name inside the appearance stream's own /Resources.
+ * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `font` is
+ * what the caption is drawn in.
  */
-export declare function pushButtonFace(w: number, h: number, style: FieldStyle, caption: string, captionWidth: number, capHeight: number, fontRes: string, size: number): string;
+export declare function pushButtonFace(w: number, h: number, style: FieldStyle, caption: string, captionWidth: number, capHeight: number, font: FaceFont, size: number): string;
 /**
  * An EMPTY signature field: the box, a signing rule across the lower third, and an optional hint centred
  * just above it. This is the placeholder look - once someone actually signs, the signing tool replaces
  * this appearance with its own.
  */
-export declare function signatureFace(w: number, h: number, style: FieldStyle, label: string, labelWidth: number, fontRes: string, size: number): string;
+export declare function signatureFace(w: number, h: number, style: FieldStyle, label: string, labelWidth: number, font: FaceFont, size: number): string;
 /** One pre-measured line of field text. The caller owns wrapping + measuring, so this module stays free
  *  of font metrics (and can be reused verbatim when filling an existing PDF). */
 /**
@@ -50,9 +61,9 @@ export interface FieldLine {
  * single line sits optically centred; a multi-line field stacks from the top, both measured off the
  * font's cap height rather than a guessed ratio.
  */
-export declare function textFieldFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, fontRes: string, multiline: boolean, align?: FieldAlign): string;
+export declare function textFieldFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, font: FaceFont, multiline: boolean, align?: FieldAlign): string;
 /**
  * A list box, baked: the visible options stacked from the top, with a highlight behind the selected
  * ones. A combo box (dropdown) uses `textFieldFace` instead - it shows only its current value.
  */
-export declare function listBoxFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, fontRes: string, align?: FieldAlign): string;
+export declare function listBoxFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, font: FaceFont, align?: FieldAlign): string;

package/dist/forms/appearance.js

@@ -1,5 +1,7 @@
 import { escPdf, num2, pdfColor } from "./pdf.js";
 import { wrapStringIntoLines } from "../text/line-breaker.js";
+/** The standard Helvetica (`/Helv`) a field's /DA names: WinAnsi literal strings. */
+export const HELV = { res: "Helv", encode: (text) => `(${escPdf(text)})` };
 // Appearance streams (/AP): the actual drawn content of a field's box, in the field's OWN coordinate
 // space (bottom-left origin, [0 0 w h]). Shared between CREATE (bake the field's look now) and, later,
 // FILL-existing (regenerate a field's look after setting its value). This is why it is its own module.
@@ -63,34 +65,34 @@ export function radioOn(w, h, style) {
 /**
  * A push button's face: the box plus its caption, centred. The caller measures the caption (this module
  * stays free of font metrics and the writer) and passes `captionWidth` in points and `capHeight` as an em
- * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `fontRes` is
- * the font's resource name inside the appearance stream's own /Resources.
+ * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `font` is
+ * what the caption is drawn in.
  */
-export function pushButtonFace(w, h, style, caption, captionWidth, capHeight, fontRes, size) {
+export function pushButtonFace(w, h, style, caption, captionWidth, capHeight, font, size) {
     // Baseline placed so the CAPITALS sit optically centred in the box, not the em square.
     const y = (h - capHeight * size) / 2;
-    const caption_ = caption ? centredText(w, h, style, caption, captionWidth, y, fontRes, size) : "";
+    const caption_ = caption ? centredText(w, h, style, caption, captionWidth, y, font, size) : "";
     return `${box(w, h, style)}\n${caption_}`;
 }
 /** One centred, clipped text run inside a field box. Clipping means an over-long caption is cut at the
  *  border instead of bleeding across the page. Shared by the push button and the signature placeholder. */
-function centredText(w, h, style, text, textWidth, baselineY, fontRes, size) {
+function centredText(w, h, style, text, textWidth, baselineY, font, size) {
     return (`q 0 0 ${num2(w)} ${num2(h)} re W n ` +
-        `BT /${fontRes} ${num2(size)} Tf ${pdfColor(style.color)} rg ` +
-        `${num2((w - textWidth) / 2)} ${num2(baselineY)} Td (${escPdf(text)}) Tj ET Q`);
+        `BT /${font.res} ${num2(size)} Tf ${pdfColor(style.color)} rg ` +
+        `${num2((w - textWidth) / 2)} ${num2(baselineY)} Td ${font.encode(text)} Tj ET Q`);
 }
 /**
  * An EMPTY signature field: the box, a signing rule across the lower third, and an optional hint centred
  * just above it. This is the placeholder look - once someone actually signs, the signing tool replaces
  * this appearance with its own.
  */
-export function signatureFace(w, h, style, label, labelWidth, fontRes, size) {
+export function signatureFace(w, h, style, label, labelWidth, font, size) {
     const ruleY = h * 0.3;
     const inset = w * 0.08;
     const stroke = style.border ?? style.color;
     const rule = `${pdfColor(stroke)} RG ${num2(Math.max(0.5, style.borderWidth * 0.75))} w ` +
         `${num2(inset)} ${num2(ruleY)} m ${num2(w - inset)} ${num2(ruleY)} l S`;
-    const hint = label ? centredText(w, h, style, label, labelWidth, ruleY + 6, fontRes, size) : "";
+    const hint = label ? centredText(w, h, style, label, labelWidth, ruleY + 6, font, size) : "";
     return `${box(w, h, style)}\n${rule}\n${hint}`;
 }
 // Horizontal padding inside a field box, on top of the border - the same small inset Acrobat leaves so
@@ -147,11 +149,11 @@ function alignX(boxWidth, pad, width, align = "left") {
  * visibly shift on first click. The measurement matches: `getStringWidth` is the plain glyph sum, so
  * measured still equals drawn.
  */
-function textBlock(lines, style, size, fontRes) {
+function textBlock(lines, style, size, font) {
     const runs = lines
-        .map((l) => `1 0 0 1 ${num2(l.x)} ${num2(l.y)} Tm (${escPdf(l.text)}) Tj`)
+        .map((l) => `1 0 0 1 ${num2(l.x)} ${num2(l.y)} Tm ${font.encode(l.text)} Tj`)
         .join("\n");
-    return `BT /${fontRes} ${num2(size)} Tf ${pdfColor(style.color)} rg\n${runs}\nET`;
+    return `BT /${font.res} ${num2(size)} Tf ${pdfColor(style.color)} rg\n${runs}\nET`;
 }
 /** Everything a field draws is clipped to its own box, so a long value is cut at the frame rather than
  *  bleeding across the page. */
@@ -163,7 +165,7 @@ function clipped(w, h, ops) {
  * single line sits optically centred; a multi-line field stacks from the top, both measured off the
  * font's cap height rather than a guessed ratio.
  */
-export function textFieldFace(w, h, style, lines, capHeight, size, fontRes, multiline, align = "left") {
+export function textFieldFace(w, h, style, lines, capHeight, size, font, multiline, align = "left") {
     const face = box(w, h, style);
     if (lines.length === 0)
         return face;
@@ -176,13 +178,13 @@ export function textFieldFace(w, h, style, lines, capHeight, size, fontRes, mult
         // Single line: centre the capitals in the box.
         y: multiline ? h - pad - capHeight * size - i * lineHeight : (h - capHeight * size) / 2,
     }));
-    return `${face}\n${clipped(w, h, textBlock(placed, style, size, fontRes))}`;
+    return `${face}\n${clipped(w, h, textBlock(placed, style, size, font))}`;
 }
 /**
  * A list box, baked: the visible options stacked from the top, with a highlight behind the selected
  * ones. A combo box (dropdown) uses `textFieldFace` instead - it shows only its current value.
  */
-export function listBoxFace(w, h, style, lines, capHeight, size, fontRes, align = "left") {
+export function listBoxFace(w, h, style, lines, capHeight, size, font, align = "left") {
     const pad = FIELD_PAD + style.borderWidth;
     const lineHeight = size * 1.15;
     const rowTop = (i) => h - pad - (i + 1) * lineHeight;
@@ -199,6 +201,6 @@ export function listBoxFace(w, h, style, lines, capHeight, size, fontRes, align
         // Baseline inside the row: lift it off the row bottom by the slack under the capitals.
         y: rowTop(i) + (lineHeight - capHeight * size) / 2,
     }));
-    const inner = [highlights, textBlock(placed, style, size, fontRes)].filter(Boolean).join("\n");
+    const inner = [highlights, textBlock(placed, style, size, font)].filter(Boolean).join("\n");
     return `${box(w, h, style)}\n${clipped(w, h, inner)}`;
 }

package/dist/ir/display-list.d.ts

@@ -1,3 +1,4 @@
+import type { ImageColor, Orientation } from "../utils/image-helper.js";
 import { Color } from "../common/color.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
@@ -9,8 +10,8 @@ import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
  * are intentionally "dumb": absolute geometry + semantic style, with no PDF
  * operators, no font indices, and no object numbers - those are the backend's job.
  *
- * Coordinates are in PDF points (1/72"). Which origin they use is still the
- * producer's concern for now; centralizing the Y-flip at this seam is Phase 3.
+ * Coordinates are in PDF points (1/72") with the engine's top-left origin. The Y-flip to PDF's
+ * bottom-left happens once per page, at this seam (`PdfBackend.flipY`).
  */
 /**
  * Structure tag for accessible (PDF/UA) tagging. `role` is the PDF structure type the content maps to
@@ -62,7 +63,7 @@ export interface Rect {
     y: number;
     width: number;
     height: number;
-    /** Solid colour, or a gradient whose anchor points are in absolute page coordinates. */
+    /** Solid color, or a gradient whose anchor points are in absolute page coordinates. */
     fill?: Color | Gradient;
     stroke?: Color;
     strokeWidth: number;
@@ -94,6 +95,10 @@ export interface Image {
     imageType: string;
     /** Flate-compressed DeviceGray alpha channel for a transparent PNG, embedded as the XObject's /SMask. */
     smask?: string;
+    /** What the samples mean (a JPEG keeps the space it was saved in); absent = RGB. */
+    color?: ImageColor;
+    /** How the stored pixels turn upright inside the placement box (EXIF); absent = as stored. */
+    orientation?: Orientation;
     /** cover/contain fits clip the placement to the element's original frame. */
     clip?: {
         x: number;
@@ -140,6 +145,9 @@ export interface Link {
     height: number;
     href?: string;
     dest?: string;
+    /** Accessible tagging only: the `/Link` structure element the annotation belongs to, and its text. */
+    structKey?: number;
+    alt?: string;
 }
 /**
  * A named destination anchor - a jump TARGET for an internal `Link({ to })`. Like `Link` it draws
@@ -177,6 +185,13 @@ export interface FormFieldNode {
     height: number;
     field: FormFieldSpec;
     style: FieldStyle;
+    /** Accessible tagging only: the `/Form` structure element the widget belongs to. */
+    structKey?: number;
+    /** The font the field's text inherits; its baked appearance draws in it when it is embedded. */
+    font?: {
+        family: string;
+        style: FontStyle;
+    };
 }
 /**
  * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the

package/dist/layout/box-constraints.d.ts

@@ -84,6 +84,11 @@ export interface SizingParams {
     /** width / height. Derives whichever axis is left open; see `resolveSize`. */
     aspectRatio?: number;
 }
+/**
+ * The width rules of a box, for a piece of it split across pages: it keeps how wide it may be, and
+ * its height comes from what it holds on that page (CSS `box-decoration-break: clone`).
+ */
+export declare function widthRules(s: SizingParams): SizingParams;
 /** Split `SizingParams` into the per-axis form `resolveSize` takes. */
 export declare function extentSpecs(p: SizingParams): {
     width: ExtentSpec;
@@ -105,6 +110,18 @@ export declare function resolveSize(width: ExtentSpec, height: ExtentSpec, aspec
     height?: number;
     constraints: BoxConstraints;
 };
+/**
+ * The open axes of a box that has its own size (an image, an SVG), after `resolveSize`: one pinned axis
+ * derives the other from the own ratio; none pinned is the own size, scaled down to `bounds` and never
+ * up - the cap is what keeps it on the page.
+ */
+export declare function sizeAtOwnRatio(width: number | undefined, height: number | undefined, own: {
+    width: number;
+    height: number;
+}, bounds: BoxConstraints): {
+    width?: number;
+    height?: number;
+};
 /** The size an element resolves to and returns UP the tree. */
 export interface Size {
     width: number;

package/dist/layout/box-constraints.js

@@ -91,6 +91,20 @@ export function resolveExtent(fixed, factor, boundedMax, hasBounded) {
         return boundedMax * factor;
     return undefined;
 }
+/**
+ * The width rules of a box, for a piece of it split across pages: it keeps how wide it may be, and
+ * its height comes from what it holds on that page (CSS `box-decoration-break: clone`).
+ */
+export function widthRules(s) {
+    return {
+        width: s.width,
+        widthFactor: s.widthFactor,
+        minWidth: s.minWidth,
+        maxWidth: s.maxWidth,
+        minWidthFactor: s.minWidthFactor,
+        maxWidthFactor: s.maxWidthFactor,
+    };
+}
 /** Split `SizingParams` into the per-axis form `resolveSize` takes. */
 export function extentSpecs(p) {
     return {
@@ -153,3 +167,20 @@ export function resolveSize(width, height, aspectRatio, constraints) {
         constraints: bounds,
     };
 }
+/**
+ * The open axes of a box that has its own size (an image, an SVG), after `resolveSize`: one pinned axis
+ * derives the other from the own ratio; none pinned is the own size, scaled down to `bounds` and never
+ * up - the cap is what keeps it on the page.
+ */
+export function sizeAtOwnRatio(width, height, own, bounds) {
+    const ratio = own.width / own.height;
+    if (width === undefined && height === undefined) {
+        // The width clamp does the width; a height cap is turned into a width at the ratio.
+        width = bounds.constrainWidth(Math.min(own.width, bounds.maxHeight * ratio));
+    }
+    if (width !== undefined && height === undefined)
+        height = bounds.constrainHeight(width / ratio);
+    else if (height !== undefined && width === undefined)
+        width = bounds.constrainWidth(height * ratio);
+    return { width, height };
+}

package/dist/layout/collect-images.d.ts

@@ -1,9 +1,11 @@
 import { PDFElement } from "../elements/pdf-element.js";
 import { ImageElement } from "../elements/image-element.js";
+import { SvgElement } from "../elements/svg-element.js";
 /**
  * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
- * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
- * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
- * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ * returns every image - a bitmap, or an SVG (which needs this only when it comes from a URL). A
+ * pre-layout pass uses this to resolve each one's intrinsic size asynchronously: layout is synchronous
+ * and cannot await a decoder or a fetch, yet it needs the aspect ratio to give a width-only image its
+ * proportional height. Cheap - images are few and this runs once.
  */
-export declare function collectImageElements(root: PDFElement): ImageElement[];
+export declare function collectImageElements(root: PDFElement): (ImageElement | SvgElement)[];

package/dist/layout/collect-images.js

@@ -1,15 +1,17 @@
 import { PDFElement, hasChildrenProp, hasChildProp } from "../elements/pdf-element.js";
 import { ImageElement } from "../elements/image-element.js";
+import { SvgElement } from "../elements/svg-element.js";
 /**
  * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
- * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
- * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
- * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ * returns every image - a bitmap, or an SVG (which needs this only when it comes from a URL). A
+ * pre-layout pass uses this to resolve each one's intrinsic size asynchronously: layout is synchronous
+ * and cannot await a decoder or a fetch, yet it needs the aspect ratio to give a width-only image its
+ * proportional height. Cheap - images are few and this runs once.
  */
 export function collectImageElements(root) {
     const out = [];
     const visit = (el) => {
-        if (el instanceof ImageElement)
+        if (el instanceof ImageElement || el instanceof SvgElement)
             out.push(el);
         const props = el.getProps();
         if (hasChildrenProp(props))
@@ -17,10 +19,10 @@ export function collectImageElements(root) {
                 visit(c);
         else if (hasChildProp(props))
             visit(props.child);
-        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer and a
-        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there). A
-        // DeferredElement's `composed` is null until layout runs, so it cannot be reached from this
-        // pre-layout pass; an image inside a deferred subtree just skips aspect pre-resolution.
+        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer, a
+        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there), and the `sources` a
+        // DeferredElement builds from. What a PageBuilder builds does not exist yet; an image there that
+        // cannot tell its size without waiting is reported by its layout (`image-unsized`).
         const w = props;
         if (w.header instanceof PDFElement)
             visit(w.header);
@@ -28,6 +30,10 @@ export function collectImageElements(root) {
             visit(w.footer);
         if (w.body instanceof PDFElement)
             visit(w.body);
+        if (Array.isArray(w.sources))
+            for (const s of w.sources)
+                if (s instanceof PDFElement)
+                    visit(s);
     };
     visit(root);
     return out;

package/dist/layout/flex-item.d.ts

@@ -0,0 +1,11 @@
+import { FlexiblePDFElement, PDFElement } from "../elements/pdf-element.js";
+import type { CrossAlign } from "./alignment.js";
+/** The `Expanded`/`Spacer` that makes this child flexible, if any. */
+export declare function flexibleOf(child: PDFElement): FlexiblePDFElement | undefined;
+export declare function alignSelfOf(child: PDFElement): CrossAlign | undefined;
+/** CSS `order`, 0 when unset. */
+export declare function orderOf(child: PDFElement): number;
+/** The child is a `Box` with percentage padding. */
+export declare function hasPercentPaddingItem(child: PDFElement): boolean;
+/** CSS `flex-shrink`, 1 when unset (the CSS default). */
+export declare function flexShrinkOf(child: PDFElement): number;

package/dist/layout/flex-item.js

@@ -0,0 +1,51 @@
+import { FlexiblePDFElement } from "../elements/pdf-element.js";
+/**
+ * How a Row or Column sees a child as a flex item. A wrapper that only marks its child (a `Link`, an
+ * `Anchor`, a `DefaultTextStyle` - see `PDFElement.proxied`) is looked through, as CSS
+ * `display: contents` is: an `Expanded`, `alignSelf`, `order` or `flexShrink` inside it acts as if the
+ * wrapper were not there. A value set on the wrapper itself wins over one set inside it.
+ */
+/**
+ * The child, then each element it is transparent for, outermost first. An `Expanded` is one of them:
+ * `Expanded(child)` is `flex: 1` on the child, so the child's `alignSelf` and `order` are the item's.
+ */
+function* itemChain(child) {
+    for (let el = child; el;) {
+        yield el;
+        el = el.proxied() ?? (el instanceof FlexiblePDFElement ? el.layoutChildren()[0] : undefined);
+    }
+}
+/** The `Expanded`/`Spacer` that makes this child flexible, if any. */
+export function flexibleOf(child) {
+    for (const el of itemChain(child))
+        if (el instanceof FlexiblePDFElement)
+            return el;
+    return undefined;
+}
+export function alignSelfOf(child) {
+    for (const el of itemChain(child))
+        if (el.alignSelf !== undefined)
+            return el.alignSelf;
+    return undefined;
+}
+/** CSS `order`, 0 when unset. */
+export function orderOf(child) {
+    for (const el of itemChain(child))
+        if (el.order !== undefined)
+            return el.order;
+    return 0;
+}
+/** The child is a `Box` with percentage padding. */
+export function hasPercentPaddingItem(child) {
+    for (const el of itemChain(child))
+        if (el.hasPercentPadding())
+            return true;
+    return false;
+}
+/** CSS `flex-shrink`, 1 when unset (the CSS default). */
+export function flexShrinkOf(child) {
+    for (const el of itemChain(child))
+        if (el.flexShrink !== undefined)
+            return el.flexShrink;
+    return 1;
+}