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

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

@@ -0,0 +1,61 @@
+/**
+ * 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"
+/** 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"
+/** 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";
+    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 {};

package/dist/common/diagnostics.js

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+const EXCERPT = 40;
+/** Engine classes whose factory carries another name. */
+const FACTORY = { Rectangle: "Box", Container: "Column" };
+export class Diagnostics {
+    constructor() {
+        this.seen = new WeakMap();
+    }
+    setHandler(handler) {
+        this.handler = handler;
+    }
+    /** Report once per `about` and code. `about` is the element the message is about, or any key. */
+    report(d) {
+        const { about, fallback = "warn", ...rest } = d;
+        if (about) {
+            const codes = this.seen.get(about) ?? new Set();
+            if (codes.has(rest.code))
+                return;
+            codes.add(rest.code);
+            this.seen.set(about, codes);
+        }
+        const diagnostic = { ...rest, ...(about ? describe(about) : {}) };
+        if (this.handler)
+            this.handler(diagnostic);
+        else if (fallback === "warn")
+            console.warn(diagnostic.message);
+    }
+}
+/** The element's kind and the first text inside it, from what every element exposes. */
+function describe(about) {
+    const name = about.constructor?.name;
+    if (!name || name === "Object")
+        return {};
+    const text = firstText(about, 0);
+    const kind = name.replace(/Element$/, "");
+    return {
+        element: FACTORY[kind] ?? kind,
+        ...(text ? { text: text.length > EXCERPT ? `${text.slice(0, EXCERPT - 1)}…` : text } : {}),
+    };
+}
+function firstText(el, depth) {
+    if (depth > 32)
+        return undefined;
+    const node = el;
+    if (node.constructor?.name === "TextElement") {
+        const content = node.getProps?.().content;
+        const s = typeof content === "string"
+            ? content
+            : Array.isArray(content)
+                ? content.map((c) => c.content ?? "").join("")
+                : "";
+        return s.replace(/\s+/g, " ").trim() || undefined;
+    }
+    for (const child of node.layoutChildren?.() ?? []) {
+        const t = firstText(child, depth + 1);
+        if (t)
+            return t;
+    }
+    return undefined;
+}
+/** The 1-based page a layout context is on, as far as it knows: drawn (`pageInfo`) or being paginated. */
+export function pageOf(ctx) {
+    return ctx.pageInfo?.pageNumber ?? ctx.paginatingPage;
+}
+/** Outside a render (an element laid out on its own) there is no document channel: warn, once each. */
+const bare = new Diagnostics();
+/** Report through the render's channel, or - laid out on its own - warn as before. */
+export function diagnose(diagnostics, d) {
+    (diagnostics ?? bare).report(d);
+}

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;

package/dist/common/gradient.js

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