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

package/dist/forms/appearance.js

@@ -0,0 +1,204 @@
+import { escPdf, num2, pdfColor } from "./pdf.js";
+import { wrapStringIntoLines } from "../text/line-breaker.js";
+// 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.
+/** Draw the field box: background fill + border stroke, inset so the stroke stays inside the BBox. */
+function box(w, h, style) {
+    const ops = [];
+    if (style.background)
+        ops.push(`${pdfColor(style.background)} rg 0 0 ${num2(w)} ${num2(h)} re f`);
+    if (style.border && style.borderWidth > 0) {
+        const bw = style.borderWidth;
+        const i = bw / 2;
+        ops.push(`${pdfColor(style.border)} RG ${num2(bw)} w ${num2(i)} ${num2(i)} ${num2(w - bw)} ${num2(h - bw)} re S`);
+    }
+    return ops.join("\n");
+}
+/** The unchecked appearance: just the box. */
+export function checkboxOff(w, h, style) {
+    return box(w, h, style);
+}
+/** The checked appearance: the box plus a vector checkmark (font-free, so it renders everywhere). */
+export function checkboxOn(w, h, style) {
+    const lw = Math.max(1, Math.min(w, h) * 0.12);
+    // A tick: down-stroke to the low point, then up-stroke to the high point. Round caps/joins (2 J / 1 j).
+    const p = (fx, fy) => `${num2(fx * w)} ${num2(fy * h)}`;
+    const tick = `${pdfColor(style.color)} RG ${num2(lw)} w 2 J 1 j ` +
+        `${p(0.22, 0.52)} m ${p(0.42, 0.3)} l ${p(0.78, 0.74)} l S`;
+    return `${box(w, h, style)}\n${tick}`;
+}
+// A circle path (4 cubic-bezier arcs, kappa = 0.5523) around (cx, cy) with radius r. Not stroked/filled -
+// the caller appends `S` (stroke) or `f` (fill).
+function circlePath(cx, cy, r) {
+    const k = 0.5523 * r;
+    const n = num2;
+    return (`${n(cx + r)} ${n(cy)} m ` +
+        `${n(cx + r)} ${n(cy + k)} ${n(cx + k)} ${n(cy + r)} ${n(cx)} ${n(cy + r)} c ` +
+        `${n(cx - k)} ${n(cy + r)} ${n(cx - r)} ${n(cy + k)} ${n(cx - r)} ${n(cy)} c ` +
+        `${n(cx - r)} ${n(cy - k)} ${n(cx - k)} ${n(cy - r)} ${n(cx)} ${n(cy - r)} c ` +
+        `${n(cx + k)} ${n(cy - r)} ${n(cx + r)} ${n(cy - k)} ${n(cx + r)} ${n(cy)} c`);
+}
+/** The ring of a radio button (the outline), in [0 0 w h]. */
+function radioRing(w, h, style) {
+    const r = Math.min(w, h) / 2;
+    const bw = style.borderWidth > 0 ? style.borderWidth : 1;
+    const ops = [];
+    if (style.background)
+        ops.push(`${pdfColor(style.background)} rg ${circlePath(w / 2, h / 2, r)} f`);
+    const stroke = style.border ?? style.color;
+    ops.push(`${pdfColor(stroke)} RG ${num2(bw)} w ${circlePath(w / 2, h / 2, r - bw / 2)} S`);
+    return ops.join("\n");
+}
+/** An unselected radio button: just the ring. */
+export function radioOff(w, h, style) {
+    return radioRing(w, h, style);
+}
+/** A selected radio button: the ring plus a filled inner dot. */
+export function radioOn(w, h, style) {
+    const r = Math.min(w, h) / 2;
+    const dot = `${pdfColor(style.color)} rg ${circlePath(w / 2, h / 2, r * 0.45)} f`;
+    return `${radioRing(w, h, style)}\n${dot}`;
+}
+/**
+ * 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.
+ */
+export function pushButtonFace(w, h, style, caption, captionWidth, capHeight, fontRes, 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) : "";
+    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) {
+    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`);
+}
+/**
+ * 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) {
+    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) : "";
+    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
+// the value does not touch the frame.
+const FIELD_PAD = 2;
+// A list box highlights its selected rows. Viewers each pick their own colour; once we bake the
+// appearance WE decide, and this light blue is the familiar selection tint.
+const SELECTION_TINT = "0.60 0.75 0.95";
+/** 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). */
+/**
+ * A field value split into the lines it is DRAWN as.
+ *
+ * An explicit line break in the value is a line break, and only then does width wrapping apply within
+ * each paragraph. Wrapping on width alone ran the paragraphs together - a multi-line field showed
+ * "first lineSecond line" - and it did so on BOTH paths, creating a field and filling one, which is why
+ * this lives here rather than in either of them.
+ */
+export function wrapFieldValue(value, fontFamily, fontSize, fontStyle, maxWidth, metrics, multiline) {
+    if (!multiline)
+        return [value.replace(/\r\n?|\n/g, " ")];
+    // CR, LF and CRLF all mean one break (PDF 7.3.4.2 says the same about a literal string).
+    return value
+        .split(/\r\n?|\n/)
+        .flatMap((para) => para === ""
+        ? [""]
+        : wrapStringIntoLines(para, fontFamily, fontSize, fontStyle, maxWidth, metrics));
+}
+/**
+ * The size a field draws its value at. `0` in `/DA` is the PDF convention for "auto, fit the box", and
+ * both paths - creating a field and filling one - have to resolve it the SAME way, or the same field
+ * comes out at two different sizes depending on which one touched it last.
+ */
+export function fieldDrawSize(fontSize, height, borderWidth, capHeight) {
+    if (fontSize > 0)
+        return fontSize;
+    const available = height - 2 * (2 + borderWidth);
+    return Math.max(4, Math.min(12, (available * 0.7) / (capHeight || 0.7)));
+}
+/** Where a line of `width` starts, given the box, its padding and the requested alignment. */
+function alignX(boxWidth, pad, width, align = "left") {
+    if (align === "center")
+        return (boxWidth - width) / 2;
+    if (align === "right")
+        return boxWidth - pad - width;
+    return pad;
+}
+/**
+ * `BT … ET` for absolutely-placed lines. `Tm` (not `Td`) so each line's position is independent.
+ *
+ * Field text is drawn UNKERNED (a plain `Tj`, never a `TJ` array), even though ordinary document text
+ * kerns by default. That is deliberate: the moment someone clicks into a field, the viewer regenerates
+ * this appearance from `/DA` - and viewers do not kern field text. Kerning here would make the value
+ * 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) {
+    const runs = lines
+        .map((l) => `1 0 0 1 ${num2(l.x)} ${num2(l.y)} Tm (${escPdf(l.text)}) Tj`)
+        .join("\n");
+    return `BT /${fontRes} ${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. */
+function clipped(w, h, ops) {
+    return `q 0 0 ${num2(w)} ${num2(h)} re W n\n${ops}\nQ`;
+}
+/**
+ * A text field's value, baked. `lines` is already wrapped (one entry for a single-line field). A
+ * 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") {
+    const face = box(w, h, style);
+    if (lines.length === 0)
+        return face;
+    const pad = FIELD_PAD + style.borderWidth;
+    const lineHeight = size * 1.15;
+    const placed = lines.map((l, i) => ({
+        text: l.text,
+        x: alignX(w, pad, l.width, align),
+        // Multi-line: the first line's capitals start one cap-height below the top inset, then step down.
+        // 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))}`;
+}
+/**
+ * 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") {
+    const pad = FIELD_PAD + style.borderWidth;
+    const lineHeight = size * 1.15;
+    const rowTop = (i) => h - pad - (i + 1) * lineHeight;
+    // Highlights first, so the text sits on top of them.
+    const highlights = lines
+        .map((l, i) => l.selected
+        ? `${SELECTION_TINT} rg ${num2(pad / 2)} ${num2(rowTop(i))} ${num2(w - pad)} ${num2(lineHeight)} re f`
+        : "")
+        .filter(Boolean)
+        .join("\n");
+    const placed = lines.map((l, i) => ({
+        text: l.text,
+        x: alignX(w, pad, l.width, 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");
+    return `${box(w, h, style)}\n${clipped(w, h, inner)}`;
+}

package/dist/forms/field.d.ts

@@ -0,0 +1,164 @@
+import type { Color } from "../common/color.js";
+/**
+ * The semantic description of ONE AcroForm field, independent of whether it is being CREATED (the field
+ * elements produce it) or FILLED in an existing PDF (the reader parses existing fields into it, later).
+ * This shared model is the spine that makes "create" and "fill existing" two parts of one feature.
+ *
+ * A discriminated union, one `kind` per PDF field family (/Tx, /Btn, /Ch, /Sig) - all of them
+ * implemented, so a `switch` over `kind` is exhaustive.
+ */
+export type FormFieldSpec = TextFieldSpec | CheckboxSpec | RadioSpec | ChoiceSpec | PushButtonSpec | SignatureSpec;
+/**
+ * What every field kind shares, whatever its family. Kept in one place so a new field type cannot
+ * silently miss them.
+ */
+export interface CommonFieldProps {
+    /** A tooltip / accessible name (/TU). */
+    tooltip?: string;
+    /** Show the field but do not let it be changed. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted (/Ff Required). */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+}
+/** How a value is aligned inside its field box (the PDF calls this "quadding", /Q). */
+export type FieldAlign = "left" | "center" | "right";
+/**
+ * A variable text field (/Tx). The PDF variants live in field flags; here they are typed props, so you
+ * never hand-assemble a `/Ff` bitmask.
+ */
+export interface TextFieldSpec extends CommonFieldProps {
+    kind: "text";
+    /** The field's name (/T) - what you read the value back by. Must be unique in the document. */
+    name: string;
+    /** The current text value (/V). */
+    value?: string;
+    /** A tooltip / accessible name for the field (/TU). */
+    tooltip?: string;
+    /** Wrap across multiple lines instead of a single line (the Multiline flag). */
+    multiline?: boolean;
+    /** Mask the typed characters (the Password flag). */
+    password?: boolean;
+    /** How the value sits in the box (default left). Applies to the baked appearance AND /Q. */
+    align?: FieldAlign;
+    /** Maximum number of characters the field accepts (/MaxLen). */
+    maxLength?: number;
+}
+/**
+ * A checkbox (/Btn, neither the Radio nor the Pushbutton flag). Its value is the "on" export name when
+ * checked and `Off` when not - PDF checkboxes use NAMES, not strings; we hide that behind `checked`.
+ */
+export interface CheckboxSpec extends CommonFieldProps {
+    kind: "checkbox";
+    /** The field name (/T). */
+    name: string;
+    /** Whether it starts checked. */
+    checked?: boolean;
+    /** The "on" export value (the /AP state name + /V when checked). Default `"Yes"`. */
+    onValue?: string;
+}
+/**
+ * One radio button (/Btn with the Radio flag). Every radio sharing a `group` is ONE AcroForm field whose
+ * `/Kids` are the individual buttons - mutually exclusive, so picking one clears the rest. `value` is this
+ * button's export name (unique within the group); it becomes the field's value when this one is picked.
+ */
+export interface RadioSpec extends CommonFieldProps {
+    kind: "radio";
+    /** The shared group name (/T of the parent field). All radios with the same `group` are one field. */
+    group: string;
+    /** This button's export value - unique in the group; the field's /V when this one is selected. */
+    value: string;
+    /** Whether this button starts selected (at most one per group should be). */
+    selected?: boolean;
+}
+/** One entry of a choice field. `label` is what the reader sees; `value` is what gets stored. */
+export interface ChoiceOption {
+    value: string;
+    label?: string;
+}
+/**
+ * A choice field (/Ch): a dropdown (combo box) or a list box. `combo` picks which. The value(s) are
+ * export strings from `options`. A combo may be `editable` (the reader can type a value not in the list);
+ * a list box may allow `multiSelect`.
+ */
+export interface ChoiceSpec extends CommonFieldProps {
+    kind: "choice";
+    /** The field name (/T). */
+    name: string;
+    /** The selectable options. */
+    options: ChoiceOption[];
+    /** `true` = dropdown (combo box), `false` = list box. */
+    combo: boolean;
+    /** Combo only: let the reader type a value that is not in the list. */
+    editable?: boolean;
+    /** List box only: allow more than one selection. */
+    multiSelect?: boolean;
+    /** The selected value (single-select). */
+    value?: string;
+    /** How the value sits in the box (default left). */
+    align?: FieldAlign;
+    /** The selected values (a `multiSelect` list box). */
+    values?: string[];
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+}
+/**
+ * What a push button does when clicked. A typed union, so an action can never be half-specified (a
+ * submit without a target is not expressible). Scripted (JavaScript) actions are deliberately out of
+ * scope - a jasy form is data, not a program.
+ */
+export type ButtonAction = {
+    kind: "reset";
+} | {
+    kind: "submit";
+    url: string;
+} | {
+    kind: "url";
+    url: string;
+};
+/**
+ * A push button (/Btn with the Pushbutton flag). Unlike every other field it holds NO value - it is a
+ * click target that fires an action. Its caption is baked into the appearance stream, so the button
+ * looks the same in every viewer and in print.
+ */
+export interface PushButtonSpec extends CommonFieldProps {
+    kind: "pushbutton";
+    /** The field name (/T). */
+    name: string;
+    /** The caption drawn on the button. */
+    label: string;
+    /** What clicking it does; omit for a button that does nothing (a plain label). */
+    action?: ButtonAction;
+}
+/**
+ * A signature field (/Sig) - a PLACEHOLDER where a signature can later be applied. jasy creates the
+ * field and its empty appearance; it does not sign (real signing needs a certificate and a byte-range
+ * digest, a separate feature). An unsigned field has no /V; a signer fills that in later.
+ */
+export interface SignatureSpec extends CommonFieldProps {
+    kind: "signature";
+    /** The field name (/T). */
+    name: string;
+    /** A hint drawn inside the empty box, e.g. "Signature" or the signer's role. */
+    label?: string;
+}
+/**
+ * How a field's WIDGET is painted: the box (border + fill) and how its value looks (font size + colour).
+ * Kept separate from the semantic spec because it maps to the widget `/MK` + `/DA`, not the field value -
+ * and the fill-existing path reuses it to restyle a field it did not create.
+ */
+export interface FieldStyle {
+    /** Border (stroke) colour of the field box. Omit for no border. */
+    border?: Color;
+    /** Background fill of the field box. Omit for transparent. */
+    background?: Color;
+    /** The value's text colour (drawn into `/DA`). */
+    color: Color;
+    /** Font size in points; `0` lets the viewer auto-size to the box (the PDF convention). */
+    fontSize: number;
+    /** Border thickness in points (only drawn when a `border` is set). */
+    borderWidth: number;
+}

package/dist/forms/field.js

@@ -0,0 +1 @@
+export {};

package/dist/forms/pdf.d.ts

@@ -0,0 +1,19 @@
+import type { Color } from "../common/color.js";
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+/** The regular face, for measuring a field's built-in Helvetica. `FontStyle` is a string enum, so this
+ *  is its exact value - asserted here once instead of importing the enum (which would be a runtime
+ *  import of the writer, see above). */
+export declare const NORMAL_STYLE: FontStyle;
+/** Escape a PDF literal string: backslash first, then the string delimiters. */
+export declare const escPdf: (s: string) => string;
+/** Trim a number to 2 decimals (PDF operands). */
+export declare const num2: (n: number) => number;
+/** A colour as PDF operands "r g b" in 0..1 (Color stores 0..255). */
+export declare const pdfColor: (c: Color) => string;
+/**
+ * Escape a PDF **Name** token (`/Yes`, `/Off`, a checkbox's export value). A Name may only hold the
+ * regular characters; whitespace, the delimiters `()<>[]{}/%` and `#` itself must be written `#XX` by
+ * BYTE. Without this, an export value like `"Ja / Nein"` would break the dictionary it sits in.
+ * Literal strings - `(text)` - use `escPdf` instead; the two escapes are not interchangeable.
+ */
+export declare const escName: (s: string) => string;

package/dist/forms/pdf.js

@@ -0,0 +1,28 @@
+// Small PDF-writer helpers shared across the forms module (widget dicts + appearance streams).
+//
+// Note: everything under `forms/` imports the object manager TYPE-ONLY. Keeping the runtime dependency
+// one-way (the writer owns a collector, never the reverse) avoids an ESM import cycle.
+/** The regular face, for measuring a field's built-in Helvetica. `FontStyle` is a string enum, so this
+ *  is its exact value - asserted here once instead of importing the enum (which would be a runtime
+ *  import of the writer, see above). */
+export const NORMAL_STYLE = "normal";
+/** Escape a PDF literal string: backslash first, then the string delimiters. */
+export const escPdf = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+/** Trim a number to 2 decimals (PDF operands). */
+export const num2 = (n) => Number(n.toFixed(2));
+/** A colour as PDF operands "r g b" in 0..1 (Color stores 0..255). */
+export const pdfColor = (c) => c
+    .toArray()
+    .map((v) => (v / 255).toFixed(3))
+    .join(" ");
+/**
+ * Escape a PDF **Name** token (`/Yes`, `/Off`, a checkbox's export value). A Name may only hold the
+ * regular characters; whitespace, the delimiters `()<>[]{}/%` and `#` itself must be written `#XX` by
+ * BYTE. Without this, an export value like `"Ja / Nein"` would break the dictionary it sits in.
+ * Literal strings - `(text)` - use `escPdf` instead; the two escapes are not interchangeable.
+ */
+export const escName = (s) => Array.from(new TextEncoder().encode(s))
+    .map((b) => b >= 0x21 && b <= 0x7e && !"()<>[]{}/%#".includes(String.fromCharCode(b))
+    ? String.fromCharCode(b)
+    : "#" + b.toString(16).padStart(2, "0").toUpperCase())
+    .join("");

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

@@ -1,5 +1,6 @@
 import { Color } from "../common/color.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
 /**
  * Display list - the seam between layout and the PDF backend.
  *
@@ -31,6 +32,9 @@ export interface TextRun {
     x: number;
     y: number;
     text: string;
+    /** The glyphs to draw, when the run was SHAPED. The backend emits these instead of encoding `text`,
+     *  which stays logical for `ToUnicode` and the accessible tree. */
+    glyphs?: number[];
     fontFamily: string;
     fontStyle: FontStyle;
     fontSize: number;
@@ -39,17 +43,31 @@ export interface TextRun {
     tag?: StructTag;
 }
 /** An axis-aligned rectangle. An absent `fill` or `stroke` means that part is not drawn. */
+/**
+ * Corner radii in points (CSS `border-radius`). Any corner left out falls back to 0. A single number
+ * everywhere is the common case and stays a plain `number` on the nodes, so nothing changed for a
+ * document that never asks for different corners.
+ */
+export interface Radii {
+    tl?: number;
+    tr?: number;
+    br?: number;
+    bl?: number;
+}
+/** True when any corner asks for a radius - the gate between a plain rect and a curved path. */
+export declare function isRounded(radius: number | Radii | undefined): boolean;
 export interface Rect {
     type: "rect";
     x: number;
     y: number;
     width: number;
     height: number;
-    fill?: Color;
+    /** Solid colour, or a gradient whose anchor points are in absolute page coordinates. */
+    fill?: Color | Gradient;
     stroke?: Color;
     strokeWidth: number;
-    /** Corner radius in points; absent/0 = sharp corners (plain `re`). */
-    radius?: number;
+    /** Corner radius in points - one number for all four, or per corner. Absent/0 = sharp (plain `re`). */
+    radius?: number | Radii;
     tag?: StructTag;
 }
 /** A straight line segment between two points. */
@@ -83,8 +101,8 @@ export interface Image {
         width: number;
         height: number;
     };
-    /** Corner radius in points for the image box; absent/0 = sharp corners. */
-    radius?: number;
+    /** Corner radius in points for the image box - one number or per corner; absent/0 = sharp. */
+    radius?: number | Radii;
     tag?: StructTag;
 }
 /**
@@ -98,7 +116,7 @@ export interface ClipPush {
     y: number;
     width: number;
     height: number;
-    radius?: number;
+    radius?: number | Radii;
 }
 /** Closes the most recent `ClipPush` (restores the graphics state). */
 export interface ClipPop {
@@ -145,6 +163,21 @@ export interface Outline {
     title: string;
     level: number;
 }
+/**
+ * An interactive form field (AcroForm). Like `Link` it draws NOTHING into the content stream - it becomes
+ * a Widget ANNOTATION on the page (`/Annots`) and a field in the catalog `/AcroForm`, both built from the
+ * shared `FormFieldSpec`. The rect is the field box in top-left engine coords; the Y-flip converts it to
+ * page space. See `forms/acroform.ts` for the widget/field assembly.
+ */
+export interface FormFieldNode {
+    type: "formfield";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    field: FormFieldSpec;
+    style: FieldStyle;
+}
 /**
  * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the
  * matching `TransformPop` is painted through `matrix`. This is what `Rotated` wraps its child's nodes
@@ -227,4 +260,4 @@ export interface Path {
     tag?: StructTag;
 }
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | TransformPush | TransformPop;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | FormFieldNode | TransformPush | TransformPop;

package/dist/ir/display-list.js

@@ -1 +1,8 @@
-export {};
+/** True when any corner asks for a radius - the gate between a plain rect and a curved path. */
+export function isRounded(radius) {
+    if (radius === undefined)
+        return false;
+    if (typeof radius === "number")
+        return radius > 0;
+    return ((radius.tl ?? 0) > 0 || (radius.tr ?? 0) > 0 || (radius.br ?? 0) > 0 || (radius.bl ?? 0) > 0);
+}

package/dist/layout/alignment.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Flex alignment vocabulary. It lives here rather than in `utils/flex-layout.ts` because the base
+ * `PDFElement` needs `CrossAlign` for `alignSelf`, and flex-layout imports the elements - defining it
+ * there would close a cycle.
+ */
+/** Distribution along the MAIN axis (CSS `justify-content`). */
+export type MainAlign = "start" | "center" | "end" | "between" | "around";
+/** Position/size ACROSS the axis (CSS `align-items` / `align-self`). `stretch` fills the cross extent;
+ *  the others place the child at its natural cross size. */
+export type CrossAlign = "start" | "center" | "end" | "stretch";

package/dist/layout/alignment.js

@@ -0,0 +1,6 @@
+/**
+ * Flex alignment vocabulary. It lives here rather than in `utils/flex-layout.ts` because the base
+ * `PDFElement` needs `CrossAlign` for `alignSelf`, and flex-layout imports the elements - defining it
+ * there would close a cycle.
+ */
+export {};

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

@@ -41,6 +41,12 @@ export declare class BoxConstraints {
      * what a padding/border element hands its child after reserving its own insets.
      */
     deflate(horizontal: number, vertical: number): BoxConstraints;
+    /**
+     * Tightens this box by an element's own `min`/`max` on either axis. A max never widens the offered
+     * room, and a min may push past it - `minHeight: 500` in a 300pt region means 500, and pagination
+     * deals with the overflow, the same answer CSS gives.
+     */
+    narrow(minWidth?: number, maxWidth?: number, minHeight?: number, maxHeight?: number): BoxConstraints;
     /** Returns the constraints clamped to lie within `parent` (Flutter's enforce). */
     enforce(parent: BoxConstraints): BoxConstraints;
 }
@@ -52,6 +58,53 @@ export declare class BoxConstraints {
  * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
  */
 export declare function resolveExtent(fixed: number | undefined, factor: number | undefined, boundedMax: number, hasBounded: boolean): number | undefined;
+/** What one axis of a sized element was asked for: a size, plus the bounds it must stay inside. */
+export interface ExtentSpec {
+    fixed?: number;
+    factor?: number;
+    min?: number;
+    minFactor?: number;
+    max?: number;
+    maxFactor?: number;
+}
+/** The sizing options every sized element accepts. Each `*Factor` is the percentage form of its pair. */
+export interface SizingParams {
+    width?: number;
+    height?: number;
+    widthFactor?: number;
+    heightFactor?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height. Derives whichever axis is left open; see `resolveSize`. */
+    aspectRatio?: number;
+}
+/** Split `SizingParams` into the per-axis form `resolveSize` takes. */
+export declare function extentSpecs(p: SizingParams): {
+    width: ExtentSpec;
+    height: ExtentSpec;
+};
+/**
+ * Resolve both axes of a sized element: relative sizing, then `aspectRatio`, then `min`/`max`.
+ *
+ * The order follows CSS: a ratio fills in the axis you left open, and min/max clamp afterwards - so an
+ * explicit bound wins over the ratio, exactly as `min-height` beats `aspect-ratio` in a browser.
+ *
+ * `min`/`max` also come back as NARROWED constraints, because an axis with no explicit size still has
+ * to obey them. `maxWidth` alone means "fill, but no wider than this", and the caller's own fill and
+ * shrink-wrap paths get that for free by using the returned constraints instead of the ones passed in.
+ * A `width` of `undefined` keeps its usual meaning: fill or shrink-wrap.
+ */
+export declare function resolveSize(width: ExtentSpec, height: ExtentSpec, aspectRatio: number | undefined, constraints: BoxConstraints): {
+    width?: number;
+    height?: number;
+    constraints: BoxConstraints;
+};
 /** The size an element resolves to and returns UP the tree. */
 export interface Size {
     width: number;