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

package/dist/api/font-url.js

@@ -5,9 +5,9 @@
  * same contract, differing only in being async. So the failure lands where you asked for the font,
  * not somewhere inside a later render.
  *
- * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
- * port, unlike the filesystem read beside it.
+ * The fetch itself - timeout, size ceiling - is `utils/fetch-bytes.ts`, shared with images.
  */
+import { fetchBytes } from "../utils/fetch-bytes.js";
 /** Thrown when a font could not be fetched or is not one we can parse. Always says which URL. */
 export class FontUrlError extends Error {
     constructor(message) {
@@ -36,82 +36,16 @@ function describeSignature(bytes) {
         return { ok: false, what: "not a font at all" };
     return { ok: false, what: "not a font we recognise" };
 }
-/** How long one font may take to arrive before we give up. A hung server must not hang a render. */
+/** How long one font may take to arrive before we give up. */
 const TIMEOUT_MS = 15000;
-/**
- * How large a font file may be. Generous on purpose - a full CJK face is tens of megabytes and is a
- * legitimate thing to embed - but not unbounded: a URL pointing at the wrong file (a video, a disk
- * image) would otherwise be read into memory in full before anyone notices it is not a font.
- */
+/** How large a font file may be: generous on purpose - a full CJK face is tens of megabytes. */
 const MAX_BYTES = 32 * 1024 * 1024;
-/** Read the body with a running ceiling, so an oversized response is dropped WHILE it arrives. */
-async function readBounded(response, url) {
-    // `Content-Length` is the cheap early exit; a server may omit or misstate it, so it is a hint only
-    // and the real ceiling is enforced below while reading.
-    const declared = Number(response.headers?.get?.("content-length") ?? NaN);
-    if (Number.isFinite(declared) && declared > MAX_BYTES) {
-        throw new FontUrlError(`the font at ${url} is ${declared} bytes; the limit is ${MAX_BYTES}`);
-    }
-    const body = response.body;
-    if (!body?.getReader) {
-        // No streaming body (an older runtime, or a stubbed response): fall back to reading it whole and
-        // checking afterwards. Weaker, but never worse than not checking at all.
-        const whole = new Uint8Array(await response.arrayBuffer());
-        if (whole.length > MAX_BYTES) {
-            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
-        }
-        return whole;
-    }
-    const reader = body.getReader();
-    const chunks = [];
-    let total = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        total += value.length;
-        if (total > MAX_BYTES) {
-            await reader.cancel();
-            throw new FontUrlError(`the font at ${url} is larger than the ${MAX_BYTES} byte limit`);
-        }
-        chunks.push(value);
-    }
-    if (chunks.length === 1)
-        return chunks[0];
-    const out = new Uint8Array(total);
-    let at = 0;
-    for (const c of chunks) {
-        out.set(c, at);
-        at += c.length;
-    }
-    return out;
-}
 /** Fetch one font file and hand back its bytes, refusing anything we could not embed. */
 async function fetchFont(url) {
-    let response;
-    try {
-        response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    }
-    catch (e) {
-        const why = e?.name === "TimeoutError" || e?.name === "AbortError"
-            ? `it did not respond within ${TIMEOUT_MS} ms`
-            : String(e?.message ?? e);
-        throw new FontUrlError(`could not fetch the font at ${url}: ${why}`);
-    }
-    if (!response.ok) {
-        throw new FontUrlError(`the font at ${url} could not be fetched: HTTP ${response.status}`);
-    }
-    // Everything past here still talks to the network, so a failure mid-body must not escape as a raw
-    // TypeError - a caller catching FontUrlError would miss it.
-    let bytes;
-    try {
-        bytes = await readBounded(response, url);
-    }
-    catch (e) {
-        if (e instanceof FontUrlError)
-            throw e;
-        throw new FontUrlError(`the font at ${url} could not be read: ${String(e?.message ?? e)}`);
-    }
+    const bytes = await fetchBytes(url, "font", FontUrlError, {
+        timeoutMs: TIMEOUT_MS,
+        maxBytes: MAX_BYTES,
+    });
     if (bytes.length < 4) {
         throw new FontUrlError(`the font at ${url} is empty`);
     }

package/dist/api/forms.d.ts

@@ -297,6 +297,9 @@ export interface PushButtonOptions {
  * A clickable push button (AcroForm /Btn). It holds no value - it fires an action. Its caption is baked
  * into the appearance, so the button looks the same in every viewer and in print.
  *
+ * Not for PDF/A: PDF/A forbids an action on a form field (ISO 19005-2/-3, 6.4.1), and an action is all a
+ * push button does.
+ *
  * ```ts
  * PushButton({ name: "send", label: "Submit", action: { submit: "https://example.com/f" }, width: 120 })
  * PushButton({ name: "clear", label: "Reset", action: "reset", width: 90 })

package/dist/api/forms.js

@@ -146,6 +146,9 @@ const toAction = (a) => {
  * A clickable push button (AcroForm /Btn). It holds no value - it fires an action. Its caption is baked
  * into the appearance, so the button looks the same in every viewer and in print.
  *
+ * Not for PDF/A: PDF/A forbids an action on a form field (ISO 19005-2/-3, 6.4.1), and an action is all a
+ * push button does.
+ *
  * ```ts
  * PushButton({ name: "send", label: "Submit", action: { submit: "https://example.com/f" }, width: 120 })
  * PushButton({ name: "clear", label: "Reset", action: "reset", width: 90 })

package/dist/api/gradient.d.ts

@@ -1,53 +1 @@
-import { type ColorInput } from "./color.js";
-import type { Gradient } from "../ir/display-list.js";
-/**
- * Gradients for a box background.
- *
- * The public form is BOX-RELATIVE - an angle and some stops - because that is what an author knows
- * when writing the document. The engine's `Gradient` wants absolute page coordinates, so the renderer
- * resolves one against the box it is painting; see `resolveGradient`.
- */
-/** A stop as written: a colour, optionally pinned to a position 0..1 along the axis. */
-export type StopInput = ColorInput | {
-    color: ColorInput;
-    at: number;
-};
-export interface LinearGradientInput {
-    kind: "linear";
-    /** Direction in degrees, CSS convention: 0 = to the top, 90 = to the right (default 180, downwards). */
-    angle: number;
-    stops: StopInput[];
-}
-export interface RadialGradientInput {
-    kind: "radial";
-    /** Centre as a fraction of the box, `[0.5, 0.5]` being the middle (the default). */
-    center: [number, number];
-    /** Outer radius as a fraction of the box's larger side (default 0.5, i.e. it touches the edges). */
-    radius: number;
-    stops: StopInput[];
-}
-export type GradientInput = LinearGradientInput | RadialGradientInput;
-export declare const isGradientInput: (v: unknown) => v is GradientInput;
-/**
- * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
- * other direction, and `{ color, at }` for a stop that is not evenly spaced.
- */
-export declare function linearGradient(...args: [...StopInput[]] | [{
-    angle?: number;
-    stops: StopInput[];
-}]): LinearGradientInput;
-/** A radial gradient, centred by default and reaching the edges. */
-export declare function radialGradient(...args: [...StopInput[]] | [{
-    center?: [number, number];
-    radius?: number;
-    stops: StopInput[];
-}]): RadialGradientInput;
-/**
- * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
- * IR wants. Called by the renderer, which is the first place the box's geometry is known.
- *
- * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
- * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
- * a 45-degree gradient reaches the corners rather than stopping short of them.
- */
-export declare function resolveGradient(g: GradientInput, x: number, y: number, width: number, height: number): Gradient;
+export * from "../common/gradient.js";

package/dist/api/gradient.js

@@ -1,97 +1,2 @@
-import { toColor } from "./color.js";
-export const isGradientInput = (v) => typeof v === "object" && v !== null && "kind" in v && "stops" in v;
-/**
- * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
- * other direction, and `{ color, at }` for a stop that is not evenly spaced.
- */
-export function linearGradient(...args) {
-    const first = args[0];
-    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
-        return { kind: "linear", angle: first.angle ?? 180, stops: first.stops };
-    }
-    return { kind: "linear", angle: 180, stops: args };
-}
-/** A radial gradient, centred by default and reaching the edges. */
-export function radialGradient(...args) {
-    const first = args[0];
-    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
-        return {
-            kind: "radial",
-            center: first.center ?? [0.5, 0.5],
-            radius: first.radius ?? 0.5,
-            stops: first.stops,
-        };
-    }
-    return { kind: "radial", center: [0.5, 0.5], radius: 0.5, stops: args };
-}
-/**
- * Spread the stops that carry no `at` evenly, first to last, the way CSS does - and check the pinned
- * ones, because they end up in a PDF stitching function's `/Bounds`, which the format requires to be
- * strictly increasing inside the domain. A bad offset there is not a wrong-looking gradient, it is a
- * malformed file, so it is refused by name here rather than emitted.
- */
-function toStops(stops) {
-    if (stops.length < 2) {
-        throw new Error("A gradient needs at least two colour stops.");
-    }
-    const last = stops.length - 1;
-    const out = stops.map((s, i) => {
-        const pinned = typeof s === "object" && s !== null && "at" in s;
-        const at = pinned ? s.at : i / last;
-        if (!Number.isFinite(at) || at < 0 || at > 1) {
-            throw new Error(`Invalid gradient stop position ${at}: it must be a number between 0 and 1.`);
-        }
-        return {
-            offset: at,
-            color: toColor(pinned ? s.color : s),
-        };
-    });
-    for (let i = 1; i < out.length; i++) {
-        if (out[i].offset <= out[i - 1].offset) {
-            throw new Error(`Gradient stops must move forward: stop ${i} sits at ${out[i].offset}, which is not after ` +
-                `${out[i - 1].offset}. (Two stops at the SAME position would be a hard colour edge in CSS; ` +
-                `PDF cannot express that in one shading, so it is refused rather than drawn wrongly.)`);
-        }
-    }
-    // A pinned first or last stop would otherwise be IGNORED - the shading's domain is always 0..1 and
-    // only the INTERIOR offsets reach /Bounds. Carrying the edge colour outwards is what CSS does.
-    if (out[0].offset > 0)
-        out.unshift({ offset: 0, color: out[0].color });
-    if (out[out.length - 1].offset < 1)
-        out.push({ offset: 1, color: out[out.length - 1].color });
-    return out;
-}
-/**
- * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
- * IR wants. Called by the renderer, which is the first place the box's geometry is known.
- *
- * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
- * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
- * a 45-degree gradient reaches the corners rather than stopping short of them.
- */
-export function resolveGradient(g, x, y, width, height) {
-    const stops = toStops(g.stops);
-    if (g.kind === "radial") {
-        const cx = x + g.center[0] * width;
-        const cy = y + g.center[1] * height;
-        const r = g.radius * Math.max(width, height);
-        return { type: "radial", x0: cx, y0: cy, r0: 0, x1: cx, y1: cy, r1: r, stops, extend: "pad" };
-    }
-    const rad = ((g.angle % 360) * Math.PI) / 180;
-    // CSS angles: 0 = up, clockwise. The engine lays out top-left down, so "up" is -y here.
-    const dx = Math.sin(rad);
-    const dy = -Math.cos(rad);
-    // Half the box's extent along the axis, so the line covers the whole box for any angle.
-    const half = (Math.abs(dx) * width + Math.abs(dy) * height) / 2;
-    const cx = x + width / 2;
-    const cy = y + height / 2;
-    return {
-        type: "linear",
-        x0: cx - dx * half,
-        y0: cy - dy * half,
-        x1: cx + dx * half,
-        y1: cy + dy * half,
-        stops,
-        extend: "pad",
-    };
-}
+// Lives in `common/` because the engine reads it too; this is its public face.
+export * from "../common/gradient.js";

package/dist/api/index.d.ts

@@ -2,12 +2,16 @@ export * from "./color.js";
 export * from "./insets.js";
 export * from "./gradient.js";
 export * from "./font-url.js";
+export { FontFormatError } from "../utils/ttf-parser.js";
+export { JpegFormatError } from "../utils/image-helper.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
 export * from "./content.js";
 export * from "./page-builder.js";
+export * from "./flow.js";
 export * from "./structure.js";
+export type { Diagnostic, DiagnosticCode, DiagnosticHandler } from "../common/diagnostics.js";
 export * from "./table.js";
 export * from "./forms.js";
 export * from "./descriptor.js";

package/dist/api/index.js

@@ -5,11 +5,14 @@ export * from "./color.js";
 export * from "./insets.js";
 export * from "./gradient.js";
 export * from "./font-url.js";
+export { FontFormatError } from "../utils/ttf-parser.js";
+export { JpegFormatError } from "../utils/image-helper.js";
 export * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
 export * from "./content.js";
 export * from "./page-builder.js";
+export * from "./flow.js";
 export * from "./structure.js";
 export * from "./table.js";
 export * from "./forms.js";

package/dist/api/layout.d.ts

@@ -187,6 +187,12 @@ export interface ExpandedOptions {
      * rest`, so `flexBasis: 120` with `flex: 0` is simply a fixed 120pt slot. Default 0.
      */
     flexBasis?: SizeInput;
+    /**
+     * How willingly this child gives up its `flexBasis` when the line overflows (CSS `flex-shrink`). Default
+     * 1, as for every flex item: an overflowing line pulls a `flexBasis: 120` slot back down to what its
+     * content can hold. `0` keeps the basis and lets the line overflow. A basis of 0 has nothing to give.
+     */
+    flexShrink?: number;
 }
 /**
  * Makes a child fill the leftover space along the stack's main axis (height in a Column,

package/dist/api/layout.js

@@ -11,6 +11,7 @@ import { BookmarkElement } from "../elements/layout/bookmark-element.js";
 import { AnchorElement } from "../elements/layout/anchor-element.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
 import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
+import { flexibleOf } from "../layout/flex-item.js";
 import { toColor } from "./color.js";
 import { isGradientInput } from "./gradient.js";
 import { toEdges } from "./insets.js";
@@ -89,10 +90,15 @@ export function Box(a, b) {
         ? [
             new PaddingElement({
                 margin: toEdges(opts.padding),
-                child: children.length === 1 ? children[0] : Column(children),
+                child: children.length === 1 && !flexibleOf(children[0]) ? children[0] : Column(children),
+                ofBox: true,
             }),
         ]
-        : children;
+        : // A Spacer/Expanded - also one inside a transparent wrapper such as a Link - needs a flex parent,
+            // alone as much as among siblings.
+            children.some((child) => flexibleOf(child) !== undefined)
+                ? [Column(children)]
+                : children;
     // A side is set if it (or the uniform `border`) is given. If ANY differs from a plain
     // uniform border, we hand the engine per-side colors (which draws individual lines).
     const sideKeys = [opts.borderTop, opts.borderRight, opts.borderBottom, opts.borderLeft];
@@ -226,5 +232,5 @@ export function Expanded(a, b) {
         basis: basis?.points,
         basisFactor: basis?.factor,
         child,
-    });
+    }).withFlexShrink(opts.flexShrink);
 }

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

@@ -24,6 +24,10 @@ export type { PageInfo };
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
  * SHRINK on later pages but must not GROW, because the body band was measured against the first build.
+ *
+ * What it builds is placed WHOLE: it never splits across pages, and a `PageBreak` inside it has no
+ * effect. Its content belongs to one page by construction - a piece continued on the next page would
+ * have been built for the wrong one. Keep it to what fits on a page; flowing content goes beside it.
  */
 export declare function PageBuilder(build: (info: PageInfo) => PDFElement): PageBuilderElement;
 /** `Text` options plus an `offset` added to the number (e.g. `-1` to not count a cover page). */

package/dist/api/page-builder.js

@@ -22,6 +22,10 @@ import { Text } from "./text.js";
  * content decides the count that the content displays): in the flowing BODY the box is reserved before the
  * total is known, so a much wider final string can paint slightly past it; and a conditional header may
  * SHRINK on later pages but must not GROW, because the body band was measured against the first build.
+ *
+ * What it builds is placed WHOLE: it never splits across pages, and a `PageBreak` inside it has no
+ * effect. Its content belongs to one page by construction - a piece continued on the next page would
+ * have been built for the wrong one. Keep it to what fits on a page; flowing content goes beside it.
  */
 export function PageBuilder(build) {
     return new PageBuilderElement({ build });

package/dist/api/structure.d.ts

@@ -3,6 +3,7 @@ import { PageElement } from "../elements/page-element.js";
 import { PDFElement } from "../elements/pdf-element.js";
 import { DefaultTextStyleElement } from "../elements/layout/default-text-style-element.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
+import type { DiagnosticHandler } from "../common/diagnostics.js";
 import { PageSize } from "../constants/page-sizes.js";
 import { type EncryptOptions } from "../crypto/security-handler.js";
 export type { EncryptOptions, Permissions } from "../crypto/security-handler.js";
@@ -38,8 +39,6 @@ export interface PageOptions extends StackOptions {
  */
 export declare function Page(children: PDFElement[]): PageElement;
 export declare function Page(opts: PageOptions, children: PDFElement[]): PageElement;
-/** Document options: PDF metadata plus the inheritable text defaults (font, size, color, lineHeight,
- *  align, bold/italic) every `Text` inherits unless it sets its own - Flutter's `DefaultTextStyle`. */
 /** Where color emoji come from when a code point isn't in the current text font, so `Text("Hi 😅")`
  *  works in one string. Either a **font** (native vector, offline - recommended; register it in
  *  `fonts`) as a string name or `{ font }`, or an **image/CDN source** `{ url, format }` (react-pdf
@@ -51,6 +50,8 @@ export type EmojiSource = string | {
     url: string;
     format?: "png";
 };
+/** Document options: PDF metadata plus the inheritable text defaults (font, size, color, lineHeight,
+ *  align, bold/italic) every `Text` inherits unless it sets its own - Flutter's `DefaultTextStyle`. */
 export interface DocumentOptions extends TextDefaults {
     /** PDF metadata. */
     meta?: {
@@ -158,6 +159,13 @@ export interface RenderOptions {
      * able to SAY which character went missing, where a server log would never be read.
      */
     onMissingGlyphs?: (characters: string[]) => void;
+    /**
+     * Everything the engine has to say about this document, one call per finding: a page break that had
+     * no effect, a group that could not be kept together, clipped overflow, removed characters, ... -
+     * each with a stable `code`, the kind of element and its first text. Without it, what warned before
+     * still goes to `console.warn`. `onOverflow: "error"` still throws.
+     */
+    onDiagnostic?: DiagnosticHandler;
     /** Encrypt the PDF with a password (AES-256, the newest standard). NOT compatible with PDF/A
      *  (ZUGFeRD invoices) - encrypting one throws, since PDF/A forbids encryption. */
     encrypt?: EncryptOptions;

package/dist/api/structure.js

@@ -180,6 +180,7 @@ export async function renderPdf(doc, options) {
             manager = om;
             om.setCompress(options?.compress !== false); // FlateDecode streams by default
             om.setOverflowPolicy(options?.onOverflow ?? "error");
+            om.diagnostics.setHandler(options?.onDiagnostic);
             om.setKerning(options?.kerning !== false); // on by default (experimental); `kerning:false` opts out
             om.acroform.setBakeAppearances(options?.fieldAppearances !== false); // baked unless opted out
             for (const [name, value] of Object.entries(fonts)) {
@@ -196,6 +197,14 @@ export async function renderPdf(doc, options) {
                         om.registerCustomFont(name, value.boldItalic, FontStyle.BoldItalic);
                 }
             }
+            // Version, id and encryption first - they create no objects, and an attachment's stream and name
+            // are written below and must already be enciphered. The handler after the version: R6 needs PDF 2.0.
+            if (options?.pdfVersion)
+                om.setPdfVersion(options.pdfVersion);
+            if (options?.documentId)
+                om.enableDocumentId();
+            if (securityHandler)
+                om.setSecurityHandler(securityHandler);
             for (const a of attachments) {
                 om.attachFile(a.name, a.data, {
                     relationship: a.relationship,
@@ -215,12 +224,6 @@ export async function renderPdf(doc, options) {
                 om.setXmpMetadata(options.xmp);
             if (options?.outputIntent)
                 om.setOutputIntent(options.outputIntent);
-            if (options?.pdfVersion)
-                om.setPdfVersion(options.pdfVersion);
-            if (options?.documentId)
-                om.enableDocumentId();
-            if (securityHandler)
-                om.setSecurityHandler(securityHandler);
             if (options?.accessible) {
                 om.struct.enabled = true;
                 if (options.lang)

package/dist/api/table.d.ts

@@ -2,14 +2,16 @@ import { PDFElement } from "../elements/pdf-element.js";
 import { Insets } from "./insets.js";
 import { ColorInput } from "./color.js";
 /**
- * A column width: a `number` of points (fixed), an `"Nfr"` fraction (splits the leftover
- * width), or `"auto"` (as wide as the widest cell in that column - measured at layout time).
+ * A column width, as in CSS grid with points for units: a `number` of points (fixed), an `"Nfr"`
+ * fraction (splits the leftover width, never narrower than its longest word), `"auto"` (as wide as the
+ * widest cell in that column, giving way down to its longest word when the table would not fit), or
+ * `"minmax(40, auto)"` (like `auto`, but never narrower than 40pt). Measured at layout time.
  */
 export type ColumnWidth = number | string;
 /** A table cell: any element, or a string (wrapped in `Text`). */
 export type Cell = PDFElement | string;
 export interface TableOptions {
-    /** One entry per column: a fixed point width, an `"Nfr"` fraction, or `"auto"`. */
+    /** One entry per column: a fixed point width, an `"Nfr"` fraction, `"auto"` or `"minmax(<pt>, auto)"`. */
     columns: ColumnWidth[];
     /** A header row that REPEATS at the top of every page the table flows onto. */
     header?: Cell[];

package/dist/api/table.js

@@ -14,27 +14,100 @@ function fractionOf(col) {
     const n = parseFloat(col);
     return Number.isFinite(n) ? n : 1;
 }
-/** The cell's unbounded (max-content) width - what an `"auto"` column sizes to. */
-function naturalWidth(cell, cellPadding, ctx) {
-    const el = cellPadding !== undefined ? Padding(cellPadding, asElement(cell)) : asElement(cell);
-    return el.calculateLayout(BoxConstraints.loose(Infinity, Infinity), { x: 0, y: 0 }, ctx).width;
+const MINMAX_AUTO = /^minmax\(\s*(\d+(?:\.\d+)?)\s*,\s*auto\s*\)$/;
+/**
+ * The floor of a content-sized column: 0 for `"auto"`, N for `"minmax(N, auto)"`, null for any other
+ * width. Other `minmax()` forms are not supported yet and say so, rather than being read as something else.
+ */
+function autoMinimum(col) {
+    if (col === "auto")
+        return 0;
+    if (typeof col !== "string" || !col.startsWith("minmax("))
+        return null;
+    const min = MINMAX_AUTO.exec(col);
+    if (!min) {
+        throw new Error(`Unsupported column width "${col}" - minmax() takes a minimum in points and "auto", e.g. "minmax(40, auto)"`);
+    }
+    return parseFloat(min[1]);
 }
-/** Replaces every `"auto"` column with the widest cell width measured down that column. */
-function resolveAutoColumns(opts, rows, ctx) {
+/**
+ * What the cells of column `i` need: `max` is the widest cell on one line (max-content), `min` the
+ * widest piece that cannot break (min-content, its longest word).
+ */
+function cellWidths(opts, rows, i, ctx) {
     // The composed cell sits in a 1pt-border Box (border-box) that eats 1pt each side, which the
     // measured content doesn't include; add it back, and `ceil` so a single-word cell can't land
     // a hair over the width and wrap to an empty first line.
     const slack = opts.cellBorder !== undefined || opts.rule !== undefined ? 2 : 0;
-    return opts.columns.map((col, i) => {
-        if (col !== "auto")
-            return col;
-        let w = opts.header ? naturalWidth(opts.header[i], opts.cellPadding, ctx) : 0;
-        for (const r of rows) {
-            if (r[i] !== undefined)
-                w = Math.max(w, naturalWidth(r[i], opts.cellPadding, ctx));
+    let min = 0;
+    let max = 0;
+    for (const cell of [opts.header?.[i], ...rows.map((r) => r[i])]) {
+        if (cell === undefined)
+            continue;
+        const el = opts.cellPadding !== undefined ? Padding(opts.cellPadding, asElement(cell)) : asElement(cell);
+        max = Math.max(max, el.measure(BoxConstraints.loose(Infinity, Infinity), ctx).width);
+        min = Math.max(min, el.minIntrinsicMain(true, ctx));
+    }
+    return { min: Math.ceil(min + slack), max: Math.ceil(max + slack) };
+}
+/** Grows `lo` toward `hi` by `extra`, in equal steps - each column stops at its own `hi`. */
+function growEvenly(lo, hi, extra) {
+    const out = [...lo];
+    let open = out.map((_, k) => k).filter((k) => hi[k] > out[k]);
+    while (extra > 1e-9 && open.length > 0) {
+        const each = extra / open.length;
+        for (const k of open) {
+            const add = Math.min(each, hi[k] - out[k]);
+            out[k] += add;
+            extra -= add;
         }
-        return Math.ceil(w + slack);
-    });
+        open = open.filter((k) => hi[k] - out[k] > 1e-9);
+    }
+    return out;
+}
+/**
+ * The column widths for a table `width` wide, as CSS grid sizes its tracks. An `"auto"` column takes
+ * its widest cell while that leaves every `fr` column its longest word; when it does not, the `auto`
+ * columns give way evenly, down to their own longest word. The `fr` columns then share what is left -
+ * one whose share would be narrower than its longest word gets exactly that, and the table overflows
+ * instead of drawing words over each other. With no width to fit (a table in a Row), nothing gives way.
+ */
+function resolveColumns(opts, rows, ctx, width) {
+    const columns = opts.columns;
+    const colGap = opts.colGap ?? opts.gap ?? 0;
+    const room = width - Math.max(0, columns.length - 1) * colGap;
+    const fixed = columns.reduce((n, c) => n + (typeof c === "number" ? c : 0), 0);
+    const autos = columns.flatMap((c, i) => (autoMinimum(c) === null ? [] : [i]));
+    const fractions = Number.isFinite(room)
+        ? columns.flatMap((c, i) => (fractionOf(c) === null ? [] : [i]))
+        : [];
+    const need = new Map();
+    for (const i of [...autos, ...fractions])
+        need.set(i, cellWidths(opts, rows, i, ctx));
+    const resolved = [...columns];
+    // 1. The auto columns: their widest cell, or less while an fr column would lose its longest word.
+    const lo = autos.map((i) => Math.max(autoMinimum(columns[i]), need.get(i).min));
+    const hi = autos.map((i) => Math.max(autoMinimum(columns[i]), need.get(i).max));
+    const frMin = fractions.reduce((n, i) => n + need.get(i).min, 0);
+    const free = room - fixed - frMin;
+    const sum = (xs) => xs.reduce((n, x) => n + x, 0);
+    const autoWidths = free >= sum(hi) ? hi : free <= sum(lo) ? lo : growEvenly(lo, hi, free - sum(lo));
+    autos.forEach((i, k) => (resolved[i] = autoWidths[k]));
+    // 2. The fr columns share the rest; one that would get less than its longest word is fixed at it.
+    let left = room - fixed - sum(autoWidths);
+    let flexible = fractions;
+    for (;;) {
+        const unit = left / flexible.reduce((n, i) => n + fractionOf(columns[i]), 0);
+        const short = flexible.filter((i) => need.get(i).min > fractionOf(columns[i]) * unit);
+        if (short.length === 0)
+            break;
+        for (const i of short) {
+            resolved[i] = need.get(i).min;
+            left -= need.get(i).min;
+        }
+        flexible = flexible.filter((i) => !short.includes(i));
+    }
+    return resolved;
 }
 /** Builds the table tree for already-resolved column widths (no `"auto"`). */
 function composeTable(opts, rows, columns) {
@@ -64,12 +137,10 @@ function composeTable(opts, rows, columns) {
             ...(ruled && rule !== undefined ? { borderBottom: rule } : {}),
         };
         const boxed = cb !== undefined || (ruled && rule !== undefined);
+        // The columns are the grid: a row never shrinks one on its own, or its cells leave their columns.
         if (typeof col === "number")
-            return Box({ width: col, ...border }, [inner]);
-        const fr = fractionOf(col);
-        if (fr !== null)
-            return Expanded({ flex: fr }, boxed ? Box({ ...border }, [inner]) : inner);
-        throw new Error(`Unsupported column width "${col}" - use a number of points or "<n>fr"`);
+            return Box({ width: col, flexShrink: 0, ...border }, [inner]);
+        return Expanded({ flex: fractionOf(col) }, boxed ? Box({ ...border }, [inner]) : inner);
     };
     // align:stretch → equal-height cells, so a wrapping cell keeps the row's bottom rule straight.
     const buildRow = (cells, firstRow, ruled = false, isHeader = false) => new StructGroup({
@@ -92,8 +163,16 @@ function composeTable(opts, rows, columns) {
  * columns are resolved at layout time (a `DeferredElement`), once metrics are available.
  */
 export function Table(opts, rows) {
-    if (opts.columns.some((c) => c === "auto")) {
-        return new DeferredElement((ctx) => composeTable(opts, rows, resolveAutoColumns(opts, rows, ctx)));
+    // Checked here, where the table is written, not at layout: a typo names its line.
+    for (const col of opts.columns) {
+        if (typeof col !== "number" && fractionOf(col) === null && autoMinimum(col) === null) {
+            throw new Error(`Unsupported column width "${col}" - use a number of points, "<n>fr", "auto" or "minmax(<pt>, auto)"`);
+        }
+    }
+    if (opts.columns.some((c) => typeof c !== "number")) {
+        return new DeferredElement((ctx, width) => composeTable(opts, rows, resolveColumns(opts, rows, ctx, width)), [opts.header ?? [], ...rows]
+            .flat()
+            .filter((cell) => typeof cell !== "string"));
     }
     return composeTable(opts, rows, opts.columns);
 }