@a2f0/agent-tool 0.1.12 → 0.1.13

package/README.md

@@ -11,6 +11,9 @@ version management, and portable skills for Claude Code, Codex, and OpenCode.
   `bun.lock` in sync.
 - **Share skills**: install the same workflow instructions where each harness
   discovers them, and check them in CI.
+- **Render brand images**: build app icons, splash screens, favicons, and store
+  graphics from the SVGs in `assets/brand/`, with every size and destination
+  declared in `agent-tool.json`.
 - **Compact output**: run noisy commands with full private logs and bounded
   diagnostics, keeping routine output out of an agent's context.
 
@@ -109,6 +112,8 @@ agent-tool skills install --apply
 | `skills list` | List embedded portable skills |
 | `skills install [--harness all\|claude\|codex\|opencode] [--apply]` | Preview by default; install or update managed skills |
 | `skills check [--harness all\|claude\|codex\|opencode]` | Read-only CI check for current managed skills |
+| `images list [target...]` | List the files each image target writes, without rendering |
+| `images build [target...] [--out dir]` | Render image targets from `assets/brand/*.svg`; `--out` redirects one target |
 | `init` / `config show` | Create or inspect data-only project policy |
 | `doctor` | Inspect local versions and required CLI flags without running a model |
 
@@ -256,6 +261,38 @@ the commit restores the manifests, lockfile, and index, unless HEAD or other
 paths changed, in which case it leaves that state for inspection. Repeating
 against the same base creates no commit.
 
+### Images
+
+`images` declares named targets of brand images rendered from SVG sources in
+`assets/brand/`. Each output names its file, pixel size or variants (such as
+Android densities or `@2x`/`@3x`), and the layers composed into it:
+
+```json
+{
+  "schemaVersion": 1,
+  "images": {
+    "targets": {
+      "ios": {
+        "dir": "ios/App/Assets.xcassets",
+        "outputs": [
+          {
+            "path": "AppIcon.appiconset/AppIcon.png",
+            "size": 1024,
+            "opaque": true,
+            "layers": [{ "source": "background", "fit": "cover" }, { "source": "logo", "scale": 0.7 }]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+`agent-tool images build ios` writes PNG, ICO, SVG, and Android color resource
+outputs with a bundled WebAssembly renderer, so builds need no ImageMagick or
+librsvg and render identically on every machine. See the
+[image reference](docs/images.md) for every setting.
+
 ## Portable skills
 
 Canonical skills live in `skills/`. The build embeds them, and the installer
@@ -393,6 +430,7 @@ yet.
 ## Further reading
 
 - [Design](docs/design.md): component boundaries and implementation choices.
+- [Images](docs/images.md): brand image sources, targets, and output settings.
 - [Validation record](docs/validation.md): observed test results and their
   limits.
 - [Extraction record](docs/extraction.md): the projects this tool was extracted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
   "license": "UNLICENSED",
@@ -33,5 +33,8 @@
   "devDependencies": {
     "@types/bun": "1.4.2",
     "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "@resvg/resvg-wasm": "2.6.2"
   }
 }

package/src/cli.ts

@@ -32,6 +32,8 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
   skills list
   skills install [--harness <all|claude|codex|opencode>] [--apply]
   skills check [--harness <all|claude|codex|opencode>]
+  images list [target...]               JSON files each image target writes
+  images build [target...] [--out <dir>]  Render assets/brand/*.svg per agent-tool.json
   init                                  Create agent-tool.json without overwriting
   config show
   doctor                                JSON versions and supported review flags
@@ -85,6 +87,22 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
     const result = doctor(process.cwd()); output(result);
     return result.tools.find(item => item.name === "git")?.compatible && result.tools.some(item => ["claude", "codex", "opencode"].includes(item.name) && item.compatible) ? 0 : 1;
   }
+  if (command === "images") {
+    const action = args.shift();
+    usage(action === "list" || action === "build", "Usage: agent-tool images <list|build> [target...] [--out <dir>]");
+    const names: string[] = [];
+    let out: string | undefined;
+    while (args.length) {
+      const value = args.shift()!;
+      if (value === "--out") { usage(action === "build" && out === undefined && !!args[0] && !args[0].startsWith("--"), "--out requires one directory and applies to build."); out = args.shift(); }
+      else { usage(!value.startsWith("-"), `Unknown images argument '${value}'.`); names.push(value); }
+    }
+    const { images } = loadConfig();
+    // Loaded on demand so other commands never initialize the renderer.
+    return import("./images/build").then(async ({ buildImages, listImages }) => {
+      output(action === "list" ? listImages(images, names) : await buildImages(process.cwd(), images, names, out)); return 0;
+    });
+  }
   if (command === "skills") {
     const action = args.shift();
     if (action === "list") { usage(args.length === 0, "Usage: agent-tool skills list"); output(Object.keys(BUNDLED_SKILLS)); return 0; }

package/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { parseImages, type ImagesConfig } from "./images/config";
 
 export interface RequiredCheck {
   name: string;
@@ -13,6 +14,7 @@ export interface AgentToolConfig {
   review: { claudeModel: string | null; codexModel: string | null; opencodeModel: string; opencodeVariants: Record<string, string>; timeoutMs: number };
   versions: { packages: string[] | null; bundles: string[]; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
   pr: { rejectClaudeBranding: boolean };
+  images: ImagesConfig;
 }
 
 export const DEFAULT_CONFIG: AgentToolConfig = {
@@ -26,6 +28,7 @@ export const DEFAULT_CONFIG: AgentToolConfig = {
   review: { claudeModel: null, codexModel: null, opencodeModel: "deepseek/deepseek-v4-pro", opencodeVariants: { low: "low", medium: "medium", high: "high", xhigh: "max", max: "max" }, timeoutMs: 600_000 },
   versions: { packages: null, bundles: [], lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
   pr: { rejectClaudeBranding: false },
+  images: { targets: {} },
 };
 
 function object(value: unknown, name: string): Record<string, unknown> {
@@ -57,6 +60,7 @@ export function parseConfig(source: string): AgentToolConfig {
     keys(settings, Object.keys(result[section]), section);
     Object.assign(result[section], settings);
   }
+  if (input.images !== undefined) result.images = parseImages(input.images);
   const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };
   if (typeof result.subject.conventional !== "boolean") invalid("subject.conventional");
   if (!Number.isSafeInteger(result.subject.maxLength) || result.subject.maxLength < 1) invalid("subject.maxLength");

package/src/images/build.ts

@@ -0,0 +1,160 @@
+import { initWasm, Resvg } from "@resvg/resvg-wasm";
+import wasm from "@resvg/resvg-wasm/index_bg.wasm" with { type: "file" };
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { composeSvg, type Canvas } from "./compose";
+import { expand, format, SOURCE_DIRECTORY, verbatim, type ImageOutput, type ImagesConfig, type ImageTarget } from "./config";
+import { encodeIco, encodePng, fromPremultiplied, type Pixels } from "./png";
+import { parseSvg, type SvgSource } from "./svg";
+
+let ready: Promise<void> | undefined;
+
+async function rasterize(svg: string, width: number, height: number, opaque: boolean): Promise<Pixels> {
+  await (ready ??= initWasm(readFileSync(wasm)));
+  // No system fonts: sources may not contain text, so nothing depends on the machine.
+  const renderer = new Resvg(svg, { fitTo: { mode: "original" }, font: { loadSystemFonts: false } });
+  const image = renderer.render();
+  try {
+    if (image.width !== width || image.height !== height) throw new Error(`Rendered ${image.width}x${image.height} instead of ${width}x${height}.`);
+    return fromPremultiplied(width, height, image.pixels, opaque);
+  } finally { image.free(); renderer.free(); }
+}
+
+class Sources {
+  private readonly loaded = new Map<string, { text: string; svg?: SvgSource }>();
+  constructor(private readonly root: string) {}
+  private entry(name: string) {
+    let entry = this.loaded.get(name);
+    if (!entry) {
+      const file = path.join(this.root, SOURCE_DIRECTORY, `${name}.svg`);
+      if (!existsSync(file)) throw new Error(`Image source '${name}' does not exist at ${SOURCE_DIRECTORY}/${name}.svg.`);
+      entry = { text: readFileSync(file, "utf8") };
+      this.loaded.set(name, entry);
+    }
+    return entry;
+  }
+  text(name: string): string { return this.entry(name).text; }
+  parsed(names: Iterable<string>): Map<string, SvgSource> {
+    return new Map([...names].map(name => { const entry = this.entry(name); return [name, entry.svg ??= parseSvg(name, entry.text)]; }));
+  }
+}
+
+function layerSources(output: Pick<ImageOutput, "layers">): string[] {
+  return output.layers.flatMap(layer => "source" in layer ? [layer.source] : []);
+}
+
+async function render(output: ImageOutput, canvas: Canvas, sources: Sources): Promise<Uint8Array | string> {
+  const kind = format(output.path);
+  if (kind === "xml") {
+    let colors = "";
+    for (const [name, color] of Object.entries(output.colors!)) {
+      let hex = typeof color === "string" ? color : "";
+      if (typeof color !== "string") {
+        // The source's mean color over white, on a canvas of its own proportions, for settings that take a color.
+        const parsed = sources.parsed([color.average]), [, , viewWidth, viewHeight] = parsed.get(color.average)!.viewBox;
+        const width = Math.max(1, Math.round(64 * Math.min(1, viewWidth / viewHeight))), height = Math.max(1, Math.round(64 * Math.min(1, viewHeight / viewWidth)));
+        const average = { layers: [{ source: color.average, fit: "cover" as const, scale: null, size: null, hide: [], tint: null, bleed: [], pixelSnap: false }], mask: null, opaque: true };
+        const { data } = await rasterize(composeSvg(average, { width, height, factor: 1 }, parsed), width, height, true);
+        const sums = [0, 0, 0];
+        for (let index = 0; index < data.length; index += 1) sums[index % 3]! += data[index]!;
+        hex = `#${sums.map(sum => Math.round(sum / (width * height)).toString(16).padStart(2, "0")).join("")}`;
+      }
+      if (hex.length === 4) hex = `#${[...hex.slice(1)].map(digit => digit + digit).join("")}`;
+      colors += `    <color name="${name}">${hex.toUpperCase()}</color>\n`;
+    }
+    return `<?xml version="1.0" encoding="utf-8"?>\n<!-- Generated by agent-tool images from agent-tool.json. Do not edit. -->\n<resources>\n${colors}</resources>\n`;
+  }
+  const copy = verbatim(output);
+  // Copies pass the same checks as composed sources: no scripts, handlers, or external references.
+  if (copy !== null) { sources.parsed([copy]); return sources.text(copy); }
+  const parsed = sources.parsed(layerSources(output));
+  if (kind === "svg") return composeSvg(output, canvas, parsed, true);
+  const pixels = async (width: number, height: number) => rasterize(composeSvg(output, { width, height, factor: canvas.factor }, parsed), width, height, output.opaque);
+  if (kind === "ico") return encodeIco(await Promise.all(output.sizes!.map(size => pixels(size, size))));
+  return encodePng(await pixels(canvas.width, canvas.height));
+}
+
+function select(config: ImagesConfig, names: string[], writable: boolean): [string, ImageTarget][] {
+  const available = Object.keys(config.targets);
+  if (!available.length) throw new Error("agent-tool.json defines no images.targets.");
+  for (const name of names) if (!config.targets[name]) throw new Error(`Unknown image target '${name}'; expected one of: ${available.join(", ")}.`);
+  // Without names, build leaves targets that need --out for an explicit request.
+  const selected = names.length ? [...new Set(names)] : available.filter(name => !writable || config.targets[name]!.dir !== null);
+  if (!selected.length) throw new Error("No image target has a dir; name one and pass --out <directory>.");
+  return selected.map(name => [name, config.targets[name]!]);
+}
+
+/** Refuses symbolic links below the base, so a committed link cannot redirect a write outside it. */
+function assertNoLinks(base: string, destination: string): void {
+  let current = base;
+  for (const part of path.relative(base, destination).split(path.sep)) {
+    current = path.join(current, part);
+    let link: boolean;
+    try { link = lstatSync(current).isSymbolicLink(); } catch { return; }
+    if (link) throw new Error(`Refusing to write through symbolic link ${path.relative(base, current)}.`);
+  }
+}
+
+function directory(name: string, target: ImageTarget, out: string | undefined): string {
+  const dir = out ?? target.dir;
+  if (dir === null) throw new Error(`Image target '${name}' has no dir; pass --out <directory>.`);
+  return dir;
+}
+
+/** Every file each selected target writes, without rendering anything. */
+export function listImages(config: ImagesConfig, names: string[]) {
+  return {
+    sources: SOURCE_DIRECTORY,
+    targets: select(config, names, false).map(([name, target]) => ({
+      name, dir: target.dir, files: target.outputs.flatMap(output => expand(output).map(file => file.path)),
+    })),
+  };
+}
+
+/**
+ * Renders the selected targets under the repository root. Files whose bytes
+ * already match are left alone, so native builds see no spurious changes, and
+ * the rest are replaced atomically.
+ */
+export async function buildImages(root: string, config: ImagesConfig, names: string[], out?: string) {
+  if (out !== undefined && names.length !== 1) throw new Error("--out needs exactly one image target.");
+  const sources = new Sources(root);
+  // Render everything first, so a bad source or setting leaves no partial set behind.
+  const rendered: { name: string; dir: string; files: { relative: string; destination: string; bytes: Uint8Array }[] }[] = [];
+  const owners = new Map<string, string>();
+  for (const [name, target] of select(config, names, true)) {
+    const dir = directory(name, target, out);
+    const files = [];
+    for (const output of target.outputs) {
+      for (const file of expand(output)) {
+        const content = await render(output, { width: file.width, height: file.height, factor: file.factor }, sources);
+        const destination = path.resolve(root, dir, file.path);
+        // An explicit --out is the caller's choice; configured directories are checked from the repository root.
+        assertNoLinks(out === undefined ? root : path.resolve(root, out), destination);
+        // Compared without case, as macOS and Windows file systems do.
+        const owner = owners.get(destination.toLowerCase());
+        if (owner !== undefined) throw new Error(`Image targets '${owner}' and '${name}' both write ${path.relative(root, destination)}.`);
+        owners.set(destination.toLowerCase(), name);
+        files.push({ relative: path.join(dir, file.path), destination, bytes: typeof content === "string" ? Buffer.from(content) : content });
+      }
+    }
+    rendered.push({ name, dir, files });
+  }
+  const targets = rendered.map(({ name, dir, files }) => {
+    const written: string[] = [], unchanged: string[] = [];
+    for (const { relative, destination, bytes } of files) {
+      if (existsSync(destination) && Buffer.compare(readFileSync(destination), bytes) === 0) { unchanged.push(relative); continue; }
+      mkdirSync(path.dirname(destination), { recursive: true });
+      // An unpredictable name created exclusively, so no committed link can stand in for it.
+      const temporary = `${destination}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(temporary, bytes, { flag: "wx" });
+        renameSync(temporary, destination);
+      } catch (error) { rmSync(temporary, { force: true }); throw error; }
+      written.push(relative);
+    }
+    return { name, dir, written, unchanged };
+  });
+  return { targets };
+}

package/src/images/compose.ts

@@ -0,0 +1,78 @@
+import { pair, type ImageOutput, type SourceLayer } from "./config";
+import { attribute, inlineSvg, renameReferences, type SvgSource } from "./svg";
+
+export interface Canvas { width: number; height: number; factor: number | null }
+
+/** Coordinates rounded so documents stay readable and byte-stable. */
+function n(value: number): string { return String(Number(value.toFixed(6))); }
+
+function nested(source: SvgSource, prefix: string, hide: Set<string>, box: [number, number, number, number], viewBox: number[], aspect: string): string {
+  const content = inlineSvg(source, prefix, hide);
+  // The source root's presentation attributes go on a group, so none can collide with or loosen the viewport's.
+  const presentation = source.attributes.map(([key, value]) => attribute(key, renameReferences(value, prefix))).join("");
+  return `<svg x="${n(box[0])}" y="${n(box[1])}" width="${n(box[2])}" height="${n(box[3])}" viewBox="${viewBox.map(n).join(" ")}" preserveAspectRatio="${aspect}" overflow="hidden">${presentation ? `<g${presentation}>${content}</g>` : content}</svg>`;
+}
+
+function placeSource(layer: SourceLayer, index: number, canvas: Canvas, source: SvgSource): string {
+  const { width, height } = canvas;
+  for (const id of layer.hide) if (!source.ids.has(id)) throw new Error(`Image source '${source.name}' has no element with id '${id}' to hide.`);
+  const hide = new Set(layer.hide);
+  const [vx, vy, vw, vh] = source.viewBox;
+  const [boxWidth, boxHeight] = layer.size === null ? [width * (layer.scale ?? 1), height * (layer.scale ?? 1)] : pair(layer.size).map(side => side * canvas.factor!);
+  const boxX = (width - boxWidth!) / 2, boxY = (height - boxHeight!) / 2;
+  const tint = (parts: string[]) => layer.tint === null ? parts.join("") : `<g filter="url(#agent-tool-tint-${index})">${parts.join("")}</g>`;
+  if (layer.fit === "cover") return tint([nested(source, `l${index}-`, hide, [boxX, boxY, boxWidth!, boxHeight!], source.viewBox, "xMidYMid slice")]);
+  let scale = Math.min(boxWidth! / vw, boxHeight! / vh);
+  if (layer.pixelSnap) {
+    if (!Number.isInteger(vw) || !Number.isInteger(vh)) throw new Error(`Image source '${source.name}' needs a whole-unit viewBox to snap to pixels.`);
+    scale = Math.floor(scale + 1e-9);
+    if (scale < 1) throw new Error(`Image source '${source.name}' (${vw}x${vh}) cannot snap to pixels within ${n(boxWidth!)}x${n(boxHeight!)}.`);
+  }
+  const drawnWidth = vw * scale, drawnHeight = vh * scale;
+  let x = (width - drawnWidth) / 2, y = (height - drawnHeight) / 2;
+  if (layer.pixelSnap) { x = Math.floor(x); y = Math.floor(y); }
+  const parts = [nested(source, `l${index}-`, hide, [x, y, drawnWidth, drawnHeight], source.viewBox, "none")];
+  // Bleeding repeats the source's outermost rendered pixel row or column out to the canvas edge.
+  const row = vh / drawnHeight, column = vw / drawnWidth;
+  const strips: Record<string, [[number, number, number, number], number[]]> = {
+    top: [[x, 0, drawnWidth, y], [vx, vy, vw, row]],
+    bottom: [[x, y + drawnHeight, drawnWidth, height - y - drawnHeight], [vx, vy + vh - row, vw, row]],
+    left: [[0, y, x, drawnHeight], [vx, vy, column, vh]],
+    right: [[x + drawnWidth, y, width - x - drawnWidth, drawnHeight], [vx + vw - column, vy, column, vh]],
+  };
+  for (const edge of layer.bleed) {
+    const [box, viewBox] = strips[edge]!;
+    if (box[2] > 0 && box[3] > 0) parts.push(nested(source, `l${index}${edge}-`, hide, box, viewBox, "none"));
+  }
+  return tint(parts);
+}
+
+/**
+ * One SVG document for an output at its pixel size. Each layer inlines its
+ * source in a nested viewport, so raster and SVG outputs share one geometry.
+ */
+export function composeSvg(output: Pick<ImageOutput, "layers" | "mask" | "opaque">, canvas: Canvas, sources: ReadonlyMap<string, SvgSource>, standalone = false): string {
+  const { width, height } = canvas;
+  const namespaces: Record<string, string> = { xlink: "http://www.w3.org/1999/xlink" };
+  const defs: string[] = [], layers: string[] = [];
+  for (const [index, layer] of output.layers.entries()) {
+    if ("fill" in layer) { layers.push(`<rect width="${width}" height="${height}" fill="${layer.fill}"/>`); continue; }
+    const source = sources.get(layer.source)!;
+    for (const [prefix, uri] of Object.entries(source.namespaces)) {
+      if (namespaces[prefix] !== undefined && namespaces[prefix] !== uri) throw new Error(`Image sources bind xmlns:${prefix} to different namespaces.`);
+      namespaces[prefix] = uri;
+    }
+    if (layer.tint !== null) {
+      // User-space bounds: resvg measures nested viewports incorrectly for bounding-box filter regions.
+      defs.push(`<filter id="agent-tool-tint-${index}" filterUnits="userSpaceOnUse" x="0" y="0" width="${width}" height="${height}" color-interpolation-filters="sRGB"><feFlood flood-color="${layer.tint}"/><feComposite in2="SourceAlpha" operator="in"/></filter>`);
+    }
+    layers.push(placeSource(layer, index, canvas, source));
+  }
+  const shortest = Math.min(width, height);
+  if (output.mask === "circle") defs.push(`<clipPath id="agent-tool-mask"><circle cx="${n(width / 2)}" cy="${n(height / 2)}" r="${n(shortest / 2)}"/></clipPath>`);
+  else if (output.mask) defs.push(`<clipPath id="agent-tool-mask"><rect width="${width}" height="${height}" rx="${n(shortest * output.mask.cornerRadius)}"/></clipPath>`);
+  const size = standalone ? "" : ` width="${width}" height="${height}"`;
+  const declarations = Object.entries(namespaces).map(([prefix, uri]) => attribute(`xmlns:${prefix}`, uri)).join("");
+  const body = output.mask ? `<g clip-path="url(#agent-tool-mask)">${layers.join("")}</g>` : layers.join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg"${declarations}${size} viewBox="0 0 ${width} ${height}">${defs.length ? `<defs>${defs.join("")}</defs>` : ""}${output.opaque ? `<rect width="${width}" height="${height}" fill="#ffffff"/>` : ""}${body}</svg>\n`;
+}

package/src/images/config.ts

@@ -0,0 +1,205 @@
+/** The data-only `images` section of agent-tool.json: named targets of rendered brand images. */
+
+export type Size = number | [number, number];
+export type Edge = "top" | "right" | "bottom" | "left";
+export interface FillLayer { fill: string }
+export interface SourceLayer {
+  source: string;
+  fit: "contain" | "cover";
+  scale: number | null;
+  size: Size | null;
+  hide: string[];
+  tint: string | null;
+  bleed: Edge[];
+  pixelSnap: boolean;
+}
+export type ImageLayer = FillLayer | SourceLayer;
+export type ColorValue = string | { average: string };
+export interface ImageOutput {
+  path: string;
+  size: Size | null;
+  variants: Record<string, number> | Record<string, [number, number]> | null;
+  sizes: number[] | null;
+  opaque: boolean;
+  mask: "circle" | { cornerRadius: number } | null;
+  layers: ImageLayer[];
+  colors: Record<string, ColorValue> | null;
+}
+export interface ImageTarget { dir: string | null; outputs: ImageOutput[] }
+export interface ImagesConfig { targets: Record<string, ImageTarget> }
+
+/** Sources live at assets/brand/<name>.svg in every repository. */
+export const SOURCE_DIRECTORY = "assets/brand";
+export const ANDROID_DENSITIES = { mdpi: 1, hdpi: 1.5, xhdpi: 2, xxhdpi: 3, xxxhdpi: 4 };
+export const MAX_PIXELS = 8192;
+const NAME = /^[a-z][a-z0-9-]*$/;
+const COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const ID = /^[A-Za-z_][\w.:-]*$/;
+const EDGES: Edge[] = ["top", "right", "bottom", "left"];
+const FORMATS = ["png", "ico", "svg", "xml"] as const;
+export type ImageFormat = typeof FORMATS[number];
+
+type Json = Record<string, unknown>;
+function fail(setting: string): never { throw new Error(`Invalid config setting '${setting}'.`); }
+function object(value: unknown, setting: string, allowed: string[]): Json {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${setting} setting '${key}'.`);
+  return value as Json;
+}
+/** An object whose keys are names chosen by the project. */
+function record(value: unknown, setting: string): Json {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  return value as Json;
+}
+function positive(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value > 0; }
+function size(value: unknown, setting: string): Size {
+  if (positive(value)) return value;
+  if (Array.isArray(value) && value.length === 2 && value.every(positive)) return [value[0], value[1]];
+  fail(setting);
+}
+export function pair(value: Size): [number, number] { return typeof value === "number" ? [value, value] : value; }
+/** Repository-relative and inside it: no absolute paths, backslashes, or dot segments. */
+export function relativePath(value: unknown): value is string {
+  return typeof value === "string" && !value.startsWith("/") && !value.includes("\\") && value.split("/").every(part => part && part !== "." && part !== "..");
+}
+export function format(path: string): ImageFormat {
+  return path.slice(path.lastIndexOf(".") + 1) as ImageFormat;
+}
+
+function parseLayer(value: unknown, setting: string): ImageLayer {
+  if (value && typeof value === "object" && "fill" in value) {
+    const layer = object(value, setting, ["fill"]);
+    if (typeof layer.fill !== "string" || !COLOR.test(layer.fill)) fail(`${setting}.fill`);
+    return { fill: layer.fill };
+  }
+  const layer = object(value, setting, ["source", "fit", "scale", "size", "hide", "tint", "bleed", "pixelSnap"]);
+  if (typeof layer.source !== "string" || !NAME.test(layer.source)) fail(`${setting}.source`);
+  const fit = layer.fit ?? "contain";
+  if (fit !== "contain" && fit !== "cover") fail(`${setting}.fit`);
+  if (layer.scale !== undefined && (!positive(layer.scale) || layer.scale > 4)) fail(`${setting}.scale`);
+  if (layer.scale !== undefined && layer.size !== undefined) throw new Error(`${setting} sets both scale and size; choose one.`);
+  const hide = layer.hide ?? [];
+  if (!Array.isArray(hide) || hide.some(id => typeof id !== "string" || !ID.test(id)) || new Set(hide).size !== hide.length) fail(`${setting}.hide`);
+  if (layer.tint !== undefined && (typeof layer.tint !== "string" || !COLOR.test(layer.tint))) fail(`${setting}.tint`);
+  const bleed = layer.bleed ?? [];
+  if (!Array.isArray(bleed) || bleed.some(edge => !EDGES.includes(edge)) || new Set(bleed).size !== bleed.length) fail(`${setting}.bleed`);
+  if (layer.pixelSnap !== undefined && typeof layer.pixelSnap !== "boolean") fail(`${setting}.pixelSnap`);
+  const result: SourceLayer = {
+    source: layer.source, fit, scale: layer.scale ?? null, size: layer.size === undefined ? null : size(layer.size, `${setting}.size`),
+    hide, tint: layer.tint ?? null, bleed, pixelSnap: layer.pixelSnap ?? false,
+  };
+  if (fit === "cover" && (result.bleed.length || result.pixelSnap)) throw new Error(`${setting} can only bleed or snap to pixels with fit "contain".`);
+  return result;
+}
+
+function parseOutput(value: unknown, setting: string): ImageOutput {
+  const input = object(value, setting, ["path", "size", "variants", "sizes", "opaque", "mask", "layers", "colors"]);
+  if (!relativePath(input.path) || !FORMATS.includes(format(input.path))) fail(`${setting}.path`);
+  const path = input.path, kind = format(path);
+  const allowed: Record<ImageFormat, string[]> = {
+    png: ["size", "variants", "opaque", "mask", "layers"],
+    svg: ["size", "variants", "opaque", "mask", "layers"],
+    ico: ["sizes", "opaque", "mask", "layers"],
+    xml: ["colors"],
+  };
+  for (const key of Object.keys(input)) if (key !== "path" && !allowed[kind].includes(key)) throw new Error(`${setting} is ${kind} output and cannot set '${key}'.`);
+
+  let variants: ImageOutput["variants"] = null;
+  if (input.variants !== undefined) {
+    const entries = Object.entries(input.variants === "android" ? ANDROID_DENSITIES : record(input.variants, `${setting}.variants`));
+    const factors = entries.every(([, factor]) => positive(factor)), pairs = entries.every(([, dimensions]) => Array.isArray(dimensions));
+    if (!entries.length || (!factors && !pairs) || entries.some(([key]) => !/^[\w@.-]*$/.test(key))) fail(`${setting}.variants`);
+    variants = Object.fromEntries(entries.map(([key, entry]) => [key, factors ? entry : pair(size(entry, `${setting}.variants.${key}`))])) as ImageOutput["variants"];
+    if (!path.includes("{variant}")) throw new Error(`${setting}.path needs {variant} to name each variant's file.`);
+  } else if (path.includes("{variant}")) throw new Error(`${setting}.path uses {variant} without variants.`);
+  const explicit = variants !== null && Object.values(variants).every(Array.isArray);
+  const base = input.size === undefined ? null : size(input.size, `${setting}.size`);
+  if (explicit && base !== null) throw new Error(`${setting} gives each variant its pixels; remove size.`);
+
+  let sizes: number[] | null = null;
+  if (kind === "ico") {
+    if (!Array.isArray(input.sizes) || !input.sizes.length || input.sizes.some(item => !Number.isInteger(item) || item < 1 || item > 256) || new Set(input.sizes).size !== input.sizes.length) fail(`${setting}.sizes`);
+    sizes = input.sizes as number[];
+  }
+  let colors: ImageOutput["colors"] = null;
+  if (kind === "xml") {
+    const entries = Object.entries(record(input.colors, `${setting}.colors`));
+    if (!entries.length) fail(`${setting}.colors`);
+    colors = {};
+    for (const [name, color] of entries) {
+      if (!/^[a-z_][a-z0-9_]*$/.test(name)) fail(`${setting}.colors.${name}`);
+      if (typeof color === "string" && COLOR.test(color)) colors[name] = color;
+      else {
+        const average = object(color, `${setting}.colors.${name}`, ["average"]).average;
+        if (typeof average !== "string" || !NAME.test(average)) fail(`${setting}.colors.${name}`);
+        colors[name] = { average };
+      }
+    }
+    return { path, size: null, variants: null, sizes: null, opaque: false, mask: null, layers: [], colors };
+  }
+
+  if (input.opaque !== undefined && typeof input.opaque !== "boolean") fail(`${setting}.opaque`);
+  let mask: ImageOutput["mask"] = null;
+  if (input.mask === "circle") mask = "circle";
+  else if (input.mask !== undefined) {
+    const radius = object(input.mask, `${setting}.mask`, ["cornerRadius"]).cornerRadius;
+    if (!positive(radius) || radius > 0.5) fail(`${setting}.mask.cornerRadius`);
+    mask = { cornerRadius: radius };
+  }
+  if (!Array.isArray(input.layers) || !input.layers.length) fail(`${setting}.layers`);
+  const layers = input.layers.map((layer, index) => parseLayer(layer, `${setting}.layers[${index}]`));
+  if ((explicit || kind === "ico") && layers.some(layer => "source" in layer && layer.size !== null)) throw new Error(`${setting} has no base size for a layer size; use scale.`);
+  const output: ImageOutput = { path, size: base, variants, sizes, opaque: input.opaque ?? false, mask, layers, colors };
+  if (kind === "png" && base === null && !explicit) throw new Error(`${setting} needs a size or sized variants.`);
+  if (kind === "svg" && base === null && !explicit && !verbatim(output)) throw new Error(`${setting} needs a size unless it copies one source unchanged.`);
+  for (const { width, height } of base === null && !explicit ? [] : expand(output)) {
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width > MAX_PIXELS || height > MAX_PIXELS) throw new Error(`${setting} renders ${width}x${height}; sizes must be whole pixels up to ${MAX_PIXELS}.`);
+  }
+  return output;
+}
+
+/** An SVG output that is one unmodified source is copied byte for byte. */
+export function verbatim(output: ImageOutput): string | null {
+  const [layer] = output.layers;
+  if (format(output.path) !== "svg" || output.layers.length !== 1 || output.size !== null || output.variants !== null || output.opaque || output.mask || !layer || !("source" in layer)) return null;
+  return layer.fit === "contain" && layer.scale === null && layer.size === null && !layer.hide.length && layer.tint === null && !layer.bleed.length && !layer.pixelSnap ? layer.source : null;
+}
+
+export function parseImages(value: unknown): ImagesConfig {
+  const input = object(value, "images", ["targets"]);
+  const targets = record(input.targets ?? {}, "images.targets");
+  const result: ImagesConfig = { targets: {} };
+  for (const [name, entry] of Object.entries(targets)) {
+    const setting = `images.targets.${name}`;
+    if (!NAME.test(name)) fail(setting);
+    const target = object(entry, setting, ["dir", "outputs"]);
+    if (target.dir !== undefined && !relativePath(target.dir)) fail(`${setting}.dir`);
+    if (!Array.isArray(target.outputs) || !target.outputs.length) fail(`${setting}.outputs`);
+    const outputs = target.outputs.map((output, index) => parseOutput(output, `${setting}.outputs[${index}]`));
+    const paths = outputs.flatMap(output => expand(output).map(file => file.path));
+    const escaping = paths.find(path => !relativePath(path));
+    if (escaping !== undefined) throw new Error(`${setting} writes '${escaping}', which is not a path inside its directory.`);
+    // Compared without case, as macOS and Windows file systems do.
+    const folded = paths.map(path => path.toLowerCase());
+    const repeated = paths.find((_, index) => folded.indexOf(folded[index]!) !== index);
+    if (repeated) throw new Error(`${setting} writes ${repeated} more than once.`);
+    result.targets[name] = { dir: target.dir ?? null, outputs };
+  }
+  return result;
+}
+
+export interface ImageFile { path: string; width: number; height: number; factor: number | null }
+
+/** One file per variant, with its pixel size and the factor that scales layer sizes. */
+export function expand(output: ImageOutput): ImageFile[] {
+  if (output.variants === null) {
+    const [width, height] = output.size === null ? [0, 0] : pair(output.size);
+    return [{ path: output.path, width, height, factor: 1 }];
+  }
+  return Object.entries(output.variants).map(([key, value]) => {
+    const path = output.path.replaceAll("{variant}", key);
+    if (Array.isArray(value)) return { path, width: value[0], height: value[1], factor: null };
+    const [width, height] = pair(output.size!).map(side => side * value) as [number, number];
+    return { path, width, height, factor: value };
+  });
+}

package/src/images/png.ts

@@ -0,0 +1,110 @@
+import { deflateSync } from "node:zlib";
+
+export interface Pixels { width: number; height: number; channels: 3 | 4; data: Uint8Array }
+
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, index) => {
+  let value = index;
+  for (let bit = 0; bit < 8; bit += 1) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+  return value >>> 0;
+});
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = CRC_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(data.length + 12);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, data.length);
+  bytes.set(new TextEncoder().encode(type), 4);
+  bytes.set(data, 8);
+  view.setUint32(data.length + 8, crc32(bytes.subarray(4, data.length + 8)));
+  return bytes;
+}
+
+function paeth(left: number, up: number, upLeft: number): number {
+  const estimate = left + up - upLeft;
+  const toLeft = Math.abs(estimate - left), toUp = Math.abs(estimate - up), toUpLeft = Math.abs(estimate - upLeft);
+  return toLeft <= toUp && toLeft <= toUpLeft ? left : toUp <= toUpLeft ? up : upLeft;
+}
+
+/**
+ * Premultiplied RGBA from the renderer to straight-alpha RGBA, or to RGB when
+ * the image is opaque: app stores reject icons that carry an alpha channel.
+ */
+export function fromPremultiplied(width: number, height: number, rgba: Uint8Array, opaque: boolean): Pixels {
+  const channels = opaque ? 3 : 4;
+  const data = new Uint8Array(width * height * channels);
+  for (let pixel = 0; pixel < width * height; pixel += 1) {
+    const alpha = rgba[pixel * 4 + 3]!;
+    if (opaque && alpha !== 255) throw new Error("An opaque image rendered a transparent pixel.");
+    for (let channel = 0; channel < 3; channel += 1) {
+      const value = rgba[pixel * 4 + channel]!;
+      data[pixel * channels + channel] = alpha === 0 ? 0 : alpha === 255 ? value : Math.min(255, Math.round(value * 255 / alpha));
+    }
+    if (!opaque) data[pixel * 4 + 3] = alpha;
+  }
+  return { width, height, channels, data };
+}
+
+/** A deterministic PNG: no timestamps or text, and each row's filter chosen by the usual minimum-sum heuristic. */
+export function encodePng({ width, height, channels, data }: Pixels): Uint8Array {
+  const stride = width * channels;
+  const filtered = new Uint8Array((stride + 1) * height);
+  const candidates = Array.from({ length: 5 }, () => new Uint8Array(stride));
+  const empty = new Uint8Array(stride);
+  for (let row = 0; row < height; row += 1) {
+    const current = data.subarray(row * stride, (row + 1) * stride);
+    const previous = row ? data.subarray((row - 1) * stride, row * stride) : empty;
+    let best = 0, bestScore = Infinity;
+    for (let type = 0; type < 5; type += 1) {
+      const output = candidates[type]!;
+      let score = 0;
+      for (let index = 0; index < stride; index += 1) {
+        const left = index >= channels ? current[index - channels]! : 0;
+        const up = previous[index]!, upLeft = index >= channels ? previous[index - channels]! : 0;
+        const predictor = type === 0 ? 0 : type === 1 ? left : type === 2 ? up : type === 3 ? (left + up) >> 1 : paeth(left, up, upLeft);
+        const value = (current[index]! - predictor) & 0xff;
+        output[index] = value;
+        score += value < 128 ? value : 256 - value;
+        if (score >= bestScore) break;
+      }
+      if (score < bestScore) { best = type; bestScore = score; }
+    }
+    filtered[row * (stride + 1)] = best;
+    filtered.set(candidates[best]!, row * (stride + 1) + 1);
+  }
+  const header = new DataView(new ArrayBuffer(13));
+  header.setUint32(0, width);
+  header.setUint32(4, height);
+  header.setUint8(8, 8);
+  header.setUint8(9, channels === 3 ? 2 : 6);
+  return Buffer.concat([
+    Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10),
+    chunk("IHDR", new Uint8Array(header.buffer)),
+    chunk("IDAT", deflateSync(filtered, { level: 9 })),
+    chunk("IEND", new Uint8Array()),
+  ]);
+}
+
+/** A Windows icon that stores one PNG per size, which every current browser reads. */
+export function encodeIco(images: readonly Pixels[]): Uint8Array {
+  const pngs = images.map(encodePng);
+  const directory = new DataView(new ArrayBuffer(6 + images.length * 16));
+  directory.setUint16(2, 1, true);
+  directory.setUint16(4, images.length, true);
+  let offset = directory.byteLength;
+  for (const [index, image] of images.entries()) {
+    const entry = 6 + index * 16;
+    // A stored dimension of 0 means 256 pixels.
+    directory.setUint8(entry, image.width % 256);
+    directory.setUint8(entry + 1, image.height % 256);
+    directory.setUint16(entry + 4, 1, true);
+    directory.setUint16(entry + 6, 32, true);
+    directory.setUint32(entry + 8, pngs[index]!.length, true);
+    directory.setUint32(entry + 12, offset, true);
+    offset += pngs[index]!.length;
+  }
+  return Buffer.concat([new Uint8Array(directory.buffer), ...pngs]);
+}

package/src/images/svg.ts

@@ -0,0 +1,197 @@
+/**
+ * Just enough XML to inline brand sources in a composed document: one copy per
+ * layer with prefixed ids, named elements dropped, and features refused when
+ * they would render differently between machines, leak between layers, or
+ * script or fetch when an output is opened.
+ */
+
+export interface SvgSource {
+  name: string;
+  viewBox: [number, number, number, number];
+  /** Root presentation attributes, such as fill or shape-rendering, that the inlined copy keeps. */
+  attributes: [string, string][];
+  namespaces: Record<string, string>;
+  ids: Set<string>;
+  tokens: Token[];
+}
+
+type Token =
+  | { kind: "raw"; text: string }
+  | { kind: "start"; name: string; attributes: [string, string][]; selfClosing: boolean }
+  | { kind: "end"; name: string };
+
+const TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<!DOCTYPE[^>[]*(\[[\s\S]*?\])?\s*>|<\/([A-Za-z_][\w.:-]*)\s*>|<([A-Za-z_][\w.:-]*)((?:\s+[^\s=/>]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>|[^<]+/y;
+const ATTRIBUTE = /\s+([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+// Static SVG only: shapes, paint servers, clipping, masking, and filters. Animation, links, and markup
+// from other namespaces could script or fetch when an output is opened, so they are refused, not trusted.
+const ELEMENTS = new Set([
+  "circle", "clipPath", "defs", "desc", "ellipse", "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite",
+  "feConvolveMatrix", "feDiffuseLighting", "feDisplacementMap", "feDistantLight", "feDropShadow", "feFlood", "feFuncA",
+  "feFuncB", "feFuncG", "feFuncR", "feGaussianBlur", "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset",
+  "fePointLight", "feSpecularLighting", "feSpotLight", "feTile", "feTurbulence", "filter", "g", "image", "line",
+  "linearGradient", "marker", "mask", "metadata", "path", "pattern", "polygon", "polyline", "radialGradient", "rect",
+  "stop", "svg", "switch", "symbol", "title", "use",
+]);
+const REASONS: Record<string, string> = {
+  style: "a <style> element; use presentation attributes",
+  text: "text, which depends on installed fonts; convert it to paths",
+};
+const ROOT_GEOMETRY = new Set(["xmlns", "version", "baseProfile", "width", "height", "x", "y", "viewBox", "preserveAspectRatio", "overflow", "id"]);
+
+const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+/** Attribute values as an XML parser sees them, so checks cannot be bypassed by encoding. */
+function decode(name: string, value: string): string {
+  if (/&(?!(?:#x[0-9a-fA-F]{1,6}|#[0-9]{1,7}|amp|lt|gt|quot|apos);)/.test(value)) throw new Error(`Image source '${name}' uses an undefined entity in '${value.slice(0, 40)}'.`);
+  const decoded = value.replace(/&(?:#x([0-9a-fA-F]+)|#([0-9]+)|(amp|lt|gt|quot|apos));/g, (reference, hex?: string, decimal?: string, entity?: string) => {
+    if (entity) return ENTITIES[entity]!;
+    const code = hex ? Number.parseInt(hex, 16) : Number(decimal);
+    if (code < 1 || code > 0x10ffff) throw new Error(`Image source '${name}' has an invalid character reference '${reference}'.`);
+    return String.fromCodePoint(code);
+  });
+  // CSS escapes could spell url( in a way the reference check cannot see; SVG values never need them.
+  if (decoded.includes("\\")) throw new Error(`Image source '${name}' uses a CSS escape in '${value.slice(0, 40)}'.`);
+  return decoded;
+}
+
+function tokenize(name: string, text: string): Token[] {
+  const tokens: Token[] = [];
+  TOKEN.lastIndex = 0;
+  while (TOKEN.lastIndex < text.length) {
+    const match = TOKEN.exec(text);
+    if (!match) throw new Error(`Image source '${name}' is not well-formed SVG near offset ${TOKEN.lastIndex}.`);
+    if (match[1] !== undefined) throw new Error(`Image source '${name}' declares a DOCTYPE subset; remove it.`);
+    if (match[0].startsWith("<!DOCTYPE") && /["']/.test(match[0]) && !/^<!DOCTYPE\s+svg\s+PUBLIC\s+"[^"]*"\s+"http:\/\/www\.w3\.org\/[^"]*"\s*>$/.test(match[0])) {
+      throw new Error(`Image source '${name}' names a DOCTYPE other than the W3C SVG DTD; remove it.`);
+    }
+    if (match[2] !== undefined) tokens.push({ kind: "end", name: match[2] });
+    else if (match[3] !== undefined) {
+      const attributes: [string, string][] = [];
+      for (const attribute of match[4]!.matchAll(ATTRIBUTE)) {
+        if (attributes.some(([key]) => key === attribute[1])) throw new Error(`Image source '${name}' repeats attribute '${attribute[1]}'.`);
+        attributes.push([attribute[1]!, decode(name, attribute[2] ?? attribute[3]!)]);
+      }
+      tokens.push({ kind: "start", name: match[3], attributes, selfClosing: match[5] === "/" });
+    } else tokens.push({ kind: "raw", text: match[0] });
+  }
+  return tokens;
+}
+
+/** The name without its namespace prefix: any prefix may be bound to the SVG or XLink namespace. */
+function local(name: string): string { return name.slice(name.indexOf(":") + 1); }
+
+/** Event handlers, stylesheets, and references to anything outside the file except embedded images, are refused. */
+function checkAttributes(name: string, element: string, attributes: [string, string][]): void {
+  for (const [key, value] of attributes) {
+    if (/^on/i.test(local(key))) throw new Error(`Image source '${name}' has a '${key}' event handler.`);
+    if (local(key) === "style") throw new Error(`Image source '${name}' has a style attribute; use presentation attributes.`);
+    if (local(key) === "base") throw new Error(`Image source '${name}' sets '${key}', which could resolve references elsewhere.`);
+    // CSS image functions can fetch without url(), for example through a mask presentation attribute.
+    if (key !== "id" && /(?:image-set|image|cross-fade|element|src)\s*\(/i.test(value)) throw new Error(`Image source '${name}' uses a CSS image function in '${value.slice(0, 40)}'.`);
+    const external = local(key) === "href"
+      ? !value.startsWith("#") && !(["image", "feImage"].includes(local(element)) && value.startsWith("data:"))
+      : value.split(/url\(/i).slice(1).some(target => !target.trimStart().replace(/^['"]/, "").startsWith("#"));
+    if (external) throw new Error(`Image source '${name}' references '${value.slice(0, 40)}'; embed it or reference an element in the file.`);
+  }
+}
+
+interface Scope { default: string | undefined; prefixes: Record<string, string> }
+function declare(parent: Scope, attributes: [string, string][]): Scope {
+  const declarations = attributes.filter(([key]) => key === "xmlns" || key.startsWith("xmlns:"));
+  if (!declarations.length) return parent;
+  const scope: Scope = { default: parent.default, prefixes: { ...parent.prefixes } };
+  for (const [key, value] of declarations) if (key === "xmlns") scope.default = value; else scope.prefixes[key.slice(6)] = value;
+  return scope;
+}
+
+function number(value: string | undefined): number | undefined {
+  const parsed = value === undefined ? NaN : Number(value.trim().replace(/px$/, ""));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function parseSvg(name: string, text: string): SvgSource {
+  const all = tokenize(name, text);
+  const start = all.findIndex(token => token.kind !== "raw");
+  const root = all[start];
+  const prologue = all.slice(0, Math.max(start, 0));
+  if (!root || root.kind !== "start" || root.name !== "svg" || prologue.some(token => token.kind === "raw" && !/^(?:\s+|<!--[\s\S]*-->|<\?xml\s[\s\S]*\?>|<!DOCTYPE[\s\S]*>)$/.test(token.text))) {
+    throw new Error(`Image source '${name}' must have an <svg> root element.`);
+  }
+  const rootAttributes = new Map(root.attributes);
+  checkAttributes(name, root.name, root.attributes);
+  if (rootAttributes.get("xmlns") !== SVG_NAMESPACE) throw new Error(`Image source '${name}' must declare xmlns="${SVG_NAMESPACE}".`);
+  const box = rootAttributes.get("viewBox")?.trim().split(/[\s,]+/).map(Number);
+  const width = number(rootAttributes.get("width")), height = number(rootAttributes.get("height"));
+  let viewBox: [number, number, number, number];
+  if (box) {
+    if (box.length !== 4 || box.some(value => !Number.isFinite(value)) || box[2]! <= 0 || box[3]! <= 0) throw new Error(`Image source '${name}' has an invalid viewBox.`);
+    viewBox = box as [number, number, number, number];
+  } else if (width && height) viewBox = [0, 0, width, height];
+  else throw new Error(`Image source '${name}' needs a viewBox or numeric width and height.`);
+
+  const tokens: Token[] = [], ids = new Set<string>(), stack: string[] = [], scopes = [declare({ default: undefined, prefixes: {} }, root.attributes)];
+  // Ends on the root's closing tag, or on the root itself when it is self-closing.
+  let index = start;
+  if (!root.selfClosing) {
+    for (index = start + 1; index < all.length; index += 1) {
+      const token = all[index]!;
+      if (token.kind === "end") {
+        if (stack.length === 0) { if (token.name !== "svg") throw new Error(`Image source '${name}' closes </${token.name}> without opening it.`); break; }
+        if (stack.pop() !== token.name) throw new Error(`Image source '${name}' closes </${token.name}> out of order.`);
+        scopes.pop();
+      } else if (token.kind === "start") {
+        const scope = declare(scopes.at(-1)!, token.attributes);
+        const prefix = token.name.includes(":") ? token.name.slice(0, token.name.indexOf(":")) : undefined;
+        if ((prefix === undefined ? scope.default : scope.prefixes[prefix]) !== SVG_NAMESPACE || !ELEMENTS.has(local(token.name))) {
+          throw new Error(`Image source '${name}' contains ${REASONS[local(token.name)] ?? `an unsupported <${token.name}> element; keep only static SVG shapes, paint, clipping, masking, and filters`}.`);
+        }
+        checkAttributes(name, token.name, token.attributes);
+        for (const [key, value] of token.attributes) if (key === "id") { if (ids.has(value)) throw new Error(`Image source '${name}' repeats id '${value}'.`); ids.add(value); }
+        if (!token.selfClosing) { stack.push(token.name); scopes.push(scope); }
+      } else if (token.text.startsWith("<?")) throw new Error(`Image source '${name}' contains a processing instruction.`);
+      tokens.push(token);
+    }
+    if (index === all.length) throw new Error(`Image source '${name}' never closes its <svg> root.`);
+  }
+  if (all.slice(index + 1).some(token => token.kind !== "raw" || !/^(?:\s+|<!--[\s\S]*-->)$/.test(token.text))) throw new Error(`Image source '${name}' has content after its <svg> root.`);
+
+  const namespaces: Record<string, string> = {};
+  const attributes: [string, string][] = [];
+  for (const [key, value] of root.attributes) {
+    if (key.startsWith("xmlns:")) namespaces[key.slice(6)] = value;
+    else if (!ROOT_GEOMETRY.has(key)) attributes.push([key, value]);
+  }
+  return { name, viewBox, attributes, namespaces, ids, tokens };
+}
+
+export function attribute(key: string, value: string): string {
+  return ` ${key}="${value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll('"', "&quot;")}"`;
+}
+
+/** Points `url(#id)` references at a copy whose ids carry the prefix. */
+export function renameReferences(value: string, prefix: string): string {
+  return value.replace(/url\(\s*(['"]?)#([^'")\s]+)\1\s*\)/gi, (_, _quote, id: string) => `url(#${prefix}${id})`);
+}
+
+/** The source's children with every id prefixed, internal references rewritten, and hidden elements removed. */
+export function inlineSvg(source: SvgSource, prefix: string, hide: ReadonlySet<string>): string {
+  const rename = (value: string) => renameReferences(value, prefix);
+  let markup = "", skipped = 0;
+  for (const token of source.tokens) {
+    if (token.kind === "start") {
+      if (skipped > 0 || token.attributes.some(([key, value]) => key === "id" && hide.has(value))) { if (!token.selfClosing) skipped += 1; continue; }
+      markup += `<${token.name}`;
+      for (const [key, value] of token.attributes) {
+        if (key === "id") markup += attribute(key, `${prefix}${value}`);
+        else if (local(key) === "href" && value.startsWith("#")) markup += attribute(key, `#${prefix}${value.slice(1)}`);
+        else markup += attribute(key, rename(value));
+      }
+      markup += token.selfClosing ? "/>" : ">";
+    } else if (token.kind === "end") {
+      if (skipped > 0) skipped -= 1;
+      else markup += `</${token.name}>`;
+    } else if (skipped === 0) markup += token.text;
+  }
+  return markup;
+}

package/src/images/wasm.d.ts

@@ -0,0 +1,5 @@
+// Bun embeds the file in compiled executables and resolves it from node_modules otherwise.
+declare module "@resvg/resvg-wasm/index_bg.wasm" {
+  const path: string;
+  export default path;
+}