@reqvire-org/ads 0.3.2 → 0.3.5

package/README.md

@@ -58,6 +58,8 @@ Linaria; integrate its extraction with your build as described in the
 | `ads init --framework react` | Set up ADS in the current project; also accepts `preact`; saved choices can omit the flag |
 | `ads check` | Check tokens, styles, imports, and ADS ownership |
 | `ads tokens` | Inspect token values and themes |
+| `ads behaviors` | Inspect registered behavior guarantees and current evidence |
+| `ads verify --unit <id>` | Run an owner's registered behavior checks |
 | `ads assets` | Generate standard web icons from the project's SVG |
 | `ads lint-config` | Generate lint config; normally called by the build |
 | `ads mcp` | Start the stdio MCP server and its local showcase |
@@ -92,9 +94,15 @@ fixtures, and runs the guards before applying it. Foundation styles, original
 assets, guides and project configuration/guard extensions have editable units too. See [guarded editing](docs/MCP.md#guarded-editing).
 
 The server exposes public components/patterns, token values,
-source guides, architecture checks, workflow prompts, and packaged ADS skills.
+source guides, controllers/hooks, architecture checks, behavioral verification,
+workflow prompts, and packaged ADS skills.
 It supports older MCP clients and the newer Skills protocol.
 
+Private controllers stay beside their component; shared controllers have their own
+edit units. Optional behavior contracts connect guarantees to maintained checks.
+Demonstrations and passing execution evidence remain distinct. See
+[controllers and verification](docs/BEHAVIORS.md).
+
 Experimental MCP Apps show an interactive token inspector and project-built
 token, component, pattern and composition scenarios. They use the same public implementations and fixtures
 as the showcase. Text and resource access remain available without Apps support.
@@ -202,13 +210,13 @@ app's bundler. With no icon source, generation is skipped. See the
 Install skills with `npx skills`:
 
 ```sh
-npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 For local development, install from this checkout:
 
 ```sh
-npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 Acknowledgments: `ads-designer`'s craft/mobile guidance, `ads-break-ui`, and
@@ -220,7 +228,7 @@ notice beside its files.
 
 - [ads-designer](skills/ads-designer/SKILL.md): start an ADS or build UI with your local ADS.
 - [ads-import](skills/ads-import/SKILL.md): import external components, patterns, styles, token values, or brand artwork.
-- [ads-assimilate](skills/ads-assimilate/SKILL.md): implement a native component inspired by an external library.
+- [ads-migrate](skills/ads-migrate/SKILL.md): implement a native component inspired by an external library.
 - [ads-break-ui](skills/ads-break-ui/SKILL.md): stress-test real components and patterns with difficult content.
 - [ads-motion](skills/ads-motion/SKILL.md): implement, review, audit, or profile component animation.
 

package/dist/behaviors.mjs

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { isBuiltin } from "node:module";
+import ts from "typescript";
+import { z } from "zod";
+import { isBehaviorFile, isDevelopmentFile, isInside, sourceFiles } from "./config.mjs";
+import { importResolver, projectCompilerOptions } from "./boundaries.mjs";
+import { inspectUnits } from "./units.mjs";
+import { publicApi } from "./public-api.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+const id = z.string().regex(/^[a-zA-Z0-9][\w.-]{0,99}$/);
+const reference = z.string().min(1).max(500);
+const subject = z.union([
+  z.object({ api: reference }).strict(),
+  z.object({ source: reference, symbol: reference.optional() }).strict(),
+]);
+export const behaviorSchema = z.object({
+  schemaVersion: z.literal(1),
+  subjects: z.record(id, subject).refine(value => Object.keys(value).length > 0 && Object.keys(value).length <= 100),
+  guarantees: z.array(z.object({ id, description: z.string().min(1).max(2000), subjects: z.array(id).min(1).max(100), checks: z.array(id).min(1).max(100) }).strict()).min(1).max(100),
+  checks: z.record(id, z.object({ file: reference, case: id, scenario: reference.optional(), profile: id }).strict()).refine(value => Object.keys(value).length > 0 && Object.keys(value).length <= 100),
+}).strict();
+
+/** Static contracts never execute project code or certify natural-language claims. */
+export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
+  const { root, dsRoot, config } = options;
+  const inventory = inspectUnits(options);
+  const files = sourceFiles(dsRoot).filter(isBehaviorFile);
+  if (!files.length) return { contracts: [], diagnostics: [] };
+  const program = suppliedProgram ?? ts.createProgram(sourceFiles(dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
+  const checker = program.getTypeChecker();
+  const apis = new Map(publicApi(program, options).map(item => [item.name, item]));
+  const scenarios = (suppliedRegistry ?? inspectScenarios(options, program)).scenarios;
+  const diagnostics = [], contracts = [], owners = new Set();
+  const relative = file => path.relative(root, file).replaceAll("\\", "/");
+  for (const file of files) {
+    const report = message => diagnostics.push({ file: relative(file), rule: "behavior-contract", line: 1, column: 1, message });
+    let value;
+    try {
+      if (statSync(file).size > 128 * 1024 || realpathSync(file) !== file) throw new Error("Behavior contracts must be regular files of at most 128 KiB.");
+      const parsed = behaviorSchema.safeParse(JSON.parse(readFileSync(file, "utf8")));
+      if (!parsed.success) throw new Error(parsed.error.issues.slice(0, 5).map(issue => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+      value = parsed.data;
+    } catch (error) { report(error.message); continue; }
+    const unit = inventory.owner(inventory.relative(relative(file)));
+    if (!["components", "patterns", "controllers"].includes(unit?.split("/")[0])) { report("Behavior contracts belong to a component, pattern or controller unit."); continue; }
+    if (owners.has(unit)) { report(`Only one behavior contract may describe ${unit}.`); continue; }
+    owners.add(unit);
+    function owned(target, field) {
+      if (path.isAbsolute(target) || target.includes("\\") || target.includes("\0")) { report(`${field} must be an owner-local relative path.`); return null; }
+      const absolute = path.resolve(path.dirname(file), target);
+      if (!isInside(dsRoot, absolute) || inventory.owner(inventory.relative(relative(absolute))) !== unit
+        || !existsSync(absolute) || !statSync(absolute).isFile() || realpathSync(absolute) !== absolute) { report(`${field} must resolve to a real file in ${unit}: ${target}`); return null; }
+      return absolute;
+    }
+    for (const [name, entry] of Object.entries(value.subjects)) {
+      if (entry.api) {
+        const api = apis.get(entry.api);
+        if (!api || inventory.owner(inventory.relative(relative(api.file))) !== unit) report(`Subject ${name} must resolve to a public API owned by ${unit}: ${entry.api}`);
+      } else {
+        const source = owned(entry.source, `Subject ${name}`);
+        if (source && isDevelopmentFile(source, options)) report(`Subject ${name} must identify runtime implementation, not a fixture, scenario or check.`);
+        if (source && entry.symbol) {
+          const ast = program.getSourceFile(source);
+          if (!ast || !checker.getSymbolsInScope(ast, ts.SymbolFlags.Value).some(symbol => symbol.name === entry.symbol && symbol.declarations?.some(declaration => declaration.getSourceFile() === ast))) report(`Subject ${name}: symbol ${entry.symbol} is not declared in ${entry.source}.`);
+        }
+      }
+    }
+    const guaranteeIds = new Set();
+    for (const guarantee of value.guarantees) {
+      if (guaranteeIds.has(guarantee.id)) report(`Duplicate guarantee ID ${guarantee.id}.`);
+      guaranteeIds.add(guarantee.id);
+      for (const name of guarantee.subjects) if (!Object.hasOwn(value.subjects, name)) report(`Guarantee ${guarantee.id} references unknown subject ${name}.`);
+      for (const check of guarantee.checks) if (!Object.hasOwn(value.checks, check)) report(`Guarantee ${guarantee.id} references unknown check ${check}.`);
+    }
+    const cases = new Set();
+    for (const [name, check] of Object.entries(value.checks)) {
+      const target = owned(check.file, `Check ${name}`);
+      if (target && !isDevelopmentFile(target, options)) report(`Check ${name} must use a development-only test/spec file.`);
+      if (!Object.hasOwn(config.mcp.behaviorProfiles, check.profile)) report(`Check ${name} references unregistered profile ${check.profile}. Register its literal runner command in ds.config.json; checks cannot install packages or assume host globals.`);
+      if (check.scenario && !scenarios.some(scenario => scenario.id === check.scenario)) report(`Check ${name} references unknown scenario ${check.scenario}.`);
+      const identity = JSON.stringify([check.file, check.case, check.profile]);
+      if (cases.has(identity)) report(`Duplicate execution identity for check ${name}. Use one check ID and reference it from several guarantees.`);
+      cases.add(identity);
+    }
+    contracts.push({ ...value, unit, file: relative(file), demonstrations: Object.fromEntries(Object.entries(value.subjects).filter(([, item]) => item.api).map(([name, item]) => [name, scenarios.filter(scenario => scenario.exercises?.includes(item.api)).map(scenario => scenario.id)])) });
+  }
+  return { contracts, diagnostics };
+}
+
+/** Headless ownership applies to shared controllers and explicitly named private subjects. */
+export function inspectControllers(options, program, report, contracts = []) {
+  const { root, dsRoot, config } = options;
+  const resolve = importResolver(options);
+  const pkg = existsSync(path.join(root, "package.json")) ? JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")) : {};
+  const declared = new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies, ...pkg.optionalDependencies }));
+  const privateFiles = new Map();
+  for (const contract of contracts) for (const subject of Object.values(contract.subjects).filter(item => item.source)) {
+    const file = path.resolve(root, path.dirname(contract.file), subject.source);
+    if (!privateFiles.has(file)) privateFiles.set(file, new Set());
+    privateFiles.get(file).add(subject.symbol ?? null);
+  }
+  const checker = program.getTypeChecker();
+  for (const source of program.getSourceFiles()) {
+    const file = source.fileName;
+    if (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "controllers"), file) && !privateFiles.has(file)) continue;
+    const wholeFile = isInside(path.join(dsRoot, "controllers"), file) || privateFiles.get(file)?.has(null);
+    const subjects = wholeFile ? [] : checker.getSymbolsInScope(source, ts.SymbolFlags.Value).filter(symbol => privateFiles.get(file)?.has(symbol.name)).flatMap(symbol => symbol.declarations ?? []);
+    const headless = node => wholeFile || subjects.some(subject => subject.getSourceFile() === source && node.pos >= subject.pos && node.end <= subject.end);
+    function emit(node, rule, message) { const p = source.getLineAndCharacterOfPosition(node.getStart()); report(file, rule, message, p.line + 1, p.character + 1); }
+    function visit(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) {
+        const typeOnly = ts.isImportDeclaration(node) && (node.importClause?.isTypeOnly || node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) && !node.importClause.name && node.importClause.namedBindings.elements.every(item => item.isTypeOnly)) || ts.isExportDeclaration(node) && node.isTypeOnly;
+        if (!typeOnly) {
+          if (wholeFile && /^(?:@linaria\/|.*\.css(?:[?#].*)?$)/.test(specifier)) emit(node, "controller-skin", "Controllers own behavior and measurements. Put CSS/Linaria skins in the consuming component or pattern.");
+          const framework = /^(?:react|react-dom)(?:\/|$)/.test(specifier) ? "react" : /^preact(?:\/|$)/.test(specifier) ? "preact" : null;
+          if (framework && config.framework !== framework) emit(node, "controller-framework", `Controller imports ${framework}, but ds.config.json selects ${config.framework ?? "no framework"}. Use the configured framework or plain TypeScript/browser APIs; MCP hosts do not supply another runtime.`);
+          const targets = resolve(specifier, file);
+          const local = specifier.startsWith(".") || specifier === config.publicAlias || targets.some(target => isInside(root, target) && !target.includes(`${path.sep}node_modules${path.sep}`) && existsSync(target));
+          if (local) {
+            if (targets.some(target => !existsSync(target))) emit(node, "controller-dependency", `Unresolved controller dependency ${specifier}. Declare real project dependencies and local modules; do not assume MCP host globals.`);
+            if (isInside(path.join(dsRoot, "controllers"), file)) {
+              const targetsInUi = targets.some(target => ["components", "patterns"].some(kind => isInside(path.join(dsRoot, kind), target)));
+              if (targetsInUi) emit(node, "controller-dependency", "Shared controllers cannot import component/pattern runtime implementations. Pass behavior adapters or callbacks from the consumer; type-only imports are allowed.");
+              if (specifier === config.publicAlias) {
+                for (const item of node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) ? node.importClause.namedBindings.elements : []) {
+                  let symbol = checker.getSymbolAtLocation(item.name);
+                  if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+                  if (symbol?.declarations?.some(declaration => ["components", "patterns"].some(kind => isInside(path.join(dsRoot, kind), declaration.getSourceFile().fileName)))) emit(item, "controller-dependency", "Shared controllers consume behavior helpers, not styled component/pattern implementations.");
+                }
+                if (!node.importClause?.namedBindings || ts.isNamespaceImport(node.importClause.namedBindings)) emit(node, "controller-dependency", "Use explicit behavior imports in shared controllers so dependency ownership can be checked.");
+              }
+            }
+          } else if (!isBuiltin(specifier)) {
+            const name = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+            if (!declared.has(name)) emit(node, "controller-dependency", `Undeclared controller dependency ${name}. Register it in the project package; ADS does not install dependencies or receive them from an MCP host.`);
+          }
+        }
+      }
+      if (headless(node) && ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)
+        || ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement" && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0]))) emit(node, "controller-skin", "Visual DOM markup belongs in components/patterns. Controllers may use framework hooks and context providers.");
+      if (!wholeFile && headless(node) && (ts.isTaggedTemplateExpression(node) || ts.isCallExpression(node))) {
+        let base = ts.isTaggedTemplateExpression(node) ? node.tag : node.expression;
+        while (ts.isPropertyAccessExpression(base) || ts.isCallExpression(base)) base = base.expression;
+        if (checker.getSymbolAtLocation(base)?.declarations?.some(declaration => ts.isImportSpecifier(declaration) && declaration.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/")
+          || ts.isNamespaceImport(declaration) && declaration.parent.parent.moduleSpecifier.text.startsWith("@linaria/"))) emit(node, "controller-skin", "Keep Linaria styling outside the declared private controller subject, in its visual consumer.");
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+}

package/dist/bootstrap-ds/ADS.md

@@ -241,3 +241,10 @@ Run `npm run build` after adding or changing components. Add meaningful tests
 for stateful behavior, accessibility, gestures, or async lifecycle where needed.
 Run `npm run dev` to inspect the real showcase. A screenshot alone does not
 verify interaction or animation. Generated output and dependencies are not source.
+
+Shared behavior may live in `controllers/<Name>/`; private controllers stay with
+their component/pattern. Use the configured framework and declared dependencies.
+Behavior contracts/checks are development-only, and scenario `exercises` links
+public hooks to demonstrations separately from rendered `covers`. Read the
+installed ADS package's `docs/BEHAVIORS.md` or MCP `ads://guides/behaviors` before
+registering guarantees, profiles and verification.

package/dist/boundaries.mjs

@@ -90,31 +90,29 @@ function isWrite(node) {
     || ts.isDeleteExpression(parent);
 }
 
-// Inspects style access itself, so aliases, computed keys, cssText and bulk writes
-// cannot silently turn a narrow property exception into a whole-file exception.
+/** Exact writes and known reads share one interpretation with exception audits.
+ * undefined = unrelated, false = read, null = unknown/bulk, string = exact write. */
+export function styleAccessProperty(node) {
+  if (!isMember(node) || memberName(node) !== "style") return undefined;
+  const access = unwrapped(node), parent = access.parent;
+  if (!isMember(parent) || parent.expression !== access) return null;
+  const property = cssName(memberName(parent)), target = unwrapped(parent);
+  if (ts.isCallExpression(target.parent) && target.parent.expression === target) {
+    if (["set-property", "remove-property"].includes(property)) {
+      const name = target.parent.arguments[0];
+      return name && ts.isStringLiteralLike(name) ? name.text : null;
+    }
+    return ["get-property-value", "get-property-priority", "item"].includes(property) ? false : null;
+  }
+  if (isWrite(target)) return property ?? null;
+  return property && !["set-property", "remove-property"].includes(property) ? false : null;
+}
+
+// Aliases, computed keys, cssText and bulk writes cannot widen an exception.
 export function styleWriteViolation(node, filename, { root, config }) {
   const allowed = config.boundaries.styleWrites.find((boundary) => path.resolve(root, boundary.file) === filename)?.properties ?? [];
-  if (isMember(node) && memberName(node) === "style") {
-    const access = unwrapped(node);
-    const parent = access.parent;
-    let property;
-    if (isMember(parent) && parent.expression === access) {
-      property = cssName(memberName(parent));
-      const target = unwrapped(parent);
-      if (ts.isCallExpression(target.parent) && target.parent.expression === target) {
-        if (["set-property", "remove-property"].includes(property)) {
-          const name = target.parent.arguments[0];
-          property = name && ts.isStringLiteralLike(name) ? name.text : null;
-        } else if (["get-property-value", "get-property-priority", "item"].includes(property)) return null;
-        else property = null;
-      } else if (!isWrite(target)) {
-        // Plain property reads are allowed. Passing a method reference or a
-        // computed member elsewhere is not a known property read.
-        if (property && !["set-property", "remove-property"].includes(property)) return null;
-        property = null;
-      }
-    }
-    if (property && property !== "css-text" && allowed.includes(property)) return null;
+  const property = styleAccessProperty(node);
+  if (property !== undefined && property !== false && !(property && property !== "css-text" && allowed.includes(property))) {
     return "Imperative styles require a file boundary and an explicit property. Bulk writes, computed property names, and style-object escapes are forbidden.";
   }
   if (ts.isCallExpression(node) && isMember(node.expression) && ["setAttribute", "setAttributeNS"].includes(memberName(node.expression))) {

package/dist/check.mjs

@@ -14,8 +14,14 @@ import { inspectShowcasePages } from "./showcase.mjs";
 import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
 import { inspectScenarioCoverage } from "./scenarios.mjs";
 import { uiOperation, importedUiApi } from "./ui-framework.mjs";
+import { inspectStyleBoundaries, pointerCaptureAdvisories } from "./style-boundaries.mjs";
+import { inspectBehaviors, inspectControllers } from "./behaviors.mjs";
+import { numericCssUnit, tokenLengthLiteral } from "./css-values.mjs";
 import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
 
+const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
+const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
+
 const showcaseControls = new Set(["a", "button", "input", "select", "textarea", "option", "optgroup", "table", "thead", "tbody", "tfoot", "tr", "td", "th", "dialog", "details", "summary", "progress", "meter"]);
 const svgTags = new Set(["svg", "g", "path", "circle", "rect", "ellipse", "line", "polyline", "polygon", "text", "tspan", "use", "defs", "clipPath", "mask", "filter", "linearGradient", "radialGradient", "stop", "marker", "pattern"]);
 const svgPresentation = new Set(["strokeWidth", "strokeLinecap", "strokeLinejoin", "strokeDasharray", "strokeDashoffset", "strokeOpacity", "strokeMiterlimit", "fillRule", "fillOpacity", "clipRule", "clipPath", "colorInterpolation", "colorInterpolationFilters", "floodColor", "floodOpacity", "stopColor", "stopOpacity", "fontFamily", "fontSize", "fontStyle", "fontWeight", "letterSpacing", "textAnchor", "dominantBaseline", "markerStart", "markerMid", "markerEnd", "vectorEffect", "shapeRendering", "textRendering", "paintOrder", "alignmentBaseline", "baselineShift", "transformOrigin"]);
@@ -24,7 +30,7 @@ const widgetRoles = new Set(["button", "link", "checkbox", "radio", "switch", "c
 export function checkProject(directory, { trackingRoot } = {}) {
   const options = { ...loadConfig(directory), ...(trackingRoot ? { trackingRoot: path.resolve(trackingRoot) } : {}) };
   const { root, config, dsRoot, sourceRoot } = options;
-  const diagnostics = [];
+  const diagnostics = [], advisories = [];
   for (const [field, file] of [["dsDir", dsRoot], ["publicEntry", path.join(dsRoot, config.publicEntry)], ["stylesEntry", path.join(dsRoot, config.stylesEntry)]]) {
     if (!existsSync(file) || (field === "dsDir" ? !statSync(file).isDirectory() : !statSync(file).isFile())) diagnostics.push({ rule: "project-structure", file: path.relative(root, file), line: 1, column: 1, message: `Missing or invalid ${field}. Bootstrap an empty ADS or configure its actual path.` });
   }
@@ -36,16 +42,21 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const resolveImport = importResolver(options);
   const rootHtml = path.join(root, "index.html");
   const files = [...new Set([...sourceFiles(sourceRoot), ...sourceFiles(dsRoot), ...(existsSync(rootHtml) ? [rootHtml] : [])])];
-  const scriptFiles = files.filter((file) => /\.[cm]?[jt]sx?$/.test(file));
+  const boundaryFiles = [...config.inlineStyleFiles, ...config.boundaries.styleWrites.map(entry => entry.file)].map(file => path.resolve(root, file)).filter(file => existsSync(file) && statSync(file).isFile());
+  const scriptFiles = [...new Set([...files, ...boundaryFiles])].filter((file) => /\.[cm]?[jt]sx?$/.test(file));
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
   function report(file, rule, message, line = 1, column = 1) {
     diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
   }
+  inspectStyleBoundaries(options, program, report);
   inspectShowcasePages(options, program, resolveImport, report);
   inspectShowcaseCoverage(options, program, report);
-  inspectScenarioCoverage(options, program, report);
+  inspectScenarioCoverage(options, program, report, (file, rule, message) => advisories.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line: 1, column: 1 }));
+  const behaviors = inspectBehaviors(options, program);
+  diagnostics.push(...behaviors.diagnostics);
+  inspectControllers(options, program, report, behaviors.contracts);
   // The foundation remains a fixed import-only entry, not an extra styling layer.
   const foundationEntry = path.join(dsRoot, config.stylesEntry);
   try {
@@ -60,7 +71,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     try { css = postcss.parse(text, { from: file }); }
     catch (error) { report(file, "css-syntax", error.reason ?? error.message, offset.line + (error.line ?? 1) - 1); return; }
     if (!foundation && (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry)) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
-    if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", "Scenarios and fixtures define no styles. Put the frame/layout in a public ADS pattern and product UI in ADS components or patterns.", offset.line);
+    if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", `Scenarios and fixtures define no styles. ${scenarioLayoutGuidance}`, offset.line);
     css.walkAtRules("import", (rule) => {
       if (foundation) report(file, "foundation-import", "Import foundation sheets through the configured styles entry. Token sheets cannot import an unchecked styling layer.", rule.source.start.line);
       const first = valueParser(rule.params).nodes.find((node) => node.type !== "space" && node.type !== "comment");
@@ -108,7 +119,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const violations = new Set();
       valueParser(decl.value).walk((node) => {
         if (node.type === "function" && node.value === "url") return false;
-        if (node.type === "word" && /^(?:#[\da-f]{3,8}|[-+]?(?:\d*\.)?\d+(?:px|rem|em|m?s))$/i.test(node.value)) violations.add("Use a token for colors, dimensions, and durations.");
+        if (node.type === "word" && (/^#[\da-f]{3,8}$/i.test(node.value) || tokenLengthLiteral(node.value) || ["s", "ms"].includes(numericCssUnit(node.value)))) violations.add("Use a token for colors, absolute/font-relative lengths (including ch), and durations. Unitless geometry and structural angle/viewport/container relationships remain valid.");
         if (node.type === "function" && /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|cubic-bezier)$/.test(node.value)) violations.add("Define color formulas and easing in tokens.");
         if (node.type === "function" && /^(?:blur|brightness|contrast|drop-shadow|grayscale|hue-rotate|invert|saturate|sepia)$/.test(node.value)) violations.add("Define visual filter effects in tokens.");
         if (node.type === "word" && /^ease(?:-in|-out|-in-out)?$/.test(node.value)) violations.add("Use a motion token for easing.");
@@ -128,6 +139,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     const source = program.getSourceFile(file);
     if (!source) continue;
+    advisories.push(...pointerCaptureAdvisories(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
     for (const diagnostic of program.getSyntacticDiagnostics(source)) {
       const position = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
       report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);
@@ -186,14 +198,14 @@ export function checkProject(directory, { trackingRoot } = {}) {
         for (const property of properties) {
           if (!ts.isPropertyAssignment(property) || !(ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name))) continue;
           if (tag && ts.isStringLiteralLike(tag) && svgTags.has(tag.text) && importedUiApi(node.expression, checker)?.module === "preact") checkSvgAttribute(property, property.name.text);
-          if (property.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(property, "no-inline-style", "UI factories follow the same style ownership as JSX. Use semantic ADS props or a narrow renderer boundary.");
+          if (property.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(property, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
           if (property.name.text === "style") inspectProperty(property.initializer);
           if (property.name.text === "className") inspectClass(property.initializer);
-          if (showcase && property.name.text === "className") nodeReport(property, "showcase-class", "Scenarios use public ADS props, not custom class names.");
+          if (showcase && property.name.text === "className") nodeReport(property, "showcase-class", `Scenarios define no custom class names. ${scenarioLayoutGuidance}`);
         }
         if (showcase && tag && ts.isStringLiteralLike(tag)) {
           const role = properties.find(property => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === "role")?.initializer;
-          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) nodeReport(node, "showcase-control", "Scenario controls must render public ADS components.");
+          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) nodeReport(node, "showcase-control", `Scenario controls must render public ADS components for actual interaction. ${scenarioLayoutGuidance}`);
         }
       }
       if (isInside(dsRoot, file) && (ts.isIdentifier(node) && ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"].includes(node.text) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node))) {
@@ -204,9 +216,9 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (showcase && (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
         const role = node.attributes.properties.find((attr) => ts.isJsxAttribute(attr) && attr.name.text === "role")?.initializer;
         const roleValue = role && ts.isStringLiteralLike(role) ? role.text : role && ts.isJsxExpression(role) && role.expression && ts.isStringLiteralLike(role.expression) ? role.expression.text : null;
-        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) nodeReport(node, "showcase-control", "Showcase and mock controls must use public ADS components. Implement missing reusable controls in the ADS, then import them here.");
+        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) nodeReport(node, "showcase-control", `Scenario controls must render public ADS components for actual interaction. ${scenarioLayoutGuidance}`);
       }
-      if (showcase && ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className") nodeReport(node, "showcase-class", "Showcase and mocks use known public ADS entities and props, not custom class names. Put styling in the owning ADS component or frame pattern.");
+      if (showcase && ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className") nodeReport(node, "showcase-class", `Scenarios define no custom class names. ${scenarioLayoutGuidance}`);
       let specifier;
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifier = node.arguments[0].text;
@@ -214,13 +226,13 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
       if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
       if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");
-      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", "Move visual policy into the local ADS, or document a narrow measured-geometry exception in inlineStyleFiles.");
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && node.initializer) {
         inspectProperty(node.initializer);
       }
       const mutation = styleWriteViolation(node, file, options);
       if (mutation) nodeReport(node, "style-mutation", mutation);
-      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Do not expose CSSProperties-based visual plumbing. Use semantic props, or document a narrow JSX renderer boundary.");
+      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Keep CSSProperties out of the public API. Use deliberate component contracts or a documented measured-geometry renderer boundary; demo layout belongs in a public review pattern.");
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className" && node.initializer) {
         inspectClass(node.initializer);
       }
@@ -234,5 +246,5 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     visit(source);
   }
-  return { ok: diagnostics.length === 0, diagnostics };
+  return { ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) };
 }

package/dist/cli.mjs

@@ -11,6 +11,8 @@ Usage: ads init [options]           Run inside your project
 
   init                 Set up ADS in the current project (requires package.json)
   check [directory]    Check tokens, ownership, imports, and showcase coverage
+  behaviors [dir]      Inspect behavior contracts and current verification evidence
+  verify [directory]   Run registered behavior checks (--unit and --check select)
   tokens [directory]   Inspect local token values and theme definitions
   assets [directory]   Generate standard web icons in .ds/assets from assets.iconSource
   lint-config [dir]    Generate .ds/oxlintrc.json with core and project plugins
@@ -25,6 +27,8 @@ Usage: ads init [options]           Run inside your project
   --port number        MCP/showcase only: loopback website port (default: automatic)
   --no-showcase        MCP only: disable the local website
   --mutations          MCP only: enable guarded ADS source editing
+  --unit id            Verify only: select one discovered behavior contract owner
+  --check id           Verify only: select a registered check (repeatable)
 
 External components and examples are imported using the ADS skills.
 No component library or example catalogue is bundled.
@@ -38,6 +42,8 @@ async function main(args) {
   let packageManager;
   let framework;
   let port;
+  let unit;
+  const selectedChecks = [];
   let showcase = true;
   let mutations = false;
   const positional = [];
@@ -46,6 +52,12 @@ async function main(args) {
     if (argument === "--json") json = true;
     else if (argument === "--no-showcase") showcase = false;
     else if (argument === "--mutations") mutations = true;
+    else if (argument === "--unit" || argument === "--check") {
+      const value = args[++index];
+      if (!value || value.startsWith("-")) throw new Error(`${argument} needs a discovered unit/check ID.`);
+      if (argument === "--unit") { if (unit) throw new Error("Specify one --unit."); unit = value; }
+      else selectedChecks.push(value);
+    }
     else if (argument === "--port") {
       const value = args[++index];
       if (port !== undefined || !/^\d+$/.test(value ?? "") || Number(value) > 65535) throw new Error("--port requires one port between 0 and 65535.");
@@ -72,6 +84,7 @@ async function main(args) {
   if (packageManager !== undefined && command !== "init") throw new Error("--package-manager is supported only by init.");
   if (framework !== undefined && command !== "init") throw new Error("--framework is supported only by init.");
   if (command === "init" && directory) throw new Error("Run ads init inside the project, without a directory argument.");
+  if ((unit || selectedChecks.length) && command !== "verify") throw new Error("--unit and --check are supported only by verify.");
   const target = path.resolve(directory ?? process.cwd());
   if (command === "mcp" || command === "showcase") {
     if (json) throw new Error("--json is not supported by mcp/showcase; mcp reserves stdout for JSON-RPC.");
@@ -82,6 +95,8 @@ async function main(args) {
   let result;
   if (command === "init") result = initProject(target, { toolPackage, packageManager, framework });
   else if (command === "check") result = checkProject(target);
+  else if (command === "behaviors") { const {behaviorStatus}=await import("./verification.mjs"); const {loadConfig}=await import("./config.mjs"); result=behaviorStatus(loadConfig(target)); }
+  else if (command === "verify") { const {createVerificationController}=await import("./verification.mjs"); const verification=createVerificationController(target); try {result=await verification.run({...(unit?{unit}:{}),...(selectedChecks.length?{checks:selectedChecks}:{})});} finally {await verification.close();} }
   else if (command === "tokens") result = inspectTokens(target);
   else if (command === "assets") result = await generateBrandAssets(target);
   else if (command === "lint-config") result = generateLintConfig(target);
@@ -90,12 +105,15 @@ async function main(args) {
   else if (command === "init") console.log(`Initialized ${target}\nFramework: ${result.framework}\nAdded ${result.toolDependency.name} (${result.toolDependency.spec}) as a development dependency.\nRun ${result.packageManager} install and ${result.packageManager} run build; the build refreshes lint configuration, runs ADS checks, and generates configured brand assets automatically.`);
   else if (command === "assets") console.log(result.skipped ? "No assets.iconSource configured; brand generation skipped." : `Generated ${result.files.length} brand assets in ${result.directory}.`);
   else if (command === "lint-config") console.log(`Generated ${result.file}\nProjects initialized with ads init refresh this automatically during lint:ds/build.`);
+  else if (command === "behaviors") console.log(JSON.stringify(result, null, 2));
+  else if (command === "verify") { for (const item of result.results) console.log(`${item.unit}#${item.check}: ${item.status} (${item.profile})`); }
   else if (command === "tokens") {
     for (const token of result.tokens) console.log(`${token.name}${token.type ? ` (${token.type})` : ""}: ${token.definitions.map((entry) => `${entry.scope}: ${entry.value}`).join("; ")}`);
   } else if (result.ok) console.log(`ADS check passed: ${target}`);
   if (!json && result.diagnostics?.length) {
     for (const diagnostic of result.diagnostics) console.error(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.rule}] ${diagnostic.message}`);
   }
+  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [advisory:${advisory.rule}] ${advisory.message}`);
   if (result.ok === false || result.diagnostics?.length) process.exitCode = 1;
 }
 

package/dist/config.mjs

@@ -17,7 +17,7 @@ export const defaultConfig = {
   boundaries: { styleWrites: [], componentVariables: [] },
   assets: { publicDirs: ["public/assets"], generatedPaths: ["dist", "dist-showcase", ".vite", ".ds"], generatedFiles: [], iconSource: null },
   oxlint: { plugins: [], rules: {}, overrides: [] },
-  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null },
+  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null, behaviorProfiles: {} },
 };
 
 export function isInside(parent, file) {
@@ -100,6 +100,18 @@ export function loadConfig(directory = process.cwd()) {
   }
   if (config.mcp.showcaseTitle !== null && (typeof config.mcp.showcaseTitle !== "string" || !config.mcp.showcaseTitle.trim() || config.mcp.showcaseTitle.length > 120)) throw new Error("mcp.showcaseTitle must be a non-empty title of at most 120 characters or null.");
   if (!Array.isArray(config.mcp.apps)) throw new Error("mcp.apps must be an array of built project previews.");
+  if (!config.mcp.behaviorProfiles || typeof config.mcp.behaviorProfiles !== "object" || Array.isArray(config.mcp.behaviorProfiles) || Object.keys(config.mcp.behaviorProfiles).length > 20) throw new Error("mcp.behaviorProfiles must be an object of up to 20 registered execution profiles.");
+  for (const [name, profile] of Object.entries(config.mcp.behaviorProfiles)) {
+    if (!/^[a-zA-Z0-9][\w.-]{0,79}$/.test(name) || !profile || typeof profile !== "object" || Array.isArray(profile)
+      || Object.keys(profile).some(key => !["command", "args", "timeoutMs", "runner", "framework", "mode"].includes(key))
+      || typeof profile.command !== "string" || !profile.command.trim() || profile.command.includes("\0")
+      || !Array.isArray(profile.args) || profile.args.some(arg => typeof arg !== "string" || arg.includes("\0"))
+      || !["protocol", "playwright"].includes(profile.runner ?? "protocol")
+      || profile.framework !== undefined && profile.framework !== config.framework
+      || profile.mode !== undefined && !["browser", "strict", "unit"].includes(profile.mode)
+      || profile.timeoutMs !== undefined && (!Number.isInteger(profile.timeoutMs) || profile.timeoutMs < 100 || profile.timeoutMs > 300000)) throw new Error(`Invalid behavior profile ${name}. Use literal executable/args, a protocol or Playwright runner, a matching framework and a bounded timeout. Profiles do not install dependencies or receive APIs from an MCP host.`);
+    if (profile.mode === "strict" && config.framework !== "react") throw new Error(`Behavior profile ${name}: React StrictMode requires framework react; use the configured framework's lifecycle tests instead.`);
+  }
   if (config.mcp.mutationChecks !== null && (!Array.isArray(config.mcp.mutationChecks) || config.mcp.mutationChecks.length > 12 || new Set(config.mcp.mutationChecks).size !== config.mcp.mutationChecks.length || config.mcp.mutationChecks.some(name => typeof name !== "string" || !/^[a-zA-Z0-9][\w:.-]*$/.test(name)))) throw new Error("mcp.mutationChecks must be null or up to 12 unique package script names.");
   if (config.mcp.previewManifest !== null) {
     const manifest = projectPath(root, config.mcp.previewManifest, "mcp.previewManifest");
@@ -136,10 +148,14 @@ export function isFixtureFile(file) {
 }
 
 /** File role, rather than folder location, keeps colocated preview code private. */
+export function isBehaviorFile(file) {
+  return /(?:^|[\\/])behavior\.json$|\.behavior\.json$/.test(file);
+}
+
 export function isDevelopmentFile(file, { dsRoot }) {
   if (!isInside(dsRoot, file)) return isTestFile(file);
   const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file)
+  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file)
     || /^(?:showcase|composition)\//.test(relative)
     || /(?:^|\/)(?:scenario|fixtures)(?:\/|$)/.test(relative)
     || /\.scenario(?:-adapter)?\.[cm]?[jt]sx?$/.test(relative);
@@ -154,7 +170,7 @@ export function sourceFiles(root) {
     if (ignored.has(entry.name) || entry.isSymbolicLink()) continue;
     const file = path.join(root, entry.name);
     if (entry.isDirectory()) files.push(...sourceFiles(file));
-    else if (entry.isFile() && /\.(css|html|[cm]?[jt]sx?)$/.test(entry.name)) files.push(file);
+    else if (entry.isFile() && (/\.(css|html|[cm]?[jt]sx?)$/.test(entry.name) || isBehaviorFile(entry.name))) files.push(file);
   }
   return files.sort();
 }

package/dist/css-values.mjs

@@ -0,0 +1,26 @@
+import valueParser from "postcss-value-parser";
+
+// CSS-language categories, independent of any project's token names or values.
+// https://www.w3.org/TR/css-values-4/#lengths
+const absoluteLengths = new Set(["px", "cm", "mm", "q", "in", "pt", "pc"]);
+const fontLengths = new Set(["em", "rem", "ex", "rex", "cap", "rcap", "ch", "rch", "ic", "ric", "lh", "rlh"]);
+const responsiveLength = /^(?:[sld]?v(?:w|h|i|b|min|max)|cq(?:w|h|i|b|min|max))$/;
+
+export function numericCssUnit(value) {
+  const parsed = valueParser.unit(value);
+  return parsed ? parsed.unit.toLowerCase() : null;
+}
+
+/** Skin lengths use tokens regardless of font metrics, physical units or notation.
+ * Responsive viewport/container relationships retain their structural treatment. */
+export function tokenLengthLiteral(value) {
+  const unit = numericCssUnit(value);
+  return absoluteLengths.has(unit) || fontLengths.has(unit);
+}
+
+/** The same CSS categories apply to length-valued foundation tokens. */
+export function dimensionValue(value) {
+  const unit = numericCssUnit(value);
+  return unit !== null && (absoluteLengths.has(unit) || fontLengths.has(unit)
+    || responsiveLength.test(unit) || unit === "%" || unit === "" && Number(value) === 0);
+}

package/dist/index.mjs

@@ -7,3 +7,5 @@ export { generateBrandAssets } from "./brand-assets.mjs";
 // same validated configuration and property boundary as the core checker.
 export { loadConfig } from "./config.mjs";
 export { importResolver, styleWriteViolation } from "./boundaries.mjs";
+export { inspectBehaviors } from "./behaviors.mjs";
+export { behaviorStatus, createVerificationController } from "./verification.mjs";

package/dist/init.mjs

@@ -183,7 +183,7 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
     }
     updates.set(entryFile, current + "\n" + reviewExport);
   }
-  for (const section of ["components", "patterns", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
+  for (const section of ["components", "patterns", "controllers", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
   addMissing(path.join(dsRoot, "assets/brand/README.md"), readFileSync(path.join(starter, "design-system/assets/brand/README.md")));
   addMissing(path.join(dsRoot, "assets/fonts/.gitkeep"), "");
   const configFile = path.join(root, "ds.config.json");