@a2f0/agent-tool 0.1.31 → 0.1.32

package/README.md

@@ -4,8 +4,8 @@ agent-tool is a command-line tool and a set of portable skills for repositories
 where Claude Code, Codex, or OpenCode make the changes. It provides shared Git,
 GitHub, review, validation, and release workflows: independent agent reviews of
 a committed branch, guarded pushes and squash merges of the exact reviewed
-commit, package versioning, brand image rendering, and compact output for noisy
-commands. Repository policy stays in `agent-tool.json`; the portable skills
+commit, package versioning, brand image rendering, screenshot staging with a
+framework-free gallery, and compact output for noisy commands. Repository policy stays in `agent-tool.json`; the portable skills
 coordinate independently reviewed changes.
 
 ## Quick start
@@ -85,6 +85,8 @@ validation suite, and release procedures.
 - [Development](docs/development.md): setup, source layout, validation, and release
   procedures for this package.
 - [Images](docs/images.md): declarative brand sources and generated outputs.
+- [Screenshots](docs/screenshots.md): staging captured screenshots into a
+  website, and the gallery and carousel web components that show them.
 - [Permissions](docs/permissions.md): which commands run without approval in
   Claude Code and Codex, and the dependency commands that enforce it.
 - [Dependency maintenance](docs/dependency-upgrades.md): active compatibility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "packageManager": "bun@1.4.3",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
@@ -15,6 +15,12 @@
   "bin": {
     "agent-tool": "src/index.ts"
   },
+  "exports": {
+    "./package.json": "./package.json",
+    "./screenshots/gallery": "./src/screenshots/gallery.ts",
+    "./screenshots/gallery.css": "./src/screenshots/gallery.css",
+    "./screenshots/manifest": "./src/screenshots/manifest.ts"
+  },
   "files": [
     "src",
     "skills",
@@ -29,12 +35,14 @@
     "agent:run": "bun src/index.ts run",
     "agent:logs": "bun src/index.ts logs",
     "test": "bun test --parallel src scripts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.browser.json",
     "generate": "bun scripts/build/bundle-skills.ts",
     "build": "bun run generate && bun build --compile --minify src/index.ts --outfile dist/agent-tool"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "21.0.4",
     "@types/bun": "1.4.3",
+    "happy-dom": "21.0.4",
     "typescript": "7.0.2"
   },
   "dependencies": {

package/src/cli.ts

@@ -6,6 +6,7 @@ import { doctor } from "./doctor";
 import { checkTerraformPlan } from "./dependencies/terraformPlan";
 import { dependencyDiff } from "./dependencies/diff";
 import { checkGraph } from "./graph/check";
+import { buildScreenshots, describeScreenshots } from "./screenshots/build";
 import { review } from "./harnesses";
 import { runAgentToolAction } from "./runAgentToolAction";
 import { BUNDLED_SKILLS } from "./skills/bundled";
@@ -77,6 +78,7 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
   permissions check [--harness <all|claude|codex>]
   images list [target...]               JSON files each image target writes
   images build [target...] [--out <dir>]  Render assets/brand/*.svg per agent-tool.json
+  screenshots build [target...] [--out <dir>] [--json]  Stage guarded captures and a gallery manifest
   graph check                           Import cycles and layer violations per agent-tool.json
   init                                  Create agent-tool.json without overwriting
   config show
@@ -157,6 +159,21 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
       output(action === "list" ? listImages(images, names) : await buildImages(process.cwd(), images, names, out)); return 0;
     });
   }
+  if (command === "screenshots") {
+    const action = args.shift();
+    usage(action === "build", "Usage: agent-tool screenshots build [target...] [--out <dir>] [--json]");
+    const names: string[] = [];
+    let out: string | undefined, json = false;
+    while (args.length) {
+      const value = args.shift()!;
+      if (value === "--out") { usage(out === undefined && !!args[0] && !args[0].startsWith("--"), "--out requires one directory."); out = args.shift(); }
+      else if (value === "--json") { usage(!json, "Duplicate --json."); json = true; }
+      else { usage(!value.startsWith("-"), `Unknown screenshots argument '${value}'.`); names.push(value); }
+    }
+    const receipt = buildScreenshots(process.cwd(), loadConfig().screenshots, names, out);
+    if (json) output(receipt); else writeSync(1, describeScreenshots(receipt));
+    return 0;
+  }
   if (command === "graph") {
     usage(args.length === 1 && args[0] === "check", "Usage: agent-tool graph check");
     const report = checkGraph(process.cwd(), loadConfig().graph);

package/src/config.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { GRAPH_DEFAULTS, parseGraph, type GraphConfig } from "./graph/config";
 import { parseImages, type ImagesConfig } from "./images/config";
 import { CLASSES, type PermissionClass } from "./permissions/catalog";
+import { parseScreenshots, SCREENSHOTS_DEFAULTS, type ScreenshotsConfig } from "./screenshots/config";
 import { WORKFLOW_DEFAULTS, validateWorkflowConfig, type WorkflowConfig } from "./workflows/config";
 
 export interface RequiredCheck {
@@ -18,6 +19,7 @@ export interface AgentToolConfig extends WorkflowConfig {
   versions: { packages: string[] | null; bundles: string[]; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
   pr: { rejectClaudeBranding: boolean };
   images: ImagesConfig;
+  screenshots: ScreenshotsConfig;
   graph: GraphConfig;
   permissions: { executables: Record<string, PermissionClass> };
 }
@@ -38,6 +40,7 @@ export const DEFAULT_CONFIG: AgentToolConfig = {
   versions: { packages: null, bundles: [], lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
   pr: { rejectClaudeBranding: false },
   images: { targets: {} },
+  screenshots: structuredClone(SCREENSHOTS_DEFAULTS),
   graph: structuredClone(GRAPH_DEFAULTS),
   permissions: { executables: {} },
 };
@@ -72,6 +75,7 @@ export function parseConfig(source: string): AgentToolConfig {
     Object.assign(result[section], settings);
   }
   if (input.images !== undefined) result.images = parseImages(input.images);
+  if (input.screenshots !== undefined) result.screenshots = parseScreenshots(input.screenshots);
   if (input.graph !== undefined) result.graph = parseGraph(input.graph);
   if (input.branch !== undefined && !Object.hasOwn(input.branch as object, "enforce")) result.branch.enforce = true;
   const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };

package/src/images/build.ts

@@ -1,12 +1,12 @@
 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 { closeSync, constants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } 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";
+import { assertNoLinks, replaceFile } from "../system/files";
 
 let ready: Promise<void> | undefined;
 
@@ -85,49 +85,6 @@ function select(config: ImagesConfig, names: string[], writable: boolean): [stri
   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)}.`);
-  }
-}
-
-/**
- * Replaces a file atomically through an unpredictable, exclusively created
- * temporary name, so no committed link can stand in for it. Sandboxed build
- * phases, such as Xcode's, may write only their declared outputs; there the
- * file is rewritten in place, refusing to follow a link.
- */
-export function replaceFile(destination: string, bytes: Uint8Array): void {
-  const temporary = `${destination}.${randomUUID()}.tmp`;
-  let created = false;
-  try {
-    writeFileSync(temporary, bytes, { flag: "wx" });
-    created = true;
-    renameSync(temporary, destination);
-  } catch (error) {
-    if (created || !["EACCES", "EPERM"].includes((error as NodeJS.ErrnoException).code ?? "")) {
-      // Best effort: the original error matters more than a temporary file left behind.
-      try { rmSync(temporary, { force: true }); } catch {}
-      throw error;
-    }
-    // Nothing was created, and a sandbox may refuse even an attempt to remove an undeclared path.
-    const descriptor = openSync(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW);
-    try {
-      // A hard link would share the file with a path outside the output, so only a sole link is rewritten.
-      const stats = fstatSync(descriptor);
-      if (!stats.isFile() || stats.nlink !== 1) throw new Error(`Refusing to rewrite ${destination}, which is not a file with a single link.`);
-      ftruncateSync(descriptor, 0);
-      // writeFileSync on a descriptor repeats short writes until every byte is written.
-      writeFileSync(descriptor, bytes);
-    } finally { closeSync(descriptor); }
-  }
-}
-
 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>.`);

package/src/images/png.ts

@@ -88,6 +88,16 @@ export function encodePng({ width, height, channels, data }: Pixels): Uint8Array
   ]);
 }
 
+const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+/** Pixel size from a PNG's header: the signature, then IHDR's big-endian width and height. */
+export function pngSize(bytes: Uint8Array): { width: number; height: number } | null {
+  if (bytes.length < 24 || SIGNATURE.some((byte, index) => bytes[index] !== byte) || new TextDecoder().decode(bytes.subarray(12, 16)) !== "IHDR") return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16), height = view.getUint32(20);
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+
 /** 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);

package/src/permissions/catalog.ts

@@ -21,7 +21,7 @@ export interface CatalogEntry { command: string; class: PermissionClass; applyCl
 export const CATALOG: CatalogEntry[] = [
   ...["--help", "--version", "logs", "runs list", "doctor", "config show", "branch check", "branch status", "commits check", "checks binaries", "repo context", "policy check", "toolchain check", "ci gate", "release plan", "release verify", "pr context", "pr checks", "pr logs", "pr preflight", "pr threads list", "versions plan", "versions check", "dependencies check-terraform-plan", "dependencies diff", "skills list", "skills check", "hooks check", "images list", "graph check", "permissions show", "permissions check", "proc list"]
     .map(command => ({ command, class: "read" as const })),
-  ...["bun install", "bun update", "bun remove", "bun test", "branch create", "versions bump", "versions prepare", "versions resolve-conflicts", "images build", "review", "init", "proc stop"]
+  ...["bun install", "bun update", "bun remove", "bun test", "branch create", "versions bump", "versions prepare", "versions resolve-conflicts", "images build", "screenshots build", "review", "init", "proc stop"]
     .map(command => ({ command, class: "local" as const })),
   { command: "skills install", class: "read", applyClass: "local" },
   { command: "hooks install", class: "read", applyClass: "local" },

package/src/screenshots/build.ts

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { pngSize } from "../images/png";
+import { assertNoLinks, replaceFile } from "../system/files";
+import type { ScreenshotsConfig, ScreenshotTarget } from "./config";
+import type { ScreenshotCapture, ScreenshotEntry, ScreenshotManifest } from "./manifest";
+
+/** The record the take-screenshots skill keeps beside a shared capture. */
+export const CAPTURE_RECORD = "capture.json";
+const MANIFEST = "manifest.json";
+const IMAGES = "img";
+
+interface CaptureRecord { status?: unknown; commit?: unknown; dirty?: unknown; finishedAt?: unknown; args?: unknown }
+export interface CaptureSummary extends ScreenshotCapture { partial: string[] }
+
+function readRecord(source: string): string | undefined {
+  try { return readFileSync(path.join(source, CAPTURE_RECORD), "utf8"); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The shared-capture guard. Every capture writes a `running` record before it
+ * touches an image, so a `complete` record that is unchanged before and after
+ * copying proves no capture overlapped the copy. A plain directory without a
+ * record (CI, an unlinked clone) copies as is; a linked, non-empty store
+ * without one is refused, since its images name no commit.
+ */
+export function checkCapture(root: string, source: string, raw: string | undefined): CaptureSummary | null {
+  if (raw === undefined) {
+    // Linked anywhere below the repository root, as `.screenshots` or through a parent directory.
+    const linked = resolved(source) !== path.join(resolved(root), path.relative(root, source));
+    let contents: string[] = [];
+    try { contents = readdirSync(source); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    if (linked && contents.length > 0) throw new Error("The shared screenshots have no capture record; capture once through the take-screenshots skill.");
+    return null;
+  }
+  let record: CaptureRecord;
+  try { record = JSON.parse(raw) as CaptureRecord; } catch { throw new Error(`The shared screenshot capture record ${CAPTURE_RECORD} is not JSON; recapture.`); }
+  if (!record || typeof record !== "object") throw new Error(`The shared screenshot capture record ${CAPTURE_RECORD} is not an object; recapture.`);
+  if (record.status !== "complete") throw new Error(`The shared screenshot capture is ${String(record.status)}; wait for it or recapture.`);
+  if (typeof record.commit !== "string" || !/^[0-9a-f]{40}$/.test(record.commit)) throw new Error("The shared screenshot capture record names no commit; recapture.");
+  if (record.dirty !== false) throw new Error("The shared screenshots were captured from uncommitted changes; recapture from a commit.");
+  const partial = Array.isArray(record.args) ? record.args.map(String) : [];
+  return { commit: record.commit, finishedAt: typeof record.finishedAt === "string" ? record.finishedAt : null, partial };
+}
+
+function select(config: ScreenshotsConfig, names: string[], out: string | undefined): [string, ScreenshotTarget][] {
+  const available = Object.keys(config.targets);
+  if (!available.length) throw new Error("agent-tool.json defines no screenshots.targets.");
+  for (const name of names) if (!config.targets[name]) throw new Error(`Unknown screenshots target '${name}'; expected one of: ${available.join(", ")}.`);
+  if (out !== undefined && new Set(names).size !== 1) throw new Error("--out needs exactly one screenshots target.");
+  const selected = names.length ? [...new Set(names)] : available.filter(name => config.targets[name]!.dir !== null);
+  if (!selected.length) throw new Error("No screenshots target has a dir; name one and pass --out <directory>.");
+  return selected.map(name => [name, config.targets[name]!]);
+}
+
+/** The path with every existing ancestor's links resolved, so overlap checks see where writes really land. */
+function resolved(file: string): string {
+  const parts: string[] = [];
+  let current = path.resolve(file);
+  for (;;) {
+    try { return path.join(realpathSync(current), ...parts.reverse()); } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return path.join(current, ...parts.reverse());
+    parts.push(path.basename(current));
+    current = parent;
+  }
+}
+/** Whether either path is the other or contains it. */
+function overlaps(first: string, second: string): boolean {
+  const a = first.toLowerCase(), b = second.toLowerCase();
+  return a === b || a.startsWith(`${b}${path.sep}`) || b.startsWith(`${a}${path.sep}`);
+}
+
+/** The first link anywhere in the capture tree whose target overlaps an output, following linked directories once. */
+function linkedInto(source: string, outputs: string[]): string | undefined {
+  const visited = new Set<string>();
+  const walk = (dir: string): string | undefined => {
+    let real: string;
+    try { real = realpathSync(dir); } catch { return undefined; }
+    if (visited.has(real)) return undefined;
+    visited.add(real);
+    let names: string[];
+    try { names = readdirSync(dir); } catch { return undefined; }
+    for (const name of names) {
+      const entry = path.join(dir, name), stats = lstatSync(entry, { throwIfNoEntry: false });
+      if (stats?.isSymbolicLink() && outputs.some(output => overlaps(resolved(entry), output))) return entry;
+      if (stats?.isDirectory() || (stats?.isSymbolicLink() && lstatSync(resolved(entry), { throwIfNoEntry: false })?.isDirectory())) {
+        const found = walk(entry);
+        if (found) return found;
+      }
+    }
+    return undefined;
+  };
+  return walk(source);
+}
+
+function sameBytes(file: string, bytes: Uint8Array): boolean {
+  const stats = lstatSync(file, { throwIfNoEntry: false });
+  return !!stats?.isFile() && stats.size === bytes.length && Buffer.compare(readFileSync(file), bytes) === 0;
+}
+
+/** Files below `dir`, relative to it, without following links; links count as files to remove. */
+function ownedFiles(dir: string): string[] {
+  const stats = lstatSync(dir, { throwIfNoEntry: false });
+  if (!stats) return [];
+  if (!stats.isDirectory()) return [""];
+  return readdirSync(dir).sort().flatMap(name => ownedFiles(path.join(dir, name)).map(file => file ? path.join(name, file) : name));
+}
+
+function removeEmptyDirectories(dir: string, keep: boolean): void {
+  const stats = lstatSync(dir, { throwIfNoEntry: false });
+  if (!stats?.isDirectory()) return;
+  for (const name of readdirSync(dir)) removeEmptyDirectories(path.join(dir, name), false);
+  if (!keep && readdirSync(dir).length === 0) rmdirSync(dir);
+}
+
+/** Removes everything the target owns: the manifest and the image tree. Other files in the directory stay. */
+function removeOutputs(dir: string): void {
+  rmSync(path.join(dir, MANIFEST), { force: true });
+  rmSync(path.join(dir, IMAGES), { force: true, recursive: true });
+}
+
+interface Staged {
+  name: string;
+  dir: string;
+  absolute: string;
+  manifest: ScreenshotManifest;
+  written: string[];
+  unchanged: string[];
+  keep: Set<string>;
+}
+
+function stageTarget(root: string, source: string, name: string, target: ScreenshotTarget, dir: string, base: string, capture: CaptureSummary | null): Staged {
+  const absolute = path.resolve(root, dir);
+  const staged: Staged = { name, dir, absolute, manifest: { schemaVersion: 1, projects: [], themes: [], screens: [], entries: [], capture: null }, written: [], unchanged: [], keep: new Set() };
+  const entries: ScreenshotEntry[] = [];
+  for (const project of target.projects) {
+    for (const theme of target.themes) {
+      for (const screen of target.screens) {
+        const file = path.join(source, project.dir, theme, `${screen.name}.png`);
+        let bytes: Uint8Array;
+        try { bytes = readFileSync(file); } catch (error) {
+          if (["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) continue;
+          throw error;
+        }
+        const size = pngSize(bytes);
+        if (!size) throw new Error(`${path.relative(root, file)} is not a PNG image.`);
+        const relative = path.join(IMAGES, project.name, theme, `${screen.name}.png`);
+        const destination = path.join(absolute, relative);
+        assertNoLinks(base, destination);
+        if (sameBytes(destination, bytes)) staged.unchanged.push(path.join(dir, relative));
+        else {
+          mkdirSync(path.dirname(destination), { recursive: true });
+          replaceFile(destination, bytes);
+          staged.written.push(path.join(dir, relative));
+        }
+        staged.keep.add(relative);
+        const version = createHash("sha256").update(bytes).digest("hex").slice(0, 8);
+        entries.push({ project: project.name, theme, name: screen.name, src: `${target.urlPrefix}${IMAGES}/${project.name}/${theme}/${screen.name}.png?v=${version}`, ...size });
+      }
+    }
+  }
+  const has = (key: keyof ScreenshotEntry, value: string) => entries.some(entry => entry[key] === value);
+  staged.manifest = {
+    schemaVersion: 1,
+    projects: target.projects.filter(project => has("project", project.name)).map(({ name, label, frame }) => frame ? { name, label, frame } : { name, label }),
+    themes: target.themes.filter(theme => has("theme", theme)).map(theme => ({ name: theme, label: theme.charAt(0).toUpperCase() + theme.slice(1).replaceAll("-", " ") })),
+    screens: target.screens.filter(screen => has("name", screen.name)).map(({ name, label, alt }) => alt ? { name, label, alt } : { name, label }),
+    entries,
+    capture: capture && { commit: capture.commit, finishedAt: capture.finishedAt },
+  };
+  return staged;
+}
+
+export interface ScreenshotsTargetReceipt {
+  name: string;
+  dir: string;
+  manifest: string;
+  entries: number;
+  projects: string[];
+  written: string[];
+  unchanged: number;
+  removed: string[];
+}
+export interface ScreenshotsReceipt { source: string; capture: CaptureSummary | null; targets: ScreenshotsTargetReceipt[] }
+
+/**
+ * Stages the selected targets from the capture source. Images are copied only
+ * when their bytes differ, files the target owns but no longer lists are
+ * removed, and the manifest is written last, atomically, once the capture
+ * record is confirmed unchanged. Any failure removes the targets' outputs, so
+ * a site never builds from a partial or unverified gallery.
+ */
+export function buildScreenshots(root: string, config: ScreenshotsConfig, names: string[], out?: string, hooks: { afterCopy?: () => void } = {}): ScreenshotsReceipt {
+  const selected = select(config, names, out);
+  const source = path.resolve(root, config.source);
+  // The source is usually a link to the shared store; compare where both really are.
+  const sources = [source, resolved(source)];
+  const claimed: { name: string; dirs: string[] }[] = [];
+  const plans = selected.map(([name, target]) => {
+    const dir = out ?? target.dir;
+    if (dir === null) throw new Error(`Screenshots target '${name}' has no dir; pass --out <directory>.`);
+    const absolute = path.resolve(root, dir);
+    const dirs = [absolute, resolved(absolute)];
+    // Pruning or cleanup in an overlapping directory would delete captures or another target's images.
+    if (dirs.some(item => sources.some(other => overlaps(item, other)))) throw new Error(`Screenshots target '${name}' overlaps the capture source.`);
+    const owner = claimed.find(other => other.dirs.some(item => dirs.some(mine => overlaps(item, mine))));
+    if (owner) throw new Error(`Screenshots targets '${owner.name}' and '${name}' write overlapping directories.`);
+    claimed.push({ name, dirs });
+    // An explicit --out is the caller's choice; configured directories are checked from the repository root.
+    const base = out === undefined ? root : absolute;
+    assertNoLinks(base, path.join(absolute, IMAGES));
+    assertNoLinks(base, path.join(absolute, MANIFEST));
+    return { name, target, dir, absolute, base };
+  });
+  // A capture linked into an output would be pruned or cleaned up with it.
+  const outputs = plans.flatMap(plan => [plan.absolute, resolved(plan.absolute)]);
+  const linked = linkedInto(source, outputs);
+  if (linked) throw new Error(`${path.relative(root, linked)} links into a screenshots output directory.`);
+  let staged: Staged[] = [];
+  try {
+    const before = readRecord(source);
+    const capture = checkCapture(root, source, before);
+    staged = plans.map(plan => stageTarget(root, source, plan.name, plan.target, plan.dir, plan.base, capture));
+    hooks.afterCopy?.();
+    if (readRecord(source) !== before) throw new Error("A screenshot capture started while copying; build again once it finishes.");
+    const targets = staged.map(item => {
+      const removed = ownedFiles(path.join(item.absolute, IMAGES)).filter(file => !item.keep.has(path.join(IMAGES, file)));
+      for (const file of removed) rmSync(path.join(item.absolute, IMAGES, file), { force: true });
+      removeEmptyDirectories(path.join(item.absolute, IMAGES), item.keep.size > 0);
+      if (!item.keep.size) rmSync(path.join(item.absolute, IMAGES), { force: true, recursive: true });
+      const manifestFile = path.join(item.absolute, MANIFEST);
+      const bytes = Buffer.from(`${JSON.stringify(item.manifest, null, 2)}\n`);
+      mkdirSync(item.absolute, { recursive: true });
+      if (sameBytes(manifestFile, bytes)) item.unchanged.push(path.join(item.dir, MANIFEST));
+      else { replaceFile(manifestFile, bytes); item.written.push(path.join(item.dir, MANIFEST)); }
+      return {
+        name: item.name, dir: item.dir, manifest: path.join(item.dir, MANIFEST), entries: item.manifest.entries.length,
+        projects: item.manifest.projects.map(project => project.name), written: item.written, unchanged: item.unchanged.length,
+        removed: removed.map(file => path.join(item.dir, IMAGES, file)),
+      };
+    });
+    return { source: config.source, capture, targets };
+  } catch (error) {
+    for (const plan of plans) if (existsSync(plan.absolute)) removeOutputs(plan.absolute);
+    throw error;
+  }
+}
+
+/** One line per target for people; `--json` prints the receipt instead. */
+export function describeScreenshots(receipt: ScreenshotsReceipt): string {
+  const lines: string[] = [];
+  if (receipt.capture) {
+    const partial = receipt.capture.partial.length ? ` (partial: ${receipt.capture.partial.join(" ")})` : "";
+    lines.push(`Screenshots from ${receipt.capture.commit.slice(0, 10)}, captured ${receipt.capture.finishedAt ?? "at an unrecorded time"}${partial}.`);
+  }
+  for (const target of receipt.targets) {
+    const counts = `${target.written.length} written, ${target.unchanged} unchanged, ${target.removed.length} removed`;
+    lines.push(target.entries
+      ? `${target.name}: staged ${target.entries} screenshot(s) across ${target.projects.join(", ")} into ${target.dir} (${counts}).`
+      : `${target.name}: no screenshots in ${receipt.source}; wrote an empty manifest to ${target.manifest} (${counts}).`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/screenshots/config.ts

@@ -0,0 +1,94 @@
+/** The data-only `screenshots` section of agent-tool.json: captured screens staged into a site. */
+
+export type Frame = "phone" | "tablet" | "none";
+export interface ScreenshotProject {
+  name: string;
+  label: string;
+  /** The capture directory under the source, when it differs from the name. */
+  dir: string;
+  frame: Frame | null;
+}
+export interface ScreenshotScreen { name: string; label: string; alt: string | null }
+export interface ScreenshotTarget {
+  dir: string | null;
+  urlPrefix: string;
+  projects: ScreenshotProject[];
+  themes: string[];
+  screens: ScreenshotScreen[];
+}
+export interface ScreenshotsConfig { source: string; targets: Record<string, ScreenshotTarget> }
+
+export const SCREENSHOTS_DEFAULTS: ScreenshotsConfig = { source: ".screenshots", targets: {} };
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const TARGET = /^[a-z][a-z0-9-]*$/;
+const FRAMES: Frame[] = ["phone", "tablet", "none"];
+
+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);
+  if (allowed) for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${setting} setting '${key}'.`);
+  return value as Json;
+}
+function text(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0 && !/[\r\n]/.test(value); }
+/** Repository-relative and inside it: no absolute paths, backslashes, or dot segments. */
+function relativePath(value: unknown): value is string {
+  return typeof value === "string" && !value.startsWith("/") && !value.includes("\\") && value.split("/").every(part => part && part !== "." && part !== "..");
+}
+export function titleCase(name: string): string {
+  return name.split("-").map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+function parseProjects(value: unknown, setting: string): ScreenshotProject[] {
+  const entries = Object.entries(object(value, setting));
+  if (!entries.length) fail(setting);
+  return entries.map(([name, entry]) => {
+    if (!NAME.test(name)) fail(`${setting}.${name}`);
+    if (text(entry)) return { name, label: entry, dir: name, frame: null };
+    const project = object(entry, `${setting}.${name}`, ["label", "dir", "frame"]);
+    if (project.label !== undefined && !text(project.label)) fail(`${setting}.${name}.label`);
+    if (project.dir !== undefined && (typeof project.dir !== "string" || !NAME.test(project.dir))) fail(`${setting}.${name}.dir`);
+    if (project.frame !== undefined && !FRAMES.includes(project.frame as Frame)) fail(`${setting}.${name}.frame`);
+    return { name, label: (project.label as string | undefined) ?? titleCase(name), dir: (project.dir as string | undefined) ?? name, frame: (project.frame as Frame | undefined) ?? null };
+  });
+}
+
+function parseScreens(value: unknown, setting: string): ScreenshotScreen[] {
+  if (!Array.isArray(value) || !value.length) fail(setting);
+  const screens = value.map((entry, index): ScreenshotScreen => {
+    if (typeof entry === "string") {
+      if (!NAME.test(entry)) fail(`${setting}[${index}]`);
+      return { name: entry, label: titleCase(entry), alt: null };
+    }
+    const screen = object(entry, `${setting}[${index}]`, ["name", "label", "alt"]);
+    if (typeof screen.name !== "string" || !NAME.test(screen.name)) fail(`${setting}[${index}].name`);
+    if (screen.label !== undefined && !text(screen.label)) fail(`${setting}[${index}].label`);
+    if (screen.alt !== undefined && !text(screen.alt)) fail(`${setting}[${index}].alt`);
+    return { name: screen.name, label: (screen.label as string | undefined) ?? titleCase(screen.name), alt: (screen.alt as string | undefined) ?? null };
+  });
+  const repeated = screens.find((screen, index) => screens.findIndex(other => other.name === screen.name) !== index);
+  if (repeated) throw new Error(`${setting} lists '${repeated.name}' more than once.`);
+  return screens;
+}
+
+export function parseScreenshots(value: unknown): ScreenshotsConfig {
+  const input = object(value, "screenshots", ["source", "targets"]);
+  if (input.source !== undefined && !relativePath(input.source)) fail("screenshots.source");
+  const result: ScreenshotsConfig = { source: (input.source as string | undefined) ?? SCREENSHOTS_DEFAULTS.source, targets: {} };
+  for (const [name, entry] of Object.entries(object(input.targets ?? {}, "screenshots.targets"))) {
+    const setting = `screenshots.targets.${name}`;
+    if (!TARGET.test(name)) fail(setting);
+    const target = object(entry, setting, ["dir", "urlPrefix", "projects", "themes", "screens"]);
+    if (target.dir !== undefined && !relativePath(target.dir)) fail(`${setting}.dir`);
+    // A URL path or absolute URL that image names are appended to; no characters that need escaping in HTML or CSS.
+    if (typeof target.urlPrefix !== "string" || !/^(?:\/|https:\/\/[^/\s]+\/)[^\s"'<>\\()]*$/.test(target.urlPrefix) || !target.urlPrefix.endsWith("/")) fail(`${setting}.urlPrefix`);
+    const projects = parseProjects(target.projects, `${setting}.projects`);
+    const dirs = projects.map(project => project.dir);
+    const shared = dirs.find((dir, index) => dirs.indexOf(dir) !== index);
+    if (shared) throw new Error(`${setting}.projects read capture directory '${shared}' more than once.`);
+    const themes = target.themes ?? ["light", "dark"];
+    if (!Array.isArray(themes) || !themes.length || themes.some(theme => typeof theme !== "string" || !NAME.test(theme)) || new Set(themes).size !== themes.length) fail(`${setting}.themes`);
+    result.targets[name] = { dir: (target.dir as string | undefined) ?? null, urlPrefix: target.urlPrefix, projects, themes: themes as string[], screens: parseScreens(target.screens, `${setting}.screens`) };
+  }
+  return result;
+}