@reqvire-org/ads 0.3.12 → 0.3.13

package/dist/skills/ads-motion/references/guarded-editing.md

@@ -6,6 +6,64 @@ tools, request `action:"diff"`, then apply the returned patchFile. Discard the
 draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
 preparation nor diff generation validates or changes live source.
 
+To verify a draft before applying it, diff it and dry-run the returned patch:
+
+```js
+ads_prepare_patch({"unit":"components/Example","action":"diff","draft":"<returned draft ID>"})
+ads_apply_patch({"unit":"components/Example","patchFile":"<returned patchFile>","dryRun":true})
+```
+
+The dry run validates the full candidate, including affected registered behavior
+checks in an isolated project copy. Configured browser checks use that candidate's
+managed preview, not the live showcase. Inspect the returned `behavior` failures
+or the registered behavior-check results in `checks`, fix the draft and diff again.
+Keep behavior.json/specs with their owner and use registered checks; a scratchpad
+run against live source cannot verify unapplied changes. After validation, apply
+with `dryRun:false`; ADS revalidates before writing. Dry-run evidence is not saved
+as passing evidence for the live project.
+
+`ads_verify({unit,checks?})` selects checks for current project source; it has no
+draft argument. There is no dedicated selected-check runner for drafts yet.
+Use a dry-run transaction for genuinely coupled draft patches.
+
+Behavior-run performance belongs to both orchestration and project checks. ADS
+selects affected owners, filters registered Playwright case tags and shares one
+candidate host per run. The project owns assertions, browser setup, worker count,
+per-test timeouts and its profile's whole-run `timeoutMs`. The latter covers the
+entire runner process, not each test. Do not rewrite APIs, drop guarantees or
+disable checks to fit the budget. Inspect measured durations before tuning it.
+
+During verification, inspect `ads_status.behaviors.progress`; during candidate
+validation, inspect `ads_status.mutations.progress`. These show completed/active/
+pending checks and timings. MCP clients requesting progress also receive updates.
+A timeout retains reported case outcomes and identifies active/unstarted checks;
+it still blocks the mutation. `reportedStatus:"passed"` within an incomplete run
+is diagnostic information, not a passing guarantee. Reports/artifacts under the
+live project's `.ds/verification/` survive candidate cleanup. Uninstrumented custom
+runners may report an unknown execution state instead of claiming a case started.
+
+For independent browser specs, consider a small parallel worker count and measure
+on the target machine. Use separate contexts/pages, independent state and the
+candidate URLs provided by `openBehaviorScenario`; avoid fixed live-server URLs,
+shared mutable fixtures and test-order assumptions. Files can run in parallel;
+tests in one file remain sequential by default. Prefer readiness assertions over
+blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actual
+gesture/motion/layout guarantees. Project settings belong in guarded configuration
+changes; ADS does not silently raise budgets or override the worker count.
+
+Named barrel imports can narrow affected checks when the project accurately
+declares package `sideEffects`; retain CSS/global effects in that policy. Missing
+or unsupported policies and dynamic/wildcard dependencies stay conservative.
+Do not change the policy merely to suppress verification of real side effects.
+
+For registered measured-geometry style writes, use direct `element.style.transform =
+value` or `element.style.setProperty("--ds-measured-value", value)` with the exact
+file/property boundary. The current guard rejects a style-object alias such as
+`const style = element.style` as an escape; it does not trace the alias to later
+writes. Keep writes explicit when adapting local controller code. This syntax
+constraint is separate from deciding which measured properties belong to the
+controller; it does not authorize unregistered visual writes.
+
 Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
 from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
 README links together. Conventional root credits/license/notice names support

package/dist/skills/ads-motion/references/scenarios.md

@@ -18,6 +18,11 @@ recovers missed atomic replacements. Do not touch source to force freshness;
 inspect build diagnostics. Upgrade the project's compiler dependency together
 with MCP when an older reporter lacks source evidence.
 
+Optional static `captureTargets` names CSS selectors within the scenario's App for
+on-demand element screenshots. It grants no render/behavior coverage and no extra
+styling permission. Use [captures.md](captures.md) for current/candidate review,
+target selection, resource reads and storage lifecycle.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/verification/browser.mjs

@@ -11,6 +11,11 @@ export async function openBehaviorScenario(page, checkId, { timeout = 30000 } =
   const check = request.checks.find(check => check.id === checkId);
   const url = check && request.scenarios[check.scenario];
   if (!url) throw new Error("This check has no managed browser scenario. StrictMode profiles must supply a project development harness; production preview bundles do not replay React development effects.");
+  return openPreviewScenario(page, url, check.scenario, { timeout });
+}
+
+/** Shared readiness for registered verification and on-demand captures. */
+export async function openPreviewScenario(page, url, scenario, { timeout = 30000 } = {}) {
   const failures = [];
   const failed = request => {
     if (failures.length < 5) failures.push(`${request.method()} ${request.url().slice(0, 300)}: ${request.failure()?.errorText ?? "request failed"}`);
@@ -22,8 +27,8 @@ export async function openBehaviorScenario(page, checkId, { timeout = 30000 } =
     while (Date.now() < end) {
       for (const frame of page.frames().filter(frame => frame !== page.mainFrame())) {
         const state = await frame.evaluate(() => ({ state: document.documentElement.dataset.adsPreviewState, id: document.documentElement.dataset.adsScenario, message: document.getElementById("ads-preview-status")?.textContent })).catch(() => ({}));
-        if (state.id === check.scenario && state.state === "ready") return frame;
-        if (state.id === check.scenario && state.state === "error") throw new Error(state.message || "The MCP App failed before verification.");
+        if (state.id === scenario && state.state === "ready") return frame;
+        if (state.id === scenario && state.state === "error") throw new Error(state.message || "The MCP App failed before verification.");
       }
       const error = await page.evaluate(() => document.querySelector('#status[data-error="true"]')?.textContent).catch(() => null);
       if (error) throw new Error(error);
@@ -31,6 +36,6 @@ export async function openBehaviorScenario(page, checkId, { timeout = 30000 } =
     }
     throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
   } catch (error) {
-    throw new Error(`Scenario ${check.scenario}: ${error.message}${failures.length ? `\nFailed browser requests:\n${failures.join("\n")}` : ""}`, { cause: error });
+    throw new Error(`Scenario ${scenario}: ${error.message}${failures.length ? `\nFailed browser requests:\n${failures.join("\n")}` : ""}`, { cause: error });
   } finally { page.off("requestfailed", failed); }
 }

package/dist/verification/playwright-reporter.cjs

@@ -1,4 +1,4 @@
-const { readFileSync, writeFileSync } = require("node:fs");
+const { readFileSync, writeFileSync, renameSync, rmSync } = require("node:fs");
 const path = require("node:path");
 
 /** Case identity is an explicit project test tag: @ads:<case-id>. */
@@ -7,18 +7,33 @@ module.exports = class AdsBehaviorReporter {
     this.request = JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
     this.cases = [];
     this.errors = [];
+    this.active = new Map();
+    this.startedAt = Date.now();
+    this.totalTests = 0;
   }
-  onTestEnd(test, result) {
+  onBegin(config, suite) { this.workers = config.workers; this.totalTests = suite.allTests().length; this.publish(); }
+  entries(test) {
     const file = path.relative(this.request.projectRoot, test.location.file).replaceAll("\\", "/");
-    for (const tag of test.tags ?? []) {
-      if (!tag.startsWith("@ads:")) continue;
-      this.cases.push({ id: tag.slice(5), file, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 4000) });
-    }
+    return (test.tags ?? []).filter(tag => tag.startsWith("@ads:")).map(tag => ({ id: tag.slice(5), file }));
+  }
+  onTestBegin(test, result) {
+    this.active.set(test.id, this.entries(test).map(entry => ({ ...entry, startedAt: (result.startTime ?? new Date()).toISOString(), workerIndex: result.workerIndex, retry: result.retry })));
+    this.publish();
+  }
+  onTestEnd(test, result) {
+    this.active.delete(test.id);
+    for (const entry of this.entries(test)) this.cases.push({ ...entry, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", durationMs: result.duration, workerIndex: result.workerIndex, retry: result.retry, completedAt: new Date().toISOString(), message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 1000) });
+    this.publish();
   }
   onError(error) {
     if (this.errors.length < 5) this.errors.push(String(error.message || error.stack || error.value || "The browser runner reported a suite error without details.").slice(0, 4000));
+    this.publish();
   }
-  onEnd() {
-    writeFileSync(process.env.ADS_VERIFY_REPORT, JSON.stringify({ schemaVersion: 1, runId: this.request.runId, cases: this.cases.slice(0, 500), errors: this.errors }));
+  publish(complete = false) {
+    const file = process.env.ADS_VERIFY_REPORT, temporary = `${file}.${process.pid}.tmp`;
+    const report = { schemaVersion: 1, runId: this.request.runId, complete, startedAt: new Date(this.startedAt).toISOString(), elapsedMs: Date.now() - this.startedAt, workers: this.workers, totalTests: this.totalTests, cases: this.cases.slice(0, 500), active: [...this.active.values()].flat().slice(0, 100), errors: this.errors };
+    try { writeFileSync(temporary, JSON.stringify(report)); renameSync(temporary, file); }
+    finally { rmSync(temporary, { force: true }); }
   }
+  onEnd() { this.publish(true); }
 };

package/dist/verification.mjs

@@ -19,13 +19,55 @@ const slash = file => file.replaceAll("\\", "/");
 const resultFile = root => path.join(root, ".ds/behavior-results.json");
 
 /** Follow real project imports; package/configuration changes also invalidate evidence. */
-function inputContext(options) { return { inventory: inspectUnits(options), scenarios: inspectScenarios(options).scenarios }; }
+function inputContext(options) {
+  const sources = new Map(), digests = new Map(), packages = new Map(), resolve = importResolver(options), resolutions = new Map();
+  return { inventory: inspectUnits(options), scenarios: inspectScenarios(options).scenarios,
+    seeds: [...configurationFiles(options)].map(file => path.join(options.root, file)).concat(sourceFiles(path.join(options.dsRoot, options.config.tokenDir)), path.join(options.dsRoot, options.config.stylesEntry)),
+    digest(file) { if (!digests.has(file)) digests.set(file, hash(readFileSync(file))); return digests.get(file); },
+    ast(file) { if (!sources.has(file)) sources.set(file, ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true)); return sources.get(file); },
+    resolve(specifier, file) { const key = `${file}\0${specifier}`; if (!resolutions.has(key)) resolutions.set(key, resolve(specifier, file)); return resolutions.get(key); },
+    hasSideEffects(file, record) {
+      let directory = path.dirname(file);
+      while (isInside(options.root, directory)) {
+        const manifest = path.join(directory, "package.json");
+        if (existsSync(manifest)) {
+          record(manifest);
+          if (!packages.has(manifest)) { try { packages.set(manifest, JSON.parse(readFileSync(manifest, "utf8")).sideEffects); } catch { packages.set(manifest, true); } }
+          const policy = packages.get(manifest), relative = slash(path.relative(directory, file));
+          if (policy === false) return false;
+          // Only the simple package sideEffects glob subset is narrowed. Unknown
+          // syntax and undeclared policies preserve the entire dependency graph.
+          if (!Array.isArray(policy) || policy.some(pattern => typeof pattern !== "string" || !/^[\w./*?-]+$/.test(pattern))) return true;
+          return policy.some(pattern => {
+            pattern = pattern.replace(/^\.\//, ""); if (!pattern.includes("/")) pattern = `**/${pattern}`;
+            const expression = pattern.match(/\*\*\/|\*\*|\*|\?|[^*?]+/g)?.map(part => part === "**/" ? "(?:.*/)?" : part === "**" ? ".*" : part === "*" ? "[^/]*" : part === "?" ? "[^/]" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("");
+            return new RegExp(`^${expression}$`).test(relative);
+          });
+        }
+        directory = path.dirname(directory);
+      }
+      return true;
+    },
+  };
+}
 
 export function behaviorInputs(options, contract, check, context = inputContext(options)) {
-  const files = new Set(), resolve = importResolver(options);
-  function visit(file) {
+  const files = new Set(), demands = new Map(), effectsVisited = new Set();
+  const resolve = context.resolve;
+  function effects(file) {
+    if (effectsVisited.has(file) || !isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    effectsVisited.add(file);
+    if (context.hasSideEffects(file, visit)) { visit(file); return; }
+    if (!/\.[cm]?[jt]sx?$/.test(file) || !lstatSync(file).isFile()) return;
+    if (lstatSync(file).isSymbolicLink() || realpathSync(file) !== file) throw new Error(`Behavior inputs cannot resolve through symlinks: ${file}`);
+    for (const statement of context.ast(file).statements) if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier)) for (const target of resolve(statement.moduleSpecifier.text, file)) effects(target);
+  }
+  function visit(file, names = null) {
     file = path.resolve(file);
-    if (files.has(file) || !isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    if (!isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    const prior = demands.get(file);
+    if (demands.has(file) && (prior === null || names && names.every(name => prior.has(name)))) return;
+    demands.set(file, names === null ? null : new Set([...(prior ?? []), ...names]));
     if (lstatSync(file).isSymbolicLink() || realpathSync(file) !== file) throw new Error(`Behavior inputs cannot resolve through symlinks: ${file}`);
     if (!lstatSync(file).isFile()) return;
     files.add(file);
@@ -39,12 +81,31 @@ export function behaviorInputs(options, contract, check, context = inputContext(
       css.walk(node => { if (node.type === "decl" || node.type === "atrule") valueParser(node.type === "decl" ? node.value : node.params).walk(value => { if (value.type === "function" && value.value.toLowerCase() === "url") localAsset(value.nodes.filter(part => part.type !== "space").map(part => part.value).join("")); }); });
     }
     if (!/\.[cm]?[jt]sx?$/.test(file)) return;
-    const ast = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    const ast = context.ast(file);
+    const barrel = names && ast.statements.every(statement => ts.isEmptyStatement(statement) || ts.isImportDeclaration(statement) && !statement.importClause || ts.isExportDeclaration(statement) && (!statement.exportClause || ts.isNamedExports(statement.exportClause)) && (!statement.exportClause || !statement.exportClause.elements.length || statement.moduleSpecifier));
+    if (barrel) {
+      for (const statement of ast.statements) {
+        if (!statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
+        for (const target of resolve(statement.moduleSpecifier.text, file)) {
+          if (ts.isImportDeclaration(statement) || !statement.exportClause) visit(target);
+          else {
+            const imported = statement.exportClause.elements.filter(entry => names.includes(entry.name.text)).map(entry => (entry.propertyName ?? entry.name).text);
+            if (imported.length) visit(target, imported);
+            effects(target);
+          }
+        }
+      }
+      return;
+    }
     function walk(node) {
       let specifier;
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
       if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require") && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) specifier = node.arguments[0].text;
-      if (specifier) for (const target of resolve(specifier, file)) visit(target);
+      if (specifier) {
+        const clause = ts.isImportDeclaration(node) && node.importClause;
+        const names = clause && !clause.namedBindings ? clause.name ? ["default"] : null : clause?.namedBindings && ts.isNamedImports(clause.namedBindings) ? [...(clause.name ? ["default"] : []), ...clause.namedBindings.elements.map(entry => (entry.propertyName ?? entry.name).text)] : null;
+        for (const target of resolve(specifier, file)) visit(target, names);
+      }
       if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "URL" && node.arguments?.[0] && ts.isStringLiteralLike(node.arguments[0])) localAsset(node.arguments[0].text);
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0]))) {
         // Computed module selection cannot provide a precise dependency closure.
@@ -56,13 +117,11 @@ export function behaviorInputs(options, contract, check, context = inputContext(
     walk(ast);
   }
   for (const file of context.inventory.units.find(unit => unit.id === contract.unit)?.files ?? []) visit(path.join(options.root, file));
-  for (const file of configurationFiles(options)) visit(path.join(options.root, file));
-  for (const file of sourceFiles(path.join(options.dsRoot, options.config.tokenDir))) visit(file);
-  visit(path.join(options.dsRoot, options.config.stylesEntry));
+  for (const file of context.seeds) visit(file);
   const scenario = check.scenario && context.scenarios.find(item => item.id === check.scenario);
   if (scenario) visit(path.join(options.root, scenario.file));
-  const rows = [...files].sort().map(file => [slash(path.relative(options.root, file)), hash(readFileSync(file))]);
-  for (const file of ["package-lock.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "node_modules/.package-lock.json"]) rows.push([file, existsSync(path.join(options.root, file)) ? hash(readFileSync(path.join(options.root, file))) : null]);
+  const rows = [...files].sort().map(file => [slash(path.relative(options.root, file)), context.digest(file)]);
+  for (const file of ["package-lock.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "node_modules/.package-lock.json"]) rows.push([file, existsSync(path.join(options.root, file)) ? context.digest(path.join(options.root, file)) : null]);
   rows.push(["profile", JSON.stringify(options.config.mcp.behaviorProfiles[check.profile])], ["node", process.version]);
   for (const file of ["./verification.mjs", "./verification/browser.mjs", "./verification/playwright-reporter.cjs"]) rows.push([`tool:${file}`, hash(readFileSync(new URL(file, import.meta.url)))]);
   return { revision: hash(JSON.stringify(rows)), files: rows.map(([file]) => file) };
@@ -104,9 +163,11 @@ export function affectedBehaviorUnits(options, changedFiles) {
   return contracts.filter(contract => Object.values(contract.checks).some(check => behaviorInputs(options, contract, check, context).files.some(file => changed.has(file)))).map(contract => contract.unit);
 }
 
-function execute(profile, args, root, env, signal) {
+export function executeDevelopmentCommand(profile, args, root, env, signal) {
   return new Promise((resolve, reject) => {
-    if (signal.aborted) { reject(new Error("Behavior verification cancelled.")); return; }
+    const label = profile.label ?? "Behavior verification";
+    if (signal.aborted) { reject(new Error(`${label} cancelled.`)); return; }
+    const startedAt = Date.now(), timeoutMs = profile.timeoutMs ?? 60000;
     let output = "", failure, child, guard, done = false;
     const kill = () => {
       if (!child?.pid) return;
@@ -121,28 +182,47 @@ function execute(profile, args, root, env, signal) {
       guard.once("error", error => { failure = error; kill(); });
       guard.once("exit", () => { if (!done) { failure ??= new Error("Verification ownership guard exited unexpectedly."); kill(); } });
     }
-    const abort = () => { failure = new Error("Behavior verification cancelled."); kill(); };
+    const abort = () => { failure = Object.assign(new Error(`${label} cancelled.`), { reason: "cancelled" }); kill(); };
     signal.addEventListener("abort", abort, { once: true });
-    const timeout = setTimeout(() => { failure = new Error("Behavior verification timed out. Inspect the registered runner and its browser/server cleanup."); kill(); }, profile.timeoutMs ?? 60000);
+    const timeout = setTimeout(() => { failure = Object.assign(new Error(`${label} timed out after ${timeoutMs} ms for the complete profile run, not each check.`), { reason: "timeout", timeoutMs }); kill(); }, timeoutMs);
     for (const stream of [child.stdout, child.stderr]) stream.on("data", chunk => { output = (output + chunk.toString()).slice(-12000); });
     child.once("error", error => { failure = error; });
     child.once("exit", kill);
     child.once("close", code => {
       done = true; kill(); guard?.stdin.end("disarm\n"); clearTimeout(timeout); signal.removeEventListener("abort", abort);
-      if (failure) reject(Object.assign(failure, { output }));
-      else resolve({ code, output });
+      const elapsedMs = Date.now() - startedAt;
+      if (failure) reject(Object.assign(failure, { output, elapsedMs }));
+      else resolve({ code, output, elapsedMs });
     });
   });
 }
 
+function readReport(file, runId) {
+  if (!existsSync(file) || realpathSync(file) !== file || !lstatSync(file).isFile() || lstatSync(file).size > 1024 * 1024) throw new Error("Runner produced no valid bounded verification report. A successful exit alone is not passing evidence.");
+  const value = JSON.parse(readFileSync(file, "utf8"));
+  if (value.schemaVersion !== 1 || value.runId !== runId || !Array.isArray(value.cases) || value.cases.length > 500 || value.active !== undefined && (!Array.isArray(value.active) || value.active.length > 100)) throw new Error("Runner report has the wrong run ID/schema or too many cases.");
+  return value;
+}
+
+function runProgress(group, report, startedAt, profile, timeoutMs) {
+  const selected = group.map(check => ({ unit: check.unit, check: check.id, id: check.case, file: slash(path.posix.join(path.posix.dirname(slash(check.contract.file)), check.file)) }));
+  const cases = selected.map(check => {
+    const matches = report?.cases.filter(item => item?.id === check.id && item.file === check.file) ?? [];
+    const running = report?.active?.find(item => item?.id === check.id && item.file === check.file);
+    return { unit: check.unit, check: check.check, state: running ? "running" : matches.length ? "completed" : Array.isArray(report?.active) ? "not_started" : "not_reported", ...(running ? { elapsedMs: Math.max(0, Date.now() - Date.parse(running.startedAt)) || 0, workerIndex: running.workerIndex } : {}), ...(matches.length ? { reportedStatus: matches.at(-1).status, durationMs: matches.reduce((sum, item) => sum + (Number.isFinite(item.durationMs) ? Math.max(0, item.durationMs) : 0), 0) } : {}) };
+  });
+  return { profile, elapsedMs: Date.now() - startedAt, timeoutMs, total: cases.length, completed: cases.filter(item => item.state === "completed").length, active: cases.filter(item => item.state === "running"), pending: cases.filter(item => ["not_started", "not_reported"].includes(item.state)).length, cases, ...(Number.isSafeInteger(report?.workers) ? { workers: report.workers } : {}) };
+}
+
 /** Registered development commands are trusted project code, never model-supplied commands. */
-export function createVerificationController(root) {
+export function createVerificationController(root, { reportRoot = root, onProgress } = {}) {
   root = path.resolve(root);
-  let active;
+  reportRoot = path.resolve(reportRoot);
+  let active, progress;
   return {
-    status: () => ({ running: !!active }),
+    status: () => ({ running: !!active, ...(active && progress ? { progress: { ...progress, elapsedMs: Date.now() - progress.startedAt } } : {}) }),
     async close() { active?.abort(); await active?.completion; },
-    async run({ unit, units, checks, persist = true } = {}, signal) {
+    async run({ unit, units, checks, persist = true } = {}, signal, notifyProgress) {
       if (active) return { ok: false, diagnostics: [{ rule: "behavior-busy", message: "A behavior verification is already running." }], results: [] };
       active = new AbortController();
       const controller = active;
@@ -162,7 +242,7 @@ export function createVerificationController(root) {
         for (const profileName of new Set(selection.map(check => check.profile))) {
           const profile = options.config.mcp.behaviorProfiles[profileName];
           const group = selection.filter(check => check.profile === profileName);
-          const directory = path.join(root, ".ds/verification", randomUUID());
+          const directory = path.join(reportRoot, ".ds/verification", randomUUID());
           mkdirSync(directory, { recursive: true });
           if (realpathSync(directory) !== directory) throw new Error("Verification output cannot resolve through a symlink.");
           const runId = randomUUID(), report = path.join(directory, "report.json"), request = path.join(directory, "request.json");
@@ -179,31 +259,55 @@ export function createVerificationController(root) {
           const requestContext = { schemaVersion: 1, runId, projectRoot: root, framework: options.config.framework, profile: profileName, mode: profile.mode ?? "unit", checks: group.map(({ contract: _contract, ...check }) => check), scenarios };
           writeFileSync(request, JSON.stringify(requestContext));
           const args = [...profile.args];
-          if (profile.runner === "playwright") args.push(...new Set(group.map(check => slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file))))), `--reporter=${fileURLToPath(new URL("./verification/playwright-reporter.cjs", import.meta.url))}`, `--output=${path.join(directory, "artifacts")}`);
+          if (profile.runner === "playwright") {
+            const tags = [...new Set(group.map(check => check.case))].map(id => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+            args.push(...new Set(group.map(check => slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file))))), `--grep=(?:^|\\s)@ads:(?:${tags.join("|")})(?=\\s|$)`, `--reporter=${fileURLToPath(new URL("./verification/playwright-reporter.cjs", import.meta.url))}`, `--output=${path.join(directory, "artifacts")}`);
+          }
           let run, reportValue, runnerError;
+          const startedAt = Date.now();
+          const update = value => {
+            progress = { ...runProgress(group, value, startedAt, profileName, profile.timeoutMs ?? 60000), startedAt };
+            onProgress?.(progress); notifyProgress?.(progress);
+          };
+          update();
+          let lastSnapshot = "", lastUpdate = Date.now();
+          const monitor = setInterval(() => {
+            let value;
+            try { value = readReport(report, runId); } catch { /* An absent/invalid intermediate snapshot cannot provide evidence. */ }
+            const snapshot = JSON.stringify(value);
+            if (snapshot !== lastSnapshot || Date.now() - lastUpdate >= 5000) { lastSnapshot = snapshot; lastUpdate = Date.now(); update(value); }
+          }, 250);
           try {
-            run = await execute(profile, args, root, { ADS_VERIFY_REQUEST: request, ADS_VERIFY_REPORT: report, ADS_VERIFY_MODE: requestContext.mode }, signal);
-            if (!existsSync(report) || realpathSync(report) !== report || lstatSync(report).size > 1024 * 1024) throw new Error("Runner produced no valid bounded verification report. A successful exit alone is not passing evidence.");
-            reportValue = JSON.parse(readFileSync(report, "utf8"));
-            if (reportValue.schemaVersion !== 1 || reportValue.runId !== runId || !Array.isArray(reportValue.cases) || reportValue.cases.length > 500) throw new Error("Runner report has the wrong run ID/schema or too many cases.");
-          } catch (error) { runnerError = error; reportValue = undefined; diagnostics.push({ rule: "behavior-runner", message: error.message, output: error.output?.slice(-4000), profile: profileName }); }
+            run = await executeDevelopmentCommand(profile, args, root, { ADS_VERIFY_REQUEST: request, ADS_VERIFY_REPORT: report, ADS_VERIFY_MODE: requestContext.mode }, signal);
+          } catch (error) { runnerError = error; }
+          finally { clearInterval(monitor); }
+          try { reportValue = readReport(report, runId); }
+          catch (error) { runnerError ??= error; }
+          update(reportValue);
+          if (runnerError) {
+            const detail = `${progress.completed}/${progress.total} checks completed; ${progress.pending} without a completed/active result. Active: ${progress.active.map(item => `${item.unit}#${item.check} (${Math.round(item.elapsedMs)} ms)`).join(", ") || "none reported"}.`;
+            diagnostics.push({ rule: "behavior-runner", message: `${runnerError.message} ${detail}`, reason: runnerError.reason, elapsedMs: runnerError.elapsedMs ?? Date.now() - startedAt, progress, output: runnerError.output?.slice(-4000), profile: profileName });
+          }
           const suiteErrors = Array.isArray(reportValue?.errors) ? reportValue.errors.slice(0, 5).map(error => String(error).slice(0, 1000)) : [];
-          const runnerFailure = run && (run.code !== 0 || suiteErrors.length) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : "reported a suite error"}. ${suiteErrors.join("; ") || reportValue?.cases.filter(item => item?.status === "failed").slice(0, 3).map(item => `${item.id}: ${item.message || "failed without a case diagnostic"}`).join("; ") || "Inspect the runner output and verification report."}`.slice(0, 3000) : undefined;
+          const runnerFailure = run && (run.code !== 0 || suiteErrors.length || reportValue?.complete === false) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : reportValue?.complete === false ? "left an incomplete report" : "reported a suite error"}. ${suiteErrors.join("; ") || reportValue?.cases.filter(item => item?.status === "failed").slice(0, 3).map(item => `${item.id}: ${item.message || "failed without a case diagnostic"}`).join("; ") || "Inspect the runner output and verification report."}`.slice(0, 3000) : undefined;
           if (runnerFailure) diagnostics.push({ rule: "behavior-runner", message: runnerFailure, output: run.output?.slice(-4000), profile: profileName });
           const afterOptions = loadConfig(root), afterContext = inputContext(afterOptions);
           for (const check of group) {
             const file = slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file)));
             const matches = reportValue?.cases.filter(item => item && item.id === check.case && item.file === file) ?? [];
             const reportedStatus = matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
-            let status = !run || runnerFailure ? "failed" : reportedStatus;
+            const interrupted = !!runnerError && !!reportValue;
+            let status = interrupted ? matches.some(item => item.status === "failed") ? "failed" : "incomplete" : !run || runnerError || runnerFailure ? "failed" : reportedStatus;
             if (runnerError?.code === "ENOENT") status = "unavailable";
             const current = behaviorInputs(afterOptions, check.contract, check, afterContext).revision === check.inputRevision;
             if (!current) status = "stale";
             if (signal.aborted) status = "cancelled";
             results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
               previewRevision: profile.mode === "browser" ? host?.previewRevision() ?? readPreviewManifest(options)?.revision ?? null : null,
-              ...(runnerFailure ? { reportedStatus, runnerExitCode: run.code } : {}),
-              message: runnerError?.message ?? (matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n") || (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : runnerFailure ? `This case reported ${reportedStatus}, but the complete run did not pass. ${runnerFailure}` : "")), report: slash(path.relative(root, report)) });
+              ...(matches.length ? { reportedStatus, durationMs: matches.reduce((sum, item) => sum + (Number.isFinite(item.durationMs) ? Math.max(0, item.durationMs) : 0), 0) } : {}),
+              ...(runnerFailure ? { runnerExitCode: run.code } : {}),
+              execution: progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state,
+              message: [matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n"), runnerError ? `${runnerError.message} This check ${matches.length ? `reported ${reportedStatus}` : `was ${progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state ?? "not reported"}`}; the complete run did not pass.` : !matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : runnerFailure ? `This case reported ${reportedStatus}, but the complete run did not pass. ${runnerFailure}` : ""].filter(Boolean).join("\n"), report: slash(path.relative(reportRoot, report)) });
           }
           if (signal.aborted) break;
         }
@@ -217,7 +321,7 @@ export function createVerificationController(root) {
         }
         return { ok: diagnostics.length === 0 && results.length > 0 && results.every(result => result.status === "passed" && result.current), diagnostics, results };
       } catch (error) { return { ok: false, diagnostics: [{ rule: "behavior-verification", message: error.message }], results }; }
-      finally { try { await host?.close(); } finally { if (active === controller) active = undefined; finish(); } }
+      finally { try { await host?.close(); } finally { if (active === controller) { active = undefined; progress = undefined; } finish(); } }
     },
   };
 }

package/docs/ADS.md

@@ -107,6 +107,11 @@ framework/dependency gates and MCP execution contract.
 Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `Scenario.tsx` exports a default independently mountable view and literal metadata
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
+Optional static `captureTargets` maps up to 20 names to CSS selectors scoped to
+that scenario's App. These support explicitly requested element screenshots; they
+do not grant coverage or styling exceptions. PNGs and current/candidate metadata
+are generated development evidence, outside source ownership and product bundles.
+See the portable [capture workflow](../skills/ads-designer/references/captures.md).
 Token entries under the configured token directory declare
 `export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
 `TokenSamples` is any project-owned public review pattern, not a required name.

package/docs/ARCHITECTURE.md

@@ -336,6 +336,39 @@ The MCP server serves compiled bytes without evaluating project TSX. Compiler
 adapters normalize each entry to mount/unmount, retaining native React or Preact
 semantics; choosing a framework does not install one into the tooling host.
 
+## On-demand visual evidence
+
+The capture unit is a registered, independently mountable scenario or one of its
+project-declared `captureTargets`. Components, patterns, compositions and token
+previews use the same real MCP App, fixtures and adapter as interactive review.
+Shared controllers/hooks need a visible demonstration. Capture introduces no
+tool-owned component templates, styling or fixture inference.
+
+ADS owns isolated preview hosting, App readiness and an owned Playwright process;
+the receiving project supplies Playwright and its installed browser. The capture
+host is the existing minimal MCP client/bridge with navigation hidden, giving the
+sandboxed App the requested viewport. Project runtime, fonts and styles remain
+inside the App resource graph. The image excludes showcase chrome.
+
+Captures exist only when requested. `ads_capture` replaces current and removes any
+candidate for that scenario/target. Guarded patch/transaction dry runs can opt into
+`screenshot:true` with explicit selected captures: after the normal gates, ADS
+renders current and candidate under matching settings without changing live source.
+A new scenario has no fabricated baseline. Final freshness/conflict checks precede
+image publication. Matching accepted source promotes candidate to current.
+
+There are at most two slots per target: current and candidate. Revisions/settings
+are metadata, not new resource identities. There is no previous slot, accumulating
+history or TTL. Stale source is identified explicitly; deleted targets are collected.
+PNG/pixel/store limits and explicit clearing bound generated storage. These images
+are visual evidence for one state, not passing behavioral guarantees.
+
+One MCP capture index and a PNG resource template expose stable image slots.
+Subscriptions receive resource updates when images change or disappear. The pair
+is published as one atomic generated record under `.ds/captures/` and stays outside
+source ownership and product bundles. Detailed usage lives in each portable skill's
+[capture reference](../skills/ads-designer/references/captures.md).
+
 ## Build checks keep the architecture in place
 
 The project build runs ADS checks before producing application or showcase
@@ -369,8 +402,12 @@ context, or the shared token foundation. ADS resolves file ownership, reconstruc
 candidate files locally and validates a temporary project copy with architecture
 checks, registered lint rules and project validation scripts. Affected registered
 behavior checks, including consumers of a changed shared controller, also run in
-the isolated candidate project. Passing checks describe
-their registered assertions, not every natural-language claim. This keeps edits
+the isolated candidate project. The project owns its test code and runner policy;
+ADS owns affected-check selection, candidate hosting, progress, evidence freshness
+and process cleanup. One profile timeout bounds its entire runner process. Parallel
+workers can share that candidate host with independent App state. Partial outcomes
+remain diagnostic when execution is interrupted; they cannot approve a mutation.
+Passing checks describe their registered assertions, not every natural-language claim. This keeps edits
 focused without requiring entire file bodies in model context. Peer units and
 unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
 branding and guides have their own units. Shared credits and text license notices

package/docs/BEHAVIORS.md

@@ -139,8 +139,25 @@ configuration must discover colocated spec files. Configure browser installation
 and any required test setup in that project. The ADS tooling host gains no
 framework or browser dependency from a profile.
 
-The Playwright adapter appends selected file paths, its reporter and a generated
-artifact directory.
+The Playwright adapter appends selected file paths and case-tag filtering, its
+reporter and a generated artifact directory. Unselected cases in the same spec
+do not run. It preserves the project's worker configuration.
+
+`timeoutMs` bounds the complete runner process for one profile, including runner
+startup, hooks, retries and all selected cases. It is not a per-test timeout.
+Playwright's own test/hook timeouts remain separate project settings. Set the
+profile budget from measured suite durations with headroom; increasing it does
+not repair a stalled assertion or cleanup.
+
+Independent specs can use multiple Playwright workers against the same managed
+candidate host. Each check needs its own page/context and state; avoid fixed ports,
+shared mutable fixtures and test-order dependencies. Start with a small worker
+count and measure on the target machine. Files normally run in parallel; tests
+within one file normally remain sequential. ADS does not force parallelism or
+change verification policy. See [Playwright parallelism](https://playwright.dev/docs/test-parallel).
+Prefer readiness/assertion polling over arbitrary sleeps. Timer-only guarantees
+may use [Playwright's clock](https://playwright.dev/docs/clock); retain real time
+when browser motion, pointer gestures or layout timing are what the check verifies.
 
 Runner failures remain blocking even when some selected cases reported passed.
 Those results retain `reportedStatus` and `runnerExitCode`, and explain the suite
@@ -150,6 +167,24 @@ scenario ID and failed browser requests in startup failures; App resource errors
 identify the resource URI. Failed assertions and startup errors are not retried
 automatically. Fix or investigate the failure before explicitly verifying again.
 
+The reporter atomically publishes partial snapshots at test start/end. While a
+run is active, `ads_status.behaviors.progress` exposes the profile, runner budget,
+elapsed time, completed/active/pending counts, worker count when available and
+case identities/timings. Candidate mutation verification exposes the same data at
+`ads_status.mutations.progress`. Clients requesting MCP progress receive updates
+and a heartbeat during the runner phase; client-side request timeouts still apply.
+`durationMs` records completed case execution, including attempts, separately from
+the suite's wall time. Parallel case durations can sum to more than wall time.
+
+After a deadline, valid completed outcomes remain visible through `reportedStatus`
+and durations, alongside active and unstarted case identities. A passed case from
+an interrupted run has blocking status `incomplete`; real assertion failures retain
+their own messages. No incomplete run can accept a mutation or certify a guarantee.
+Reports and artifacts stay under the live project's `.ds/verification/` even after
+the candidate copy is removed. This is diagnostic output, not passing live-source
+evidence. Old/custom runners without incremental progress use `not_reported` for
+cases whose execution state cannot be established.
+
 Use native test tags for stable case identity:
 
 ```ts
@@ -210,7 +245,13 @@ selected `checks` and optional `scenarios` URLs. Write a bounded JSON report:
 }
 ```
 
-Case statuses are `passed`, `failed` or `skipped`, with optional `message`.
+Case statuses are `passed`, `failed` or `skipped`, with optional `message` and
+`durationMs`. Protocol runners may atomically publish intermediate reports with
+`complete:false` and an `active` list of `{id,file,startedAt,workerIndex?}`, then
+publish `complete:true` at completion. Older final reports without `complete`
+remain supported after normal process completion. An explicitly incomplete report
+cannot pass even with exit code zero. Partial reports retain the same schema/run
+identity and size limits as final reports.
 `file` is project-relative. Nonzero process exit, missing cases, skipped cases,
 wrong run IDs and unavailable reports do not pass. Test commands are trusted
 project code; an adapter cannot prove the quality or honesty of their assertions.
@@ -245,10 +286,23 @@ Computed module selection conservatively includes all ADS owners. Environment,
 network and other unregistered external inputs remain the runner's responsibility;
 an evidence record is not a proof about arbitrary external state.
 
+For named imports through simple re-export barrels, ADS follows selected bindings
+and retains dependencies with declared side effects. This narrowing requires a
+package `sideEffects:false` or a supported simple `sideEffects` glob array; preserve
+CSS/global effects in that policy. Unknown policies/patterns, wildcard exports and
+computed imports remain conservative. Barrel source changes still invalidate
+dependents. ADS caches source parsing, resolution and digests within an inspection
+only; later runs read current source again.
+
 Guarded mutations execute affected registered behavior contracts after core,
 Oxlint and configured project checks, before writing source. Imported shared
 controller changes also select dependent contracts conservatively. Rejected and
 dry-run patches publish no source changes. Verification output stays under `.ds/`.
+To check a prepared draft, request its diff and pass the returned `patchFile` to
+`ads_apply_patch` with `dryRun:true`. This checks the isolated candidate, including
+affected behavior contracts and its configured browser preview. Candidate evidence
+is not persisted as passing evidence for live source. `ads_verify` selects checks
+for current source and has no draft argument.
 
 ## Packaging and performance
 

package/docs/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.13
+
+- Add on-demand scenario/named-element PNG captures and screenshot-enabled guarded
+  dry runs. Expose stable current/candidate resources, freshness and notifications;
+  standalone captures clear earlier candidates, matching applies promote them, and
+  bounded storage keeps no previous/history/TTL. Document architecture and portable
+  skill usage without introducing project-specific renderers or fixtures.
+- Report behavior progress, worker activity and per-case durations, preserving
+  partial outcomes and candidate artifacts on timeout while blocking incomplete
+  runs. Send requested MCP progress updates and expose candidate progress in status.
+- Filter selected Playwright case tags, preserve project worker configuration and
+  verify concurrent Apps against one candidate host. Narrow named barrel dependencies
+  under declared side-effect policies and reuse parsing/digests within an inspection.
+- Explain draft behavior verification through diff preparation and candidate
+  dry runs in all five portable skills. Distinguish candidate checks from
+  selected live-source verification through `ads_verify`.
+
 ## 0.3.12
 
 - Let the documentation unit create shared credits, conventional root license