@reqvire-org/ads 0.3.3 → 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/check.mjs

@@ -15,6 +15,8 @@ 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.";
@@ -51,7 +53,10 @@ export function checkProject(directory, { trackingRoot } = {}) {
   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 {
@@ -114,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.");

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,6 +105,8 @@ 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}`);

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");

package/dist/mcp/build-status.mjs

@@ -10,7 +10,8 @@ export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json"
 const maxBytes = 256 * 1024;
 const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional(), code: z.string().max(100).optional() }).strict();
 const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
-const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
+const progressSchema = z.object({ phase: z.enum(["queued", "validation", "compilation", "validation-and-compilation", "publication", "idle"]), startedAt: z.string().datetime(), updatedAt: z.string().datetime() }).strict();
+const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), progress: progressSchema.optional(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
 export const artifactDigest = (file) => {
   if (realpathSync(file) !== file) throw new Error("Preview output cannot resolve through a symlink.");
   if (statSync(file).size > 2 * 1024 * 1024) throw new Error("Preview exceeds 2 MiB.");
@@ -37,8 +38,9 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   const entries = new Map(apps.map((app) => [app.id, { id: app.id, state: "idle", revision: 0, lastSuccessfulRevision: null, artifactDigest: null, diagnostics: [] }]));
   let sequence = 0;
   let diagnostics = [];
+  let progress;
   function save() {
-    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()], ...(diagnostics.length ? { diagnostics } : {}) };
+    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()], ...(progress ? { progress } : {}), ...(diagnostics.length ? { diagnostics } : {}) };
     let text = JSON.stringify(snapshot.parse(value));
     // A shared graph failure applies to every scenario. Store repeated details
     // once only when necessary; ordinary reports retain inline diagnostics.
@@ -67,6 +69,11 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   save();
   return {
     session,
+    progress(phase) {
+      const now = new Date().toISOString();
+      progress = { phase, startedAt: !progress || progress.phase === "idle" ? now : progress.startedAt, updatedAt: now };
+      save();
+    },
     failure(error) {
       diagnostics = (Array.isArray(error) ? error : [error]).slice(0, 20).map(error => normalizeDiagnostic(root, error));
       for (const value of entries.values()) { value.state = "error"; ++value.revision; value.diagnostics = []; }
@@ -153,7 +160,7 @@ export function inspectBuildStatus(root, config, { session, processState, file =
       current, stale: state === "unreported" ? null : !current, available, diagnostics };
   });
   const state = reportError || report?.diagnostics?.length || previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
-  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };
+  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, ...(report?.progress ? { progress: report.progress } : {}), previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };
 }
 
 export class PreviewBuildError extends Error {

package/dist/mcp/catalog.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import ts from "typescript";
 import { isInside, sourceFiles } from "../config.mjs";
 import { projectCompilerOptions } from "../boundaries.mjs";
-import { publicUi } from "../scenarios.mjs";
+import { publicApi } from "../public-api.mjs";
 import { projectGuideFiles } from "../project-documents.mjs";
 
 export const PROJECT_URI = "ads://project";
@@ -24,7 +24,7 @@ export function projectDocuments(options) {
   for (const name of projectGuideFiles(root)) files.push(path.join(root, name));
   return [...new Set(files)].filter((file) => isInside(root, realpathSync(file))).sort().map((file) => {
     const relative = path.relative(root, file).replaceAll("\\", "/");
-    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : "text/plain", file };
+    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : file.endsWith(".json") ? "application/json" : "text/plain", file };
   });
 }
 
@@ -32,27 +32,30 @@ export function inspectCatalog(options, scenarios = []) {
   const { root, dsRoot, config } = options;
   const entry = path.join(dsRoot, config.publicEntry);
   if (!existsSync(entry)) return [];
-  const program = ts.createProgram([entry], projectCompilerOptions(options));
+  const program = ts.createProgram([entry], { ...projectCompilerOptions(options), allowJs: true });
   const checker = program.getTypeChecker();
   const source = program.getSourceFile(entry);
   const module = source && checker.getSymbolAtLocation(source);
   if (!module) return [];
   const documents = projectDocuments(options);
   const items = [];
-  const renderable = new Set(publicUi(program, options).filter(item => item.renderable).map(item => item.name));
+  const api = new Map(publicApi(program, options).map(item => [item.name, item]));
   for (const exported of checker.getExportsOfModule(module)) {
     let symbol = exported;
     if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
     const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
-    if (!(symbol.flags & ts.SymbolFlags.Value) || !declaration || !renderable.has(exported.name)) continue;
+    if (!(symbol.flags & ts.SymbolFlags.Value) || !declaration || !api.has(exported.name)) continue;
     const file = declaration.getSourceFile().fileName;
-    const kind = isInside(path.join(dsRoot, "components"), file) ? "components" : isInside(path.join(dsRoot, "patterns"), file) ? "patterns" : null;
+    const kind = api.get(exported.name).kind;
+    const ui = api.get(exported.name).renderable;
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    if (!ui && !type.getCallSignatures().length && !type.getConstructSignatures().length) continue;
     if (!kind) continue;
     const relative = path.relative(root, file).replaceAll("\\", "/");
     const line = declaration.getSourceFile().getLineAndCharacterOfPosition(declaration.getStart()).line + 1;
     const guides = documents.filter((doc) => doc.file.endsWith(".md") && path.dirname(doc.file) === path.dirname(file)).map((doc) => doc.uri);
-    items.push({ name: exported.name, kind, importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
-      previews: scenarios.filter(item => item.covers.includes(exported.name)).map(item => item.id) });
+    items.push({ name: exported.name, kind, apiKind: ui ? "ui" : "behavior", importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
+      previews: scenarios.filter(item => item.covers.includes(exported.name) || item.exercises?.includes(exported.name)).map(item => item.id) });
   }
   return items.sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/mcp/context.mjs

@@ -5,7 +5,7 @@ import { projectGuideFiles } from "../project-documents.mjs";
 
 export const GUIDE_URI = "ads://project/guide";
 // Put the task triggers and entry path first: some hosts shorten server guidance.
-export const serverInstructions = "Use ADS for UI work: components, patterns, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner at a time. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
+export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner at a time. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
 
 function manager(root, pkg) {
   if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
@@ -35,7 +35,7 @@ export function workflow(previews) {
     next: "Find the requested public UI with ads_catalog (query + kind + small limit), then read its source/guide and one selected ADS skill. For a broad UI request, inspect the public barrel and targeted application entry files in sourceRoot.",
     skills: [
       { task: "Build, refine or debug UI using the project ADS", name: "ads-designer" },
-      { task: "Adapt a component-library reference", name: "ads-assimilate" },
+      { task: "Adapt a component-library reference", name: "ads-migrate" },
       { task: "Import from another project's design-system", name: "ads-import" },
       { task: "Implement or review motion", name: "ads-motion" },
       { task: "Stress-test layout, states and interactions", name: "ads-break-ui" },

package/dist/mcp/mutations.mjs

@@ -5,6 +5,7 @@ import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, re
 import path from "node:path";
 import ts from "typescript";
 import { isInside, loadConfig } from "../config.mjs";
+import { affectedBehaviorUnits, createVerificationController } from "../verification.mjs";
 import { checkProject } from "../check.mjs";
 import { generateLintConfig } from "../lint-config.mjs";
 import { generateBrandAssets } from "../brand-assets.mjs";
@@ -260,6 +261,15 @@ export function createMutationController(directory) {
           verified.push({ name: "brand assets", passed: true, skipped: !!brand.skipped });
         }
         for (const check of extraChecks) verified.push(await checkCommand(check.command, check.args, candidate, signal));
+        const behaviorUnits = affectedBehaviorUnits(candidateOptions, changes.map(change => change.path));
+        if (behaviorUnits.length) {
+          const verification = createVerificationController(candidate);
+          let evidence;
+          try { evidence = await verification.run({ units: behaviorUnits, persist: false }, signal); }
+          finally { await verification.close(); }
+          if (!evidence.ok) return lastResult = { ok: false, applied: false, diagnostics: [...evidence.diagnostics, ...evidence.results.filter(item => item.status !== "passed").map(item => ({ rule: "behavior-check", message: `${item.unit}#${item.check}: ${item.status}. ${item.message}` }))].slice(0, 50), checks: verified, behavior: evidence };
+          verified.push({ name: "registered behavior checks", passed: true, results: evidence.results });
+        }
         if (signal?.aborted) throw fail("mutation-cancelled", "Mutation cancelled before application.");
         if (snapshot(candidateOptions) !== expected) throw fail("mutation-check", "A validation command changed source files. Use checks without source-writing side effects.");
         if (snapshot(loadConfig(root)) !== before) throw fail("mutation-conflict", "Project inputs changed during validation; no changes were applied. Read current source and retry.");

package/dist/mcp/preview-owner-guard.mjs

@@ -0,0 +1,29 @@
+import { spawn } from "node:child_process";
+
+// The only stdin writer is the MCP owner. EOF also arrives after SIGKILL or a
+// client launcher crash, when the owner's JavaScript cleanup cannot execute.
+const pid = Number(process.argv[2]);
+if (!Number.isSafeInteger(pid) || pid <= 1 || pid === process.pid) throw new Error("Invalid owned preview process group");
+let released = false, stopping = false, timer, input = "";
+function stop() {
+  if (released || stopping) return;
+  stopping = true;
+  if (process.platform === "win32") {
+    const terminator = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    terminator.on("error", () => { process.exitCode = 1; });
+    return;
+  }
+  try { process.kill(-pid, "SIGTERM"); }
+  catch (error) { if (error.code !== "ESRCH") process.exitCode = 1; return; }
+  timer = setTimeout(() => {
+    try { process.kill(-pid, "SIGKILL"); }
+    catch (error) { if (error.code !== "ESRCH") process.exitCode = 1; }
+  }, 1500);
+}
+process.stdin.on("data", bytes => {
+  input = (input + bytes).slice(-32);
+  if (input === "disarm\n") { released = true; clearTimeout(timer); }
+});
+for (const event of ["end", "close", "error"]) process.stdin.once(event, stop);
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, stop);
+process.stdin.resume();