@runbooks/design 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# `@runbooks/design`
+
+Tokens, graph primitives, the specimen sheet, and the SVG renderer.
+
+**Tasks:** [D-01](../../tasks/v0/D-01-design-tokens.md),
+[D-02](../../tasks/v0/D-02-graph-visual-primitives.md) · **Normative:** RUNBOOK.md §18.2
+
+One rule decides most of what is here: **each channel encodes exactly one property.**
+Hue is risk. Stroke weight and fill are run state — the type carrying them has no field a
+colour could go in, which is why "state never by hue" survives the next person to touch
+it. Trust is saturation, in the catalog only.
+
+`specimen/*.svg` is the baseline: it is committed, compared byte for byte, and it is what
+"check against the specimen sheet" in a task means.

package/dist/color.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Contrast maths, so accessibility floors are asserted rather than believed.
+ *
+ * WCAG relative luminance and contrast ratio, implemented here rather than pulled in:
+ * it is twenty lines, and a dependency in a package the graph renderer uses is a
+ * dependency in every SVG export.
+ */
+export interface Rgb {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+export declare function hexToRgb(hex: string): Rgb;
+export declare function luminance(hex: string): number;
+export declare function contrast(a: string, b: string): number;
+/** Perceived lightness, for checking a scale survives greyscale and colour blindness. */
+export declare function lightness(hex: string): number;

package/dist/color.js

@@ -0,0 +1,24 @@
+export function hexToRgb(hex) {
+    const clean = hex.replace("#", "");
+    return {
+        r: parseInt(clean.slice(0, 2), 16),
+        g: parseInt(clean.slice(2, 4), 16),
+        b: parseInt(clean.slice(4, 6), 16),
+    };
+}
+function channel(value) {
+    const c = value / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+export function luminance(hex) {
+    const { r, g, b } = hexToRgb(hex);
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+export function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+/** Perceived lightness, for checking a scale survives greyscale and colour blindness. */
+export function lightness(hex) {
+    return luminance(hex);
+}

package/dist/geometry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/geometry.test.js

@@ -0,0 +1,155 @@
+import { describe, it, expect } from "vitest";
+import { toGraph } from "@runbooks/graph";
+import { loadCorpus } from "@runbooks/fixtures";
+import { renderGraph } from "./render.js";
+import { measure } from "./text.js";
+/**
+ * The picture's geometry, asserted rather than looked at.
+ *
+ * Every claim here was a defect first, seen on `/r/std/k8s-node-not-ready-drain`: labels
+ * ran out past both edges of their outlines, connectors were drawn as chords between two
+ * boxes and cut through whatever lay between them, and the three branch labels of one
+ * decision were printed at the same point, over each other and over the lines they named.
+ * None of that is visible to a test that checks the SVG contains an `<svg>`.
+ */
+const RECORDS = loadCorpus().map((entry) => ({
+    name: entry.name,
+    graph: toGraph(entry.doc),
+}));
+/** Every drawn line, as segments, from the path data the renderer emits. */
+function segments(svg) {
+    const out = [];
+    for (const [, d] of svg.matchAll(/<path d="([^"]+)"[^>]*data-line="1"/g)) {
+        const points = [];
+        for (const [, command, x, y] of d.matchAll(/([ML])\s+(-?[\d.]+)\s+(-?[\d.]+)/g)) {
+            void command;
+            points.push({ x: Number(x), y: Number(y) });
+        }
+        for (let i = 0; i + 1 < points.length; i++) {
+            out.push({ x1: points[i].x, y1: points[i].y, x2: points[i + 1].x, y2: points[i + 1].y });
+        }
+    }
+    return out;
+}
+const rendered = RECORDS.map((entry) => ({
+    ...entry,
+    render: renderGraph(entry.graph, { theme: "light", idPrefix: entry.name }),
+}));
+describe("every line runs at 0, 45 or 90 degrees", () => {
+    it.each(rendered)("$name", ({ render }) => {
+        const drawn = segments(render.svg);
+        expect(drawn.length, "no lines were drawn at all").toBeGreaterThan(0);
+        for (const s of drawn) {
+            const dx = Math.abs(s.x2 - s.x1);
+            const dy = Math.abs(s.y2 - s.y1);
+            const straight = dx < 0.6 || dy < 0.6;
+            const diagonal = Math.abs(dx - dy) < 0.6;
+            expect(straight || diagonal, `a segment runs at ${Math.round((Math.atan2(dy, dx) * 180) / Math.PI)}°: ${JSON.stringify(s)}`).toBe(true);
+        }
+    });
+});
+/**
+ * A connector goes round a box it is not attached to. It used to go through: on the k8s
+ * procedure the arrow into `Escalate` crossed `Wait for the node to recover`, which reads
+ * as a route through a step that is not on it.
+ */
+describe("no connector crosses a node it does not touch", () => {
+    it.each(rendered)("$name", ({ render, graph }) => {
+        const drawn = segments(render.svg);
+        for (const node of graph.nodes) {
+            const box = render.boxes[node.id];
+            // Shrunk, because a connector legitimately lands on the outline of the box it
+            // arrives at, and grazes the corner of the one it leaves.
+            const left = box.x + 3;
+            const right = box.x + box.w - 3;
+            const top = box.y + 3;
+            const bottom = box.y + box.h - 3;
+            for (const s of drawn) {
+                const inside = (x, y) => x > left && x < right && y > top && y < bottom;
+                expect(inside(s.x1, s.y1) || inside(s.x2, s.y2), `a line ends inside ${node.id}: ${JSON.stringify(s)}`).toBe(false);
+                // A horizontal or vertical run passing clean through the box.
+                if (Math.abs(s.y1 - s.y2) < 0.6 && s.y1 > top && s.y1 < bottom) {
+                    const spans = Math.min(s.x1, s.x2) < left && Math.max(s.x1, s.x2) > right;
+                    expect(spans, `a line crosses ${node.id} horizontally`).toBe(false);
+                }
+                if (Math.abs(s.x1 - s.x2) < 0.6 && s.x1 > left && s.x1 < right) {
+                    const spans = Math.min(s.y1, s.y2) < top && Math.max(s.y1, s.y2) > bottom;
+                    expect(spans, `a line crosses ${node.id} vertically`).toBe(false);
+                }
+            }
+        }
+    });
+});
+/** A box is as wide as its own label, which is what stopped the labels overflowing. */
+describe("every label fits inside its outline", () => {
+    it.each(rendered)("$name", ({ render, graph }) => {
+        for (const node of graph.nodes) {
+            const box = render.boxes[node.id];
+            const group = new RegExp(`<g transform="translate\\\\([^)]*\\\\)"[^>]*data-node="${node.id}"[\\\\s\\\\S]*?</g>`).exec(render.svg);
+            expect(group, `${node.id} was not drawn`).toBeTruthy();
+            for (const [, line] of group[0].matchAll(/<text[^>]*>([^<]*)<\/text>/g)) {
+                const text = line.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"');
+                expect(measure(text, 13), `"${text}" is wider than the ${Math.round(box.w)}px box it is drawn in`).toBeLessThanOrEqual(box.w);
+            }
+        }
+    });
+});
+/**
+ * Two branches of one decision are told apart by their labels, so the labels have to be
+ * in two different places. All three were printed at the midpoint of the stub they share.
+ */
+describe("no two edge labels are drawn on top of each other", () => {
+    it.each(rendered)("$name", ({ render }) => {
+        const placed = [...render.svg.matchAll(/<rect x="(-?[\d.]+)" y="(-?[\d.]+)"[^>]*rx="3"/g)].map(([, x, y]) => ({ x: Number(x), y: Number(y) }));
+        for (let i = 0; i < placed.length; i++) {
+            for (let j = i + 1; j < placed.length; j++) {
+                const apart = Math.abs(placed[i].x - placed[j].x) > 8 || Math.abs(placed[i].y - placed[j].y) > 8;
+                expect(apart, `two edge labels sit at ${JSON.stringify(placed[i])}`).toBe(true);
+            }
+        }
+    });
+});
+/**
+ * A crossing is marked. Two lines meeting at a point read as a junction, and a reader
+ * tracing a branch loses it at every intersection; the bridge says which is continuous.
+ */
+describe("a crossing is bridged rather than left as a junction", () => {
+    it("marks the crossings on a procedure that has them", () => {
+        const withCrossings = rendered.find(({ render }) => {
+            const drawn = segments(render.svg);
+            return drawn.some((a) => drawn.some((b) => Math.abs(a.y1 - a.y2) < 0.6 &&
+                Math.abs(b.x1 - b.x2) < 0.6 &&
+                b.x1 > Math.min(a.x1, a.x2) + 4 &&
+                b.x1 < Math.max(a.x1, a.x2) - 4 &&
+                a.y1 > Math.min(b.y1, b.y2) + 4 &&
+                a.y1 < Math.max(b.y1, b.y2) - 4));
+        });
+        // The bridge is a pair of 45° cuts, so a bridged path has diagonal segments in the
+        // middle of an otherwise horizontal run.
+        if (!withCrossings)
+            return;
+        const drawn = segments(withCrossings.render.svg);
+        const diagonals = drawn.filter((s) => Math.abs(Math.abs(s.x2 - s.x1) - Math.abs(s.y2 - s.y1)) < 0.6 && Math.abs(s.x2 - s.x1) > 0.6);
+        expect(diagonals.length, "lines cross and nothing marks it").toBeGreaterThan(0);
+    });
+});
+/** Pointing at one thing says which one thing it is (§18.2: weight, never hue). */
+describe("hovering picks something out", () => {
+    const { svg } = rendered[0].render;
+    it("gives every edge a target a pointer can actually hit", () => {
+        expect(svg).toMatch(/data-hit="1"/);
+    });
+    it("responds to a hover on a node and on an edge", () => {
+        expect(svg).toMatch(/\[data-node\]:hover[^{]*\{stroke-width/);
+        expect(svg).toMatch(/\[data-edge\]:hover[^{]*\{stroke-width/);
+    });
+    it("borrows no hue for it, since risk owns that channel", () => {
+        const rules = /<style>([\s\S]*?)<\/style>/.exec(svg)?.[1] ?? "";
+        const hover = rules
+            .split("}")
+            .filter((rule) => rule.includes(":hover") || rule.includes(":focus-visible"));
+        for (const rule of hover) {
+            expect(rule, `a hover rule sets a colour: ${rule}`).not.toMatch(/(^|[^-])\bstroke:|fill:|color:/);
+        }
+    });
+});

package/dist/icons.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The icon set (D-03, §18.2).
+ *
+ * §18.2 allows an icon **only where a label does not fit**, and the list is therefore
+ * closed: the three capability classes, the approval lock, the untrusted triangle, the
+ * upstream-change arrow. Six.
+ *
+ * The exclusion is the load-bearing part. **There is no icon for risk.** Risk is a text
+ * label plus a colour, and §18.2 already says no property may be carried by colour alone
+ * — adding a glyph would be a third channel encoding one property, which reads as three
+ * different facts to somebody scanning a list.
+ *
+ * Inline SVG paths rather than a font or a sprite sheet, so they inherit `currentColor`
+ * and stay crisp at the one size they are drawn for. A font would need loading before the
+ * first paint and a sprite sheet needs a second request to say what a lock looks like.
+ */
+export declare const ICONS: readonly ["capability-mcp", "capability-cli", "capability-iam", "approval-lock", "untrusted", "upstream-changed"];
+export type IconName = (typeof ICONS)[number];
+export interface Icon {
+    readonly name: IconName;
+    /** What a screen reader says. Never omitted: an icon is never the only carrier (§18.2). */
+    readonly label: string;
+    /** Why this glyph, so a redraw keeps the meaning rather than the shape. */
+    readonly why: string;
+    /**
+     * Path data on a 16×16 grid, 1.5px stroke, no fills.
+     *
+     * Absolute commands only. A relative path is shorter and its numbers are deltas, which
+     * means nobody — including a test — can tell from the data whether the glyph stays
+     * inside its box. Here every number is a coordinate.
+     */
+    readonly path: string;
+}
+/** One grid, so two icons beside each other have the same optical weight. */
+export declare const GRID = 16;
+export declare const STROKE = 1.5;
+export declare function icon(name: IconName): Icon;
+export interface IconOptions {
+    /** Defaults to the icon's own label; override for context ("MCP server: github"). */
+    readonly label?: string;
+    /**
+     * Set when the meaning is already in adjacent text, which is the common case: a card
+     * shows the capability class as a word beside the glyph, and reading it twice is
+     * noise. Then the icon is `aria-hidden` and decorative — which is only honest when
+     * something else carries the meaning.
+     */
+    readonly decorative?: boolean;
+}
+/**
+ * One icon as inline SVG.
+ *
+ * `currentColor` and no fill, so the glyph takes the colour of the text it sits in and
+ * has one appearance to reason about instead of a light and a dark variant.
+ */
+export declare function renderIcon(name: IconName, options?: IconOptions): string;
+/** The icon for a capability URN, by its class. Unknown classes get none rather than a guess. */
+export declare function iconForCapability(urn: string): IconName | undefined;
+/**
+ * Adding an icon requires naming the label that would not fit (D-03).
+ *
+ * Stated as a function because the rule is about the next person, and a rule in a
+ * comment is a rule they will read after adding the icon.
+ */
+export declare function mayAdd(proposal: {
+    readonly labelThatDoesNotFit?: string;
+}): {
+    readonly allowed: boolean;
+    readonly why: string;
+};

package/dist/icons.js

@@ -0,0 +1,103 @@
+/**
+ * The icon set (D-03, §18.2).
+ *
+ * §18.2 allows an icon **only where a label does not fit**, and the list is therefore
+ * closed: the three capability classes, the approval lock, the untrusted triangle, the
+ * upstream-change arrow. Six.
+ *
+ * The exclusion is the load-bearing part. **There is no icon for risk.** Risk is a text
+ * label plus a colour, and §18.2 already says no property may be carried by colour alone
+ * — adding a glyph would be a third channel encoding one property, which reads as three
+ * different facts to somebody scanning a list.
+ *
+ * Inline SVG paths rather than a font or a sprite sheet, so they inherit `currentColor`
+ * and stay crisp at the one size they are drawn for. A font would need loading before the
+ * first paint and a sprite sheet needs a second request to say what a lock looks like.
+ */
+export const ICONS = [
+    "capability-mcp",
+    "capability-cli",
+    "capability-iam",
+    "approval-lock",
+    "untrusted",
+    "upstream-changed",
+];
+/** One grid, so two icons beside each other have the same optical weight. */
+export const GRID = 16;
+export const STROKE = 1.5;
+const DEFINITIONS = {
+    "capability-mcp": {
+        label: "MCP server",
+        why: "Two boxes and a line between them: a tool on the other side of a connection, which is what distinguishes an MCP call from a local one.",
+        path: "M2.5 4.5 L6.5 4.5 L6.5 8.5 L2.5 8.5 Z M9.5 7.5 L13.5 7.5 L13.5 11.5 L9.5 11.5 Z M6.5 6.5 L9.5 6.5 L9.5 9.5",
+    },
+    "capability-cli": {
+        label: "Command line",
+        why: "A prompt chevron and a caret. The one glyph every practitioner already reads as a shell.",
+        path: "M2.5 5 L5.5 8 L2.5 11 M7.5 11.5 L13.5 11.5",
+    },
+    "capability-iam": {
+        label: "Named permission",
+        why: "A key, because the capability is not a tool but a right somebody granted.",
+        path: "M6 10 A2.5 2.5 0 1 0 6 5 A2.5 2.5 0 1 0 6 10 M8.5 7.5 L13.5 7.5 M11.5 7.5 L11.5 10 M13 7.5 L13 9.5",
+    },
+    "approval-lock": {
+        label: "Requires approval",
+        why: "A closed padlock. The step is shut until a person opens it, which is what a gate is; an open shackle would read as already granted.",
+        path: "M4.5 7.5 L11.5 7.5 L11.5 13.5 L4.5 13.5 Z M6.5 7.5 L6.5 5.5 A1.5 1.5 0 0 1 9.5 5.5 L9.5 7.5",
+    },
+    untrusted: {
+        label: "Below the trust threshold",
+        why: "A triangle with a bar, not a cross. This is a warning about what is unverified, not a prohibition — a record below T2 is readable, and dimming plus this is how §18.2 says to show it.",
+        path: "M8 2.5 L13.5 12.5 L2.5 12.5 Z M8 6.5 L8 9.5 M8 11 L8 11.5",
+    },
+    "upstream-changed": {
+        label: "Source has changed",
+        why: "An arrow leaving a document. The source moved on; the record did not, which is the whole distinction §3 draws.",
+        path: "M10.5 2.5 L3.5 2.5 L3.5 13.5 L12.5 13.5 L12.5 8 M9.5 6.5 L13.5 2.5 M10.5 2.5 L13.5 2.5 L13.5 5.5",
+    },
+};
+export function icon(name) {
+    return { name, ...DEFINITIONS[name] };
+}
+/**
+ * One icon as inline SVG.
+ *
+ * `currentColor` and no fill, so the glyph takes the colour of the text it sits in and
+ * has one appearance to reason about instead of a light and a dark variant.
+ */
+export function renderIcon(name, options = {}) {
+    const definition = icon(name);
+    const label = options.label ?? definition.label;
+    const accessibility = options.decorative
+        ? 'aria-hidden="true" focusable="false"'
+        : `role="img" aria-label="${label.replace(/"/g, """)}"`;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${GRID}" height="${GRID}"`,
+        ` viewBox="0 0 ${GRID} ${GRID}" fill="none" stroke="currentColor"`,
+        ` stroke-width="${STROKE}" stroke-linecap="round" stroke-linejoin="round"`,
+        ` data-icon="${name}" ${accessibility}>`,
+        `<path d="${definition.path}"/>`,
+        "</svg>",
+    ].join("");
+}
+/** The icon for a capability URN, by its class. Unknown classes get none rather than a guess. */
+export function iconForCapability(urn) {
+    const head = urn.split(":", 1)[0];
+    return head === "mcp" || head === "cli" || head === "iam" ? `capability-${head}` : undefined;
+}
+/**
+ * Adding an icon requires naming the label that would not fit (D-03).
+ *
+ * Stated as a function because the rule is about the next person, and a rule in a
+ * comment is a rule they will read after adding the icon.
+ */
+export function mayAdd(proposal) {
+    if (!proposal.labelThatDoesNotFit) {
+        return {
+            allowed: false,
+            why: "§18.2 allows an icon only where a label does not fit. Name the label and where it does not fit; if it fits, use the words.",
+        };
+    }
+    return { allowed: true, why: `"${proposal.labelThatDoesNotFit}" does not fit, so a glyph earns its place.` };
+}

package/dist/icons.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/icons.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ICONS, GRID, STROKE, icon, renderIcon, iconForCapability, mayAdd } from "./icons.js";
+import { PALETTES } from "./tokens.js";
+function repoRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")))
+            return dir;
+        dir = resolve(dir, "..");
+    }
+    throw new Error("repo root not found");
+}
+/** §18.2 allows an icon only where a label does not fit, so the list is closed. */
+describe("the set is the six §18.2 names and no more", () => {
+    it("is exactly what the runbook lists", () => {
+        expect([...ICONS]).toEqual([
+            "capability-mcp",
+            "capability-cli",
+            "capability-iam",
+            "approval-lock",
+            "untrusted",
+            "upstream-changed",
+        ]);
+    });
+    /** An icon for risk would be a third channel encoding one property. */
+    it("has none for risk, which is a label plus a colour", () => {
+        expect(ICONS.some((name) => /risk|destruct|irreversible|danger/.test(name))).toBe(false);
+    });
+    it("requires the label that would not fit before another is added", () => {
+        expect(mayAdd({}).allowed).toBe(false);
+        expect(mayAdd({}).why).toMatch(/if it fits, use the words/);
+        expect(mayAdd({ labelThatDoesNotFit: "reversible-write" }).allowed).toBe(true);
+    });
+});
+describe("every icon is drawn to one grid", () => {
+    it.each([...ICONS])("%s is on the 16px grid at 1.5px", (name) => {
+        const svg = renderIcon(name);
+        expect(svg).toContain(`width="${GRID}"`);
+        expect(svg).toContain(`viewBox="0 0 ${GRID} ${GRID}"`);
+        expect(svg).toContain(`stroke-width="${STROKE}"`);
+    });
+    it.each([...ICONS])("%s has no fill, so it inherits the text colour", (name) => {
+        const svg = renderIcon(name);
+        expect(svg).toContain('fill="none"');
+        expect(svg).toContain('stroke="currentColor"');
+        expect(svg).not.toMatch(/fill="(?!none)/);
+    });
+    it.each([...ICONS])("%s uses absolute commands, so its numbers are coordinates", (name) => {
+        // A relative path is shorter and unreadable: nobody can tell from `h4v4h-4` whether
+        // the glyph stays in its box, which is the only question that matters here.
+        expect(icon(name).path).not.toMatch(/[hvlcsqta]/);
+    });
+    it.each([...ICONS])("%s stays inside its box, so two icons align optically", (name) => {
+        const coordinates = [...icon(name).path.matchAll(/-?\d+(\.\d+)?/g)].map((m) => Number(m[0]));
+        for (const value of coordinates) {
+            expect(value, `${name} draws at ${value}, outside the ${GRID}px grid`).toBeGreaterThanOrEqual(0);
+            expect(value).toBeLessThanOrEqual(GRID);
+        }
+    });
+    /**
+     * Only the coordinates that follow M and L, because an arc's parameters include radii
+     * and two flags — and a test that treated a flag as a coordinate would be measuring
+     * something that is not on the canvas. That is what the first version of this did.
+     */
+    it.each([...ICONS])("%s keeps its strokes off the very edge, so nothing is clipped", (name) => {
+        const points = [...icon(name).path.matchAll(/[ML]\s*(-?\d+(?:\.\d+)?)\s+(-?\d+(?:\.\d+)?)/g)];
+        expect(points.length, `${name} has no drawn points`).toBeGreaterThan(1);
+        for (const [, x, y] of points) {
+            for (const value of [Number(x), Number(y)]) {
+                expect(value).toBeGreaterThanOrEqual(STROKE / 2 - 0.75);
+                expect(value).toBeLessThanOrEqual(GRID - STROKE / 2 + 0.75);
+            }
+        }
+    });
+    it("is one appearance rather than a light and a dark variant", () => {
+        // currentColor is what makes that true: the glyph takes the colour of its text, and
+        // both palettes already guarantee that text's contrast (D-01).
+        for (const name of ICONS)
+            expect(renderIcon(name)).not.toMatch(/#[0-9a-f]{3,6}/i);
+        expect(Object.keys(PALETTES).sort()).toEqual(["dark", "light"]);
+    });
+});
+/** §18.2's accessibility rule: no property is carried by one channel alone. */
+describe("no icon is the sole carrier of meaning", () => {
+    it.each([...ICONS])("%s has an accessible label", (name) => {
+        expect(icon(name).label.length).toBeGreaterThan(3);
+        expect(renderIcon(name)).toContain(`aria-label="${icon(name).label}"`);
+    });
+    it("takes a label from the context when there is a better one", () => {
+        expect(renderIcon("capability-mcp", { label: "MCP server: github" })).toContain('aria-label="MCP server: github"');
+    });
+    it("hides itself only when something else says the same thing", () => {
+        const decorative = renderIcon("capability-cli", { decorative: true });
+        expect(decorative).toContain('aria-hidden="true"');
+        expect(decorative).not.toContain("aria-label");
+    });
+    it("escapes a label rather than emitting broken markup", () => {
+        expect(renderIcon("untrusted", { label: 'a "quoted" thing' })).toContain("&quot;quoted&quot;");
+    });
+    it.each([...ICONS])("%s records why this glyph, so a redraw keeps the meaning", (name) => {
+        expect(icon(name).why.length).toBeGreaterThan(40);
+    });
+});
+describe("the capability icons follow the URN's class", () => {
+    it.each([
+        ["mcp:github", "capability-mcp"],
+        ["cli:kubectl", "capability-cli"],
+        ["iam:aws:s3:GetObject", "capability-iam"],
+    ])("%s → %s", (urn, expected) => {
+        expect(iconForCapability(urn)).toBe(expected);
+    });
+    it("gives an unknown class no icon rather than a guess", () => {
+        expect(iconForCapability("quantum:thing")).toBeUndefined();
+        expect(iconForCapability("kubectl")).toBeUndefined();
+    });
+    it("matches the three classes the vocabulary publishes", () => {
+        const vocabulary = JSON.parse(readFileSync(join(repoRoot(), "spec", "v1", "vocabularies", "capability-classes.json"), "utf8"));
+        for (const entry of vocabulary.entries) {
+            expect(iconForCapability(`${entry.id}:thing`), `${entry.id} has no icon`).toBeDefined();
+        }
+        expect(vocabulary.entries).toHaveLength(3);
+    });
+});
+describe("inline, not a font and not a sprite sheet", () => {
+    it("emits the path in the markup", () => {
+        expect(renderIcon("approval-lock")).toMatch(/<path d="M/);
+    });
+    it("needs no second request and no font load", () => {
+        const svg = renderIcon("approval-lock");
+        expect(svg).not.toMatch(/<use|xlink:href|@font-face/);
+    });
+    it("says why in the module, where somebody would change it", () => {
+        const source = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "icons.ts"), "utf8").replace(/\s*\*\s*/g, " ");
+        expect(source).toMatch(/needs a second request to say what a lock looks like/);
+        expect(source).toMatch(/There is no icon for risk/);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./color.js";
+export * from "./tokens.js";
+export * from "./primitives.js";
+export * from "./specimen.js";
+export * from "./text.js";
+export * from "./mark.js";
+export * from "./render.js";
+export * from "./stylesheet.js";
+export * from "./icons.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./color.js";
+export * from "./tokens.js";
+export * from "./primitives.js";
+export * from "./specimen.js";
+export * from "./text.js";
+export * from "./mark.js";
+export * from "./render.js";
+export * from "./stylesheet.js";
+export * from "./icons.js";

package/dist/mark.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The catalog's mark, and the picture a link to it shows.
+ *
+ * Both are drawn from the tokens for the same reason everything else here is: a mark
+ * hand-drawn beside the palette is a second copy of a decision, and it is the copy that
+ * goes stale — which is exactly what happened to every graph on the site the day the
+ * catalog turned dark.
+ *
+ * The mark is the product's own claim in one shape: a procedure is a graph, and the thing
+ * that matters about it is where it branches and which branch is dangerous. Three nodes
+ * and a fork, with the fork's far branch in the destructive hue — the same colour, from
+ * the same scale, that a reader will meet on a record page.
+ */
+import { type Theme } from "./tokens.js";
+/**
+ * The icon, square, at any size.
+ *
+ * No text: at 16px a word is a smudge, and a favicon is read at 16px more often than
+ * anywhere else. The shape has to survive that, so it is three filled dots and two
+ * strokes and nothing finer.
+ */
+export declare function markSvg(theme: Theme, size?: number): string;
+export interface PreviewOptions {
+    readonly theme: Theme;
+    readonly title: string;
+    /** Up to two lines under the title. Wrapped here, by measure, rather than by the caller. */
+    readonly summary?: string;
+    /** The record's own graph, if this preview is for a record. */
+    readonly graph?: string;
+    readonly footer?: string;
+}
+export declare const PREVIEW_WIDTH = 1200;
+export declare const PREVIEW_HEIGHT = 630;
+/**
+ * The card a link shows in a chat, a search result or a timeline.
+ *
+ * A record's preview carries that record's own graph, because the graph *is* the summary —
+ * a reader who sees it has already been told whether the procedure branches and whether
+ * there is red in it. Drawing something else for the preview would be a second opinion
+ * about the procedure, which is the thing this repository refuses everywhere else.
+ */
+export declare function previewSvg(options: PreviewOptions): string;