@reqvire-org/ads 0.3.3 → 0.3.6

package/dist/scenarios-compiler.mjs

@@ -4,7 +4,8 @@ import path from "node:path";
 import { loadConfig, isInside } from "./config.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
 import { artifactDigest, createBuildReporter } from "./mcp/build-status.mjs";
-import { readPreviewManifest } from "./preview-resources.mjs";
+import { cachedPreviewPublication, previewArtifactHtml, readPreviewManifest } from "./preview-resources.mjs";
+import { previewArtifactPath, withPreviewSession } from "./preview-scope.mjs";
 
 const digest = value => createHash("sha256").update(value).digest("hex");
 const fileDigest = file => { try { return digest(readFileSync(file)); } catch { return null; } };
@@ -13,7 +14,7 @@ const fileDigest = file => { try { return digest(readFileSync(file)); } catch {
  * Cache state is development output, never proof that a failed build is current. */
 export function createPreviewCache(options, compilerFiles = []) {
   const { root, config } = options;
-  const adapterFiles = [import.meta.filename, path.join(import.meta.dirname, "preview-resources.mjs"), path.join(import.meta.dirname, "scenarios-vite.mjs"), ...compilerFiles,
+  const adapterFiles = [import.meta.filename, path.join(import.meta.dirname, "preview-resources.mjs"), path.join(import.meta.dirname, "preview-scope.mjs"), path.join(import.meta.dirname, "scenarios-vite.mjs"), ...compilerFiles,
     ...["package.json", "package-lock.json", "bun.lock", "bun.lockb", "node_modules/.package-lock.json"].map(file => path.join(root, file))];
   const adapterDigest = () => digest(JSON.stringify(adapterFiles.map(file => [file, fileDigest(file)])));
   const loadedAdapter = adapterDigest();
@@ -62,14 +63,17 @@ export function createPreviewCache(options, compilerFiles = []) {
     ["scheduler", fileDigest(import.meta.filename)],
     ["node-runtime", `${process.version}/${process.platform}/${process.arch}`],
   ]));
-  function reusable(entry) {
+  function reusable(entry, expectedHtml) {
     const cached = value.entries[entry.id];
     if (!cached || cached.metadata !== JSON.stringify(entry) || cached.compiler !== compilerDigest()) return false;
     if (!cached.dependencies || !Object.keys(cached.dependencies).length) return false;
     if (Object.entries(cached.dependencies).some(([file, hash]) => fileDigest(path.resolve(root, file)) !== hash)) return false;
-    try { return cached.artifact === artifactDigest(path.join(root, entry.artifact)); } catch { return false; }
+    if (expectedHtml !== undefined && cached.artifact !== `sha256:${digest(expectedHtml)}`) return false;
+    const file = path.join(root, previewArtifactPath(options, entry.artifact));
+    if (expectedHtml !== undefined && !existsSync(file)) return true;
+    try { return cached.artifact === artifactDigest(file); } catch { return false; }
   }
-  return { inputs, reusable, validated: stamp => value.validation === stamp,
+  return { inputs, reusable, graphRevision: () => value.graphRevision, recordGraph(revision) { value.graphRevision = revision; save(); }, validated: stamp => value.validation === stamp,
     assertCompiler() {
       if (adapterDigest() !== loadedAdapter) throw Object.assign(new Error("Preview compiler code or dependencies changed. Invoke the preview again to restart the builder and load current code."), { code: "ADS_PREVIEW_RESTART" });
     },
@@ -78,7 +82,7 @@ export function createPreviewCache(options, compilerFiles = []) {
       value.entries[entry.id] = { metadata: JSON.stringify(entry), compiler: compilerDigest(),
         dependencies: Object.fromEntries([...new Set([path.join(root, entry.file), ...dependencies])]
           .filter(file => isInside(root, file) && !file.includes(`${path.sep}node_modules${path.sep}`)).map(file => [path.relative(root, file), fileDigest(file)])),
-        artifact: artifactDigest(path.join(root, entry.artifact)) };
+        artifact: artifactDigest(path.join(root, previewArtifactPath(options, entry.artifact))) };
       save();
     },
   };
@@ -87,11 +91,11 @@ export function createPreviewCache(options, compilerFiles = []) {
 /** Shared scheduling and cache; the project supplies its own React/Preact build. */
 export async function runScenarioCompiler(directory, { watched = false, validate, build, buildGraph, compilerFiles = [] }) {
   const root = path.resolve(directory);
-  let options = loadConfig(root);
+  let options = withPreviewSession(loadConfig(root), process.env.ADS_MCP_BUILD_SESSION);
   if (buildGraph && (!options.config.mcp.previewManifest || !options.config.framework)) throw new Error("Resource preview builds require an explicit framework and mcp.previewManifest in ds.config.json.");
   const cache = createPreviewCache(options, compilerFiles);
   function registry() {
-    options = loadConfig(root);
+    options = withPreviewSession(loadConfig(root), process.env.ADS_MCP_BUILD_SESSION);
     const result = inspectScenarios(options);
     if (result.diagnostics.length) throw Object.assign(new Error(result.diagnostics.map(item => `${item.file}: ${item.message}`).join("\n")), { scenarios: result.scenarios });
     mkdirSync(path.join(root, ".ds/scenarios"), { recursive: true });
@@ -104,7 +108,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     if (!watched) throw error;
     registryFailure = error; entries = error.scenarios ?? [];
   }
-  const reporter = createBuildReporter(root, { apps: entries.map(entry => ({ id: entry.id, file: entry.artifact })) });
+  const buildApps = () => entries.map(entry => ({ id: entry.id, file: previewArtifactPath(options, entry.artifact) }));
+  const reporter = createBuildReporter(root, { apps: buildApps() });
   const requested = new Set();
   const pending = new Set();
   let active;
@@ -126,6 +131,16 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       cache.validate(stamp);
     });
   }
+  async function checkedBuild(stamp, build) {
+    const started = generation;
+    let checking = true, compiling = true;
+    function progress() { if (started === generation) reporter.progress(checking && compiling ? "validation-and-compilation" : checking ? "validation" : compiling ? "compilation" : "publication"); }
+    progress();
+    return Promise.allSettled([
+      gate(stamp).finally(() => { checking = false; progress(); }),
+      Promise.resolve().then(build).finally(() => { compiling = false; progress(); }),
+    ]);
+  }
   async function compile(entry) {
     if (buildGraph) return compileGraph();
     const revision = reporter.begin(entry.id);
@@ -154,16 +169,18 @@ export async function runScenarioCompiler(directory, { watched = false, validate
           if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
         }
       } };
-      const outcomes = await Promise.allSettled([gate(stamp), reuse ? Promise.resolve() : build(entry, options, track)]);
+      const outcomes = await checkedBuild(stamp, () => reuse ? undefined : build(entry, options, track));
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
       if (stopped || started !== generation || stamp !== cache.inputs()) return; // Watch queued a newer revision.
       if (!reuse) cache.record(entry, dependencies);
       reporter.ready(entry.id, revision);
+      reporter.progress("idle");
     } catch (error) {
       if (started !== generation) return;
       reporter.error(entry.id, revision, error);
+      reporter.progress("idle");
       console.error(error);
       if (!watched) process.exitCode = 1;
     }
@@ -190,9 +207,13 @@ export async function runScenarioCompiler(directory, { watched = false, validate
         }
       } };
       cache.assertCompiler();
-      let reusable = entries.every(entry => cache.reusable(entry));
-      if (reusable) { try { reusable = Boolean(readPreviewManifest(options, { verify: true })); } catch { reusable = false; } }
-      const outcomes = await Promise.allSettled([gate(stamp), reusable ? Promise.resolve(null) : buildGraph(entries, options, track)]);
+      const cached = cachedPreviewPublication(options, entries, cache.graphRevision());
+      let reusable = cached && entries.every(entry => cache.reusable(entry, previewArtifactHtml(entry.id, cached.revision)));
+      if (reusable) {
+        try { readPreviewManifest(options, { verify: true }); }
+        catch { reusable = false; }
+      }
+      const outcomes = await checkedBuild(stamp, () => reusable ? null : buildGraph(entries, options, track));
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
@@ -200,18 +221,18 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const publication = outcomes[1].value;
       if (publication) {
         publication.publish(reporter.session);
-        for (const entry of entries) cache.record(entry, [...dependencies, ...publication.assetFiles]);
+        for (const entry of entries) cache.record(entry, dependencies);
+        cache.recordGraph(publication.revision);
       } else {
-        const file = path.join(root, options.config.mcp.previewManifest);
-        const manifest = readPreviewManifest(options);
-        writeFileSync(`${file}.tmp`, JSON.stringify({ ...manifest, session: reporter.session }));
-        renameSync(`${file}.tmp`, file);
+        cached.publish(reporter.session);
       }
       for (const entry of entries) { pending.delete(entry.id); reporter.ready(entry.id, revisions.get(entry.id)); }
       publishedStamp = stamp;
+      reporter.progress("idle");
     } catch (error) {
       if (started !== generation) return;
       for (const entry of entries) { pending.delete(entry.id); reporter.error(entry.id, revisions.get(entry.id), error); }
+      reporter.progress("idle");
       console.error(error);
       if (!watched) process.exitCode = 1;
     }
@@ -261,12 +282,13 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     clearTimeout(timer);
     timer = setTimeout(() => {
       ++generation;
+      reporter.progress("queued");
       validation = undefined;
       const changes = [...changed]; changed.clear();
       try {
         entries = registry();
         registryFailure = undefined;
-        reporter.setApps(entries.map(entry => ({ id: entry.id, file: entry.artifact })));
+        reporter.setApps(buildApps());
         reporter.clearFailure();
         request(false);
         for (const id of requested) if (!entries.some(entry => entry.id === id)) { requested.delete(id); pending.delete(id); }

package/dist/scenarios.mjs

@@ -1,12 +1,14 @@
 import path from "node:path";
 import { existsSync } from "node:fs";
 import ts from "typescript";
+import { publicApi } from "./public-api.mjs";
 import { uiOperation } from "./ui-framework.mjs";
 import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./config.mjs";
 import { projectCompilerOptions } from "./boundaries.mjs";
 import { inspectTokens } from "./tokens.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { validTokenSamples } from "./token-samples.mjs";
+import { scopedTokens } from "./scoped-tokens.mjs";
 
 export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
 
@@ -27,54 +29,27 @@ function literal(node, checker, seen = new Set()) {
 }
 
 export function publicUi(program, options) {
-  const checker = program.getTypeChecker();
-  const entry = program.getSourceFile(path.join(options.dsRoot, options.config.publicEntry));
-  const module = entry && checker.getSymbolAtLocation(entry);
-  const items = [];
-  for (const exported of module ? checker.getExportsOfModule(module) : []) {
-    let symbol = exported;
-    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
-    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
-    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
-    const file = declaration.getSourceFile().fileName;
-    if (isDevelopmentFile(file, options)) continue;
-    const kind = isInside(path.join(options.dsRoot, "components"), file) ? "components" : isInside(path.join(options.dsRoot, "patterns"), file) ? "patterns" : null;
-    if (!kind) continue;
-    let renderable = false;
-    function visit(node) {
-      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) renderable = true;
-      if (ts.isCallExpression(node) && ["createElement", "forwardRef", "memo"].includes(uiOperation(node.expression, checker))) renderable = true;
-      if (ts.isTaggedTemplateExpression(node)) {
-        let tag = node.tag;
-        if (ts.isCallExpression(tag)) tag = tag.expression;
-        let base = tag;
-        while (ts.isPropertyAccessExpression(base)) base = base.expression;
-        const symbol = checker.getSymbolAtLocation(base);
-        if (symbol?.declarations?.some(item => ts.isImportSpecifier(item) && (item.propertyName ?? item.name).text === "styled" && item.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/") || ts.isNamespaceImport(item) && item.parent.parent.moduleSpecifier.text.startsWith("@linaria/") && /^\.styled(?:\.|$)/.test(tag.getText().slice(base.getText().length)))) renderable = true;
-      }
-      ts.forEachChild(node, visit);
-    }
-    visit(declaration);
-    items.push({ name: exported.name, kind, file, declaration, renderable });
-  }
-  return items;
+  return publicApi(program, options).filter(item => item.kind !== "controllers");
 }
 
 /** Discover metadata statically. The MCP process never imports scenario modules. */
 export function inspectScenarios(options, suppliedProgram) {
   const { root, dsRoot } = options;
   const files = sourceFiles(dsRoot).filter(isScenarioFile);
-  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], projectCompilerOptions(options));
+  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
   const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
-  const tokenNames = new Set(inspectTokens(root).tokens.map(token => token.name));
+  const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
+  const tokenInventory = inspectTokens(root);
+  const tokenNames = new Set(tokenInventory.tokens.map(token => token.name));
+  const scoped = scopedTokens(options);
   const scenarios = [];
   const diagnostics = [];
   const ids = new Set();
   function report(file, message) { diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: 1, column: 1, message }); }
   for (const file of files) {
     const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-    const kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
+    let kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
     if (!["tokens", "components", "patterns", "composition"].includes(kind)) { report(file, "Scenarios live beside tokens/components/patterns or under composition/, not inside showcase pages."); continue; }
     const id = relative.replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
     if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
@@ -90,6 +65,11 @@ export function inspectScenarios(options, suppliedProgram) {
         for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") metadata = literal(declaration.initializer, checker);
       }
     }
+    if (metadata?.kind !== undefined) {
+      const owner = scoped.inventory.owner(relative);
+      if (metadata.kind !== "tokens" || !scoped.definitions.some(entry => entry.unit === owner)) { report(file, "Only an owner with registered local tokens may set kind: tokens for a colocated token preview."); continue; }
+      kind = "tokens";
+    }
     if (!entry) report(file, "Export a default independently mountable scenario entrypoint.");
     const module = checker.getSymbolAtLocation(source);
     const defaultExport = module && checker.getExportsOfModule(module).find(item => item.name === "default");
@@ -105,21 +85,26 @@ export function inspectScenarios(options, suppliedProgram) {
     }
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     if (![".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].some(extension => existsSync(fixtureBase + extension))) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+    if (!metadata || Object.keys(metadata).some((key) => !["title", "kind", "covers", "exercises", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+      || Object.hasOwn(metadata, "exercises") && (!Array.isArray(metadata.exercises) || metadata.exercises.some(name => typeof name !== "string" || !behaviorApis.has(name)))
       || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
       || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
       || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
-      report(file, "Export static metadata with nonempty covers. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
+      report(file, "Export static metadata with nonempty covers naming rendered public UI. Optional exercises names public behavioral APIs, not rendered UI. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
     }
     if (!["composition", "tokens"].includes(kind) && metadata.covers.some((name) => known.get(name).kind !== kind)) report(file, "Component scenarios cover primitives; pattern scenarios cover patterns. Use composition/ for larger interfaces.");
     const tokens = [...new Set([...(metadata.tokens ?? []), ...(metadata.samples ?? []).map(sample => sample.token)])];
-    for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real foundation token.` });
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real token from its defining owner.` });
+    if (kind === "tokens") {
+      const owner = scoped.inventory.owner(relative);
+      for (const name of tokens) if (tokenInventory.tokens.find(token => token.name === name)?.owner !== owner) report(file, `Token ${name} needs a preview beside its defining owner. Shared tokens belong under the configured token directory; local tokens stay with their component/pattern.`);
+    }
+    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(metadata.exercises ? { exercises: [...new Set(metadata.exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
 
-export function inspectScenarioCoverage(options, program, report) {
+export function inspectScenarioCoverage(options, program, report, advise = () => {}) {
   const registry = inspectScenarios(options, program);
   for (const item of registry.diagnostics) report(path.join(options.root, item.file), item.rule, item.message, item.line, item.column);
   const checker = program.getTypeChecker();
@@ -153,7 +138,7 @@ export function inspectScenarioCoverage(options, program, report) {
     return symbol.declarations?.length ? symbol : null;
   }
   const identities = new Map();
-  for (const item of ui) {
+  for (const item of publicApi(program, options)) {
     if (!identities.has(item.declaration)) identities.set(item.declaration, new Set());
     identities.get(item.declaration).add(item.name);
   }
@@ -165,12 +150,16 @@ export function inspectScenarioCoverage(options, program, report) {
   for (const scenario of registry.scenarios) {
     const source = program.getSourceFile(path.join(options.root, scenario.file));
     const rendered = new Set();
+    const exercised = new Set(), referencedApis = new Set();
     const referencedTokens = new Set();
     let samplesPassed = false;
     const visited = new Set();
     function visit(node, reached = false) {
       if (!node || visited.has(node)) return;
-      if (!reached && (ts.isFunctionDeclaration(node) || ts.isVariableDeclaration(node))) return;
+      if (!reached && ts.isFunctionDeclaration(node)) return;
+      // Calls/construction in a mounted adapter execute even when only a result
+      // property is read later. Unused literal fixture fields still do not count.
+      if (!reached && ts.isVariableDeclaration(node) && !(node.initializer && (ts.isCallExpression(node.initializer) || ts.isNewExpression(node.initializer)))) return;
       if (!reached && (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && !ts.isCallExpression(node.parent) && !ts.isJsxExpression(node.parent)) return;
       visited.add(node);
       if (ts.isStringLiteralLike(node) && (isSharedToken(node.text) || scenario.tokens.includes(node.text))) referencedTokens.add(node.text);
@@ -180,18 +169,25 @@ export function inspectScenarioCoverage(options, program, report) {
       if (expression) {
         const symbol = canonical(symbolOf(expression));
         const names = identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
-        for (const name of names ?? []) rendered.add(name);
+        for (const name of names ?? []) { rendered.add(name); exercised.add(name); }
         if (scenario.kind === "tokens" && [...names ?? []].some(name => scenario.covers.includes(name))) {
           const attributes = ts.isCallExpression(node) ? literal(node.arguments[1], checker) : Object.assign({}, ...node.attributes.properties.map(attribute => ts.isJsxSpreadAttribute(attribute) ? literal(attribute.expression, checker) : ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name) && attribute.initializer && ts.isJsxExpression(attribute.initializer) ? { [attribute.name.text]: literal(attribute.initializer.expression, checker) } : {}));
           if (JSON.stringify(attributes?.samples) === JSON.stringify(scenario.samples)) samplesPassed = true;
         }
       }
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        let expression = node.expression;
+        if (ts.isPropertyAccessExpression(expression) && ["call", "apply"].includes(expression.name.text)) expression = expression.expression;
+        const symbol = canonical(symbolOf(expression));
+        for (const name of identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]) ?? []) exercised.add(name);
+      }
       // Follow local adapters reachable from the default entry. Unused example
       // functions do not satisfy coverage; production implementations are never
       // traversed to manufacture coverage for their internal dependencies.
       if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node) || ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) || ts.isElementAccessExpression(node.parent))) {
         const symbol = canonical(symbolOf(node));
         const declaration = symbol?.valueDeclaration;
+        for (const name of identities.get(declaration ?? symbol?.declarations?.[0]) ?? []) referencedApis.add(name);
         if (declaration && isDevelopmentFile(declaration.getSourceFile().fileName, options)) visit(declaration, true);
       }
       ts.forEachChild(node, child => visit(child, reached && (ts.isExportAssignment(node) || ts.isVariableDeclaration(node))));
@@ -201,6 +197,10 @@ export function inspectScenarioCoverage(options, program, report) {
       if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no public render reference in this scenario. Render the real API; an import alone does not count.`);
       else covered.add(name);
     }
+    for (const name of scenario.exercises ?? []) {
+      if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
+      else if (!exercised.has(name)) advise(source.fileName, "scenario-exercise-review", `${name} is referenced dynamically. Verify its invocation in the registered browser/behavior checks; a reference alone does not prove execution.`);
+    }
     for (const name of referencedTokens) if (!declaredTokens.has(name)) report(source.fileName, "token-scenario-reference", `Reachable scenario input references undeclared token ${name}.`);
     if (scenario.kind === "tokens" && !samplesPassed) report(source.fileName, "token-scenario-render", "Pass the declared fixture.samples into a rendered public review pattern's samples prop. Printing token names or reading unused fixtures is not sample coverage.");
     for (const name of scenario.tokens) {
@@ -221,3 +221,33 @@ export function writeScenarioRegistry(options, write) {
   write({ schemaVersion: 1, scenarios: registry.scenarios });
   return registry.scenarios;
 }
+
+/** Locate the actual consumed array, rather than regenerating a whole fixture. */
+export function tokenSampleSource(options, scenario) {
+  const file = path.join(options.root, scenario.file);
+  const program = ts.createProgram([file], { ...projectCompilerOptions(options), allowJs:true, resolveJsonModule:true });
+  const checker = program.getTypeChecker(), source = program.getSourceFile(file);
+  function resolve(node, seen = new Set()) {
+    while (node && (ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node))) node = node.expression;
+    if (!node || seen.has(node)) return null;
+    if (ts.isArrayLiteralExpression(node) || ts.isObjectLiteralExpression(node)) return node;
+    let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+    if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    return declaration?.initializer ? resolve(declaration.initializer, new Set([...seen,node])) : null;
+  }
+  for (const statement of source.statements) if (ts.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) {
+    if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "scenario") continue;
+    const metadata = resolve(declaration.initializer);
+    const property = metadata && ts.isObjectLiteralExpression(metadata) && metadata.properties.find(node => ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name)) && node.name.text === "samples");
+    const array = property && resolve(property.initializer);
+    if (array && ts.isArrayLiteralExpression(array)) {
+      const source = array.getSourceFile();
+      const scoped = scopedTokens(options), owner = scoped.inventory.owner(scoped.inventory.relative(scenario.file));
+      const relative = path.relative(options.root, source.fileName).replaceAll("\\", "/");
+      if (!isDevelopmentFile(source.fileName, options) || scoped.inventory.owner(scoped.inventory.relative(relative)) !== owner) throw new Error("The consumed samples array must live in this scenario's own development fixture.");
+      return {file:relative, content:source.text, start:array.getStart(source), end:array.end};
+    }
+  }
+  throw new Error("Cannot locate a literal consumed samples array. Keep fixture.samples statically inspectable; edit other fixture shapes with a normal owner patch.");
+}

package/dist/scoped-tokens.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import postcss from "postcss";
+import ts from "typescript";
+import { inspectUnits } from "./units.mjs";
+import { isDevelopmentFile } from "./config.mjs";
+import { foundationSelector } from "./foundation.mjs";
+import { isSharedToken, tokenContract } from "./token-policy.mjs";
+
+/** An explicit owner contract, never a heuristic based on a token's name. */
+export function scopedTokens(options) {
+  if (options.scopedTokens) return options.scopedTokens;
+  const inventory = inspectUnits(options), definitions = [], diagnostics = [];
+  const report = (file, message, line = 1) => diagnostics.push({rule:"scoped-token", file, message, line, column:1});
+  for (const unit of inventory.units.filter(unit => ["components", "patterns"].includes(unit.kind))) {
+    for (const manifest of unit.files.filter(file => /(?:^|\/)tokens\.json$|\.tokens\.json$/.test(file))) {
+      const absolute = path.join(options.root, manifest);
+      try {
+        if (statSync(absolute).size > 65536 || realpathSync(absolute) !== absolute) throw new Error("Token manifests must be ordinary files no larger than 64 KiB.");
+        const data = JSON.parse(readFileSync(absolute, "utf8"));
+        const stylesheet = manifest.replace(/\.json$/, ".css");
+        if (!data || data.schemaVersion !== 1 || Object.keys(data).some(key => !["schemaVersion", "namespace"].includes(key))
+          || typeof data.namespace !== "string" || !/^--[a-z][a-z0-9-]*-$/.test(data.namespace)
+          || /^(?:--ds-|--ux-|--showcase-)/.test(data.namespace) || isSharedToken(data.namespace + "value")
+          || tokenContract.naming.prefixes.some(prefix => prefix.startsWith(data.namespace))
+          || [...tokenContract.naming.names,...Object.keys(tokenContract.tokens)].some(name => name.startsWith(data.namespace))) throw new Error("Use {schemaVersion:1, namespace:\"--<owner>-\"}; shared and runtime-variable prefixes are reserved.");
+        if (definitions.some(entry => entry.unit === unit.id || entry.namespace.startsWith(data.namespace) || data.namespace.startsWith(entry.namespace))) throw new Error("Each unit has one token namespace; namespaces must not overlap other owners.");
+        if (!unit.files.includes(stylesheet) || !existsSync(path.join(options.root, stylesheet))) throw new Error(`Colocate the definition-only stylesheet ${stylesheet}.`);
+        const file = path.join(options.root, stylesheet);
+        if (realpathSync(file) !== file) throw new Error("Scoped token stylesheets cannot resolve through symlinks.");
+        const css = postcss.parse(readFileSync(file, "utf8"), {from:file});
+        let count = 0;
+        css.walk(node => {
+          if (node.type === "comment" || node.type === "root") return;
+          if (node.type === "atrule" && ["media", "supports", "layer"].includes(node.name) && node.nodes) return;
+          if (node.type === "rule" && node.parent.type !== "rule" && !foundationSelector(node.selector, {definitions:true})) return;
+          if (node.type === "decl" && node.parent.type === "rule" && node.prop.startsWith(data.namespace) && node.prop.length > data.namespace.length && !node.important) { count++; return; }
+          report(stylesheet, "Owner token sheets contain only namespaced custom-property definitions under root/theme conditions. UI selectors, imports, font faces, animations and ordinary declarations belong in their runtime owners.", node.source?.start.line);
+        });
+        if (!count) report(stylesheet, "Define at least one real namespaced token.");
+        const imported = unit.files.filter(file => /\.[cm]?[jt]sx?$/.test(file) && !isDevelopmentFile(path.join(options.root, file), options)).some(source => {
+          const ast = ts.createSourceFile(source, readFileSync(path.join(options.root, source), "utf8"), ts.ScriptTarget.Latest, true);
+          return ast.statements.some(node => ts.isImportDeclaration(node) && !node.importClause && ts.isStringLiteralLike(node.moduleSpecifier) && path.resolve(options.root, path.dirname(source), node.moduleSpecifier.text) === file);
+        });
+        if (!imported) report(manifest, `Import ./${path.basename(stylesheet)} from this owner's runtime source so its real preview and product consume the same definitions.`);
+        definitions.push({unit:unit.id, namespace:data.namespace, manifest, file:stylesheet});
+      } catch (error) { report(manifest, error.reason ?? error.message, error.line); }
+    }
+  }
+  const result = {definitions, diagnostics, inventory};
+  options.scopedTokens = result;
+  return result;
+}
+
+export function scopedTokenOwner(options, name) {
+  return scopedTokens(options).definitions.find(entry => name.startsWith(entry.namespace));
+}

package/dist/skills/README.md

@@ -3,13 +3,13 @@
 Install the skills you need 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
 ```
 
 Each skill includes its own instructions and references. `ads-designer` also
@@ -36,7 +36,7 @@ the browser, and provides a running URL or exact command for review. See the
 |-------|-----|---------|
 | [ads-designer](ads-designer/SKILL.md) | Bootstrap or build UI using the local ADS, with craft/mobile guidance | `$ads-designer build a settings page using this project's ADS` |
 | [ads-import](ads-import/SKILL.md) | Import selected external ADS source, brand artwork, or compatible source token values | `$ads-import /path/to/source-repo component Toast` |
-| [ads-assimilate](ads-assimilate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-assimilate https://github.com/emilkowalski/sonner` |
+| [ads-migrate](ads-migrate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-migrate https://github.com/emilkowalski/sonner` |
 | [ads-break-ui](ads-break-ui/SKILL.md) | Stress-test real components/patterns; optionally fix demonstrated failures | `$ads-break-ui AppShell +fix` |
 | [ads-motion](ads-motion/SKILL.md) | Implement, review, audit, or profile motion | `$ads-motion review Toast` |
 

package/dist/skills/ads-break-ui/SKILL.md

@@ -36,8 +36,8 @@ and `boundaries.styleWrites` entries together with its source. Unused permission
 fail the core checks; do not pre-register a boundary without its implementation.
 Use `dryRun: true` to
 inspect validation; applying re-runs the gates. Fix rejected patches in their
-owner. Report unsupported coupled changes instead of bypassing a rejection with
-direct source writes. Shared styles/helpers use `foundation`, root guides use
+owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
+never bypass a rejection with direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
 Intentional configuration, rule exceptions, registered guard code and compiler
 changes use `configuration`; validate the proposed settings and keep mandatory
@@ -45,6 +45,25 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 `.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
+For owner drafts, token-sample reconciliation, coupled transactions and local
+constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
+
+
+Controllers are UI behavior owners: private helpers stay with their component or
+pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
 
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
@@ -226,6 +245,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
 in a public review/layout pattern; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
+Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
+and `lh`; calculations and fallback values follow the same rule. Structural
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/skills/ads-break-ui/references/guarded-editing.md

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+shared or --ds-/--ux-/--showcase- variables. Only that owner consumes/defines its
+local tokens; aliases can use shared or own tokens. UI styles stay in Linaria.
+Add a colocated token scenario with `kind:"tokens"`, real fixture `samples` and a
+public review pattern. These inputs belong to the same owner and need real sample
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

package/dist/skills/ads-break-ui/references/verification.md

@@ -26,6 +26,12 @@ The showcase keeps a notification stream open. Wait for document loading and the
 selected App's ready/error state; `networkidle` is not a readiness condition.
 For tall previews, scroll the App document to its last example and verify it is
 reachable without the host shell scrolling or clipping the preview.
+Compare references under equivalent framing. With `content-visibility`, App
+readiness can precede off-screen layout: bring measured content into view and
+wait for observable geometry to settle. Record initial placeholder behavior
+separately when relevant; a framed/top-level difference alone does not identify
+an ADS defect. Wait for actual focus/positioning readiness for keyboard checks;
+exercise rapid input as a separate case instead of adding arbitrary delays.
 Capture the fixture, viewport/container size, theme, zoom, and actions alongside
 each failure. CSS viewport emulation is useful; it is not evidence of real
 mobile keyboard, browser chrome, or assistive-technology behavior.