@reqvire-org/ads 0.3.3 → 0.3.6

package/dist/tokens.mjs

@@ -4,7 +4,9 @@ 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";
+import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
 
 export { tokenContract };
 
@@ -33,8 +35,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);
@@ -48,7 +50,10 @@ export function inspectTokens(directory) {
   const { root, dsRoot, config } = options;
   const definitions = new Map();
   const diagnostics = [];
+  const scoped = scopedTokens(options);
+  diagnostics.push(...scoped.diagnostics);
   const files = sourceFiles(path.join(dsRoot, config.tokenDir)).filter((file) => file.endsWith(".css"));
+  files.push(...scoped.definitions.map(entry => path.join(root, entry.file)));
   files.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
   for (const file of files) {
     let css;
@@ -67,6 +72,7 @@ export function inspectTokens(directory) {
         column: decl.source.start.column,
         scope: context(decl),
         value: decl.value,
+        ...(scoped.definitions.some(entry => entry.file === path.relative(root, file).replaceAll("\\", "/")) ? { owner:scoped.definitions.find(entry => entry.file === path.relative(root, file).replaceAll("\\", "/")).unit } : {}),
       };
       if (!definitions.has(decl.prop)) definitions.set(decl.prop, []);
       definitions.get(decl.prop).push(definition);
@@ -106,7 +112,8 @@ export function inspectTokens(directory) {
       }
       const resolvedReferences = new Map();
       for (const ref of references(entry.value)) {
-        if (!isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name}, which does not follow ADS's fixed token naming contract.`);
+        const local = scopedTokenOwner(options, ref.name);
+        if (local ? entry.owner !== local.unit : !isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name} outside its shared/owner token contract.`);
         if (!scope.has(ref.name) && !ref.fallback) report("token-reference", name, entry, `${name} references undefined ${ref.name}.`);
         else if (scope.has(ref.name)) resolvedReferences.set(ref.name, resolveAlias(ref.name, [...chain, name]));
       }
@@ -136,7 +143,7 @@ export function inspectTokens(directory) {
   }
   return {
     contractVersion: tokenContract.version,
-    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], definitions: entries })),
+    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], ...(scopedTokenOwner(options, name) ? {owner:scopedTokenOwner(options, name).unit, namespace:scopedTokenOwner(options, name).namespace} : {owner:"tokens"}), definitions: entries })),
     diagnostics,
   };
 }

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;
 }
 
@@ -89,15 +100,16 @@ export function inspectUnits(options) {
   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.filter(file => /^(?:components|patterns)\/.+\/tokens\.json$/.test(file))) directories.add(path.posix.dirname(file));
   for (const file of files) {
-    if (!/^(?:components|patterns|composition)\//.test(file) || !source.test(file)) continue;
+    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|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
+  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);
@@ -113,7 +125,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];
@@ -134,6 +146,12 @@ export function inspectUnits(options) {
   }
   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." });
+    if (/^(?:components|patterns|controllers|composition)\//.test(unit.id)) {
+      for (let directory = unit.id; directory !== "."; directory = path.posix.dirname(directory)) {
+        const marker = path.join(dsRoot, directory, ".gitkeep");
+        if (existsSync(marker) && readFileSync(marker).length === 0) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, marker)), allowedChanges: "Delete this empty placeholder only while adding real source in the selected owner below it." });
+      }
+    }
   }
   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))) };
@@ -142,7 +160,7 @@ export function inspectUnits(options) {
 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. */
@@ -150,6 +168,14 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
   validateUnitId(unit);
   for (const change of changes) {
     const relative = inventory.relative(change.path);
+    if (path.posix.basename(relative) === ".gitkeep") {
+      const directory = path.posix.dirname(relative);
+      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition)\//.test(relative)
+        || !(unit === directory || unit.startsWith(directory + "/"))
+        || !changes.some(item => item.originalContent === null && item.content !== null && source.test(item.path)
+          && (inventory.relative(item.path).startsWith(unit + "/") || inventory.relative(item.path).startsWith(unit + ".")))) throw fail("Only delete an existing empty .gitkeep while adding source in the selected owner beneath it. Other hidden-file changes are not allowed.", change.path);
+      continue;
+    }
     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;
@@ -207,7 +233,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" ? host?.previewRevision() ?? 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

@@ -7,7 +7,8 @@ UX, and Skin pillars. [GUIDE.md](GUIDE.md) gives setup and configuration steps.
 ## Ownership boundary
 
 MCP source editing is opt-in through `ads mcp --mutations`. Its write operation
-accepts a Git unified diff for one ADS unit and validates its source, scenario and
+accepts a Git unified diff for one ADS unit (or bounded owner patches for coupled
+transactions) and validates its source, scenario and
 fixture changes against core checks, registered Oxlint rules and project checks
 before application. This includes
 foundation, documentation, original assets and an explicit configuration unit for
@@ -88,6 +89,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"] };`.
@@ -131,7 +147,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders
@@ -153,6 +169,48 @@ preview builds; review meaningful states in both themes and sizes.
 
 ## Shared token contract
 
+### Owner-local tokens
+
+Shared semantics remain in the configured token foundation. Constants specific
+to one component or pattern may live beside it:
+
+```text
+components/Notice/
+  Notice.tsx                 # imports ./tokens.css; UI styling stays in Linaria
+  tokens.json              # {"schemaVersion":1,"namespace":"--notice-"}
+  tokens.css               # :root { --notice-width: 356px; }
+  Scenario.tsx
+  fixture.ts
+  Tokens.scenario.tsx      # kind: "tokens", public review pattern + samples
+  Tokens.fixture.ts
+```
+
+Flat owners use `<Owner>.tokens.json` and `<Owner>.tokens.css`. A unit has one
+explicit namespace, unique across owners and separate from shared/runtime-variable
+prefixes. The stylesheet contains only namespaced custom-property definitions
+under root/theme conditions; imports, selectors for UI, ordinary declarations,
+font faces and animations remain outside it. Its runtime owner imports it, so
+product and preview consume the same values. Raw UI styling remains token-backed.
+
+Local token aliases may reference shared tokens or their own namespace, with
+undefined references and cycles rejected. Other owners consume shared tokens;
+they cannot redefine, write or directly consume another owner's local namespace.
+Measured runtime variables retain their existing exact `styleWrites` boundary.
+`ads_tokens` returns each token's owner, definitions and local namespace.
+
+A colocated scenario sets `kind:"tokens"` and declares real fixture `samples`
+consumed by a public review pattern. Its ID still derives from its source path.
+Every local token needs this real sample coverage, just like shared tokens.
+Definitions, metadata, fixture and token scenario belong to the same edit unit.
+Manifests/fixtures are development inputs; production includes the runtime's
+imported CSS definitions, never the preview adapter or tooling manifest.
+
+Use `ads_prepare_token_samples` to propose sample reconciliation from explicit
+project property/probe bindings. The tool preserves project sample meaning and
+reports missing mappings instead of choosing them from token prefixes.
+
+### Shared definitions
+
 Keep compatible token names, meanings, value types, and alias relationships;
 project values and theme overrides may differ. The
 [Data pillar](ARCHITECTURE.md#data-gives-implementations-a-common-language)
@@ -160,7 +218,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 +288,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