@reqvire-org/ads 0.3.3 → 0.3.5

package/dist/verification/browser.mjs

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+
+/** Development-only Playwright helper. No browser or framework dependency is installed. */
+export function verificationRequest() {
+  if (!process.env.ADS_VERIFY_REQUEST) throw new Error("Run this check through ads_verify so the request and selected profile are explicit.");
+  return JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
+}
+
+export async function openBehaviorScenario(page, checkId, { timeout = 30000 } = {}) {
+  const request = verificationRequest();
+  const check = request.checks.find(check => check.id === checkId);
+  const url = check && request.scenarios[check.scenario];
+  if (!url) throw new Error("This check has no managed browser scenario. StrictMode profiles must supply a project development harness; production preview bundles do not replay React development effects.");
+  await page.goto(url, { waitUntil: "load", timeout });
+  const end = Date.now() + timeout;
+  while (Date.now() < end) {
+    for (const frame of page.frames().filter(frame => frame !== page.mainFrame())) {
+      const state = await frame.evaluate(() => ({ state: document.documentElement.dataset.adsPreviewState, id: document.documentElement.dataset.adsScenario, message: document.getElementById("ads-preview-status")?.textContent })).catch(() => ({}));
+      if (state.id === check.scenario && state.state === "ready") return frame;
+      if (state.state === "error") throw new Error(state.message || "The MCP App failed before verification.");
+    }
+    const error = await page.evaluate(() => document.querySelector('#status[data-error="true"]')?.textContent).catch(() => null);
+    if (error) throw new Error(error);
+    await page.waitForTimeout(50);
+  }
+  throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
+}

package/dist/verification/playwright-reporter.cjs

@@ -0,0 +1,20 @@
+const { readFileSync, writeFileSync } = require("node:fs");
+const path = require("node:path");
+
+/** Case identity is an explicit project test tag: @ads:<case-id>. */
+module.exports = class AdsBehaviorReporter {
+  constructor() {
+    this.request = JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
+    this.cases = [];
+  }
+  onTestEnd(test, result) {
+    const file = path.relative(this.request.projectRoot, test.location.file).replaceAll("\\", "/");
+    for (const tag of test.tags ?? []) {
+      if (!tag.startsWith("@ads:")) continue;
+      this.cases.push({ id: tag.slice(5), file, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", message: result.errors?.map(error => error.message).join("\n").slice(0, 4000) });
+    }
+  }
+  onEnd() {
+    writeFileSync(process.env.ADS_VERIFY_REPORT, JSON.stringify({ schemaVersion: 1, runId: this.request.runId, cases: this.cases.slice(0, 500) }));
+  }
+};

package/dist/verification.mjs

@@ -0,0 +1,214 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+import { loadConfig, sourceFiles, isInside } from "./config.mjs";
+import { importResolver } from "./boundaries.mjs";
+import { inspectUnits, configurationFiles } from "./units.mjs";
+import { inspectBehaviors } from "./behaviors.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+import { readPreviewManifest } from "./preview-resources.mjs";
+
+export const BEHAVIOR_URI = "ads://project/behaviors";
+const hash = bytes => createHash("sha256").update(bytes).digest("hex");
+const slash = file => file.replaceAll("\\", "/");
+const resultFile = root => path.join(root, ".ds/behavior-results.json");
+
+/** Follow real project imports; package/configuration changes also invalidate evidence. */
+function inputContext(options) { return { inventory: inspectUnits(options), scenarios: inspectScenarios(options).scenarios }; }
+
+export function behaviorInputs(options, contract, check, context = inputContext(options)) {
+  const files = new Set(), resolve = importResolver(options);
+  function visit(file) {
+    file = path.resolve(file);
+    if (files.has(file) || !isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    if (lstatSync(file).isSymbolicLink() || realpathSync(file) !== file) throw new Error(`Behavior inputs cannot resolve through symlinks: ${file}`);
+    if (!lstatSync(file).isFile()) return;
+    files.add(file);
+    const localAsset = specifier => {
+      if (!specifier || /^(?:[a-z][\w+.-]*:|\/|#)/i.test(specifier)) return;
+      visit(path.resolve(path.dirname(file), specifier.replace(/[?#].*$/, "")));
+    };
+    if (file.endsWith(".css")) {
+      const css = postcss.parse(readFileSync(file, "utf8"), { from: file });
+      css.walkAtRules("import", rule => { const first = valueParser(rule.params).nodes.find(node => node.type !== "space" && node.type !== "comment"); if (first?.type === "string") localAsset(first.value); });
+      css.walk(node => { if (node.type === "decl" || node.type === "atrule") valueParser(node.type === "decl" ? node.value : node.params).walk(value => { if (value.type === "function" && value.value.toLowerCase() === "url") localAsset(value.nodes.filter(part => part.type !== "space").map(part => part.value).join("")); }); });
+    }
+    if (!/\.[cm]?[jt]sx?$/.test(file)) return;
+    const ast = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    function walk(node) {
+      let specifier;
+      if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
+      if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require") && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) specifier = node.arguments[0].text;
+      if (specifier) for (const target of resolve(specifier, file)) visit(target);
+      if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "URL" && node.arguments?.[0] && ts.isStringLiteralLike(node.arguments[0])) localAsset(node.arguments[0].text);
+      if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0]))) {
+        // Computed module selection cannot provide a precise dependency closure.
+        // Conservatively invalidate against every owned ADS input instead.
+        for (const unit of context.inventory.units) for (const owned of unit.files) visit(path.join(options.root, owned));
+      }
+      ts.forEachChild(node, walk);
+    }
+    walk(ast);
+  }
+  for (const file of context.inventory.units.find(unit => unit.id === contract.unit)?.files ?? []) visit(path.join(options.root, file));
+  for (const file of configurationFiles(options)) visit(path.join(options.root, file));
+  for (const file of sourceFiles(path.join(options.dsRoot, options.config.tokenDir))) visit(file);
+  visit(path.join(options.dsRoot, options.config.stylesEntry));
+  const scenario = check.scenario && context.scenarios.find(item => item.id === check.scenario);
+  if (scenario) visit(path.join(options.root, scenario.file));
+  const rows = [...files].sort().map(file => [slash(path.relative(options.root, file)), hash(readFileSync(file))]);
+  for (const file of ["package-lock.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "node_modules/.package-lock.json"]) rows.push([file, existsSync(path.join(options.root, file)) ? hash(readFileSync(path.join(options.root, file))) : null]);
+  rows.push(["profile", JSON.stringify(options.config.mcp.behaviorProfiles[check.profile])], ["node", process.version]);
+  for (const file of ["./verification.mjs", "./verification/browser.mjs", "./verification/playwright-reporter.cjs"]) rows.push([`tool:${file}`, hash(readFileSync(new URL(file, import.meta.url)))]);
+  return { revision: hash(JSON.stringify(rows)), files: rows.map(([file]) => file) };
+}
+
+function saved(root) {
+  try {
+    const file = resultFile(root);
+    if (realpathSync(file) !== file || lstatSync(file).size > 2 * 1024 * 1024) return {};
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    return value.schemaVersion === 1 && value.results && typeof value.results === "object" && !Array.isArray(value.results) ? value.results : {};
+  } catch { return {}; }
+}
+const identity = (unit, check) => `${unit}#${check}`;
+
+export function behaviorStatus(options) {
+  const inventory = inspectBehaviors(options), evidence = saved(options.root);
+  const context = inventory.contracts.length ? inputContext(options) : null;
+  return { ...inventory, contracts: inventory.contracts.map(contract => {
+    const checks = Object.fromEntries(Object.entries(contract.checks).map(([id, check]) => {
+      const previous = evidence[identity(contract.unit, id)];
+      const revision = behaviorInputs(options, contract, check, context).revision;
+      const current = previous?.revision === revision && previous.profile === check.profile && previous.file === check.file && previous.case === check.case;
+      return [id, { ...check, result: previous ? { ...previous, current, status: current ? previous.status : "stale" } : { status: "not_run", current: false } }];
+    }));
+    return { ...contract, checks, guarantees: contract.guarantees.map(guarantee => {
+      const results = guarantee.checks.map(id => checks[id]?.result ?? { status: "unavailable", current: false });
+      const status = results.every(result => result.current && result.status === "passed") ? "passed" : results.find(result => result.status !== "passed")?.status ?? "not_run";
+      return { ...guarantee, result: { status, current: results.every(result => result.current) } };
+    }) };
+  }) };
+}
+
+export function affectedBehaviorUnits(options, changedFiles) {
+  const changed = new Set(changedFiles.map(file => slash(path.relative(options.root, path.resolve(options.root, file)))));
+  const contracts = inspectBehaviors(options).contracts;
+  if (!contracts.length) return [];
+  const context = inputContext(options);
+  return contracts.filter(contract => Object.values(contract.checks).some(check => behaviorInputs(options, contract, check, context).files.some(file => changed.has(file)))).map(contract => contract.unit);
+}
+
+function execute(profile, args, root, env, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(new Error("Behavior verification cancelled.")); return; }
+    let output = "", failure, child, guard, done = false;
+    const kill = () => {
+      if (!child?.pid) return;
+      if (process.platform === "win32") { const stop = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" }); stop.on("error", () => child.kill("SIGKILL")); }
+      else try { process.kill(-child.pid, "SIGKILL"); } catch (error) { if (error.code !== "ESRCH") failure ??= error; }
+    };
+    child = spawn(profile.command === "node" ? process.execPath : profile.command, args, { cwd: root, detached: process.platform !== "win32", shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+      env: { ...process.env, ...env, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) } });
+    if (child.pid) {
+      guard = spawn(process.execPath, [fileURLToPath(new URL("./mcp/preview-owner-guard.mjs", import.meta.url)), String(child.pid)], { detached: process.platform !== "win32", stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
+      guard.stdin.on("error", () => {});
+      guard.once("error", error => { failure = error; kill(); });
+      guard.once("exit", () => { if (!done) { failure ??= new Error("Verification ownership guard exited unexpectedly."); kill(); } });
+    }
+    const abort = () => { failure = new Error("Behavior verification cancelled."); kill(); };
+    signal.addEventListener("abort", abort, { once: true });
+    const timeout = setTimeout(() => { failure = new Error("Behavior verification timed out. Inspect the registered runner and its browser/server cleanup."); kill(); }, profile.timeoutMs ?? 60000);
+    for (const stream of [child.stdout, child.stderr]) stream.on("data", chunk => { output = (output + chunk.toString()).slice(-12000); });
+    child.once("error", error => { failure = error; });
+    child.once("exit", kill);
+    child.once("close", code => {
+      done = true; kill(); guard?.stdin.end("disarm\n"); clearTimeout(timeout); signal.removeEventListener("abort", abort);
+      if (failure) reject(Object.assign(failure, { output }));
+      else resolve({ code, output });
+    });
+  });
+}
+
+/** Registered development commands are trusted project code, never model-supplied commands. */
+export function createVerificationController(root) {
+  root = path.resolve(root);
+  let active;
+  return {
+    status: () => ({ running: !!active }),
+    async close() { active?.abort(); await active?.completion; },
+    async run({ unit, units, checks, persist = true } = {}, signal) {
+      if (active) return { ok: false, diagnostics: [{ rule: "behavior-busy", message: "A behavior verification is already running." }], results: [] };
+      active = new AbortController();
+      const controller = active;
+      signal = signal ? AbortSignal.any([signal, active.signal]) : active.signal;
+      let finish; controller.completion = new Promise(resolve => { finish = resolve; });
+      let host;
+      const results = [], diagnostics = [];
+      try {
+        const options = loadConfig(root), inventory = inspectBehaviors(options);
+        if (inventory.diagnostics.length) return { ok: false, diagnostics: inventory.diagnostics, results };
+        const selectedUnits = new Set(units ?? (unit ? [unit] : inventory.contracts.map(item => item.unit)));
+        const contracts = inventory.contracts.filter(item => selectedUnits.has(item.unit));
+        if (!contracts.length || [...selectedUnits].some(id => !contracts.some(contract => contract.unit === id))) return { ok: false, diagnostics: [{ rule: "behavior-selection", message: "No behavior contract matches the complete selection. Discover exact owner/check IDs with ads_behaviors." }], results };
+        const context = inputContext(options);
+        const selection = contracts.flatMap(contract => Object.entries(contract.checks).filter(([id]) => !checks || checks.includes(id)).map(([id, check]) => ({ unit: contract.unit, id, ...check, inputRevision: behaviorInputs(options, contract, check, context).revision, contract })));
+        if (!selection.length || checks?.some(id => !selection.some(check => check.id === id))) return { ok: false, diagnostics: [{ rule: "behavior-selection", message: "Unknown check selection. Use check IDs returned by ads_behaviors." }], results };
+        for (const profileName of new Set(selection.map(check => check.profile))) {
+          const profile = options.config.mcp.behaviorProfiles[profileName];
+          const group = selection.filter(check => check.profile === profileName);
+          const directory = path.join(root, ".ds/verification", randomUUID());
+          mkdirSync(directory, { recursive: true });
+          if (realpathSync(directory) !== directory) throw new Error("Verification output cannot resolve through a symlink.");
+          const runId = randomUUID(), report = path.join(directory, "report.json"), request = path.join(directory, "request.json");
+          const scenarios = {};
+          if (profile.mode === "browser" && group.some(check => check.scenario)) {
+            const { startAdsMcp } = await import("./mcp/server.mjs");
+            host ??= await startAdsMcp(root, { stdio: false, showcase: true });
+            for (const check of group.filter(check => check.scenario)) { const url = new URL(host.url); url.searchParams.set("scenario", check.scenario); scenarios[check.scenario] = url.href; }
+          }
+          const requestContext = { schemaVersion: 1, runId, projectRoot: root, framework: options.config.framework, profile: profileName, mode: profile.mode ?? "unit", checks: group.map(({ contract: _contract, ...check }) => check), scenarios };
+          writeFileSync(request, JSON.stringify(requestContext));
+          const args = [...profile.args];
+          if (profile.runner === "playwright") args.push(...new Set(group.map(check => slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file))))), `--reporter=${fileURLToPath(new URL("./verification/playwright-reporter.cjs", import.meta.url))}`, `--output=${path.join(directory, "artifacts")}`);
+          let run, reportValue, runnerError;
+          try {
+            run = await execute(profile, args, root, { ADS_VERIFY_REQUEST: request, ADS_VERIFY_REPORT: report, ADS_VERIFY_MODE: requestContext.mode }, signal);
+            if (!existsSync(report) || realpathSync(report) !== report || lstatSync(report).size > 1024 * 1024) throw new Error("Runner produced no valid bounded verification report. A successful exit alone is not passing evidence.");
+            reportValue = JSON.parse(readFileSync(report, "utf8"));
+            if (reportValue.schemaVersion !== 1 || reportValue.runId !== runId || !Array.isArray(reportValue.cases) || reportValue.cases.length > 500) throw new Error("Runner report has the wrong run ID/schema or too many cases.");
+          } catch (error) { runnerError = error; diagnostics.push({ rule: "behavior-runner", message: error.message, output: error.output?.slice(-4000), profile: profileName }); }
+          const afterOptions = loadConfig(root), afterContext = inputContext(afterOptions);
+          for (const check of group) {
+            const file = slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file)));
+            const matches = reportValue?.cases.filter(item => item && item.id === check.case && item.file === file) ?? [];
+            let status = !run || run.code !== 0 ? "failed" : matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
+            if (runnerError?.code === "ENOENT") status = "unavailable";
+            const current = behaviorInputs(afterOptions, check.contract, check, afterContext).revision === check.inputRevision;
+            if (!current) status = "stale";
+            if (signal.aborted) status = "cancelled";
+            results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
+              previewRevision: profile.mode === "browser" ? readPreviewManifest(options)?.revision ?? null : null,
+              message: runnerError?.message ?? (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : matches.filter(item => item.status !== "passed").map(item => String(item.message ?? item.status).slice(0, 2000)).join("\n")), report: slash(path.relative(root, report)) });
+          }
+          if (signal.aborted) break;
+        }
+        if (persist) {
+          const evidence = saved(root);
+          for (const result of results) evidence[identity(result.unit, result.check)] = result;
+          const file = resultFile(root), temporary = `${file}.${randomUUID()}.tmp`;
+          const content = JSON.stringify({ schemaVersion: 1, results: evidence });
+          if (Buffer.byteLength(content) > 2 * 1024 * 1024) throw new Error("Verification evidence exceeds 2 MiB. Remove obsolete generated evidence and retry.");
+          try { writeFileSync(temporary, content); renameSync(temporary, file); } finally { rmSync(temporary, { force: true }); }
+        }
+        return { ok: diagnostics.length === 0 && results.length > 0 && results.every(result => result.status === "passed" && result.current), diagnostics, results };
+      } catch (error) { return { ok: false, diagnostics: [{ rule: "behavior-verification", message: error.message }], results }; }
+      finally { try { await host?.close(); } finally { if (active === controller) active = undefined; finish(); } }
+    },
+  };
+}

package/docs/ADS.md

@@ -88,6 +88,21 @@ design-system/
     main.tsx
 ```
 
+Private controllers remain in that component/pattern owner. Shared controllers use
+`controllers/<Name>/` with an index or same-name runtime entry and independently
+guarded public re-exports. They may use the configured framework and declared
+dependencies, plain TypeScript and browser APIs; CSS/Linaria and visual DOM belong
+to consumers. They require no artificial visual scenario.
+
+Optional colocated `behavior.json` (flat: `<Owner>.behavior.json`) registers
+subjects, guarantees and owner-local checks against project-configured runner
+profiles. `exercises` records public behavioral APIs demonstrated by a scenario;
+`covers` retains its rendered UI contract. ADS validates references and reachable
+uses; execution evidence is separate and becomes stale when its inputs change.
+Runtime imports/re-exports of manifests, tests, fixtures and scenarios are rejected.
+See [controllers and behavioral verification](BEHAVIORS.md) for the schema,
+framework/dependency gates and MCP execution contract.
+
 Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `Scenario.tsx` exports a default independently mountable view and literal metadata
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
@@ -160,7 +175,17 @@ explains the model.
 
 Consume token references instead of raw visual values. Color formulas, effects,
 durations, easing, typography, sizing, and layering values belong in the token
-source.
+source. Absolute and font-relative length literals require token references,
+including `ch`, `ex`, `cap`, `ic`, `lh` and their root-relative forms, even inside
+`calc()`, `min()` or fallbacks. CSS numeric notation does not change ownership.
+Unitless geometry, percentages, grid fractions and viewport/container relationships
+retain their structural use.
+
+Angle units (`deg`, `grad`, `rad`, `turn`) remain available for geometric rotation,
+skew, orientation and complete turns. Static checks do not infer whether an angle
+is art direction: put a tunable visual angle in the project's tokens when it is
+part of that design contract. Angle-bearing color effects still require tokens.
+These categories follow [CSS Values and Units](https://www.w3.org/TR/css-values-4/#lengths).
 
 Token names and ownership prefixes are fixed by ADS architecture, not project
 configuration. `--ds-*` belongs to components, `--ux-*` to patterns, and
@@ -220,7 +245,7 @@ motion values.
 
 External content workflows are agent skills; there is no CLI
 `ads import` command. Use the [skill guide](../skills/README.md) for installation,
-selection, import, assimilation, stress testing, and motion workflows.
+selection, import, migration, stress testing, and motion workflows.
 
 Record the source revision and integrate selected source, dependencies, public
 exports, assets, documentation, and applicable rules. Preserve destination token

package/docs/ARCHITECTURE.md

@@ -149,6 +149,33 @@ preserving compatible consumer APIs. Markup, accessibility, events, layout, and
 motion still need verification when an implementation changes. Imported or
 adapted source carries its credits and applicable notices in its local guide.
 
+## Controllers own reusable behavior
+
+A private controller stays beside its component or pattern. Shared behavior uses
+`controllers/<Name>/` as an independent edit owner. Controllers may be plain
+functions/classes, framework hooks or context providers; sharing code does not
+implicitly share instances. Use the configured framework and declared project
+dependencies, with no runtime supplied by the MCP host. Shared controllers do not
+import styled consumers or introduce another skin layer. Existing measurement and
+style-write boundaries still apply.
+
+Optional owner-local `behavior.json` contracts identify public APIs or private
+source/symbols, named guarantees and registered execution checks. Scenario
+`exercises` links public behavior APIs to reachable demonstrations; `covers`
+continues to describe rendered public UI. Controllers need no artificial standalone
+visual scenario. Static registration is separate from current passing evidence.
+
+Manifests, checks, scenarios and fixtures are development inputs; production
+imports only actual components/controllers and their styles. Browser checks can
+exercise the real MCP App. React development StrictMode uses a project development
+harness, since production previews do not replay those effects. The
+[behavior contract](BEHAVIORS.md) defines profiles, execution and evidence freshness.
+
+The normal compiled import graph delivers controller dependencies through MCP
+resources. There is no eager global controller registry. ESM splitting and selected
+asset loading remain in place; tree shaking depends on actual imports, exports and
+side effects, rather than the controller directory name.
+
 ## The showcase is the shared design workspace
 
 Humans and coding agents inspect the same project through MCP. The showcase is
@@ -289,11 +316,22 @@ Bounded tools establish what exists; explicit resource reads provide detail.
 Prompts and packaged skills explain how to reason through Data, UX and Skin and
 how to inspect the real implementation before changing it.
 
+The MCP runtime owns its browser hosts and preview builder lifetime. Closing the
+client connection releases them together; a separate ownership guard can stop
+detached builders after abrupt owner death. A preview process must not outlive
+its owner and continue publishing stale output.
+Build reports expose queued, validation, compilation and publication progress.
+A timed-out preview request marks the builder stalled; the next explicit request
+restarts it within the same MCP session. A running process alone is not freshness.
+
 Opt-in MCP editing makes validation part of the write operation. The agent sends
 a Git unified diff for one logical ADS unit: its implementation and owned preview
 context, or the shared token foundation. ADS resolves file ownership, reconstructs
 candidate files locally and validates a temporary project copy with architecture
-checks, registered lint rules and project validation scripts. This keeps edits
+checks, registered lint rules and project validation scripts. Affected registered
+behavior checks, including consumers of a changed shared controller, also run in
+the isolated candidate project. Passing checks describe
+their registered assertions, not every natural-language claim. This keeps edits
 focused without requiring entire file bodies in model context. Peer units and
 unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
 branding and guides have their own units. Project configuration, registered guards

package/docs/BEHAVIORS.md

@@ -0,0 +1,230 @@
+# Controllers and behavioral verification
+
+Controllers own reusable UI behavior: state, subscriptions, DOM measurements and
+lifecycle coordination. A controller may be a class, function, hook, state
+machine or context provider. Linaria and tokens own its consumers' visual design.
+
+Private controllers stay inside their component/pattern mutation unit. Shared
+controllers use `design-system/controllers/<Name>/` with an `index` entry or a
+runtime file matching the directory name. The unit ID is `controllers/<Name>`.
+Its implementation, tests and guides can change together, including only its own
+required public re-exports. A shared controller needs no artificial visual preview.
+Consumers normally create separate instances; sharing implementation does not
+implicitly share state.
+
+Use the project's `framework` from `ds.config.json` for framework-specific APIs.
+Plain TypeScript, browser APIs and local behavior helpers remain supported.
+Declare external dependencies in the project package. ADS does not install them
+or assume a renderer/library supplied by an MCP host. The framework field selects
+compilation/mounting; controller checks also validate runtime imports. Type-only
+UI references are allowed, but shared controllers cannot import component/pattern
+runtime implementations. Keep business data in application adapters. Measured
+style writes retain exact `boundaries.styleWrites` properties; they do not allow
+shared-token overrides or an extra styling layer.
+These gates inspect supported direct imports, markup and style boundaries.
+External package internals and delegated DOM behavior still require source,
+build and browser review; declaring a dependency does not prove it is headless.
+
+## Development boundary
+
+Production includes real components, controllers, tokens and compiled styles.
+Scenarios and fixtures are included only in previews. Behavior manifests and test
+files are development/tooling inputs. Runtime imports and public re-exports of
+those inputs are rejected, including dynamic imports and aliases.
+
+## Register guarantees
+
+An optional `behavior.json` belongs to one directory unit. Flat units use
+`<Owner>.behavior.json`. Existing projects without manifests remain valid and have
+no implied behavioral verification. A manifest is declarative and contains no
+executable command:
+
+```json
+{
+  "schemaVersion": 1,
+  "subjects": {
+    "controller": { "source": "./scroller-controller.ts", "symbol": "ScrollerController" },
+    "scroll-api": { "api": "useMessageScroller" }
+  },
+  "guarantees": [
+    {
+      "id": "prepend-anchor",
+      "description": "Prepending history preserves the visible anchor after layout settles.",
+      "subjects": ["controller", "scroll-api"],
+      "checks": ["prepend-anchor"]
+    }
+  ],
+  "checks": {
+    "prepend-anchor": {
+      "file": "./behavior.spec.ts",
+      "case": "prepend-anchor",
+      "scenario": "components/MessageScroller",
+      "profile": "widget"
+    }
+  }
+}
+```
+
+Names above are illustrative project choices. A subject identifies a public export
+through `api`, or an owner-local implementation `source` with an optional top-level
+`symbol`. Private subjects do not become public API. A guarantee references known
+subjects and checks. Each check names an owner-local test/spec file, stable case
+ID, registered profile and optional discovered scenario. Several guarantees may
+reference one check. Repeated execution identities use the same check ID.
+
+Static validation establishes registration and ownership, not that the guarantee
+is true. README prose is not automatically certified. Link specific guarantees
+when describing the evidence available for a behavior.
+
+## Link a public API to a demonstration
+
+Scenario `covers` retains its existing render-reference contract. Optional
+`exercises` identifies public behavioral APIs:
+
+```tsx
+export const scenario = {
+  title: "Message scrolling",
+  covers: ["MessageScroller", "MessageScrollerViewport"],
+  exercises: ["useMessageScroller", "useMessageScrollerScrollable"],
+};
+```
+
+Call hooks in a rendered local scenario adapter. Calls/construction are matched by
+resolved symbol, not a `use*` naming convention. An unused import, dead adapter or
+metadata string does not count. Dynamically passed behavior references produce a
+review advisory when a direct call cannot be established; verify those through
+registered execution checks rather than changing the API for the analyzer.
+
+Public APIs appear in `ads_catalog` with `apiKind: "ui"` or `"behavior"` and their
+scenario links. `ads_behaviors` joins contracts to demonstrations and evidence.
+A demonstrated API is not automatically a verified guarantee.
+
+## Register execution profiles
+
+Profiles are explicit trusted development commands in `ds.config.json`. They use
+literal executable/argument arrays, no shell interpolation or model-supplied
+command. For a project with an installed Playwright test runner:
+
+```json
+{
+  "mcp": {
+    "behaviorProfiles": {
+      "widget": {
+        "runner": "playwright",
+        "command": "npm",
+        "args": ["run", "test:behavior", "--"],
+        "mode": "browser",
+        "timeoutMs": 60000
+      }
+    }
+  }
+}
+```
+
+Here `test:behavior` invokes the project's local `playwright test`. Its Playwright
+configuration must discover colocated spec files. Configure browser installation
+and any required test setup in that project. The ADS tooling host gains no
+framework or browser dependency from a profile.
+
+The Playwright adapter appends selected file paths, its reporter and a generated
+artifact directory. Use native test tags for stable case identity:
+
+```ts
+import { test, expect } from "@playwright/test";
+import { openBehaviorScenario } from "@reqvire-org/ads/verification";
+
+test("history preserves the visible anchor", { tag: "@ads:prepend-anchor" }, async ({ page }) => {
+  const frame = await openBehaviorScenario(page, "prepend-anchor");
+  // Perform real interactions and assert the project's guarantee here.
+  await expect(frame.getByRole("region", { name: "Messages" })).toBeVisible();
+});
+```
+
+The shown assertion is only a harness example; it does not establish anchoring.
+Write meaningful assertions for the registered guarantee. The helper waits for
+the current selected scenario inside the real sandboxed MCP App. It uses `load`
+and explicit readiness, not `networkidle`: MCP keeps event connections open.
+
+`mode: "browser"` starts an isolated managed showcase on an automatic port. Test
+requests contain its scenario URLs, and cleanup closes its host/compiler tree.
+Mutation candidates use their own source, generated graph and server; a passing
+test against an older fixed-port live showcase cannot validate a candidate.
+
+Use `mode: "strict"` only for React with a project development harness that mounts
+the relevant API in StrictMode. The production MCP App does not replay development
+effects. This profile does not receive a production showcase URL from the helper.
+For Preact, register its actual lifecycle tests without claiming React StrictMode.
+The profile names record the chosen environment; ADS does not infer that a test's
+assertions cover every lifecycle condition.
+
+Other runners use `runner: "protocol"` (the default). ADS provides
+`ADS_VERIFY_REQUEST` and `ADS_VERIFY_REPORT` absolute paths. Read the request's
+`schemaVersion`, unique `runId`, `projectRoot`, `framework`, `profile`, `mode`,
+selected `checks` and optional `scenarios` URLs. Write a bounded JSON report:
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "<the request's runId>",
+  "cases": [
+    {
+      "id": "prepend-anchor",
+      "file": "design-system/components/MessageScroller/behavior.spec.ts",
+      "status": "passed"
+    }
+  ]
+}
+```
+
+Case statuses are `passed`, `failed` or `skipped`, with optional `message`.
+`file` is project-relative. Nonzero process exit, missing cases, skipped cases,
+wrong run IDs and unavailable reports do not pass. Test commands are trusted
+project code; an adapter cannot prove the quality or honesty of their assertions.
+
+## Execute and inspect evidence
+
+Use `ads_behaviors` for bounded discovery; request an exact unit for its contract.
+General listings return counts and short API/guarantee/scenario summaries. Exact
+owner requests return the registered details; source reads remain available for
+bounded inspection of large contracts. No full guide or test body is injected
+into discovery results.
+Call `ads_verify({unit, checks?})` for selected registered checks. Read
+`ads://project/behaviors` for current evidence or `ads://guides/behaviors` for this
+guide. CLI/CI equivalents are:
+
+```sh
+ads behaviors . --json
+ads verify . --unit controllers/ScrollFollow
+ads verify . --unit components/MessageScroller --check prepend-anchor --json
+```
+
+Execution has bounded output, a configured timeout, cancellation and process-tree
+ownership. Evidence records case/profile identity, source/dependency revision,
+completion time, report path and the available preview revision. Later input
+changes mark results stale; changes during execution prevent a current pass.
+Guarantees report passing only when all their checks have current passing evidence.
+Passing applies to those cases and profiles, not every application state.
+
+Revisions include owned files, literal import dependencies, local CSS imports and
+asset URLs, token foundation, project/runner configuration, lockfiles and tooling.
+Computed module selection conservatively includes all ADS owners. Environment,
+network and other unregistered external inputs remain the runner's responsibility;
+an evidence record is not a proof about arbitrary external state.
+
+Guarded mutations execute affected registered behavior contracts after core,
+Oxlint and configured project checks, before writing source. Imported shared
+controller changes also select dependent contracts conservatively. Rejected and
+dry-run patches publish no source changes. Verification output stays under `.ds/`.
+
+## Packaging and performance
+
+Controllers follow normal component/scenario imports into the project's compiled
+resource graph. Their framework dependencies are bundled by the project compiler
+and served through MCP resources inside the App iframe; external hosts install
+nothing. The selected scenario loads its dependency closure. Shared modules are
+cached within that App instance, and each separately opened App has its own runtime.
+
+Keep ESM modules and explicit imports. Avoid an eagerly imported controller
+registry. Tree shaking and shared chunks follow the project bundler: class methods,
+side effects, global CSS and dynamic maps can retain extra code. Inspect emitted
+resources instead of assuming a controller produces a minimal bundle.

package/docs/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.5
+
+- Bound preview-watch test teardown, publish selection requests atomically and
+  wait for the changed preview output before checking revision/queue order.
+  Cap the release test stage so failed cleanup cannot hold publication indefinitely.
+
+- Stabilize the development StrictMode browser harness across dependency-optimizer
+  reloads. Verify the broken controller fails its cleanup assertion and the
+  repaired controller passes. Version 0.3.4 was not published after CI caught the
+  harness navigation race.
+
+- Add shared controller units, framework/dependency and headless ownership checks,
+  while retaining private controllers in their consumers' units.
+- Add optional owner-local behavior contracts, scenario `exercises`, public hook
+  discovery, `ads_behaviors`/`ads_verify`, revision-bound results and subscribed
+  evidence resources. Guarded edits run affected registered checks in candidates.
+- Add registered protocol/Playwright execution profiles with cancellation,
+  process-tree cleanup, real sandboxed-App checks and development StrictMode
+  harness guidance. Keep behavior metadata/tests outside production imports.
+- Rename the external-library adaptation workflow and MCP prompt to `ads-migrate`;
+  retain `ads-import` for ADS-compatible source and token transfers.
+- Expose compiler progress phases and restart a timed-out builder on the next
+  explicit preview request without requiring an MCP reconnect.
+
+- Close the raw `ch` sizing gap across absolute/font-relative CSS length units,
+  nested calculations and numeric notation. Share unit categories with dimension
+  token validation; keep structural angles and responsive geometry available.
+  Preserve the demo's text measures in owned tokens with preview coverage.
+
+- Close the whole MCP runtime on stdio wire closure, including broken output,
+  and stop browser sockets, subscriptions and preview processes together.
+- Add an independent preview ownership guard so abrupt MCP process or process-group
+  death also terminates detached builders and their descendants.
+
 ## 0.3.3
 
 - Reject unused inline-style permissions and imperative property permissions.