@reqvire-org/ads 0.3.11 → 0.3.13

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.
@@ -333,6 +338,10 @@ in each item's local README. Record source repository/file links, revision,
 authors, concrete influences, and integration differences. Preserve applicable
 license notices for copied/adapted source and assets. The project guide records
 local implementation choices and links to the local item guides.
+Shared `CREDITS.md`, conventional root notices and text files in `licenses/` use
+the `documentation` mutation unit; its `filePolicy` describes supported new paths.
+They can be added with README links in one guarded patch, without duplicating a
+shared license into every component. Colocated notices retain their owning unit.
 
 ## Build contract
 

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,11 +402,19 @@ 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. Project configuration, registered guards
+branding and guides have their own units. Shared credits and text license notices
+belong to the documentation unit, including conventional root notices and shared
+`licenses/` collections. Colocated notices remain with their component or asset
+owner. Documentation paths and UTF-8 validation do not grant code/configuration
+ownership. Project configuration, registered guards
 and compiler integration form an explicit configuration unit; their proposed
 settings pass the same mandatory validation. Binary assets can travel as Git patch
 artifacts without entering model context, and compiler configuration changes

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,33 @@
 # 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
+  notices and text `licenses/` collections in one guarded owner patch. Expose its
+  new-file policy, discover readable provenance resources without enlarging
+  workflow guide context, preserve verbatim UTF-8 notices and keep code/peer/path
+  boundaries. Verify drafts, dry runs, publication, reads and rejection atomically.
+- Add generic skill examples for preserving reference baselines and intended
+  public APIs while resolving coverage diagnostics; verify conditional controls
+  through browser state transitions instead of screenshots alone.
+
 ## 0.3.11
 
 - Bind preview success to project input content as well as artifact bytes. Source

package/docs/GUIDE.md

@@ -5,7 +5,54 @@ contains a Node CLI, shared token contract, static checks, an Oxlint plugin, and
 empty foundation scaffolding. It includes no component or pattern catalogue,
 fonts, mock screens, or UI runtime dependency.
 
-
+## Use ADS through MCP
+
+Connect your coding agent using the [MCP client setup](MCP.md#connect-codex-or-claude).
+The client launches `ads mcp` in your project; add `--mutations` to enable guarded
+source editing. Initialization also supplies `ads-mcp` and `ads-read-mcp` launch
+scripts. The server starts its showcase and configured preview compiler, so use
+the returned showcase URL rather than starting a separate preview application.
+
+An agent uses the MCP tools to inspect, edit and review the project:
+
+1. Call `ads_status` to identify the connected project, available commands,
+   mutation mode, showcase URL and build freshness.
+2. Find public UI/behavior APIs with `ads_catalog`, inspect relevant definitions
+   with `ads_tokens`, and discover preview IDs with `ads_scenarios`. Read one
+   relevant workflow through `ads_skills` and `ads_read_skill` before editing.
+3. Open a discovered preview with `ads_show_scenario` or `ads_show_tokens`. These
+   render the project's actual scenario, fixtures and adapter through MCP Apps.
+   Use the returned showcase link when the client cannot render Apps.
+4. When editing is enabled, discover ownership with `ads_units`, read relevant
+   source through `ads_read_file`, and submit an owner Git patch through
+   `ads_apply_patch`. Use `ads_apply_transaction` for genuinely coupled owners.
+   Prepare/diff a local draft with `ads_prepare_patch` when useful. Dry-run first;
+   ADS checks an isolated candidate before any live source is written.
+5. Review diagnostics, registered behavior evidence and the rendered result.
+   `ads_behaviors` discovers guarantees; `ads_verify` executes selected registered
+   checks. Recheck `ads_status.build` after changes; notifications alone do not
+   establish current output.
+
+For an on-demand screenshot, call `ads_capture` with a discovered scenario ID and
+optionally a named `captureTargets` element, theme and viewport. To compare a
+proposed change before applying it, add `screenshot:true` and an explicit
+`captures:[{scenario:"<discovered ID>"}]` selection to the patch/transaction dry run.
+Normal patches and dry runs create no screenshots. Capture uses project-installed
+Playwright and its browser; ADS installs neither.
+
+Read `ads://project/captures` and the returned PNG image URIs through MCP
+`resources/read`. Each target keeps only current and candidate: a successful
+standalone screenshot replaces current and clears candidate; a screenshot-enabled
+dry run replaces the pair; applying matching source promotes candidate. Source
+changes mark images stale. There is no previous slot, history or TTL.
+`ads_capture_clear` discards candidate or clears both images. Subscribe to resource
+updates when supported, and explicitly reread otherwise. Screenshots provide visual
+evidence for one state; they do not replace behavior checks.
+
+The [MCP guide](MCP.md) details tool/resource schemas, prompts, skills and
+notifications. The portable [capture guide](../skills/ads-designer/references/captures.md)
+explains screenshot setup, named targets, limits and comparison usage; MCP serves
+the same guide at `ads://guides/captures`.
 
 ## Implementation support