@brunosouzas/design-system 0.0.0-stage → 0.1.1

package/dist/src/pieces/metro.js

@@ -0,0 +1,205 @@
+// Metro and diagram pieces (spec illustration-pieces, change
+// metro-and-diagram-pieces; design §3). They paint what the caller lays out:
+// positions, text measurement and truncation stay with the consumer
+// (stackledger's map engine). Each draws on a surface, light or dark, with the
+// ink sticker of stackledger's map: hard shadow in the surface's shadow colour,
+// a light rim on dark, then the face outlined in ink.
+//
+// What can go wrong: every parameter is checked by its schema first; the
+// cross-parameter limits (room for the outline, width against height, arrow
+// length) are checked here and thrown as a RangeError naming the parameter.
+import { tokens } from "../../tokens/generated/tokens.js";
+import { drawn, el, g, r2 } from "./node.js";
+import { col, colour, label, MAX_SIZE, PATH_DATA, paint, pos, size } from "./params.js";
+import { definePiece } from "./piece.js";
+export const SURFACES = ["light", "dark"];
+const ink = tokens.color.ink;
+const white = tokens.color.white;
+const font = tokens.font.sans;
+const bold = tokens.font.weightBold;
+const M = tokens.map;
+const surfaceParam = { kind: "enum", values: SURFACES };
+const inkScaleParam = { kind: "number", min: 0.25, max: 8 };
+const dataColour = (required = true) => ({ kind: "dataColor", required });
+const point = (required = true) => ({ kind: "point", required });
+const inkSchema = { surface: surfaceParam, inkScale: inkScaleParam };
+/** Collects the limits between parameters (piece.ts, `relations`). */
+const limits = (...checks) => checks.filter((check) => check !== false);
+/** The surface's colours and the ink measures at a scale. */
+const inkOf = ({ surface = "light", inkScale = 1 }) => {
+    const s = tokens.surface[surface];
+    return { s, outline: M.outline * inkScale, rim: s.rimWidth * inkScale, offset: M.shadow * inkScale };
+};
+/** Outlined shapes need room for their ink: smallest dimension ≥ 4 × outline. */
+const roomFor = (name, smallest, inkParams) => {
+    const need = 4 * inkOf(inkParams).outline;
+    return smallest < need && { path: name, message: `leaves no room for the outline: needs at least ${r2(need)} at this ink scale` };
+};
+const atLeast = (name, value, least, what) => value < least && { path: name, message: `must be at least ${what} (${r2(least)}), found ${r2(value)}` };
+/** The ink sticker (design §3): shadow copy, rim on dark, then the face. */
+const sticker = (shape, face, inkParams) => {
+    const { s, outline, rim, offset } = inkOf(inkParams);
+    const wide = r2(outline + 2 * rim);
+    return [
+        // Joins are set here, so a sticker draws the same inside any group.
+        shape(offset, offset, { fill: s.shadow, stroke: s.shadow, "stroke-width": wide, "stroke-linejoin": "round" }),
+        ...(s.rimWidth > 0 ? [shape(0, 0, { fill: s.rim, stroke: s.rim, "stroke-width": wide, "stroke-linejoin": "round" })] : []),
+        shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" }),
+    ];
+};
+// Every text sets its own anchor, size and weight, so a surrounding group (a cover's label style) does not leak in.
+const words = (x, y, value, attrs) => el("text", { x: r2(x), y: r2(y), "font-family": font, ...attrs }, value);
+const pill = (x, y, w, h) => (dx, dy, attrs) => el("rect", { x: r2(x + dx), y: r2(y + dy), width: r2(w), height: r2(h), rx: r2(h / 2), ...attrs });
+const badgeWidth = ({ width, text }) => width ?? Math.max(30, 7.6 * Array.from(text).length + 18);
+/** A line's terminal badge: a pill in the line colour with its code in white, centred on (x, y). */
+export const lineBadge = definePiece("lineBadge", { x: pos(), y: pos(), text: label(), fill: dataColour(), width: size(), height: size(), flat: { kind: "boolean" }, ...inkSchema }, (params) => {
+    const { x, y, text, fill, height = M.badgeHeight, flat = false } = params;
+    const width = badgeWidth(params);
+    const face = paint(fill);
+    const { outline } = inkOf(params);
+    const inset = flat ? outline / 2 : 0;
+    const shape = pill(x - width / 2 + inset, y - height / 2 + inset, width - 2 * inset, height - 2 * inset);
+    const body = flat ? [shape(0, 0, { fill: face, stroke: ink, "stroke-width": r2(outline), "stroke-linejoin": "round" })] : sticker(shape, face, params);
+    return drawn(body, [words(x, y + 4.5, text, { fill: white, "font-size": M.badgeTextSize, "font-weight": bold, "text-anchor": "middle" })]);
+}, (params) => {
+    const height = params.height ?? M.badgeHeight;
+    return limits(atLeast("width", badgeWidth(params), height, "the height"), roomFor("height", height, params));
+});
+/** Closed capsule round the segment a-b (stackledger's capsulePath). */
+const capsule = (a, b, r, dx, dy) => {
+    // The normal comes from the segment itself; the shadow's offset moves the result, so a very short
+    // segment never collapses to zero length once moved.
+    const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+    const n = [(-(b[1] - a[1]) / length) * r, ((b[0] - a[0]) / length) * r];
+    const p = (q, k) => `${r2(q[0] + dx + n[0] * k)},${r2(q[1] + dy + n[1] * k)}`;
+    const radius = r2(r);
+    return `M${p(a, 1)} L${p(b, 1)} A${radius},${radius} 0 0 0 ${p(b, -1)} L${p(a, -1)} A${radius},${radius} 0 0 0 ${p(a, 1)} Z`;
+};
+const markerRadius = ({ r, to }) => r ?? (to ? M.stopRadius + M.interchangeExtra : M.stopRadius);
+/** A stop (disc), or with `to` an interchange (capsule from the centre to `to`); deprecated is muted. */
+export const stationMarker = definePiece("stationMarker", { cx: pos(), cy: pos(), to: point(false), r: size(), state: { kind: "enum", values: ["normal", "deprecated"] }, ...inkSchema }, (params) => {
+    const { cx, cy, to, state = "normal" } = params;
+    const r = markerRadius(params);
+    const face = state === "deprecated" ? inkOf(params).s.muted : white;
+    const long = to !== undefined && Math.hypot(to[0] - cx, to[1] - cy) > 0;
+    const shape = long
+        ? (dx, dy, attrs) => el("path", { d: capsule([cx, cy], to, r, dx, dy), ...attrs })
+        : (dx, dy, attrs) => el("circle", { cx: r2(cx + dx), cy: r2(cy + dy), r: r2(r), ...attrs });
+    return drawn(sticker(shape, face, params));
+}, (params) => limits(roomFor("r", 2 * markerRadius(params), params)));
+const PIPE_PATH = { kind: "string", required: true, nonEmpty: true, pattern: new RegExp(`^\\s*[Mm]${PATH_DATA.source.slice(1, -2)}*$`), patternName: "SVG path data starting with M (commands, numbers, commas and spaces only)" };
+/** A line: its colour over an ink casing, round caps and joins, no shadow. */
+export const pipe = definePiece("pipe", { d: PIPE_PATH, fill: dataColour(), width: { kind: "number", min: 0, exclusiveMin: true, max: 100 }, casing: { kind: "number", min: 0, max: 50 } }, ({ d, fill, width = M.lineWidth, casing = M.casing }) => {
+    const line = { d, fill: "none", "stroke-linecap": "round", "stroke-linejoin": "round" };
+    return drawn([
+        // Stroke widths as given: a valid hairline must not round to zero.
+        ...(casing > 0 ? [el("path", { ...line, stroke: ink, "stroke-width": width + casing })] : []),
+        el("path", { ...line, stroke: paint(fill), "stroke-width": width }),
+    ]);
+});
+const countWidth = ({ width, text, height = M.countHeight }) => {
+    const characters = Array.from(text).length;
+    return width ?? (characters === 1 ? height : Math.max(height, 6.4 * characters + 8));
+};
+/** A count (rules of a skill): a circle when as wide as high, a pill otherwise, in the surface's panel colour. */
+export const countBadge = definePiece("countBadge", { cx: pos(), cy: pos(), text: label(), width: size(), height: size(), ...inkSchema }, (params) => {
+    const { cx, cy, text, height = M.countHeight } = params;
+    const width = countWidth(params);
+    const { s } = inkOf(params);
+    const shape = width === height ? (dx, dy, attrs) => el("circle", { cx: r2(cx + dx), cy: r2(cy + dy), r: r2(height / 2), ...attrs }) : pill(cx - width / 2, cy - height / 2, width, height);
+    return drawn(sticker(shape, s.panel, params), [words(cx, cy + 4, text, { fill: s.text, "font-size": M.countTextSize, "font-weight": bold, "text-anchor": "middle" })]);
+}, (params) => {
+    const height = params.height ?? M.countHeight;
+    return limits(atLeast("width", countWidth(params), height, "the height"), roomFor("height", height, params));
+});
+const nodeSchema = {
+    x: pos(),
+    y: pos(),
+    width: size(true),
+    height: size(),
+    title: label(),
+    subtitle: label(false),
+    state: { kind: "enum", values: ["normal", "focus", "placeholder"] },
+    ...inkSchema,
+};
+const nodeLimits = (kind) => (params) => {
+    const { width, height = M.nodeHeight, subtitle, state = "normal" } = params;
+    const radius = params.radius ?? M.nodeRadius;
+    return limits(atLeast("width", width, 2 * height, "twice the height"), kind === "box" && radius > height / 2 && { path: "radius", message: `must be at most half the height (${r2(height / 2)}), found ${r2(radius)}` }, state === "placeholder" && subtitle !== undefined && { path: "subtitle", message: "a placeholder has no subtitle" }, state !== "placeholder" && roomFor("height", height, params));
+};
+const drawNode = (kind, params) => {
+    const { x, y, width, height = M.nodeHeight, title, subtitle, state = "normal" } = params;
+    const radius = kind === "pill" ? height / 2 : (params.radius ?? M.nodeRadius);
+    const shape = kind === "hex"
+        ? (dx, dy, attrs) => {
+            const [l, t, c] = [x + dx, y + dy, height / 2];
+            const points = [[l + c, t], [l + width - c, t], [l + width, t + c], [l + width - c, t + height], [l + c, t + height], [l, t + c]];
+            return el("polygon", { points: points.map(([px, py]) => `${r2(px)},${r2(py)}`).join(" "), ...attrs });
+        }
+        : (dx, dy, attrs) => el("rect", { x: r2(x + dx), y: r2(y + dy), width: r2(width), height: r2(height), rx: r2(radius), ...attrs });
+    const { s } = inkOf(params);
+    const middle = y + height / 2;
+    if (state === "placeholder") {
+        return drawn([shape(0, 0, { fill: "none", stroke: s.muted, "stroke-width": 1.5, "stroke-dasharray": "5 4", "stroke-linejoin": "round" })], [words(x + width / 2, middle + 4.5, title, { fill: s.muted, "font-size": M.labelSize, "font-weight": 400, "text-anchor": "middle" })]);
+    }
+    const focus = state === "focus";
+    const inset = kind === "box" ? 12 : height / 2;
+    const titleFill = focus ? ink : s.text;
+    const text = subtitle === undefined
+        ? [words(x + inset, middle + 4.5, title, { fill: titleFill, "font-size": M.labelSize, "font-weight": bold, "text-anchor": "start" })]
+        : [
+            words(x + inset, middle - 3, title, { fill: titleFill, "font-size": M.labelSize, "font-weight": bold, "text-anchor": "start" }),
+            words(x + inset, middle + 14, subtitle, { fill: focus ? ink : s.muted, "font-size": 11, "font-weight": 400, "text-anchor": "start" }),
+        ];
+    return drawn(sticker(shape, focus ? tokens.color.caller : s.panel, params), text);
+};
+/** A diagram box (a skill, a software item): rounded rect with a title and an optional subtitle. */
+export const nodeBlock = definePiece("nodeBlock", { ...nodeSchema, radius: { kind: "number", min: 0, max: MAX_SIZE } }, (p) => drawNode("box", p), nodeLimits("box"));
+/** A diagram pill (a playbook). */
+export const pillNode = definePiece("pillNode", nodeSchema, (p) => drawNode("pill", p), nodeLimits("pill"));
+/** A diagram hexagon (an agent). */
+export const hexNode = definePiece("hexNode", nodeSchema, (p) => drawNode("hex", p), nodeLimits("hex"));
+/** An edge with a head at `to`: curved (leaves and enters horizontally) or straight, with an optional label. */
+export const messageArrow = definePiece("messageArrow", {
+    from: point(),
+    to: point(),
+    curve: { kind: "enum", values: ["bezier", "straight"] },
+    head: { kind: "boolean" },
+    label: label(false),
+    width: { kind: "number", min: 1, max: 12 },
+    surface: surfaceParam,
+}, ({ from, to, curve = "bezier", head = true, label: text, width = M.edgeWidth, surface = "light" }) => {
+    const s = tokens.surface[surface];
+    const length = 5 * width;
+    const distance = Math.hypot(to[0] - from[0], to[1] - from[1]);
+    const dx = to[0] - from[0];
+    // A curve whose ends are almost above each other has no horizontal entry: draw it straight.
+    const bent = curve === "bezier" && Math.abs(dx) > 2 * length;
+    const direction = bent ? [Math.sign(dx), 0] : [dx / distance, (to[1] - from[1]) / distance];
+    const end = head ? [to[0] - direction[0] * length, to[1] - direction[1] * length] : to;
+    const mx = (from[0] + to[0]) / 2;
+    const at = (p) => `${r2(p[0])},${r2(p[1])}`;
+    const d = bent ? `M${at(from)} C${r2(mx)},${r2(from[1])} ${r2(mx)},${r2(to[1])} ${at(end)}` : `M${at(from)} L${at(end)}`;
+    const body = [el("path", { d, fill: "none", stroke: s.text, "stroke-width": r2(width), "stroke-linecap": "round" })];
+    if (head) {
+        const normal = [-direction[1] * 2 * width, direction[0] * 2 * width];
+        const points = [to, [end[0] + normal[0], end[1] + normal[1]], [end[0] - normal[0], end[1] - normal[1]]];
+        body.push(el("polygon", { points: points.map(at).join(" "), fill: s.text, stroke: s.text, "stroke-width": 1, "stroke-linejoin": "round" }));
+    }
+    const words_ = [];
+    if (text !== undefined) {
+        const middle = [mx, (from[1] + to[1]) / 2];
+        const w = 6.4 * Array.from(text).length + 16;
+        body.push(el("rect", { x: r2(middle[0] - w / 2), y: r2(middle[1] - 9), width: r2(w), height: 18, rx: 9, fill: s.background, stroke: s.text, "stroke-width": 1.5 }));
+        words_.push(words(middle[0], middle[1] + 4, text, { fill: s.text, "font-size": 11, "font-weight": 400, "text-anchor": "middle" }));
+    }
+    return drawn(body, words_);
+}, ({ from, to, head = true, width = M.edgeWidth }) => {
+    const distance = Math.hypot(to[0] - from[0], to[1] - from[1]);
+    return limits(distance === 0 && { path: "to", message: "must differ from from" }, distance > 0 && head && distance < 10 * width && { path: "to", message: `is too close to from for the head: needs at least ${r2(10 * width)}, found ${r2(distance)}` });
+});
+/** stackledger's mark (favicon, header): an ink square with a bent line and two stations, 32 units scaled to `size`. */
+export const ledgerMark = definePiece("ledgerMark", { x: pos(), y: pos(), size: { kind: "number", min: 12, max: 512 }, line: col() }, ({ x, y, size: side = 32, line = "illustration.accent" }) => drawn([
+    g({ transform: `translate(${r2(x)} ${r2(y)}) scale(${side / 32})` }, el("rect", { x: 0, y: 0, width: 32, height: 32, rx: 7, fill: ink, stroke: "none" }), el("path", { d: "M7 23 L14 16 L25 16", fill: "none", stroke: colour(line, "line"), "stroke-width": 4.5, "stroke-linecap": "round", "stroke-linejoin": "round" }), el("circle", { cx: 14, cy: 16, r: 4, fill: white, stroke: ink, "stroke-width": 2 }), el("circle", { cx: 25, cy: 16, r: 2.6, fill: white, stroke: ink, "stroke-width": 1.6 })),
+]));
+export const METRO_PIECES = { lineBadge, stationMarker, pipe, countBadge, nodeBlock, pillNode, hexNode, messageArrow, ledgerMark };

package/dist/src/pieces/node.d.ts

@@ -0,0 +1,27 @@
+export declare const SVG_TAGS: readonly ["svg", "g", "title", "desc", "defs", "clipPath", "rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text"];
+export type SvgTag = (typeof SVG_TAGS)[number];
+export type AttrValue = string | number;
+export type Attrs = Readonly<Record<string, AttrValue>>;
+export type SvgNode = {
+    readonly tag: SvgTag;
+    readonly attrs: Attrs;
+    readonly children: readonly (SvgNode | string)[];
+};
+/** What a piece draws: shapes go in the outlined group, words and glyphs after every shape. */
+export type Drawn = {
+    readonly body: readonly SvgNode[];
+    readonly text: readonly SvgNode[];
+};
+type Child = SvgNode | string | null | false | undefined;
+export declare const el: (tag: SvgTag, attrs?: Attrs, ...children: Child[]) => SvgNode;
+export declare const g: (attrs: Attrs, ...children: Child[]) => SvgNode;
+export declare const drawn: (body: readonly SvgNode[], text?: readonly SvgNode[]) => Drawn;
+/**
+ * Hard offset shadow (STY-1): an ink copy of the shape translated by `offset`,
+ * then the shape. Inside the outlined group the copy keeps the outline too, as
+ * the motion components' shadow does.
+ */
+export declare const shadowed: (shape: SvgNode, offset?: number) => SvgNode[];
+/** Rounds to two decimals so computed geometry stays short and stable in the output. */
+export declare const r2: (value: number) => number;
+export {};

package/dist/src/pieces/node.js

@@ -0,0 +1,52 @@
+// SVG node contract of the illustration pieces (spec illustration-pieces;
+// design §3 of the illustration-pieces change).
+//
+// Why: a piece returns plain data, not markup or React, so the same drawing
+// becomes an SVG string for covers and diagrams and React elements for
+// Remotion scenes, and tests can inspect it without a browser.
+//
+// What can go wrong: nothing here reads files or the clock; helpers only build
+// objects. Colour and number guards live in params.ts.
+import { tokens } from "../../tokens/generated/tokens.js";
+export const SVG_TAGS = [
+    "svg",
+    "g",
+    "title",
+    "desc",
+    "defs",
+    "clipPath",
+    "rect",
+    "circle",
+    "ellipse",
+    "line",
+    "polyline",
+    "polygon",
+    "path",
+    "text",
+];
+export const el = (tag, attrs = {}, ...children) => ({
+    tag,
+    attrs,
+    children: children.filter((child) => child !== null && child !== false && child !== undefined),
+});
+export const g = (attrs, ...children) => el("g", attrs, ...children);
+export const drawn = (body, text = []) => ({ body, text });
+/**
+ * Hard offset shadow (STY-1): an ink copy of the shape translated by `offset`,
+ * then the shape. Inside the outlined group the copy keeps the outline too, as
+ * the motion components' shadow does.
+ */
+export const shadowed = (shape, offset = tokens.shadow.block) => [
+    {
+        ...shape,
+        attrs: {
+            ...shape.attrs,
+            fill: tokens.color.ink,
+            // The offset applies after the shape's own transform, so a turned shape casts a turned shadow.
+            transform: shape.attrs.transform === undefined ? `translate(${offset} ${offset})` : `translate(${offset} ${offset}) ${shape.attrs.transform}`,
+        },
+    },
+    shape,
+];
+/** Rounds to two decimals so computed geometry stays short and stable in the output. */
+export const r2 = (value) => (Math.abs(value) < 1e12 ? Math.round(value * 100) / 100 : value);

package/dist/src/pieces/params.d.ts

@@ -0,0 +1,77 @@
+export type ParamSpec = {
+    kind: "number";
+    required?: boolean;
+    min?: number;
+    exclusiveMin?: boolean;
+    max?: number;
+    integer?: boolean;
+} | {
+    kind: "color";
+    required?: boolean;
+}
+/** A token path, or a colour from the consumer's data (#RRGGBB): pipe and lineBadge fills only. */
+ | {
+    kind: "dataColor";
+    required?: boolean;
+} | {
+    kind: "string";
+    required?: boolean;
+    nonEmpty?: boolean;
+    pattern?: RegExp;
+    patternName?: string;
+} | {
+    kind: "enum";
+    required?: boolean;
+    values: readonly string[];
+} | {
+    kind: "boolean";
+    required?: boolean;
+} | {
+    kind: "point";
+    required?: boolean;
+} | {
+    kind: "array";
+    required?: boolean;
+    minItems?: number;
+    maxItems?: number;
+    of: ParamSpec;
+} | {
+    kind: "object";
+    required?: boolean;
+    fields: Schema;
+};
+export type Schema = Readonly<Record<string, ParamSpec>>;
+export type Problem = {
+    path: string;
+    message: string;
+};
+/** A data colour: exactly six hex digits after the sign, nothing else. */
+export declare const DATA_COLOUR: RegExp;
+/** The hex value of a data colour parameter: a token path resolved, a data colour as given. */
+export declare const paint: (value: string, name?: string) => string;
+/** Every colour token, by its dotted path: any token whose value is #RRGGBB. */
+export declare const COLOUR_TOKENS: ReadonlyMap<string, string>;
+export declare const isColourLiteral: (value: string) => boolean;
+/** The hex value of a colour token path; throws a RangeError for anything else. */
+export declare const colour: (path: string, name?: string) => string;
+/** Every problem of `params` against `schema`; paths are `prefix.name`. */
+export declare const checkParams: (schema: Schema, params: Record<string, unknown>, prefix?: string) => Problem[];
+/** Validates params for a call from code; the first problem becomes a RangeError. */
+export declare const assertParams: (piece: string, schema: Schema, params: Record<string, unknown>) => void;
+export declare const num: (extra?: Omit<Extract<ParamSpec, {
+    kind: "number";
+}>, "kind">) => ParamSpec;
+/** Largest size a piece accepts, far above any banner. Positions and points have no bound. */
+export declare const MAX_SIZE = 10000;
+/** Most items in any list parameter (rows, lines, nodes, tiles). */
+export declare const MAX_ITEMS = 50;
+/** A count of repeated parts (units, steps, teeth): an integer from `min` to `max`. */
+export declare const count: (min: number, max: number) => ParamSpec;
+/** A size: greater than 0 (or at least `min`, where fixed insets need room), at most MAX_SIZE. */
+export declare const size: (required?: boolean, min?: number) => ParamSpec;
+/** A position: any finite number, because a map position has no maximum. */
+export declare const pos: () => ParamSpec;
+export declare const col: () => ParamSpec;
+/** SVG path data: commands, digits, signs, dots, commas and spaces only. */
+export declare const PATH_DATA: RegExp;
+export declare const label: (required?: boolean) => ParamSpec;

package/dist/src/pieces/params.js

@@ -0,0 +1,149 @@
+// Parameter schemas of the pieces: one description per piece, used both when
+// code calls a piece (first problem thrown as a RangeError) and by the cover
+// command (every problem collected, with its JSON path).
+//
+// Why one schema: the cover spec and a scene must accept exactly the same
+// parameters, or a cover that validates could fail to draw.
+import { tokens } from "../../tokens/generated/tokens.js";
+/** A data colour: exactly six hex digits after the sign, nothing else. */
+export const DATA_COLOUR = /^#[0-9A-Fa-f]{6}$/;
+/** The hex value of a data colour parameter: a token path resolved, a data colour as given. */
+export const paint = (value, name = "fill") => (DATA_COLOUR.test(value) ? value : colour(value, name));
+const COLOUR_LITERAL = /^\s*(#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\()/;
+/** Every colour token, by its dotted path: any token whose value is #RRGGBB. */
+export const COLOUR_TOKENS = (() => {
+    const found = new Map();
+    const visit = (prefix, node) => {
+        if (typeof node === "string") {
+            if (/^#[0-9a-fA-F]{6}$/.test(node))
+                found.set(prefix, node);
+            return;
+        }
+        if (typeof node === "object" && node !== null) {
+            for (const [name, child] of Object.entries(node))
+                visit(prefix ? `${prefix}.${name}` : name, child);
+        }
+    };
+    visit("", tokens);
+    return found;
+})();
+export const isColourLiteral = (value) => COLOUR_LITERAL.test(value);
+/** The hex value of a colour token path; throws a RangeError for anything else. */
+export const colour = (path, name = "colour") => {
+    const value = COLOUR_TOKENS.get(path);
+    if (value === undefined)
+        throw new RangeError(`${name}: expected a colour token path such as color.healthy, found ${JSON.stringify(path)}`);
+    return value;
+};
+const describe = (value) => (value === undefined ? "nothing" : JSON.stringify(value));
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const checkValue = (spec, value, path, out) => {
+    const report = (message) => {
+        out.push({ path, message });
+    };
+    switch (spec.kind) {
+        case "number": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                return report(`expected a finite number, found ${describe(value)}`);
+            if (spec.integer && !Number.isInteger(value))
+                return report(`expected an integer, found ${value}`);
+            if (spec.min !== undefined && (spec.exclusiveMin ? value <= spec.min : value < spec.min)) {
+                return report(`expected a number ${spec.exclusiveMin ? "greater than" : "at least"} ${spec.min}, found ${value}`);
+            }
+            if (spec.max !== undefined && value > spec.max)
+                return report(`expected a number at most ${spec.max}, found ${value}`);
+            return;
+        }
+        case "color":
+            if (typeof value !== "string")
+                return report(`expected a colour token path, found ${describe(value)}`);
+            if (isColourLiteral(value))
+                return report("colour literals are not allowed; use a token path");
+            if (!COLOUR_TOKENS.has(value))
+                return report(`expected a colour token path such as color.healthy, found ${describe(value)}`);
+            return;
+        case "dataColor":
+            if (typeof value !== "string")
+                return report(`expected a colour token path or #RRGGBB, found ${describe(value)}`);
+            if (DATA_COLOUR.test(value) || COLOUR_TOKENS.has(value))
+                return;
+            return report(`expected a colour token path or a data colour #RRGGBB, found ${describe(value)}`);
+        case "string":
+            if (typeof value !== "string")
+                return report(`expected a string, found ${describe(value)}`);
+            if (spec.nonEmpty && value.trim() === "")
+                return report("expected a non-empty string");
+            if (spec.pattern && !spec.pattern.test(value))
+                return report(`expected ${spec.patternName ?? spec.pattern.source}`);
+            return;
+        case "enum":
+            if (typeof value !== "string" || !spec.values.includes(value)) {
+                return report(`expected one of ${spec.values.join(", ")}, found ${describe(value)}`);
+            }
+            return;
+        case "boolean":
+            if (typeof value !== "boolean")
+                return report(`expected true or false, found ${describe(value)}`);
+            return;
+        case "point":
+            // Any finite number: a map position has no maximum (spec illustration-pieces, "Positions of any size").
+            if (!Array.isArray(value) || value.length !== 2 || !value.every((n) => typeof n === "number" && Number.isFinite(n))) {
+                return report(`expected a point [x, y] of finite numbers, found ${describe(value)}`);
+            }
+            return;
+        case "array":
+            if (!Array.isArray(value))
+                return report(`expected an array, found ${describe(value)}`);
+            if (spec.minItems !== undefined && value.length < spec.minItems)
+                return report(`expected at least ${spec.minItems} item(s)`);
+            if (value.length > (spec.maxItems ?? MAX_ITEMS))
+                return report(`expected at most ${spec.maxItems ?? MAX_ITEMS} item(s)`);
+            value.forEach((item, index) => checkValue(spec.of, item, `${path}[${index}]`, out));
+            return;
+        case "object":
+            if (!isPlainObject(value))
+                return report(`expected an object, found ${describe(value)}`);
+            out.push(...checkParams(spec.fields, value, path));
+            return;
+    }
+};
+/** Every problem of `params` against `schema`; paths are `prefix.name`. */
+export const checkParams = (schema, params, prefix = "") => {
+    const out = [];
+    const at = (name) => (prefix ? `${prefix}.${name}` : name);
+    for (const name of Object.keys(params)) {
+        if (!Object.hasOwn(schema, name))
+            out.push({ path: at(name), message: `unknown parameter (expected ${Object.keys(schema).join(", ")})` });
+    }
+    for (const [name, spec] of Object.entries(schema)) {
+        if (!Object.hasOwn(params, name) || params[name] === undefined) {
+            if (spec.required)
+                out.push({ path: at(name), message: "missing required parameter" });
+            continue;
+        }
+        checkValue(spec, params[name], at(name), out);
+    }
+    return out;
+};
+/** Validates params for a call from code; the first problem becomes a RangeError. */
+export const assertParams = (piece, schema, params) => {
+    const problems = checkParams(schema, params);
+    if (problems.length > 0)
+        throw new RangeError(`${piece}: ${problems[0].path}: ${problems[0].message}`);
+};
+// Shorthands for schemas.
+export const num = (extra = {}) => ({ kind: "number", ...extra });
+/** Largest size a piece accepts, far above any banner. Positions and points have no bound. */
+export const MAX_SIZE = 10000;
+/** Most items in any list parameter (rows, lines, nodes, tiles). */
+export const MAX_ITEMS = 50;
+/** A count of repeated parts (units, steps, teeth): an integer from `min` to `max`. */
+export const count = (min, max) => ({ kind: "number", integer: true, min, max });
+/** A size: greater than 0 (or at least `min`, where fixed insets need room), at most MAX_SIZE. */
+export const size = (required = false, min) => min === undefined ? { kind: "number", min: 0, exclusiveMin: true, max: MAX_SIZE, required } : { kind: "number", min, max: MAX_SIZE, required };
+/** A position: any finite number, because a map position has no maximum. */
+export const pos = () => ({ kind: "number", required: true });
+export const col = () => ({ kind: "color" });
+/** SVG path data: commands, digits, signs, dots, commas and spaces only. */
+export const PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9eE.,+\-\s]+$/;
+export const label = (required = true) => ({ kind: "string", nonEmpty: true, required });

package/dist/src/pieces/piece.d.ts

@@ -0,0 +1,9 @@
+import type { Drawn } from "./node.ts";
+import { type Problem, type Schema } from "./params.ts";
+export type Relations<P> = (params: P) => Problem[];
+export type Piece<P extends object> = ((params: P) => Drawn) & {
+    readonly pieceName: string;
+    readonly schema: Schema;
+    readonly relations?: Relations<P>;
+};
+export declare const definePiece: <P extends object>(name: string, schema: Schema, draw: (params: P) => Drawn, relations?: Relations<P>) => Piece<P>;

package/dist/src/pieces/piece.js

@@ -0,0 +1,28 @@
+import { assertParams } from "./params.js";
+// A number the piece computed and would draw: finite, or the drawing overflows
+// (spec illustration-pieces, "Drawing overflow"). Strings are the piece's own
+// path data and transforms; caller path data (road.d, pipe.d) has its own check
+// and only ever holds path characters, never the words Infinity or NaN.
+const NON_FINITE = /Infinity|NaN/;
+const overflows = (node) => {
+    if (typeof node === "string")
+        return false;
+    for (const value of Object.values(node.attrs)) {
+        if (typeof value === "number" ? !Number.isFinite(value) : NON_FINITE.test(value))
+            return true;
+    }
+    return node.children.some(overflows);
+};
+export const definePiece = (name, schema, draw, relations) => {
+    const piece = (params) => {
+        assertParams(name, schema, params);
+        const problems = relations?.(params) ?? [];
+        if (problems.length > 0)
+            throw new RangeError(`${name}: ${problems[0].path}: ${problems[0].message}`);
+        const drawn = draw(params);
+        if ([...drawn.body, ...drawn.text].some(overflows))
+            throw new RangeError(`${name}: the drawing overflows`);
+        return drawn;
+    };
+    return Object.assign(piece, { pieceName: name, schema, relations });
+};

package/dist/src/pieces/pose.d.ts

@@ -0,0 +1,16 @@
+import { type SvgNode } from "./node.ts";
+export type Pose = {
+    x: number;
+    y: number;
+    /** Degrees, clockwise. */
+    tilt?: number;
+    /** Vertical stretch; the width shrinks by its square root, so volume reads constant. */
+    squash?: number;
+    /** Pixels above the base. */
+    hop?: number;
+    scale?: number;
+    /** Horizontal offset in pixels. */
+    shake?: number;
+    opacity?: number;
+};
+export declare const pose: (node: SvgNode, params: Pose) => SvgNode;

package/dist/src/pieces/pose.js

@@ -0,0 +1,30 @@
+// Animation by parameter (spec illustration-pieces, "Animation by
+// parameter"): the wrapper of the approved cast motion test. A scene computes
+// the numbers from the frame and wraps the piece; the anchor (x, y) is the
+// piece's base, usually its feet, so squash and tilt keep it on the ground.
+import { g } from "./node.js";
+const finite = (name, value) => {
+    if (!Number.isFinite(value))
+        throw new RangeError(`pose: ${name} must be a finite number, found ${value}`);
+};
+export const pose = (node, params) => {
+    const { x, y, tilt = 0, squash = 1, hop = 0, scale = 1, shake = 0, opacity = 1 } = params;
+    // Each parameter is checked completely (finite, then range) before the next, in this order.
+    for (const [name, value] of Object.entries({ x, y, tilt, squash, hop, scale, shake, opacity })) {
+        finite(name, value);
+        if ((name === "squash" || name === "scale") && value <= 0)
+            throw new RangeError(`pose: ${name} must be greater than 0, found ${value}`);
+        if (name === "opacity" && (value < 0 || value > 1))
+            throw new RangeError(`pose: opacity must be within 0 and 1, found ${value}`);
+    }
+    if (tilt === 0 && squash === 1 && hop === 0 && scale === 1 && shake === 0 && opacity === 1)
+        return node;
+    // Finite inputs can still overflow once combined (scale 1e308 with squash 4).
+    const parts = { "x + shake": x + shake, "y - hop": y - hop, "horizontal scale": scale / Math.sqrt(squash), "vertical scale": scale * squash };
+    for (const [name, value] of Object.entries(parts)) {
+        if (!Number.isFinite(value))
+            throw new RangeError(`pose: ${name} overflows, found ${value}`);
+    }
+    const transform = `translate(${parts["x + shake"]} ${parts["y - hop"]}) rotate(${tilt}) scale(${parts["horizontal scale"]} ${parts["vertical scale"]}) translate(${-x} ${-y})`;
+    return g(opacity < 1 ? { transform, opacity } : { transform }, node);
+};

package/dist/src/pieces/react.d.ts

@@ -0,0 +1,4 @@
+import { type ReactElement } from "react";
+import type { SvgNode } from "./node.ts";
+export declare const reactName: (name: string) => string;
+export declare const toReact: (node: SvgNode, key?: number) => ReactElement;

package/dist/src/pieces/react.js

@@ -0,0 +1,13 @@
+// React renderer of the node tree (spec illustration-pieces, "React
+// renderer"): the same drawing as toSvg, as React elements for Remotion scenes.
+// Hyphenated SVG attributes take React's camelCase names; aria-* and data-*
+// stay as they are, because React expects them hyphenated.
+import { createElement } from "react";
+export const reactName = (name) => name.startsWith("aria-") || name.startsWith("data-") ? name : name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+export const toReact = (node, key = 0) => {
+    const props = { key };
+    for (const [name, value] of Object.entries(node.attrs))
+        props[reactName(name)] = value;
+    const children = node.children.map((child, index) => (typeof child === "string" ? child : toReact(child, index)));
+    return createElement(node.tag, props, ...children);
+};

package/dist/src/pieces/render.d.ts

@@ -0,0 +1,2 @@
+import type { SvgNode } from "./node.ts";
+export declare const toSvg: (node: SvgNode | string, depth?: number) => string;