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

package/dist/api/content.d.ts

@@ -27,7 +27,7 @@ export interface SvgOptions extends BoundsInput {
     /** Alternate text (tagged PDF). With it the drawing is a `Figure`; without it, decoration. */
     alt?: string;
 }
-/** An image source: a local file path (Node), raw bytes (e.g. a browser fetch/upload), or a `CustomImage`. */
+/** An image source: a URL (`http(s):`, `data:`), a local file path (Node), raw bytes, or a `CustomImage`. */
 export type ImageSource = string | Uint8Array | CustomImage;
 /** How the image fills its box (locked §4). Mirrors CSS `object-fit`. */
 export type ImageFit = "none" | "contain" | "cover" | "fill";
@@ -36,8 +36,8 @@ export interface ImageOptions extends BoundsInput {
      *  space). Pin exactly ONE axis and the other follows the image's aspect ratio (CSS `height: auto`). */
     width?: SizeInput;
     height?: SizeInput;
-    /** Fit within the box. Default `none`, except where the box was DERIVED rather than given outright -
-     *  exactly one axis pinned, or an `aspectRatio` - which defaults to `fill` so the image scales into it. */
+    /** Fit within the box. Default `none` (the image's own size); with any explicit size or an
+     *  `aspectRatio`, `fill` - the image scales into its box, as `<img width height>` does. */
     fit?: ImageFit;
     /** Corner radius in points (rounds the image box). */
     radius?: RadiusInput;
@@ -73,8 +73,8 @@ export declare function Canvas(paint: CanvasPaint): CanvasElement;
  */
 export declare function Svg(source: SvgSource, opts?: SvgOptions): SvgElement;
 /**
- * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
- * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
+ * An image. `src` is a URL (fetched when the document renders), a local file path, raw bytes, or a
+ * ready `CustomImage`. Maps to an `ImageElement`.
  *
  * An SVG source is routed to `Svg` instead, so `Image({ src: "logo.svg" })` just works and a logo
  * stays a VECTOR in the PDF rather than becoming a bitmap.

package/dist/api/content.js

@@ -1,6 +1,6 @@
 import { LineElement } from "../elements/line-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
-import { ImageElement, CustomLocalImage, CustomBytesImage, BoxFit, } from "../elements/image-element.js";
+import { ImageElement, CustomLocalImage, CustomBytesImage, CustomUrlImage, isImageUrl, BoxFit, } from "../elements/image-element.js";
 import { toColor } from "./color.js";
 import { toEdges } from "./insets.js";
 import { toBounds, toDimension, toRadius, } from "./dimension.js";
@@ -84,13 +84,17 @@ export function Svg(source, opts = {}) {
 /** SVG is recognised by its extension or by its own opening bytes - never by a caller having to say. */
 function isSvg(src) {
     if (typeof src === "string") {
+        // A URL by its media type (`data:image/svg+xml`) or the extension of its PATH - a query may follow.
+        const path = isImageUrl(src) ? src.trim().replace(/[?#].*$/, "") : src.trim();
+        if (/^data:image\/svg\+xml[;,]/i.test(src.trim()))
+            return true;
         // `.svgz` is a GZIPPED svg. It is caught here rather than left to the image path, because the
         // error a user needs says what the file is - not "unsupported image bytes".
-        if (/\.svgz$/i.test(src.trim())) {
+        if (/\.svgz$/i.test(path)) {
             throw new Error("@jasy/pdf: SVGZ (a gzip-compressed SVG) is not supported. Decompress it first " +
                 "(`gunzip logo.svgz`) and pass the plain .svg.");
         }
-        return /\.svg$/i.test(src.trim()) || /^\s*[<\ufeff]/.test(src);
+        return /\.svg$/i.test(path) || /^\s*[<\ufeff]/.test(src);
     }
     if (src instanceof Uint8Array) {
         const head = new TextDecoder().decode(src.subarray(0, 200)).trimStart();
@@ -99,8 +103,8 @@ function isSvg(src) {
     return false;
 }
 /**
- * An image. `src` is a local file path (wrapped in a `CustomLocalImage`) or a ready
- * `CustomImage` for non-filesystem sources. Maps to an `ImageElement`.
+ * An image. `src` is a URL (fetched when the document renders), a local file path, raw bytes, or a
+ * ready `CustomImage`. Maps to an `ImageElement`.
  *
  * An SVG source is routed to `Svg` instead, so `Image({ src: "logo.svg" })` just works and a logo
  * stays a VECTOR in the PDF rather than becoming a bitmap.
@@ -129,7 +133,9 @@ function rasterImage(src, opts = {}) {
     const fit = opts.fit ? FIT[opts.fit] : sized ? BoxFit.fill : undefined;
     return new ImageElement({
         image: typeof src === "string"
-            ? new CustomLocalImage(src)
+            ? isImageUrl(src)
+                ? new CustomUrlImage(src)
+                : new CustomLocalImage(src)
             : src instanceof Uint8Array
                 ? new CustomBytesImage(src)
                 : src,

package/dist/api/font-url.d.ts

@@ -5,8 +5,7 @@
  * 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.
  */
 /** One font file by URL, or a styled family of them. Mirrors `FontSource`, with strings meaning URLs. */
 export type UrlFontSource = string | {

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/index.d.ts

@@ -2,12 +2,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 * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.js";
 export * from "./content.js";
 export * from "./page-builder.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,6 +5,7 @@ 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 * from "./dimension.js";
 export * from "./text.js";
 export * from "./layout.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";
@@ -90,9 +91,13 @@ export function Box(a, b) {
             new PaddingElement({
                 margin: toEdges(opts.padding),
                 child: children.length === 1 ? children[0] : Column(children),
+                ofBox: true,
             }),
         ]
-        : children;
+        : // A Spacer/Expanded - also one inside a transparent wrapper such as a Link - needs a flex parent.
+            children.length > 1 && 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 +231,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,14 @@ 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)));
     }
     return composeTable(opts, rows, opts.columns);
 }

package/dist/common/diagnostics.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What the engine tells the author about a document it rendered anyway - one channel for every such
+ * signal, so an application (or an agent, which cannot see the page) can act on it by `code`.
+ *
+ * Without a handler nothing changes: what warned before still goes to `console.warn`, what was silent
+ * stays silent. A handler receives everything, once per element and code - layout runs several times
+ * per render, and the same mistake must not be reported for each pass.
+ */
+export type DiagnosticCode = 
+/** A `PageBreak` outside a paginating flow (in a Row, in a PageBuilder) - drawn as nothing. */
+"page-break-ignored"
+/** `breakBefore` / `breakAfter` on a child of a Row or a table row, which never breaks. */
+ | "break-ignored"
+/** A `keepTogether` group contains a forced break; the break wins and the group is split. */
+ | "keep-together-split"
+/** Content taller than its page region that cannot break, placed whole and clipped. */
+ | "overflow-clipped"
+/** Characters no font could draw, removed (PDF/A forbids `.notdef`). */
+ | "missing-glyphs";
+export interface Diagnostic {
+    code: DiagnosticCode;
+    severity: "warning" | "info";
+    message: string;
+    /** The kind of element it is about, by the factory name an author writes: `"Row"`, `"Box"`, `"Text"`. */
+    element?: string;
+    /** The first text inside that element, shortened - so the place can be found in the document. */
+    text?: string;
+    /** The 1-based page, when the element is being laid out on a known page. */
+    page?: number;
+}
+export type DiagnosticHandler = (diagnostic: Diagnostic) => void;
+/** Whether a diagnostic goes to `console.warn` when no handler is set - only what warned before. */
+type Fallback = "warn" | "silent";
+export declare class Diagnostics {
+    private handler?;
+    private readonly seen;
+    setHandler(handler: DiagnosticHandler | undefined): void;
+    /** Report once per `about` and code. `about` is the element the message is about, or any key. */
+    report(d: Omit<Diagnostic, "element" | "text"> & {
+        about?: object;
+        fallback?: Fallback;
+    }): void;
+}
+/** The 1-based page a layout context is on, as far as it knows: drawn (`pageInfo`) or being paginated. */
+export declare function pageOf(ctx: {
+    pageInfo?: {
+        pageNumber: number;
+    };
+    paginatingPage?: number;
+}): number | undefined;
+/** Report through the render's channel, or - laid out on its own - warn as before. */
+export declare function diagnose(diagnostics: Diagnostics | undefined, d: Parameters<Diagnostics["report"]>[0]): void;
+export {};