@reqvire-org/ads 0.3.5 → 0.3.7

package/dist/public-api.mjs

@@ -2,6 +2,38 @@ import path from "node:path";
 import ts from "typescript";
 import { isDevelopmentFile, isInside } from "./config.mjs";
 import { uiOperation } from "./ui-framework.mjs";
+import { projectCompilerOptions } from "./boundaries.mjs";
+
+const resolvedCallables = new WeakMap();
+
+// The syntax guard omits libraries and dependency types. Resolve an ambiguous
+// public value lazily against the project's actual types, without importing it.
+// Keep the result with this immutable program so repeated discovery shares it.
+function resolvedCallable(program, options, name) {
+  if (!resolvedCallables.has(program)) {
+    const { dsRoot, config } = options;
+    const entryFile = path.join(dsRoot, config.publicEntry);
+    const compiler = projectCompilerOptions(options);
+    const semantic = ts.createProgram([entryFile], {
+      ...compiler, allowJs: true,
+      paths: { ...compiler.paths, [config.publicAlias]: [entryFile] },
+      types: compiler.types ?? [],
+    });
+    const checker = semantic.getTypeChecker();
+    const entry = semantic.getSourceFile(entryFile);
+    const module = entry && checker.getSymbolAtLocation(entry);
+    const callables = new Map();
+    for (const exported of module ? checker.getExportsOfModule(module) : []) {
+      const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+      const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+      if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
+      const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+      callables.set(exported.name, !!(type.getCallSignatures().length || type.getConstructSignatures().length));
+    }
+    resolvedCallables.set(program, callables);
+  }
+  return resolvedCallables.get(program).get(name) ?? false;
+}
 
 export function publicApi(program, options) {
   const checker = program.getTypeChecker();
@@ -33,7 +65,11 @@ export function publicApi(program, options) {
     }
     visit(declaration);
     const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
-    items.push({ name: exported.name, kind, file, declaration, renderable: kind !== "controllers" && renderable, behavioral: !!(type.getCallSignatures().length || type.getConstructSignatures().length) });
+    const behavioral = !!(type.getCallSignatures().length || type.getConstructSignatures().length
+      || !renderable && !!(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+      && (program.getCompilerOptions().noLib || program.getCompilerOptions().noResolve)
+      && resolvedCallable(program, options, exported.name));
+    items.push({ name: exported.name, kind, file, declaration, renderable: kind !== "controllers" && renderable, behavioral });
   }
   return items;
 }

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;
@@ -202,8 +207,12 @@ 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 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;
@@ -212,12 +221,10 @@ 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;
@@ -281,7 +288,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       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

@@ -8,6 +8,7 @@ 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");
 
@@ -39,14 +40,16 @@ export function inspectScenarios(options, suppliedProgram) {
   const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
   const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
-  const tokenNames = new Set(inspectTokens(root).tokens.map(token => token.name));
+  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; }
@@ -62,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");
@@ -77,17 +85,31 @@ 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", "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)))
+    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, "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 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;
     }
+    // A bad behavioral entry must fail validation without erasing independent
+    // render evidence and manufacturing missing-coverage errors for real UI.
+    const exercises = [];
+    if (Object.hasOwn(metadata, "exercises")) {
+      if (!Array.isArray(metadata.exercises)) report(file, "Scenario exercises must be a static array naming public behavioral APIs.");
+      else for (const [index, name] of metadata.exercises.entries()) {
+        if (typeof name !== "string") report(file, `Scenario exercises[${index}] must name a public behavioral API, not ${JSON.stringify(name) ?? "an unresolved value"}.`);
+        else if (!behaviorApis.has(name)) report(file, `Scenario exercises[${index}] ${JSON.stringify(name)} is not a recognized public behavioral API. Use a public callable function, hook or controller; rendered UI belongs in covers. Discover the project's exports before declaring exercises.`);
+        else exercises.push(name);
+      }
+    }
     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)], ...(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("\\", "/") });
+    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)], ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(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 };
 }
@@ -209,3 +231,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/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,8 +45,16 @@ 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).
 
 
+For atomic base/variant styling or an `atomic-composition-review` warning, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
+
 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,

package/dist/skills/ads-break-ui/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports, nested composition, conditional
+expressions and variant-object lookups. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. An empty warning list does not establish
+visual correctness. Actual failed registered browser/behavior checks remain
+blocking; potentially intentional source overlaps remain warnings.

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.

package/dist/skills/ads-designer/SKILL.md

@@ -68,8 +68,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
@@ -77,6 +77,14 @@ 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).
+
+For atomic base/variant styling or an `atomic-composition-review` warning, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
 
 Controllers are UI behavior owners: private helpers stay with their component or
 pattern; reusable controllers use discovered `controllers/<Name>` units. Use the

package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md

@@ -36,8 +36,14 @@ Projects sharing this ADS use the same token names, meanings, and value types;
 their concrete values and theme overrides can differ. Reuse existing local values
 when importing components/patterns, add missing shared definitions, and import
 source token values only when adopting that theme is requested.
-Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
-are rejected. Shared assignments belong in token files. Components own
+Shared token names and prefixes follow the ADS contract. A component/pattern may
+register one unique local namespace in colocated `tokens.json` and define it in
+`tokens.css`, imported by its runtime. Flat owners use `<Owner>.tokens.json` and
+`<Owner>.tokens.css`. These definition-only sheets contain root/theme custom
+properties, not UI selectors or ordinary styles. Other owners consume shared
+tokens; they cannot override or consume a peer's local namespace. A colocated
+`kind:"tokens"` scenario needs real samples for every local token. Shared
+assignments remain in the shared token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
 
@@ -183,7 +189,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders

package/dist/skills/ads-designer/assets/bootstrap-ds/README.md

@@ -62,6 +62,10 @@ the public `TokenPreview` pattern owns their presentation and applies the real C
 variables. Add/remove samples alongside token definitions. `ads check` rejects
 missing coverage and invented names; the App verifies the declared CSS bindings
 in the browser. Extend or replace the project-owned pattern as your tokens evolve.
+`ads_prepare_token_samples` can prepare a fixture patch from explicit project
+property/probe bindings. It preserves existing samples and reports unmapped tokens;
+it does not guess how a new value should look. Component/pattern constants can use
+the colocated namespace contract in [ADS.md](ADS.md), with their own token scenario.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and
@@ -79,6 +83,8 @@ stale retained output. Switching or rebuilding a scenario unmounts its previous
 state. `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and
 returns an unmount callback; it is not the shell. Keep the saved `framework`,
 compiler and mount adapter consistent.
+Managed sessions own their graph output; standalone prebuilds cannot replace it.
+Verified generated graph snapshots preserve warm-start reuse across sessions.
 
 The application and previews use the same foundation CSS and Linaria pipeline.
 The source barrel loads the foundation once. The private `build:lib` script uses
@@ -98,3 +104,7 @@ from a user-selected external repository, preserving revisions and licenses.
 inspection builds it automatically, then loads selected entries. Browser review
 still checks layout, accessibility, keyboard/focus, states, themes and motion. A clean
 build or delivered HTML alone does not establish those behaviors.
+Opt-in MCP editing uses owner Git patches. `ads_prepare_patch` creates a temporary
+owner draft/diff; `ads_apply_transaction` validates bounded coupled owner patches
+against one final candidate. Preparation changes no live source. Keep all guards
+and review the rendered result after applying.