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

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

@@ -3,11 +3,13 @@ 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";

package/dist/api/index.js

@@ -6,11 +6,13 @@ 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.js

@@ -90,12 +90,13 @@ 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,
             }),
         ]
-        : // 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)
+        : // 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

package/dist/api/table.js

@@ -170,7 +170,9 @@ export function Table(opts, rows) {
         }
     }
     if (opts.columns.some((c) => typeof c !== "number")) {
-        return new DeferredElement((ctx, width) => composeTable(opts, rows, resolveColumns(opts, rows, ctx, width)));
+        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);
 }

package/dist/api/text.d.ts

@@ -5,8 +5,8 @@ import { ResolvedTextStyle, type TextTransform } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
 import type { Hyphenator } from "../text/word-splitting.js";
 export type { TextOverflow, Direction, TextTransform, Hyphenator };
-/** Text styling shared by `Text`, `Paragraph` and `span`. `bold`/`italic` are booleans
- *  (locked §7.3) and combine into one engine `FontStyle`. */
+/** Text styling shared by `Text`, `Paragraph` and `span` - what applies to a run. `bold`/`italic` are
+ *  booleans (locked §7.3) and combine into one engine `FontStyle`. */
 export interface TextStyle {
     size?: number;
     /** Font family, or a STACK: each code point is drawn by the first family in the list that has a
@@ -26,16 +26,10 @@ export interface TextStyle {
     skipInk?: boolean;
     /** Extra space after every glyph, in points (CSS `letter-spacing`). Negative tightens. Default 0. */
     letterSpacing?: number;
-    /** Base writing direction (CSS `direction`): `"rtl"` starts the line on the right, for Hebrew or
-     *  Arabic. Mixed text is reordered per Unicode UAX #9 either way, so Hebrew inside an `ltr`
-     *  paragraph already comes out right - this decides where the LINE starts. */
-    direction?: Direction;
     /** CSS `text-transform`: recase the text. `capitalize` upper-cases the first letter of each word. */
     textTransform?: TextTransform;
     /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
     wordSpacing?: number;
-    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
-    textIndent?: number;
     /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
      *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
      *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
@@ -57,6 +51,12 @@ export interface TextStyle {
     to?: string;
 }
 export interface TextOptions extends Omit<TextStyle, "verticalAlign"> {
+    /** Base writing direction (CSS `direction`): `"rtl"` starts the line on the right, for Hebrew or
+     *  Arabic. Mixed text is reordered per Unicode UAX #9 either way, so Hebrew inside an `ltr`
+     *  paragraph already comes out right - this decides where the LINE starts. */
+    direction?: Direction;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent?: number;
     /** Text-internal alignment (left/center/right) - independent of a parent's `cross` (§5). */
     align?: "left" | "center" | "right" | "justify";
     /** Cap the number of wrapped lines (default: unlimited - the text grows down as far as it needs,

package/dist/api/text.js

@@ -58,7 +58,13 @@ export function span(text, style = {}) {
         fontColor: style.color !== undefined ? toColor(style.color) : undefined,
         underline: style.underline,
         strikethrough: style.strikethrough,
+        skipInk: style.skipInk,
         letterSpacing: style.letterSpacing,
+        textTransform: style.textTransform,
+        wordSpacing: style.wordSpacing,
+        ligatures: style.ligatures,
+        breakWord: style.breakWord,
+        hyphenate: style.hyphenate,
         verticalAlign: style.verticalAlign,
         href: style.href,
         dest: style.to,

package/dist/canvas/painter.d.ts

@@ -1,5 +1,5 @@
-import { type ColorInput } from "../api/color.js";
-import { type GradientInput } from "../api/gradient.js";
+import { type ColorInput } from "../common/color-input.js";
+import { type GradientInput } from "../common/gradient.js";
 import type { IRNode, StrokeStyle } from "../ir/display-list.js";
 /**
  * The imperative escape hatch: a box in the layout that you draw into yourself.

package/dist/canvas/painter.js

@@ -1,5 +1,5 @@
-import { toColor } from "../api/color.js";
-import { isGradientInput, resolveGradient } from "../api/gradient.js";
+import { toColor } from "../common/color-input.js";
+import { isGradientInput, resolveGradient } from "../common/gradient.js";
 import { pathData } from "../svg/shapes.js";
 import { boundsOf, quadToCubic } from "../vector/path.js";
 const DEGREES = Math.PI / 180;

package/dist/common/color-input.d.ts

@@ -0,0 +1,24 @@
+import { Color } from "./color.js";
+/**
+ * Every way to name a color. The FORM picks the convention, so there is never a guess
+ * (locked design §2):
+ *
+ * | form                      | example                  | meaning                        |
+ * |---------------------------|--------------------------|--------------------------------|
+ * | named (full CSS set)      | `"steelblue"`, `"transparent"` | the ~148 CSS color names |
+ * | hex 6 / 3                 | `"#1450aa"` / `"#14a"`   | CSS RGB                        |
+ * | hex 8 / 4                 | `"#1450aacc"` / `"#14ac"`| CSS RGBA (alpha LAST)          |
+ * | number                    | `0xff1450aa`             | Flutter ARGB (alpha FIRST)     |
+ * | `rgb()` / `rgba()`        | `rgb(20,90,170)`         | channels 0–255 (`rgba` a=0–1)  |
+ * | `Color` instance          | `new Color(20,90,170)`   | the engine layer, still valid  |
+ */
+export type ColorInput = string | number | Color;
+/** Channels 0–255, fully opaque. */
+export declare function rgb(r: number, g: number, b: number): Color;
+/** Channels 0–255, alpha 0–1. */
+export declare function rgba(r: number, g: number, b: number, a: number): Color;
+/**
+ * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
+ * so a color means the same thing no matter how it was written.
+ */
+export declare function toColor(input: ColorInput): Color;

package/dist/common/color-input.js

@@ -0,0 +1,278 @@
+import { Color } from "./color.js";
+/** Channels 0–255, fully opaque. */
+export function rgb(r, g, b) {
+    return new Color(r, g, b, 1);
+}
+/** Channels 0–255, alpha 0–1. */
+export function rgba(r, g, b, a) {
+    return new Color(r, g, b, a);
+}
+/**
+ * Normalizes any `ColorInput` to an engine `Color`. The single funnel every factory uses,
+ * so a color means the same thing no matter how it was written.
+ */
+export function toColor(input) {
+    if (input instanceof Color)
+        return input;
+    if (typeof input === "number")
+        return fromArgbNumber(input);
+    const s = input.trim().toLowerCase();
+    if (s.startsWith("#"))
+        return fromHex(s);
+    const named = CSS_COLORS[s];
+    if (named)
+        return new Color(named[0], named[1], named[2], named[3] ?? 1);
+    const call = /^([a-z-]+)\(([^)]*)\)$/.exec(s);
+    if (call)
+        return fromFunction(call[1], call[2], input);
+    throw new Error(`Unknown color: "${input}"`);
+}
+/**
+ * The CSS colour FUNCTIONS. `rgb()`/`rgba()` and `hsl()`/`hsla()` are the sRGB family, so they convert
+ * exactly and are supported; a wide-gamut function (`color()`, `lab()`, `oklch()`) is named and
+ * refused rather than silently squashed into sRGB, since the result would be a colour nobody chose.
+ *
+ * Both syntaxes are accepted, because both occur in the wild: the legacy comma form
+ * `rgb(20, 90, 170)` and the modern space form with an optional slash-alpha `rgb(20 90 170 / 50%)`.
+ */
+function fromFunction(name, body, original) {
+    if (name !== "rgb" && name !== "rgba" && name !== "hsl" && name !== "hsla") {
+        throw new Error(`Unsupported color function "${name}()" in "${String(original)}". ` +
+            `Use a hex value, a CSS colour name, rgb()/rgba() or hsl()/hsla().`);
+    }
+    const [main, alphaPart] = body.split("/");
+    const parts = main
+        .trim()
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    const alphaText = alphaPart !== undefined ? alphaPart.trim() : parts[3];
+    if (parts.length < 3)
+        throw new Error(`Unknown color: "${String(original)}"`);
+    const alpha = alphaText === undefined ? 1 : ratio(alphaText, original);
+    const [a, b, c] = parts;
+    if (name === "rgb" || name === "rgba") {
+        return new Color(channel(a, original), channel(b, original), channel(c, original), alpha);
+    }
+    const [r, g, bl] = hslToRgb(number(a, original), ratio(b, original), ratio(c, original));
+    return new Color(r, g, bl, alpha);
+}
+const NUMERIC = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+/**
+ * One component of a colour function. `Number.parseFloat` stops at the first character it cannot use
+ * and returns what it had, so `rgb(20abc, 90, 170)` would silently become `rgb(20, 90, 170)` - a
+ * colour nobody wrote. The whole token has to be a number.
+ */
+function number(text, original) {
+    const t = text.trim();
+    if (!NUMERIC.test(t))
+        throw new Error(`Unknown color: "${String(original)}"`);
+    return Number(t);
+}
+/** An rgb channel: 0-255, or a percentage of 255. */
+const channel = (text, original) => text.trim().endsWith("%")
+    ? (number(text.trim().slice(0, -1), original) / 100) * 255
+    : number(text, original);
+/** A 0..1 ratio written either as a number or as a percentage (alpha, saturation, lightness). */
+const ratio = (text, original) => text.trim().endsWith("%")
+    ? number(text.trim().slice(0, -1), original) / 100
+    : number(text, original);
+/** CSS hue-saturation-lightness to 0-255 channels. */
+function hslToRgb(hue, s, l) {
+    const h = ((hue % 360) + 360) % 360;
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    const sector = Math.floor(h / 60) % 6;
+    const rgbPrime = [
+        [c, x, 0],
+        [x, c, 0],
+        [0, c, x],
+        [0, x, c],
+        [x, 0, c],
+        [c, 0, x],
+    ][sector];
+    return rgbPrime.map((v) => Math.round((v + m) * 255));
+}
+/** Flutter ARGB: 0xAARRGGBB, alpha FIRST. A 6-digit number has alpha 0x00 = transparent. */
+function fromArgbNumber(n) {
+    const a = (n >>> 24) & 0xff;
+    const r = (n >>> 16) & 0xff;
+    const g = (n >>> 8) & 0xff;
+    const b = n & 0xff;
+    return new Color(r, g, b, a / 255);
+}
+/** CSS hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA. Alpha is LAST. */
+function fromHex(s) {
+    const hex = s.slice(1);
+    const expand = (h) => h
+        .split("")
+        .map((c) => c + c)
+        .join("");
+    let full;
+    if (hex.length === 3 || hex.length === 4)
+        full = expand(hex);
+    else if (hex.length === 6 || hex.length === 8)
+        full = hex;
+    else
+        throw new Error(`Invalid hex color: "${s}"`);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    const a = full.length === 8 ? parseInt(full.slice(6, 8), 16) / 255 : 1;
+    if ([r, g, b].some(Number.isNaN))
+        throw new Error(`Invalid hex color: "${s}"`);
+    return new Color(r, g, b, a);
+}
+// The full CSS named-color set (~148, incl. the synonyms grey/gray and `transparent`).
+// [r, g, b] or [r, g, b, alpha]. Lower-cased keys; `toColor` lower-cases the input.
+const CSS_COLORS = {
+    transparent: [0, 0, 0, 0],
+    aliceblue: [240, 248, 255],
+    antiquewhite: [250, 235, 215],
+    aqua: [0, 255, 255],
+    aquamarine: [127, 255, 212],
+    azure: [240, 255, 255],
+    beige: [245, 245, 220],
+    bisque: [255, 228, 196],
+    black: [0, 0, 0],
+    blanchedalmond: [255, 235, 205],
+    blue: [0, 0, 255],
+    blueviolet: [138, 43, 226],
+    brown: [165, 42, 42],
+    burlywood: [222, 184, 135],
+    cadetblue: [95, 158, 160],
+    chartreuse: [127, 255, 0],
+    chocolate: [210, 105, 30],
+    coral: [255, 127, 80],
+    cornflowerblue: [100, 149, 237],
+    cornsilk: [255, 248, 220],
+    crimson: [220, 20, 60],
+    cyan: [0, 255, 255],
+    darkblue: [0, 0, 139],
+    darkcyan: [0, 139, 139],
+    darkgoldenrod: [184, 134, 11],
+    darkgray: [169, 169, 169],
+    darkgrey: [169, 169, 169],
+    darkgreen: [0, 100, 0],
+    darkkhaki: [189, 183, 107],
+    darkmagenta: [139, 0, 139],
+    darkolivegreen: [85, 107, 47],
+    darkorange: [255, 140, 0],
+    darkorchid: [153, 50, 204],
+    darkred: [139, 0, 0],
+    darksalmon: [233, 150, 122],
+    darkseagreen: [143, 188, 143],
+    darkslateblue: [72, 61, 139],
+    darkslategray: [47, 79, 79],
+    darkslategrey: [47, 79, 79],
+    darkturquoise: [0, 206, 209],
+    darkviolet: [148, 0, 211],
+    deeppink: [255, 20, 147],
+    deepskyblue: [0, 191, 255],
+    dimgray: [105, 105, 105],
+    dimgrey: [105, 105, 105],
+    dodgerblue: [30, 144, 255],
+    firebrick: [178, 34, 34],
+    floralwhite: [255, 250, 240],
+    forestgreen: [34, 139, 34],
+    fuchsia: [255, 0, 255],
+    gainsboro: [220, 220, 220],
+    ghostwhite: [248, 248, 255],
+    gold: [255, 215, 0],
+    goldenrod: [218, 165, 32],
+    gray: [128, 128, 128],
+    grey: [128, 128, 128],
+    green: [0, 128, 0],
+    greenyellow: [173, 255, 47],
+    honeydew: [240, 255, 240],
+    hotpink: [255, 105, 180],
+    indianred: [205, 92, 92],
+    indigo: [75, 0, 130],
+    ivory: [255, 255, 240],
+    khaki: [240, 230, 140],
+    lavender: [230, 230, 250],
+    lavenderblush: [255, 240, 245],
+    lawngreen: [124, 252, 0],
+    lemonchiffon: [255, 250, 205],
+    lightblue: [173, 216, 230],
+    lightcoral: [240, 128, 128],
+    lightcyan: [224, 255, 255],
+    lightgoldenrodyellow: [250, 250, 210],
+    lightgray: [211, 211, 211],
+    lightgrey: [211, 211, 211],
+    lightgreen: [144, 238, 144],
+    lightpink: [255, 182, 193],
+    lightsalmon: [255, 160, 122],
+    lightseagreen: [32, 178, 170],
+    lightskyblue: [135, 206, 250],
+    lightslategray: [119, 136, 153],
+    lightslategrey: [119, 136, 153],
+    lightsteelblue: [176, 196, 222],
+    lightyellow: [255, 255, 224],
+    lime: [0, 255, 0],
+    limegreen: [50, 205, 50],
+    linen: [250, 240, 230],
+    magenta: [255, 0, 255],
+    maroon: [128, 0, 0],
+    mediumaquamarine: [102, 205, 170],
+    mediumblue: [0, 0, 205],
+    mediumorchid: [186, 85, 211],
+    mediumpurple: [147, 112, 219],
+    mediumseagreen: [60, 179, 113],
+    mediumslateblue: [123, 104, 238],
+    mediumspringgreen: [0, 250, 154],
+    mediumturquoise: [72, 209, 204],
+    mediumvioletred: [199, 21, 133],
+    midnightblue: [25, 25, 112],
+    mintcream: [245, 255, 250],
+    mistyrose: [255, 228, 225],
+    moccasin: [255, 228, 181],
+    navajowhite: [255, 222, 173],
+    navy: [0, 0, 128],
+    oldlace: [253, 245, 230],
+    olive: [128, 128, 0],
+    olivedrab: [107, 142, 35],
+    orange: [255, 165, 0],
+    orangered: [255, 69, 0],
+    orchid: [218, 112, 214],
+    palegoldenrod: [238, 232, 170],
+    palegreen: [152, 251, 152],
+    paleturquoise: [175, 238, 238],
+    palevioletred: [219, 112, 147],
+    papayawhip: [255, 239, 213],
+    peachpuff: [255, 218, 185],
+    peru: [205, 133, 63],
+    pink: [255, 192, 203],
+    plum: [221, 160, 221],
+    powderblue: [176, 224, 230],
+    purple: [128, 0, 128],
+    rebeccapurple: [102, 51, 153],
+    red: [255, 0, 0],
+    rosybrown: [188, 143, 143],
+    royalblue: [65, 105, 225],
+    saddlebrown: [139, 69, 19],
+    salmon: [250, 128, 114],
+    sandybrown: [244, 164, 96],
+    seagreen: [46, 139, 87],
+    seashell: [255, 245, 238],
+    sienna: [160, 82, 45],
+    silver: [192, 192, 192],
+    skyblue: [135, 206, 235],
+    slateblue: [106, 90, 205],
+    slategray: [112, 128, 144],
+    slategrey: [112, 128, 144],
+    snow: [255, 250, 250],
+    springgreen: [0, 255, 127],
+    steelblue: [70, 130, 180],
+    tan: [210, 180, 140],
+    teal: [0, 128, 128],
+    thistle: [216, 191, 216],
+    tomato: [255, 99, 71],
+    turquoise: [64, 224, 208],
+    violet: [238, 130, 238],
+    wheat: [245, 222, 179],
+    white: [255, 255, 255],
+    whitesmoke: [245, 245, 245],
+    yellow: [255, 255, 0],
+    yellowgreen: [154, 205, 50],
+};

package/dist/common/diagnostics.d.ts

@@ -9,14 +9,22 @@
 export type DiagnosticCode = 
 /** A `PageBreak` outside a paginating flow (in a Row, in a PageBuilder) - drawn as nothing. */
 "page-break-ignored"
+/** A `ColumnBreak` outside a Region of a Flow - drawn as nothing. */
+ | "column-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"
+/** Content wider than its box (a word that does not break, a Row whose children need more), drawn
+ *  past the box's edge - as CSS draws it; `overflow: "hidden"` on a Box clips it. */
+ | "overflow-wide"
 /** Characters no font could draw, removed (PDF/A forbids `.notdef`). */
- | "missing-glyphs";
+ | "missing-glyphs"
+/** An image whose own size was not known at layout (a URL first built in a `PageBuilder`), so the
+ *  axis it would have derived fills what it is offered instead. */
+ | "image-unsized";
 export interface Diagnostic {
     code: DiagnosticCode;
     severity: "warning" | "info";

package/dist/common/gradient.d.ts

@@ -0,0 +1,53 @@
+import { type ColorInput } from "./color-input.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;