@reqvire-org/ads 0.3.2 → 0.3.5

package/dist/style-boundaries.mjs

@@ -0,0 +1,59 @@
+import path from "node:path";
+import ts from "typescript";
+import { isUiCssProperties, styleAccessProperty } from "./boundaries.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+const nameOf = node => node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null;
+
+/** Audit explicit permissions without inferring project-specific style APIs. */
+export function inspectStyleBoundaries({ root, config }, program, report) {
+  const checker = program.getTypeChecker(), usage = new Map();
+  function inspect(file) {
+    if (usage.has(file)) return usage.get(file);
+    const result = { inline: false, writes: new Set() }, source = program.getSourceFile(file);
+    function visit(node) {
+      if ((ts.isJsxAttribute(node) && nameOf(node.name) === "style") || isUiCssProperties(node, checker)) result.inline = true;
+      if (ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement") {
+        const props = node.arguments[1];
+        if (props && ts.isObjectLiteralExpression(props) && props.properties.some(property => nameOf(property.name) === "style")) result.inline = true;
+      }
+      const property = styleAccessProperty(node);
+      if (typeof property === "string") result.writes.add(property);
+      ts.forEachChild(node, visit);
+    }
+    if (source) visit(source);
+    usage.set(file, result);
+    return result;
+  }
+  const configFile = path.join(root, "ds.config.json");
+  for (const file of config.inlineStyleFiles) {
+    if (!inspect(path.resolve(root, file)).inline) report(configFile, "stale-style-boundary", `inlineStyleFiles entry ${file} has no JSX/factory style or UI CSSProperties use. Remove the unused permission; migrate source and its own boundary entries together in the owner's patch.`);
+  }
+  for (const { file, properties } of config.boundaries.styleWrites) {
+    const used = inspect(path.resolve(root, file)).writes;
+    for (const property of properties) if (!used.has(property)) report(configFile, "stale-style-boundary", `styleWrites entry ${file} never writes ${property}. Remove the unused property in the owner's source/boundary patch.`);
+  }
+}
+
+/** A local review signal, never proof that delegated cleanup is absent/correct. */
+export function pointerCaptureAdvisories(source) {
+  const captures = [], cleanup = [];
+  function hasHandler(node) {
+    while (node && (ts.isJsxExpression(node) || ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+    return !!node && ![ts.SyntaxKind.NullKeyword, ts.SyntaxKind.FalseKeyword].includes(node.kind) && !(ts.isIdentifier(node) && node.text === "undefined");
+  }
+  function visit(node) {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      if (node.expression.name.text === "setPointerCapture") captures.push(node);
+      if (node.expression.name.text === "addEventListener" && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0]) && node.arguments[0].text === "lostpointercapture" && hasHandler(node.arguments[1])) cleanup.push(node);
+    }
+    if ((ts.isJsxAttribute(node) || ts.isPropertyAssignment(node) || ts.isMethodDeclaration(node)) && /^(?:onLostPointerCapture(?:Capture)?|onlostpointercapture)$/.test(nameOf(node.name) ?? "") && (ts.isMethodDeclaration(node) || hasHandler(node.initializer))) cleanup.push(node);
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isPropertyAccessExpression(node.left) && node.left.name.text === "onlostpointercapture" && hasHandler(node.right)) cleanup.push(node);
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  return cleanup.length ? [] : captures.map(node => {
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return { rule: "pointer-capture-review", line: position.line + 1, column: position.character + 1, message: "Pointer capture has no locally visible lostpointercapture cleanup handler. Verify cancellation and capture-loss cleanup, including any delegated hook/helper. This advisory does not prove cleanup is missing or correct." };
+  });
+}

package/dist/tokens.mjs

@@ -4,6 +4,7 @@ import postcss from "postcss";
 import valueParser from "postcss-value-parser";
 import { loadConfig, sourceFiles } from "./config.mjs";
 import { foundationFiles, isSharedToken, tokenContract } from "./token-policy.mjs";
+import { dimensionValue, numericCssUnit } from "./css-values.mjs";
 import { checkComponentVariable } from "./boundaries.mjs";
 
 export { tokenContract };
@@ -33,8 +34,8 @@ function matchesType(value, type) {
   if (/^(?:inherit|initial|unset|revert(?:-layer)?)$/.test(value)) return true;
   switch (type) {
     case "color": return /^(?:#[\da-f]{3,8}|[a-z][\w-]*|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\([\s\S]+\))$/i.test(value);
-    case "dimension": return /^[-+]?(?:\d*\.)?\d+(?:px|r?em|ch|ex|cap|lh|rlh|v[wh]|[sld]v[wh]|vmin|vmax|cm|mm|in|pt|pc|%)$/i.test(value) || /^[-+]?0(?:\.0+)?$/.test(value);
-    case "duration": return /^[-+]?(?:\d*\.)?\d+m?s$/i.test(value);
+    case "dimension": return dimensionValue(value);
+    case "duration": return ["s", "ms"].includes(numericCssUnit(value));
     case "number": return /^[-+]?(?:\d*\.)?\d+$/.test(value);
     case "easing": return /^(?:linear|ease(?:-in|-out|-in-out)?|step-start|step-end|(?:cubic-bezier|steps|linear)\([\s\S]+\))$/.test(value);
     case "shadow": return value === "none" || /(?:\d(?:px|rem|em)|var\()/.test(value);

package/dist/units.mjs

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import ts from "typescript";
 import postcss from "postcss";
-import { isInside } from "./config.mjs";
+import { isDevelopmentFile, isInside } from "./config.mjs";
 import { importResolver } from "./boundaries.mjs";
 import { isProjectDocument, projectGuideFiles } from "./project-documents.mjs";
 import { foundationFiles, foundationImportTarget } from "./token-policy.mjs";
@@ -16,14 +16,21 @@ export function configurationFiles(options) {
   const { root, config, sourceRoot, dsRoot } = options;
   const files = new Set(["ds.config.json", "package.json"]);
   for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (entry.isFile() && /^(?:(?:ts|js)config[^/]*\.jsonc?|(?:vite|vitest|linaria|babel|postcss|biome|oxlint)[^/]*\.(?:jsonc?|[cm]?[jt]s)|\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?)$/.test(entry.name)) files.add(entry.name);
+    if (entry.isFile() && /^(?:(?:ts|js)config[^/]*\.jsonc?|(?:vite|vitest|playwright|linaria|babel|postcss|biome|oxlint)[^/]*\.(?:jsonc?|[cm]?[jt]s)|\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?)$/.test(entry.name)) files.add(entry.name);
   }
   const resolve = importResolver(options), visited = new Set();
   function visit(file, entrypoint = false, typeConfig = false) {
     if (!isInside(root, file) || file === root || /(?:^|[\\/])(?:node_modules|\.git|\.ds|dist)(?:[\\/]|$)/.test(path.relative(root, file)) || visited.has(file) || !existsSync(file)) return;
+    // Registering a test command must not reassign its colocated checks or
+    // fixtures to configuration. Those remain in the behavior owner's patch.
+    if (isInside(dsRoot, file) && isDevelopmentFile(file, options)) return;
     if (!entrypoint && isInside(sourceRoot, file) && !isInside(dsRoot, file)) return;
-    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
-      if (/\.[jt]sx$|\.(?:scenario|fixture)\./.test(file)) return;
+    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|controllers|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
+      if (isInside(path.join(dsRoot, "controllers"), file) || isDevelopmentFile(file, options)) return;
+      const folder = path.dirname(file), stem = path.basename(file).split(".")[0];
+      const anchored = ["index", path.basename(folder)].some(name => [".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"].some(extension => existsSync(path.join(folder, name + extension))));
+      const sidecar = path.basename(file).split(".").length > 2 && [".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"].some(extension => existsSync(path.join(folder, stem + extension)));
+      if (anchored || sidecar || /\.[jt]sx$/.test(file)) return;
       if (source.test(file) && /(?:from\s*["'](?:react|preact|@linaria\/)|\b(?:require|import)\s*\(\s*["'](?:react|preact|@linaria\/))/.test(readFileSync(file,"utf8"))) return;
     }
     visited.add(file);
@@ -65,6 +72,10 @@ export function configurationFiles(options) {
     if (["npm", "bun"].includes(watch.command) && watch.args[0] === "run") script(watch.args[1]);
     else for (const argument of [watch.command, ...watch.args]) if (/\.[cm]?[jt]sx?$/.test(argument)) visit(path.resolve(root, argument), true);
   }
+  for (const profile of Object.values(config.mcp.behaviorProfiles)) {
+    if (["npm", "bun"].includes(profile.command) && profile.args[0] === "run") script(profile.args[1]);
+    else for (const argument of [profile.command, ...profile.args]) if (/\.[cm]?[jt]sx?$/.test(argument)) visit(path.resolve(root, argument), true);
+  }
   return files;
 }
 
@@ -84,8 +95,20 @@ export function inspectUnits(options) {
   }
   walk(dsRoot);
   files.sort();
-  const directoryUnits = files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))).sort((a, b) => b.length - a.length);
-  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
+  // Runtime entry conventions keep directory ownership stable when an optional
+  // preview is removed. A flat scenario family still denotes separate owners.
+  const sameName = name => name.replace(/[-_]/g, "").toLowerCase();
+  const flatFamilies = new Set(files.filter(file => /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
+  const directories = new Set(files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))));
+  for (const file of files) {
+    if (!/^(?:components|patterns|controllers|composition)\//.test(file) || !source.test(file)) continue;
+    const directory = slash(path.dirname(file)), name = path.basename(file).replace(source, "");
+    if (!directory.includes("/") || /\.(?:scenario|fixture|scenario-adapter)$/.test(name)) continue;
+    if (flatFamilies.has(directory)) continue;
+    if (name === "index" || sameName(name) === sameName(path.posix.basename(directory)) || name === "fixture") directories.add(directory);
+  }
+  const directoryUnits = [...directories].sort((a, b) => b.length - a.length);
+  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|controllers|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
     const base = path.basename(file).split(".")[0];
     return slash(path.join(path.dirname(file), base));
   }))].sort((a, b) => b.length - a.length);
@@ -101,7 +124,7 @@ export function inspectUnits(options) {
     if (relative.startsWith(tokenDir + "/")) return "tokens";
     if (relative.startsWith("assets/")) return relative.split("/").length > 2 ? relative.split("/").slice(0, 2).join("/") : "assets";
     if (!relative.includes("/")) return /(?:\.(?:md|txt)$|^LICENSE$)/i.test(relative) ? "documentation" : "foundation";
-    if (!/^(?:components|patterns|composition)\//.test(relative)) return relative.split("/")[0];
+    if (!/^(?:components|patterns|controllers|composition)\//.test(relative)) return relative.split("/")[0];
     for (const directory of directoryUnits) if (relative.startsWith(directory + "/")) return directory;
     for (const unit of flatUnits) if (relative.startsWith(unit + "/") || relative.startsWith(unit + ".")) return unit;
     const base = path.basename(relative).split(".")[0];
@@ -120,12 +143,17 @@ export function inspectUnits(options) {
     const file = slash(path.relative(root, path.join(dsRoot, relative)));
     if (!units.get(id).files.includes(file)) units.get(id).files.push(file);
   }
+  for (const unit of units.values()) if (boundaryCompanion(unit.id)) {
+    (unit.companionFiles ??= []).push({ path: "ds.config.json", allowedChanges: "Only this owner's inlineStyleFiles and boundaries.styleWrites entries, together with its source change; preserve all other configuration and peer permissions." });
+  }
   return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, stylesEntry, tokenDir,
     relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
 }
 
+function boundaryCompanion(unit) { return !["configuration", "documentation", "assets"].includes(unit.split("/")[0]); }
+
 export function validateUnitId(unit) {
-  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
+  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "controllers", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
 }
 
 /** Reject arbitrary file batches, even when every path is inside the ADS. */
@@ -134,6 +162,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
   for (const change of changes) {
     const relative = inventory.relative(change.path);
     if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
+    if (change.path === "ds.config.json" && boundaryCompanion(unit)) continue; // Validated against only this owner below.
     if (relative === inventory.publicEntry) continue;
     if (unit === "tokens" && relative === inventory.stylesEntry) continue; // Controlled foundation import bookkeeping.
     if (allowNew && change.originalContent === null && (relative.startsWith(unit + "/") || relative.startsWith(unit + "."))) continue;
@@ -153,6 +182,24 @@ export function checkUnitCandidate(afterOptions, unit, changes, before) {
     if (unit === "configuration" && (entry.id === "configuration" || after.owner(relative) === "configuration")) continue;
     if (after.owner(relative) !== entry.id) throw fail("A patch cannot change ownership of existing peer units. Choose an unoccupied owner path.", file);
   }
+  const boundaryChange = changes.find(change => change.path === "ds.config.json");
+  if (boundaryChange && unit !== "configuration") {
+    if (!boundaryCompanion(unit) || typeof boundaryChange.originalContent !== "string" || typeof boundaryChange.content !== "string") throw fail("This unit cannot create/delete configuration.", boundaryChange.path);
+    if (!changes.some(change => change.path !== boundaryChange.path && (before.owner(before.relative(change.path)) === unit || after.owner(after.relative(change.path)) === unit))) throw fail("Boundary companions require a source change in the selected owner.", boundaryChange.path);
+    function peerPolicy(content, inventory) {
+      const config = JSON.parse(content);
+      const owns = file => typeof file === "string" && inventory.owner(inventory.relative(file)) === unit;
+      config.inlineStyleFiles = (config.inlineStyleFiles ?? []).filter(file => !owns(file));
+      config.boundaries = { ...config.boundaries, styleWrites: (config.boundaries?.styleWrites ?? []).filter(entry => !owns(entry.file)) };
+      return config;
+    }
+    function canonical(value) {
+      if (Array.isArray(value)) return value.map(canonical);
+      if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+      return value;
+    }
+    if (JSON.stringify(canonical(peerPolicy(boundaryChange.originalContent, before))) !== JSON.stringify(canonical(peerPolicy(boundaryChange.content, after)))) throw fail("Boundary companion patches may change only inlineStyleFiles and styleWrites entries owned by the selected unit; preserve all other configuration and peer permissions.", boundaryChange.path);
+  }
   const foundationChange = changes.find(change => before.relative(change.path) === before.stylesEntry);
   if (unit === "tokens" && foundationChange) {
     const { originalContent: current, content: proposed } = foundationChange;
@@ -171,7 +218,7 @@ export function checkUnitCandidate(afterOptions, unit, changes, before) {
   }
   const exportChange = changes.find(change => before.relative(change.path) === before.publicEntry);
   if (exportChange) {
-    if (!["components", "patterns"].includes(unit.split("/")[0])) throw fail("Only a component/pattern unit may update its public re-exports.", exportChange.path);
+    if (!["components", "patterns", "controllers"].includes(unit.split("/")[0])) throw fail("Only a component/pattern/controller unit may update its public re-exports.", exportChange.path);
     const current = exportChange.originalContent ?? "", proposed = exportChange.content;
     if (proposed === null) throw fail("The shared public entry cannot be deleted.", exportChange.path);
     const resolve = importResolver(afterOptions);

package/dist/verification/browser.mjs

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+
+/** Development-only Playwright helper. No browser or framework dependency is installed. */
+export function verificationRequest() {
+  if (!process.env.ADS_VERIFY_REQUEST) throw new Error("Run this check through ads_verify so the request and selected profile are explicit.");
+  return JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
+}
+
+export async function openBehaviorScenario(page, checkId, { timeout = 30000 } = {}) {
+  const request = verificationRequest();
+  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.");
+  await page.goto(url, { waitUntil: "load", timeout });
+  const end = Date.now() + timeout;
+  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.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);
+    await page.waitForTimeout(50);
+  }
+  throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
+}

package/dist/verification/playwright-reporter.cjs

@@ -0,0 +1,20 @@
+const { readFileSync, writeFileSync } = require("node:fs");
+const path = require("node:path");
+
+/** Case identity is an explicit project test tag: @ads:<case-id>. */
+module.exports = class AdsBehaviorReporter {
+  constructor() {
+    this.request = JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
+    this.cases = [];
+  }
+  onTestEnd(test, result) {
+    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).join("\n").slice(0, 4000) });
+    }
+  }
+  onEnd() {
+    writeFileSync(process.env.ADS_VERIFY_REPORT, JSON.stringify({ schemaVersion: 1, runId: this.request.runId, cases: this.cases.slice(0, 500) }));
+  }
+};

package/dist/verification.mjs

@@ -0,0 +1,214 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+import { loadConfig, sourceFiles, isInside } from "./config.mjs";
+import { importResolver } from "./boundaries.mjs";
+import { inspectUnits, configurationFiles } from "./units.mjs";
+import { inspectBehaviors } from "./behaviors.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+import { readPreviewManifest } from "./preview-resources.mjs";
+
+export const BEHAVIOR_URI = "ads://project/behaviors";
+const hash = bytes => createHash("sha256").update(bytes).digest("hex");
+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 }; }
+
+export function behaviorInputs(options, contract, check, context = inputContext(options)) {
+  const files = new Set(), resolve = importResolver(options);
+  function visit(file) {
+    file = path.resolve(file);
+    if (files.has(file) || !isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    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);
+    const localAsset = specifier => {
+      if (!specifier || /^(?:[a-z][\w+.-]*:|\/|#)/i.test(specifier)) return;
+      visit(path.resolve(path.dirname(file), specifier.replace(/[?#].*$/, "")));
+    };
+    if (file.endsWith(".css")) {
+      const css = postcss.parse(readFileSync(file, "utf8"), { from: file });
+      css.walkAtRules("import", rule => { const first = valueParser(rule.params).nodes.find(node => node.type !== "space" && node.type !== "comment"); if (first?.type === "string") localAsset(first.value); });
+      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);
+    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 (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.
+        // Conservatively invalidate against every owned ADS input instead.
+        for (const unit of context.inventory.units) for (const owned of unit.files) visit(path.join(options.root, owned));
+      }
+      ts.forEachChild(node, walk);
+    }
+    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));
+  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]);
+  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) };
+}
+
+function saved(root) {
+  try {
+    const file = resultFile(root);
+    if (realpathSync(file) !== file || lstatSync(file).size > 2 * 1024 * 1024) return {};
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    return value.schemaVersion === 1 && value.results && typeof value.results === "object" && !Array.isArray(value.results) ? value.results : {};
+  } catch { return {}; }
+}
+const identity = (unit, check) => `${unit}#${check}`;
+
+export function behaviorStatus(options) {
+  const inventory = inspectBehaviors(options), evidence = saved(options.root);
+  const context = inventory.contracts.length ? inputContext(options) : null;
+  return { ...inventory, contracts: inventory.contracts.map(contract => {
+    const checks = Object.fromEntries(Object.entries(contract.checks).map(([id, check]) => {
+      const previous = evidence[identity(contract.unit, id)];
+      const revision = behaviorInputs(options, contract, check, context).revision;
+      const current = previous?.revision === revision && previous.profile === check.profile && previous.file === check.file && previous.case === check.case;
+      return [id, { ...check, result: previous ? { ...previous, current, status: current ? previous.status : "stale" } : { status: "not_run", current: false } }];
+    }));
+    return { ...contract, checks, guarantees: contract.guarantees.map(guarantee => {
+      const results = guarantee.checks.map(id => checks[id]?.result ?? { status: "unavailable", current: false });
+      const status = results.every(result => result.current && result.status === "passed") ? "passed" : results.find(result => result.status !== "passed")?.status ?? "not_run";
+      return { ...guarantee, result: { status, current: results.every(result => result.current) } };
+    }) };
+  }) };
+}
+
+export function affectedBehaviorUnits(options, changedFiles) {
+  const changed = new Set(changedFiles.map(file => slash(path.relative(options.root, path.resolve(options.root, file)))));
+  const contracts = inspectBehaviors(options).contracts;
+  if (!contracts.length) return [];
+  const context = inputContext(options);
+  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) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(new Error("Behavior verification cancelled.")); return; }
+    let output = "", failure, child, guard, done = false;
+    const kill = () => {
+      if (!child?.pid) return;
+      if (process.platform === "win32") { const stop = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" }); stop.on("error", () => child.kill("SIGKILL")); }
+      else try { process.kill(-child.pid, "SIGKILL"); } catch (error) { if (error.code !== "ESRCH") failure ??= error; }
+    };
+    child = spawn(profile.command === "node" ? process.execPath : profile.command, args, { cwd: root, detached: process.platform !== "win32", shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+      env: { ...process.env, ...env, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) } });
+    if (child.pid) {
+      guard = spawn(process.execPath, [fileURLToPath(new URL("./mcp/preview-owner-guard.mjs", import.meta.url)), String(child.pid)], { detached: process.platform !== "win32", stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
+      guard.stdin.on("error", () => {});
+      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(); };
+    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);
+    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 });
+    });
+  });
+}
+
+/** Registered development commands are trusted project code, never model-supplied commands. */
+export function createVerificationController(root) {
+  root = path.resolve(root);
+  let active;
+  return {
+    status: () => ({ running: !!active }),
+    async close() { active?.abort(); await active?.completion; },
+    async run({ unit, units, checks, persist = true } = {}, signal) {
+      if (active) return { ok: false, diagnostics: [{ rule: "behavior-busy", message: "A behavior verification is already running." }], results: [] };
+      active = new AbortController();
+      const controller = active;
+      signal = signal ? AbortSignal.any([signal, active.signal]) : active.signal;
+      let finish; controller.completion = new Promise(resolve => { finish = resolve; });
+      let host;
+      const results = [], diagnostics = [];
+      try {
+        const options = loadConfig(root), inventory = inspectBehaviors(options);
+        if (inventory.diagnostics.length) return { ok: false, diagnostics: inventory.diagnostics, results };
+        const selectedUnits = new Set(units ?? (unit ? [unit] : inventory.contracts.map(item => item.unit)));
+        const contracts = inventory.contracts.filter(item => selectedUnits.has(item.unit));
+        if (!contracts.length || [...selectedUnits].some(id => !contracts.some(contract => contract.unit === id))) return { ok: false, diagnostics: [{ rule: "behavior-selection", message: "No behavior contract matches the complete selection. Discover exact owner/check IDs with ads_behaviors." }], results };
+        const context = inputContext(options);
+        const selection = contracts.flatMap(contract => Object.entries(contract.checks).filter(([id]) => !checks || checks.includes(id)).map(([id, check]) => ({ unit: contract.unit, id, ...check, inputRevision: behaviorInputs(options, contract, check, context).revision, contract })));
+        if (!selection.length || checks?.some(id => !selection.some(check => check.id === id))) return { ok: false, diagnostics: [{ rule: "behavior-selection", message: "Unknown check selection. Use check IDs returned by ads_behaviors." }], results };
+        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());
+          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");
+          const scenarios = {};
+          if (profile.mode === "browser" && group.some(check => check.scenario)) {
+            const { startAdsMcp } = await import("./mcp/server.mjs");
+            host ??= await startAdsMcp(root, { stdio: false, showcase: true });
+            for (const check of group.filter(check => check.scenario)) { const url = new URL(host.url); url.searchParams.set("scenario", check.scenario); scenarios[check.scenario] = url.href; }
+          }
+          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")}`);
+          let run, reportValue, runnerError;
+          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; diagnostics.push({ rule: "behavior-runner", message: error.message, output: error.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) ?? [];
+            let status = !run || run.code !== 0 ? "failed" : matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
+            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" ? readPreviewManifest(options)?.revision ?? null : null,
+              message: runnerError?.message ?? (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : matches.filter(item => item.status !== "passed").map(item => String(item.message ?? item.status).slice(0, 2000)).join("\n")), report: slash(path.relative(root, report)) });
+          }
+          if (signal.aborted) break;
+        }
+        if (persist) {
+          const evidence = saved(root);
+          for (const result of results) evidence[identity(result.unit, result.check)] = result;
+          const file = resultFile(root), temporary = `${file}.${randomUUID()}.tmp`;
+          const content = JSON.stringify({ schemaVersion: 1, results: evidence });
+          if (Buffer.byteLength(content) > 2 * 1024 * 1024) throw new Error("Verification evidence exceeds 2 MiB. Remove obsolete generated evidence and retry.");
+          try { writeFileSync(temporary, content); renameSync(temporary, file); } finally { rmSync(temporary, { force: true }); }
+        }
+        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(); } }
+    },
+  };
+}

package/docs/ADS.md

@@ -88,6 +88,21 @@ design-system/
     main.tsx
 ```
 
+Private controllers remain in that component/pattern owner. Shared controllers use
+`controllers/<Name>/` with an index or same-name runtime entry and independently
+guarded public re-exports. They may use the configured framework and declared
+dependencies, plain TypeScript and browser APIs; CSS/Linaria and visual DOM belong
+to consumers. They require no artificial visual scenario.
+
+Optional colocated `behavior.json` (flat: `<Owner>.behavior.json`) registers
+subjects, guarantees and owner-local checks against project-configured runner
+profiles. `exercises` records public behavioral APIs demonstrated by a scenario;
+`covers` retains its rendered UI contract. ADS validates references and reachable
+uses; execution evidence is separate and becomes stale when its inputs change.
+Runtime imports/re-exports of manifests, tests, fixtures and scenarios are rejected.
+See [controllers and behavioral verification](BEHAVIORS.md) for the schema,
+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"] };`.
@@ -160,7 +175,17 @@ explains the model.
 
 Consume token references instead of raw visual values. Color formulas, effects,
 durations, easing, typography, sizing, and layering values belong in the token
-source.
+source. Absolute and font-relative length literals require token references,
+including `ch`, `ex`, `cap`, `ic`, `lh` and their root-relative forms, even inside
+`calc()`, `min()` or fallbacks. CSS numeric notation does not change ownership.
+Unitless geometry, percentages, grid fractions and viewport/container relationships
+retain their structural use.
+
+Angle units (`deg`, `grad`, `rad`, `turn`) remain available for geometric rotation,
+skew, orientation and complete turns. Static checks do not infer whether an angle
+is art direction: put a tunable visual angle in the project's tokens when it is
+part of that design contract. Angle-bearing color effects still require tokens.
+These categories follow [CSS Values and Units](https://www.w3.org/TR/css-values-4/#lengths).
 
 Token names and ownership prefixes are fixed by ADS architecture, not project
 configuration. `--ds-*` belongs to components, `--ux-*` to patterns, and
@@ -220,7 +245,7 @@ motion values.
 
 External content workflows are agent skills; there is no CLI
 `ads import` command. Use the [skill guide](../skills/README.md) for installation,
-selection, import, assimilation, stress testing, and motion workflows.
+selection, import, migration, stress testing, and motion workflows.
 
 Record the source revision and integrate selected source, dependencies, public
 exports, assets, documentation, and applicable rules. Preserve destination token
@@ -291,10 +316,14 @@ The checks enforce the architecture's ownership boundaries:
 | Tokens and styles | Fixed token vocabulary, required definitions, declared value types and references, raw visual values, shared-token assignments, foundation import order, and component/pattern namespaces |
 | Public API and dependencies | Consumers use public ADS imports; ADS implementations and showcase do not import application source; runtime code does not import showcase fixtures |
 | Interaction policy | Primitive state variables stay inside components; non-state customization hooks require explicit registration |
-| Renderer exceptions | Inline JSX styles and imperative style writes require narrow configured boundaries; public props omit inherited style and reject open-ended visual strings |
+| Renderer exceptions | Inline styles and imperative writes require used, narrow configured boundaries; stale entries fail; public props omit inherited style and reject open-ended visual strings |
 | Preview ownership | Scenarios define no CSS, custom classes, or native controls; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
 | Assets | Source/public collisions and configured generated artifacts in source are rejected |
 
+Pointer capture without locally visible capture-loss cleanup produces a
+nonblocking advisory. Review delegated cleanup and browser behavior; neither a
+warning nor a handler's presence establishes lifecycle correctness.
+
 Document a new ownership exception with its guard/configuration change and
 tests. Passing static checks establishes only the policies and source formats
 they cover. Browser review and behavior tests still verify accessibility,