@reqvire-org/ads 0.3.12 → 0.3.13

package/README.md

@@ -19,6 +19,25 @@ ADS supports **React and native Preact** with the same architecture guards and
 MCP preview flow. The empty starter uses React; this repository’s working example
 uses Preact. See [implementation support](docs/GUIDE.md#implementation-support).
 
+## What ADS does
+
+- **Inspect** components, patterns, controllers, tokens and their owning source
+  through focused MCP tools.
+- **Preview** real UI through MCP Apps and the local showcase, using the same
+  project-owned scenarios and fixtures.
+- **Edit with guards** using owner patches, coupled transactions and isolated
+  dry runs that validate architecture, lint and registered project checks.
+- **Compare visual changes** with on-demand screenshots of current source and
+  proposed candidates, exposed as MCP image resources.
+- **Verify behavior** through project-owned guarantees and registered tests,
+  with progress, timings and evidence tied to current source.
+- **Guide agents** with prompts and portable skills for building, importing,
+  migrating, motion and UI stress testing.
+
+See [using ADS through MCP](docs/GUIDE.md#use-ads-through-mcp) for the workflow and
+[visual captures](docs/MCP.md#screenshots-and-candidate-comparison) for screenshot
+setup and comparison.
+
 ## Set up your project
 
 Run **inside your project**, where `package.json` lives. Requires Node 22.12 or newer.
@@ -99,7 +118,7 @@ they keep source writes behind the same guards. See
 
 The server exposes public components/patterns, token values,
 source guides, controllers/hooks, architecture checks, behavioral verification,
-workflow prompts, and packaged ADS skills.
+on-demand screenshots, workflow prompts, and packaged ADS skills.
 It supports older MCP clients and the newer Skills protocol.
 
 Private controllers stay beside their component; shared controllers have their own

package/dist/capture/worker.mjs

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { openPreviewScenario } from "../verification/browser.mjs";
+
+// Runs only as an owned child, using the receiving project's browser dependency.
+const request = JSON.parse(readFileSync(process.argv[2], "utf8"));
+const playwright = createRequire(import.meta.url)(request.playwright);
+let browser;
+try {
+  browser = await playwright[request.settings.browser].launch({ headless: true, ...(request.settings.channel ? { channel: request.settings.channel } : {}) });
+  const images = [];
+  for (const [index, app] of request.apps.entries()) {
+    const context = await browser.newContext({ viewport: app.viewport, deviceScaleFactor: 1, colorScheme: app.theme });
+    try {
+      const page = await context.newPage(), timeout = request.settings.timeoutMs;
+      const frame = await openPreviewScenario(page, app.url, app.scenario, { timeout });
+      await frame.locator("html").waitFor({ state: "visible", timeout });
+      await frame.waitForFunction(theme => document.documentElement.dataset.theme === theme, app.theme, { timeout });
+      await frame.evaluate(async () => {
+        await document.fonts.ready;
+        await Promise.all([...document.images].map(image => image.decode().catch(() => {})));
+        await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+      });
+      const actualViewport = await frame.evaluate(() => ({ width: innerWidth, height: innerHeight }));
+      if (actualViewport.width !== app.viewport.width || actualViewport.height !== app.viewport.height) throw new Error(`App viewport differs from requested capture settings: ${JSON.stringify(actualViewport)}`);
+      const target = frame.locator(app.selector);
+      if (await target.count() !== 1) throw new Error(`Capture target ${app.target ?? "widget"} must resolve to exactly one element.`);
+      await target.waitFor({ state: "visible", timeout });
+      const bounds = await target.boundingBox();
+      if (!bounds || bounds.width * bounds.height > 8 * 1024 * 1024) throw new Error("Capture target is empty or exceeds 8 megapixels.");
+      await target.screenshot({ path: path.join(request.output, `${index}.png`), type: "png", animations: app.animations, caret: "hide", scale: "css", timeout });
+      if (await frame.locator("html").getAttribute("data-ads-preview-state") !== "ready") throw new Error("The App stopped being ready during capture.");
+      images.push({ index, scenario: app.scenario, actualViewport, capturedAt: new Date().toISOString() });
+    } finally { await context.close(); }
+  }
+  writeFileSync(path.join(request.output, "report.json"), JSON.stringify({ schemaVersion: 1, runId: request.runId, images }));
+} finally { await browser?.close(); }

package/dist/capture-store.mjs

@@ -0,0 +1,123 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+
+export const CAPTURES_URI = "ads://project/captures";
+export const captureLimits = { selections: 8, imageBytes: 4 * 1024 * 1024, pixels: 8 * 1024 * 1024, storeBytes: 256 * 1024 * 1024, pairBytes: 12 * 1024 * 1024 };
+export const captureSpec = z.object({
+  scenario: z.string().min(1).max(256), target: z.string().regex(/^[a-zA-Z0-9][\w.-]{0,79}$/).optional(),
+  theme: z.enum(["light", "dark"]).default("light"),
+  viewport: z.object({ width: z.number().int().min(100).max(4096), height: z.number().int().min(100).max(4096) }).strict().default({ width: 1280, height: 800 }),
+  animations: z.enum(["disabled", "allow"]).default("disabled"),
+}).strict().refine(value => value.viewport.width * value.viewport.height <= captureLimits.pixels, "Capture viewport exceeds 8 megapixels.");
+export const screenshotFields = { screenshot: z.boolean().optional(), captures: z.array(captureSpec).min(1).max(captureLimits.selections).optional() };
+export const captureKey = ({ scenario, target }) => createHash("sha256").update(JSON.stringify([scenario, target ?? null])).digest("hex");
+export const captureUri = (key, slot) => `ads://captures/${key}/${slot}`;
+const missing = message => Object.assign(new Error(message), { code: "ADS_CAPTURE_NOT_FOUND" });
+const validTarget = (record, scenarios, revision) => scenarios.some(scenario => scenario.id === record.scenario && (!record.target || Object.hasOwn(scenario.captureTargets ?? {}, record.target))) || record.proposedTarget === true && record.candidate?.baseRevision === revision;
+const summary = image => { if (!image) return null; const { blob: _blob, ...metadata } = image; return metadata; };
+
+/** Two slots in one atomically replaced file: no revision-addressed image history. */
+export function createCaptureStore(root) {
+  root = path.resolve(root);
+  const directory = path.join(root, ".ds/captures"), cache = new Map();
+  function safeDirectory(create = false) {
+    for (const file of [path.join(root, ".ds"), directory]) {
+      if (!existsSync(file)) { if (!create) return false; mkdirSync(file); }
+      if (!lstatSync(file).isDirectory() || realpathSync(file) !== file) throw new Error("Capture storage must use ordinary project .ds/captures directories.");
+    }
+    return true;
+  }
+  function files() { return safeDirectory() ? readdirSync(directory).filter(file => /^[a-f0-9]{64}\.json$/.test(file)).sort() : []; }
+  function read(key) {
+    if (!safeDirectory()) return null;
+    const file = path.join(directory, `${key}.json`);
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) return null;
+    if (!stat.isFile() || stat.nlink !== 1 || realpathSync(file) !== file || stat.size > captureLimits.pairBytes) throw new Error("Invalid or oversized capture pair file.");
+    const signature = `${stat.ino}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`;
+    if (cache.get(key)?.signature === signature) return cache.get(key).value;
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (value.schemaVersion !== 1 || value.key !== key || captureKey(value) !== key || !value.current && !value.candidate || [value.current, value.candidate].filter(Boolean).some(image => typeof image.blob !== "string" || image.blob.length > Math.ceil(captureLimits.imageBytes / 3) * 4 || image.mimeType !== "image/png")) throw new Error("Invalid capture pair schema.");
+    cache.set(key, { signature, value });
+    return value;
+  }
+  function remove(key) { rmSync(path.join(directory, `${key}.json`), { force: true }); cache.delete(key); }
+  function commit(records) {
+    safeDirectory(true);
+    const lock = path.join(directory, ".publish-lock");
+    function acquire() { writeFileSync(lock, JSON.stringify({ pid: process.pid }), { flag: "wx" }); }
+    try { acquire(); }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const stat = lstatSync(lock);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024) throw new Error("Invalid capture publication lock.");
+      const owner = JSON.parse(readFileSync(lock, "utf8"));
+      if (!Number.isSafeInteger(owner.pid) || owner.pid <= 1) throw new Error("Invalid capture publication owner.");
+      let alive = true;
+      try { process.kill(owner.pid, 0); } catch (error) { if (error.code === "ESRCH") alive = false; }
+      if (alive) throw new Error("Another capture publication is in progress; retry after it finishes.");
+      rmSync(lock); acquire();
+    }
+    const staged = [], written = [];
+    try {
+      let total = files().reduce((sum, file) => sum + lstatSync(path.join(directory, file)).size, 0);
+      for (const record of records) {
+        if (record.key !== captureKey(record)) throw new Error("Capture key does not match its scenario/target.");
+        const file = path.join(directory, `${record.key}.json`), content = JSON.stringify(record), bytes = Buffer.byteLength(content);
+        if (bytes > captureLimits.pairBytes) throw new Error("Capture pair exceeds 12 MiB.");
+        const old = read(record.key), previous = old ? readFileSync(file) : null;
+        total += bytes - (previous?.length ?? 0);
+        if (total > captureLimits.storeBytes) throw new Error("Capture storage exceeds 256 MiB. Clear unneeded targets with ads_capture_clear before capturing again.");
+        const temporary = path.join(directory, `.capture-${randomUUID()}`);
+        writeFileSync(temporary, content);
+        staged.push({ file, temporary, previous, key: record.key });
+      }
+      for (const entry of staged) { renameSync(entry.temporary, entry.file); cache.delete(entry.key); written.push(entry); }
+    } catch (error) {
+      for (const entry of written.reverse()) { if (entry.previous) writeFileSync(entry.file, entry.previous); else rmSync(entry.file, { force: true }); cache.delete(entry.key); }
+      throw error;
+    } finally { for (const entry of staged) rmSync(entry.temporary, { force: true }); rmSync(lock, { force: true }); }
+  }
+  return {
+    commit,
+    resourceUris: () => files().flatMap(file => { try { const record = read(file.slice(0, -5)); return ["current", "candidate"].filter(slot => record[slot]).map(slot => captureUri(record.key, slot)); } catch { return []; } }),
+    fingerprint: () => files().map(file => { const stat = lstatSync(path.join(directory, file)); return `${file}:${stat.mtimeMs}:${stat.size}`; }).join("\n"),
+    list(scenarios, revision, { prune = true } = {}) {
+      const captures = [], diagnostics = [];
+      for (const file of files()) {
+        const key = file.slice(0, -5);
+        try {
+          const record = read(key);
+          if (!validTarget(record, scenarios, revision) && prune) { remove(key); continue; }
+          captures.push({ key, scenario: record.scenario, ...(record.target ? { target: record.target } : {}), current: record.current ? { ...summary(record.current), resourceUri: captureUri(key, "current"), stale: record.current.sourceRevision !== revision } : null, ...(!record.current ? { currentAbsent: "This scenario/target is new in the candidate; no baseline image exists." } : {}), candidate: record.candidate ? { ...summary(record.candidate), resourceUri: captureUri(key, "candidate"), stale: record.candidate.baseRevision !== revision } : null });
+        } catch (error) { diagnostics.push({ key, message: error.message }); }
+      }
+      return { captures, diagnostics, limits: captureLimits };
+    },
+    readResource(uri, scenarios, revision, { allowUnknownTargets = false } = {}) {
+      const match = /^ads:\/\/captures\/([a-f0-9]{64})\/(current|candidate)$/.exec(uri);
+      if (!match) throw missing("Unknown screenshot URI. Discover captures through ads://project/captures.");
+      const record = read(match[1]), slot = match[2];
+      if (!record || !allowUnknownTargets && !validTarget(record, scenarios, revision) || !record[slot]) throw missing("This capture slot is absent or was replaced/cleared. Request a new capture with ads_capture or a screenshot-enabled dry run.");
+      return { uri, mimeType: "image/png", blob: record[slot].blob, _meta: { ...summary(record[slot]), stale: (slot === "candidate" ? record[slot].baseRevision : record[slot].sourceRevision) !== revision } };
+    },
+    clear({ scenario, target, candidateOnly = false }) {
+      const key = captureKey({ scenario, target }), record = read(key);
+      if (!record) return { cleared: false };
+      if (candidateOnly && record.current) { commit([{ ...record, candidate: null }]); return { cleared: true, key, slots: ["candidate"] }; }
+      remove(key); return { cleared: true, key, slots: ["current", "candidate"] };
+    },
+    promote(revision, scenarios) {
+      const records = [];
+      for (const file of files()) {
+        const record = read(file.slice(0, -5));
+        if (!validTarget(record, scenarios, revision)) { remove(record.key); continue; }
+        if (record.candidate?.sourceRevision === revision) records.push({ ...record, proposedTarget: undefined, current: { ...record.candidate, baseRevision: undefined, proposal: undefined }, candidate: null });
+      }
+      if (records.length) commit(records);
+      return records.map(record => record.key);
+    },
+  };
+}

package/dist/capture.mjs

@@ -0,0 +1,117 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import sharp from "sharp";
+import { loadConfig } from "./config.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+import { previewSourceRevision } from "./preview-inputs.mjs";
+import { executeDevelopmentCommand } from "./verification.mjs";
+import { captureKey, captureSpec, captureLimits, createCaptureStore } from "./capture-store.mjs";
+
+export function captureSelections(values) {
+  if (!Array.isArray(values) || !values.length || values.length > captureLimits.selections) throw new Error("Select 1–8 exact scenarios/targets with captures:[{scenario,target?,theme?,viewport?}]. Discover IDs with ads_scenarios.");
+  const selections = values.map(value => captureSpec.parse(value));
+  if (new Set(selections.map(captureKey)).size !== selections.length) throw new Error("Select each scenario/target once; settings replace that target's slots rather than creating extra history.");
+  return selections;
+}
+
+export function createCaptureController(root) {
+  root = path.resolve(root);
+  const store = createCaptureStore(root);
+  let active, progress;
+  return {
+    store,
+    status: () => ({ running: !!active, ...(progress ? { progress: { ...progress, elapsedMs: Date.now() - progress.startedAt } } : {}) }),
+    async close() { active?.abort(); await active?.completion; },
+    async run({ captures, candidateRoot, proposal, publish = true } = {}, signal, notifyProgress) {
+      if (active) throw new Error("A screenshot capture is already running. Wait for ads_status.captures.running to clear.");
+      const selections = captureSelections(captures);
+      const controller = new AbortController(); active = controller;
+      signal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+      let finish; controller.completion = new Promise(resolve => { finish = resolve; });
+      const hosts = [];
+      let temporary;
+      const startedAt = Date.now();
+      const update = (stage = progress?.stage ?? "preparing", completed = progress?.completed ?? 0, total = progress?.total ?? selections.length * (candidateRoot ? 2 : 1)) => {
+        progress = { profile: "screenshots", stage, startedAt, elapsedMs: Date.now() - startedAt, completed, total, active: [], message: `Screenshots: ${stage}; ${completed}/${total} images complete; ${Date.now() - startedAt} ms elapsed.` };
+        notifyProgress?.(progress);
+      };
+      const heartbeat = setInterval(update, 5000); heartbeat.unref();
+      try {
+        update();
+        const options = loadConfig(root), require = createRequire(path.join(root, "package.json"));
+        let playwright;
+        for (const name of ["@playwright/test", "playwright"]) { try { playwright = require.resolve(name); break; } catch { /* Try the other supported project-installed entry. */ } }
+        if (!playwright) throw new Error("Screenshots require project-local @playwright/test or playwright and its installed browser. ADS installs neither. Install/configure these in the connected project, then retry; mcp.capture selects browser/channel/timeoutMs.");
+        const projects = [root, ...(candidateRoot ? [path.resolve(candidateRoot)] : [])].map(directory => {
+          const options = loadConfig(directory), registry = inspectScenarios(options);
+          if (registry.diagnostics.length) throw new Error(`Scenario registration failed: ${registry.diagnostics[0].message}`);
+          const apps = selections.map((selection, selectionIndex) => {
+            const scenario = registry.scenarios.find(scenario => scenario.id === selection.scenario);
+            if ((!scenario || selection.target && !Object.hasOwn(scenario.captureTargets ?? {}, selection.target)) && directory === root && candidateRoot) return null;
+            if (!scenario) throw new Error(`Unknown scenario ${selection.scenario}. Discover exact IDs with ads_scenarios.`);
+            if (selection.target && !Object.hasOwn(scenario.captureTargets ?? {}, selection.target)) throw new Error(`Unknown capture target ${selection.target} in ${selection.scenario}. Discover captureTargets with ads_scenarios; omit target for the full widget viewport.`);
+            return { ...selection, selectionIndex, selector: selection.target ? scenario.captureTargets[selection.target] : "html", scenarioFile: scenario.file, fixtureFile: scenario.fixture };
+          }).filter(Boolean);
+          return { options, revision: previewSourceRevision(options), apps };
+        });
+        const outputRoot = path.join(root, ".ds");
+        mkdirSync(outputRoot, { recursive: true });
+        if (realpathSync(outputRoot) !== outputRoot) throw new Error("Capture work output cannot resolve through a symlink.");
+        for (const entry of readdirSync(outputRoot)) if (/^capture-work-[a-zA-Z0-9]+$/.test(entry)) {
+          const work = path.join(outputRoot, entry), ownerFile = path.join(work, "owner.json");
+          try {
+            if (!lstatSync(work).isDirectory() || realpathSync(work) !== work || realpathSync(ownerFile) !== ownerFile || lstatSync(ownerFile).size > 1024) continue;
+            const { pid } = JSON.parse(readFileSync(ownerFile, "utf8"));
+            if (!Number.isSafeInteger(pid) || pid <= 1) continue;
+            try { process.kill(pid, 0); } catch (error) { if (error.code === "ESRCH") rmSync(work, { recursive: true, force: true }); }
+          } catch { /* Unknown or still-active work directories are not ours to remove. */ }
+        }
+        temporary = mkdtempSync(path.join(outputRoot, "capture-work-"));
+        writeFileSync(path.join(temporary, "owner.json"), JSON.stringify({ pid: process.pid }));
+        const apps = [];
+        const { startAdsMcp } = await import("./mcp/server.mjs");
+        for (const [projectIndex, project] of projects.entries()) {
+          if (signal.aborted) throw new Error("Screenshot capture cancelled.");
+          if (!project.apps.length) { hosts.push(null); continue; }
+          const host = await startAdsMcp(project.options.root, { stdio: false, showcase: true });
+          hosts.push(host);
+          for (const selection of project.apps) {
+            const url = new URL(host.url); url.searchParams.set("scenario", selection.scenario); url.searchParams.set("capture", "1"); url.searchParams.set("theme", selection.theme);
+            apps.push({ ...selection, projectIndex, url: url.href });
+          }
+        }
+        const request = path.join(temporary, "request.json"), report = path.join(temporary, "report.json"), runId = randomUUID();
+        const settings = { browser: "chromium", timeoutMs: 60000, ...options.config.mcp.capture };
+        writeFileSync(request, JSON.stringify({ schemaVersion: 1, runId, playwright, settings, apps, output: temporary }));
+        update("rendering", 0, apps.length);
+        const run = await executeDevelopmentCommand({ command: "node", timeoutMs: settings.timeoutMs, label: "Screenshot capture" }, [fileURLToPath(new URL("./capture/worker.mjs", import.meta.url)), request], root, {}, signal);
+        if (run.code !== 0) throw new Error(`Screenshot browser failed (${run.code}): ${run.output.slice(-3000)}`);
+        if (!existsSync(report) || realpathSync(report) !== report || lstatSync(report).size > 128 * 1024) throw new Error("Screenshot runner produced no bounded report.");
+        const value = JSON.parse(readFileSync(report, "utf8"));
+        if (value.schemaVersion !== 1 || value.runId !== runId || !Array.isArray(value.images) || value.images.length !== apps.length) throw new Error("Screenshot runner returned the wrong run identity or image count.");
+        const images = new Map();
+        for (const [index, app] of apps.entries()) {
+          const file = path.join(temporary, `${index}.png`), stat = lstatSync(file);
+          if (!stat.isFile() || stat.nlink !== 1 || realpathSync(file) !== file || stat.size > captureLimits.imageBytes) throw new Error("Screenshot output must be an ordinary PNG no larger than 4 MiB.");
+          const bytes = readFileSync(file), metadata = await sharp(bytes).metadata();
+          if (metadata.format !== "png" || !metadata.width || !metadata.height || metadata.width * metadata.height > captureLimits.pixels) throw new Error("Screenshot output exceeds 8 megapixels or is not PNG.");
+          const project = projects[app.projectIndex];
+          images.set(`${app.projectIndex}:${app.selectionIndex}`, { mimeType: "image/png", blob: bytes.toString("base64"), digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`, width: metadata.width, height: metadata.height, bytes: bytes.length, capturedAt: value.images[index].capturedAt, sourceRevision: project.revision, buildRevision: hosts[app.projectIndex].previewRevision(), settings: { theme: app.theme, viewport: app.viewport, animations: app.animations, browser: settings.browser, ...(settings.channel ? { channel: settings.channel } : {}), scale: "css" }, scenarioFile: app.scenarioFile, fixtureFile: app.fixtureFile });
+        }
+        for (const project of projects) if (previewSourceRevision(loadConfig(project.options.root)) !== project.revision) throw new Error("Project inputs changed while capturing. No capture slots were replaced; retry against current source.");
+        if (signal.aborted) throw new Error("Screenshot capture cancelled before publication.");
+        update("publishing", apps.length, apps.length);
+        const records = selections.map((selection, index) => ({ schemaVersion: 1, key: captureKey(selection), scenario: selection.scenario, ...(selection.target ? { target: selection.target } : {}), current: images.get(`0:${index}`) ?? null, ...(!images.has(`0:${index}`) ? { proposedTarget: true } : {}), candidate: candidateRoot ? { ...images.get(`1:${index}`), baseRevision: projects[0].revision, proposal } : null }));
+        if (!publish) return { records, baseRevision: projects[0].revision };
+        store.commit(records);
+        return { ok: true, captures: store.list(inspectScenarios(loadConfig(root)).scenarios, projects[0].revision).captures.filter(record => selections.some(selection => captureKey(selection) === record.key)) };
+      } finally {
+        try { await Promise.all(hosts.map(host => host?.close())); }
+        finally { clearInterval(heartbeat); try { if (temporary) rmSync(temporary, { recursive: true, force: true }); } finally { active = undefined; progress = undefined; finish(); } }
+      }
+    },
+  };
+}

package/dist/config.mjs

@@ -17,7 +17,7 @@ export const defaultConfig = {
   boundaries: { styleWrites: [], componentVariables: [] },
   assets: { publicDirs: ["public/assets"], generatedPaths: ["dist", "dist-showcase", ".vite", ".ds"], generatedFiles: [], iconSource: null },
   oxlint: { plugins: [], rules: {}, overrides: [] },
-  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null, behaviorProfiles: {} },
+  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null, behaviorProfiles: {}, capture: {} },
 };
 
 export function isInside(parent, file) {
@@ -100,6 +100,11 @@ export function loadConfig(directory = process.cwd()) {
   }
   if (config.mcp.showcaseTitle !== null && (typeof config.mcp.showcaseTitle !== "string" || !config.mcp.showcaseTitle.trim() || config.mcp.showcaseTitle.length > 120)) throw new Error("mcp.showcaseTitle must be a non-empty title of at most 120 characters or null.");
   if (!Array.isArray(config.mcp.apps)) throw new Error("mcp.apps must be an array of built project previews.");
+  const capture = config.mcp.capture;
+  if (!capture || typeof capture !== "object" || Array.isArray(capture) || Object.keys(capture).some(key => !["browser", "channel", "timeoutMs"].includes(key))
+    || !["chromium", "firefox", "webkit"].includes(capture.browser ?? "chromium")
+    || capture.channel !== undefined && (typeof capture.channel !== "string" || !/^[\w-]{1,60}$/.test(capture.channel) || ![undefined, "chromium"].includes(capture.browser))
+    || capture.timeoutMs !== undefined && (!Number.isInteger(capture.timeoutMs) || capture.timeoutMs < 100 || capture.timeoutMs > 300000)) throw new Error("mcp.capture accepts browser (chromium/firefox/webkit), an optional Chromium channel, and timeoutMs (100–300000). Install Playwright and its browser in the project; ADS installs nothing.");
   if (!config.mcp.behaviorProfiles || typeof config.mcp.behaviorProfiles !== "object" || Array.isArray(config.mcp.behaviorProfiles) || Object.keys(config.mcp.behaviorProfiles).length > 20) throw new Error("mcp.behaviorProfiles must be an object of up to 20 registered execution profiles.");
   for (const [name, profile] of Object.entries(config.mcp.behaviorProfiles)) {
     if (!/^[a-zA-Z0-9][\w.-]{0,79}$/.test(name) || !profile || typeof profile !== "object" || Array.isArray(profile)

package/dist/mcp/context.mjs

@@ -5,7 +5,7 @@ import { projectGuideFiles } from "../project-documents.mjs";
 
 export const GUIDE_URI = "ads://project/guide";
 // Put the task triggers and entry path first: some hosts shorten server guidance.
-export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
+export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For requested visual evidence, use ads_capture or screenshot-enabled patch dry runs; read ads://guides/captures for named targets, image resources and the current/candidate lifecycle. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
 
 function manager(root, pkg) {
   if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];

package/dist/mcp/mutations.mjs

@@ -11,6 +11,9 @@ import { generateLintConfig } from "../lint-config.mjs";
 import { generateBrandAssets } from "../brand-assets.mjs";
 import { projectContext } from "./context.mjs";
 import { applyFilePatch, parseUnifiedPatch } from "./patch.mjs";
+import { createCaptureController, captureSelections } from "../capture.mjs";
+import { previewSourceRevision } from "../preview-inputs.mjs";
+import { inspectScenarios } from "../scenarios.mjs";
 import { checkUnitCandidate, checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
 
 export const mutationLimits = { units: 8, files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
@@ -143,10 +146,11 @@ function checks(options) {
   return scripts.map(script => ({ command: context.packageManager, args: ["run", script] }));
 }
 
-export function createMutationController(directory) {
+export function createMutationController(directory, { captures = createCaptureController(directory) } = {}) {
   const root = path.resolve(directory);
   let busy = false;
   let lastResult = null;
+  let progress;
   let active;
   return {
     status() {
@@ -154,7 +158,7 @@ export function createMutationController(directory) {
       let commands = [], diagnostics = [];
       try { commands = checks(options).map(check => [check.command, ...check.args].join(" ")); }
       catch (error) { diagnostics = [error.diagnostic ?? { rule: "mutation-check", message: error.message }]; }
-      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", transactions:{tool:"ads_apply_transaction",maxUnits:mutationLimits.units,finalCandidateChecks:true}, preparation:{owner:"ads_prepare_patch",tokenSamples:"ads_prepare_token_samples"}, dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, lastResult };
+      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", transactions:{tool:"ads_apply_transaction",maxUnits:mutationLimits.units,finalCandidateChecks:true}, preparation:{owner:"ads_prepare_patch",tokenSamples:"ads_prepare_token_samples"}, dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, ...(progress ? { progress } : {}), lastResult };
     },
     cancel() { active?.abort(); },
     units() { return inspectUnits(loadConfig(root)).units; },
@@ -170,7 +174,7 @@ export function createMutationController(directory) {
       return { ...source, unit, content, offset, nextOffset: end < source.content.length ? end : null, totalChars: source.content.length,
         startLine: source.content.slice(0, offset).split("\n").length };
     },
-    async apply({ unit, patch, patchFile, patches, dryRun = false }, signal) {
+    async apply({ unit, patch, patchFile, patches, dryRun = false, screenshot = false, captures: selections }, signal, notifyProgress) {
       if (busy) return { ok: false, applied: false, diagnostics: [{ rule: "mutation-busy", message: "Another mutation is validating; retry after it finishes." }] };
       busy = true;
       active = new AbortController();
@@ -179,6 +183,8 @@ export function createMutationController(directory) {
       const verified = [];
       try {
         const options = loadConfig(root);
+        if (screenshot && !dryRun || selections !== undefined && !screenshot) throw fail("mutation-capture", "Use screenshot:true only with dryRun:true and an explicit captures:[{scenario,target?,theme?,viewport?}] selection. Ordinary patches create no screenshots.");
+        if (screenshot) selections = captureSelections(selections);
         if (patches !== undefined && (unit !== undefined || patch !== undefined || patchFile !== undefined || !Array.isArray(patches) || patches.length < 2 || patches.length > mutationLimits.units)) throw fail("mutation-batch", "A transaction requires 2–8 distinct owner patches, without a top-level unit/patch.");
         const groups = patches ?? [{unit,patch,patchFile}];
         if (new Set(groups.map(group => group.unit)).size !== groups.length) throw fail("mutation-batch", "Use one patch per distinct unit in a transaction.");
@@ -279,17 +285,29 @@ export function createMutationController(directory) {
         for (const check of extraChecks) verified.push(await checkCommand(check.command, check.args, candidate, signal));
         const behaviorUnits = affectedBehaviorUnits(candidateOptions, changes.map(change => change.path));
         if (behaviorUnits.length) {
-          const verification = createVerificationController(candidate);
+          const verification = createVerificationController(candidate, { reportRoot: root, onProgress: value => { progress = { stage: "behavior", ...value }; notifyProgress?.(progress); } });
           let evidence;
           try { evidence = await verification.run({ units: behaviorUnits, persist: false }, signal); }
           finally { await verification.close(); }
           if (!evidence.ok) return lastResult = { ok: false, applied: false, diagnostics: [...evidence.diagnostics, ...evidence.results.filter(item => item.status !== "passed").map(item => ({ rule: "behavior-check", message: `${item.unit}#${item.check}: ${item.status}. ${item.message}` }))].slice(0, 50), checks: verified, behavior: evidence };
           verified.push({ name: "registered behavior checks", passed: true, results: evidence.results });
         }
+        let screenshots;
+        if (screenshot) {
+          progress = { stage: "capture", total: selections.length, completed: 0, active: [], profile: "screenshots", elapsedMs: 0 };
+          notifyProgress?.(progress);
+          const proposal = digest(Buffer.from(JSON.stringify(changes.map(change => [change.path, change.content === null ? null : digest(Buffer.from(change.content))]))));
+          screenshots = await captures.run({ captures: selections, candidateRoot: candidate, proposal, publish: false }, signal, value => { progress = value; notifyProgress?.(value); });
+        }
         if (signal?.aborted) throw fail("mutation-cancelled", "Mutation cancelled before application.");
         if (snapshot(candidateOptions) !== expected) throw fail("mutation-check", "A validation command changed source files. Use checks without source-writing side effects.");
         if (snapshot(loadConfig(root)) !== before) throw fail("mutation-conflict", "Project inputs changed during validation; no changes were applied. Read current source and retry.");
         for (const change of changes) address(options, change.path);
+        if (screenshots) {
+          captures.store.commit(screenshots.records);
+          const selected = new Set(screenshots.records.map(record => record.key));
+          screenshots = { ok: true, captures: captures.store.list(inspectScenarios(loadConfig(root)).scenarios, screenshots.baseRevision).captures.filter(record => selected.has(record.key)) };
+        }
         if (!dryRun) {
           const written = [];
           const directories = [];
@@ -317,11 +335,13 @@ export function createMutationController(directory) {
         }
         const warnings = [];
         if (!dryRun && (assets || configuration)) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
+        if (!dryRun && captures.store.fingerprint()) { try { captures.store.promote(previewSourceRevision(loadConfig(root)), inspectScenarios(loadConfig(root)).scenarios); } catch (error) { warnings.push({ rule: "mutation-capture", message: `Source was applied; capture promotion needs recovery: ${error.message}` }); } }
         return lastResult = { ok: true, ...(patches ? {units,transaction:true} : {unit}), applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
+          ...(screenshots ? { screenshots } : {}),
           preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." };
       } catch (error) {
         return lastResult = { ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message }], checks: verified };
-      } finally { try { if (temporary) rmSync(temporary, { recursive: true, force: true }); } finally { busy = false; active = undefined; } }
+      } finally { try { if (temporary) rmSync(temporary, { recursive: true, force: true }); } finally { busy = false; active = undefined; progress = undefined; } }
     },
   };
 }