@reqvire-org/ads 0.3.7 → 0.3.9

package/dist/mcp/server.mjs

@@ -85,7 +85,8 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return [
       { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
       { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
-      { uri: "ads://guides/atomic-styles", name: "Atomic style composition: conflicts, prevention and fixes", mimeType: "text/markdown" },
+      { uri: "ads://guides/atomic-styles", name: "Atomic styles: composition conflicts and custom-property extraction", mimeType: "text/markdown" },
+      { uri: "ads://guides/scenarios", name: "Scenario coverage and public class-helper contracts", mimeType: "text/markdown" },
       { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
       { uri: BUILD_URI, name: "Preview build status and diagnostics", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/tokens`, name: "Project token values and themes", mimeType: "application/json" },
@@ -123,6 +124,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
     if (uri === "ads://guides/behaviors") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../../docs/BEHAVIORS.md", import.meta.url), "utf8") }] };
     if (uri === "ads://guides/atomic-styles") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/atomic-styles.md", import.meta.url), "utf8") }] };
+    if (uri === "ads://guides/scenarios") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/scenarios.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -205,7 +207,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const matches = inventory.tokens.filter((token) => token.name.toLowerCase().includes(search.toLowerCase()));
         return json({ total: matches.length, tokens: matches.slice(0, limit), categories: tokenScenarios(), diagnosticCount: inventory.diagnostics.length, resourceUri: `${PROJECT_URI}/tokens` });
       } },
-      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Atomic composition warnings identify overlapping properties and link ads://guides/atomic-styles for causes and fixes. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
+      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking advisories, with warnings before informational limits. Atomic warnings include helper/forwarded-class paths and ads://guides/atomic-styles guidance; unresolved paths do not establish safe composition. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
         const result = checkProject(root);
         return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), advisoryCount: result.advisories?.length ?? 0, advisories: (result.advisories ?? []).slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
       } },

package/dist/scenario-trace.mjs

@@ -0,0 +1,149 @@
+import path from "node:path";
+import ts from "typescript";
+import postcss from "postcss";
+import { isDevelopmentFile, isInside } from "./config.mjs";
+import { publicApi } from "./public-api.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+import { inspectUnits } from "./units.mjs";
+import { createSourceValues, reference, union, isFunction } from "./source-values.mjs";
+
+/** Source evidence only. No project modules execute, and unknown paths grant no
+ * permission. Coverage uses intersections across unresolved render branches;
+ * class helpers must retain provenance through every possible returned value. */
+export function createScenarioTrace(program, options) {
+  const checker = program.getTypeChecker(), maxBranches = 32;
+  function linaria(expression, name, seen = new Set()) {
+    if (!expression || seen.has(expression)) return false;
+    seen.add(expression);
+    const base = ts.isPropertyAccessExpression(expression) ? expression.expression : expression;
+    const symbol = checker.getSymbolAtLocation(base);
+    for (const declaration of symbol?.declarations ?? []) {
+      if (ts.isImportSpecifier(declaration) && (declaration.propertyName ?? declaration.name).text === name && ["@linaria/atomic", "@linaria/core"].includes(declaration.parent.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isNamespaceImport(declaration) && ts.isPropertyAccessExpression(expression) && expression.name.text === name && ["@linaria/atomic", "@linaria/core"].includes(declaration.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isVariableDeclaration(declaration) && declaration.parent.flags & ts.NodeFlags.Const && linaria(declaration.initializer, name, seen)) return true;
+    }
+    return false;
+  }
+  const isCx = expression => linaria(expression, "cx");
+  const { state, next, at, resolve, get, arrays, returns, props } = createSourceValues(program, options, { preserveCall: expression => isCx(expression) || uiOperation(expression, checker) === "createElement", strict: true });
+  const publicNodes = new Map(), helpers = new Map(), inventory = inspectUnits(options);
+  const locationKey = value => JSON.stringify([value.file, value.line, value.column]);
+  function runtimeOwner(file) {
+    return ["components", "patterns"].some(folder => isInside(path.join(options.dsRoot, folder), file)) && !isDevelopmentFile(file, options)
+      ? inventory.owner(inventory.relative(path.relative(options.root, file))) : null;
+  }
+  for (const item of publicApi(program, options)) {
+    const value = resolve(reference(item.declaration.name ?? item.declaration), state());
+    if (value.kind !== "node") continue;
+    if (item.renderable) {
+      if (!publicNodes.has(value.node)) publicNodes.set(value.node, new Set());
+      publicNodes.get(value.node).add(item.name);
+    } else if (item.behavioral && item.kind !== "controllers" && isFunction(value.node)) helpers.set(locationKey(at(value.node, "helper", "")), runtimeOwner(item.file));
+  }
+  const combine = sets => new Set(sets.flatMap(value => [...value]));
+  const common = sets => new Set(sets[0] ? [...sets[0]].filter(name => sets.every(set => set.has(name))) : []);
+
+  function element(node, env, via) {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const attributes = props(opening, env, via);
+      const children = ts.isJsxElement(node) ? node.children.filter(child => !ts.isJsxText(child) || child.text.trim()) : [];
+      if (children.length) attributes.layers.push(new Map([["children", children.length === 1 ? reference(children[0], env, via) : { kind: "array", values: children.map(child => reference(child, env, via)) }]]));
+      return { tag: reference(opening.tagName, env, via), attributes, intrinsic: ts.isIdentifier(opening.tagName) && /^[a-z]/.test(opening.tagName.text) };
+    }
+    if (ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement") {
+      const attributes = { kind: "object", layers: node.arguments[1] && node.arguments[1].kind !== ts.SyntaxKind.NullKeyword ? [reference(node.arguments[1], env, via)] : [] };
+      const children = node.arguments.slice(2).map(child => reference(child, env, via));
+      if (children.length) attributes.layers.push(new Map([["children", children.length === 1 ? children[0] : { kind: "array", values: children }]]));
+      return { tag: reference(node.arguments[0], env, via), attributes, intrinsic: !!node.arguments[0] && ts.isStringLiteralLike(node.arguments[0]) };
+    }
+    return null;
+  }
+
+  function traceRenders(site) {
+    const limits = new Set();
+    function render(input, context) {
+      const value = resolve(input, next(context));
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "unknown") { if (value.reason) limits.add(value.reason); return new Set(); }
+      if (value.kind === "union") {
+        if (value.values.length > maxBranches) { limits.add("Scenario render tracing reached its alternative limit."); return new Set(); }
+        return common(value.values.map(item => render(item, next(context))));
+      }
+      if (value.kind === "array") return combine(value.values.map(item => render(item, next(context))));
+      if (value.kind !== "node") return new Set();
+      const { node, env, via } = value;
+      if (ts.isJsxExpression(node)) return render(reference(node.expression, env, via), next(context));
+      if (ts.isJsxFragment(node)) return combine(node.children.map(child => render(reference(child, env, via), next(context))));
+      if (ts.isArrayLiteralExpression(node)) return combine(node.elements.map(child => render(reference(ts.isSpreadElement(child) ? child.expression : child, env, via), next(context))));
+      const view = element(node, env, via);
+      if (!view) return new Set();
+      if (view.intrinsic) return render(get(view.attributes, "children", next(context)), next(context));
+      function component(input) {
+        const target = resolve(input, next(context));
+        if (["provider", "context"].includes(target.kind)) return render(get(view.attributes, "children", next(context)), next(context));
+        if (target.kind === "union") return target.values.length <= maxBranches ? common(target.values.map(component)) : new Set();
+        if (target.kind !== "node") return new Set();
+        const names = new Set(publicNodes.get(target.node) ?? []);
+        if (isFunction(target.node) && !isDevelopmentFile(target.node.getSourceFile().fileName, options)) {
+          const outputs = returns(target, [view.attributes], next(context), "component");
+          for (const name of render(union(outputs), next(context))) names.add(name);
+        }
+        return names;
+      }
+      return component(view.tag);
+    }
+    return { rendered: render(reference(site), state()), limits: [...limits].slice(0, 3) };
+  }
+
+  function classValue(expression, property = false) {
+    const reasons = new Set();
+    const result = (ok, atoms = false, hooks = false) => ({ ok, branches: [{ atoms, hooks }] });
+    const owned = (file, via) => {
+      const owner = runtimeOwner(file);
+      return !!owner && via?.some(location => helpers.get(locationKey(location)) === owner);
+    };
+    function verify(input, context) {
+      const value = resolve(input, next(context));
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "union") {
+        if (value.values.length > maxBranches) { reasons.add("Class provenance reached its alternative limit."); return result(false); }
+        const branches = value.values.map(item => verify(item, next(context)));
+        return { ok: branches.every(item => item.ok), branches: branches.flatMap(item => item.branches) };
+      }
+      if (value.kind === "literal" && !value.value) return result(true);
+      if (value.kind === "literal" && typeof value.value === "string" && value.origin && owned(value.origin.getSourceFile().fileName, value.via)) return result(true, false, true);
+      if (value.kind === "node") {
+        const { node, env, via } = value;
+        if (ts.isTaggedTemplateExpression(node) && linaria(node.tag, "css")) {
+          const source = node.getSourceFile().fileName;
+          let declarations = 0;
+          const template = node.template;
+          const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text : template.head.text + template.templateSpans.map(span => `__ads_expression__${span.literal.text}`).join("");
+          try { postcss.parse(text).walkDecls(() => ++declarations); } catch { /* Source CSS guards own malformed templates. */ }
+          if (owned(source, via) && declarations) return result(true, true);
+          reasons.add("The returned style must originate in runtime component/pattern Linaria through a public callable helper.");
+          return result(false);
+        }
+        if (ts.isCallExpression(node) && isCx(node.expression)) {
+          const arguments_ = node.arguments.flatMap(argument => ts.isSpreadElement(argument) ? arrays(reference(argument.expression, env, via), context) ?? [reference(argument.expression, env, via)] : [reference(argument, env, via)]);
+          const values = arguments_.map(argument => verify(argument, next(context)));
+          let branches = [{ atoms: false, hooks: false }];
+          for (const value of values) branches = [...new Map(branches.flatMap(first => value.branches.map(second => ({ atoms: first.atoms || second.atoms, hooks: first.hooks || second.hooks }))).map(branch => [JSON.stringify(branch), branch])).values()];
+          return { ok: values.every(item => item.ok), branches };
+        }
+      }
+      reasons.add(value.reason || "A returned class value is an arbitrary string or cannot be traced to owned Linaria.");
+      return result(false);
+    }
+    const context = state();
+    const input = property ? get(reference(expression), "className", next(context)) : reference(expression);
+    const value = resolve(input, next(context));
+    if (property && value.kind === "literal" && value.value === undefined) return { present: false, ok: true, reasons: [] };
+    const proof = verify(input, context);
+    const ok = proof.ok && proof.branches.some(branch => branch.atoms) && proof.branches.every(branch => !branch.hooks || branch.atoms);
+    if (!ok && !reasons.size) reasons.add("Each nonempty return path needs owned Linaria styles; stable hooks alone are not styling evidence.");
+    return { present: !property || value.kind !== "unknown", ok, reasons: [...reasons].slice(0, 3) };
+  }
+  return { traceRenders, classValue };
+}

package/dist/scenarios-compiler.mjs

@@ -14,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, "preview-scope.mjs"), path.join(import.meta.dirname, "scenarios-vite.mjs"), ...compilerFiles,
+  const adapterFiles = [import.meta.filename, ...["preview-resources.mjs", "preview-scope.mjs", "scenarios-vite.mjs", "linaria.mjs", "linaria/atomic-css.cjs", "linaria/atomic-styled.cjs", "linaria/preserve-values.cjs"].map(file => path.join(import.meta.dirname, file)), ...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();
@@ -46,6 +46,7 @@ export function createPreviewCache(options, compilerFiles = []) {
     for (const name of readdirSync(import.meta.dirname).filter(name => name.endsWith(".mjs"))) {
       rows.push([`ads-tool/${name}`, fileDigest(path.join(import.meta.dirname, name))]);
     }
+    for (const name of readdirSync(path.join(import.meta.dirname, "linaria"))) rows.push([`ads-tool/linaria/${name}`, fileDigest(path.join(import.meta.dirname, "linaria", name))]);
     return digest(JSON.stringify(rows.sort((a, b) => a[0].localeCompare(b[0]))));
   }
   function save() {

package/dist/scenarios.mjs

@@ -9,6 +9,7 @@ import { inspectTokens } from "./tokens.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { validTokenSamples } from "./token-samples.mjs";
 import { scopedTokens } from "./scoped-tokens.mjs";
+import { createScenarioTrace } from "./scenario-trace.mjs";
 
 export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
 
@@ -114,7 +115,7 @@ export function inspectScenarios(options, suppliedProgram) {
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
 
-export function inspectScenarioCoverage(options, program, report, advise = () => {}) {
+export function inspectScenarioCoverage(options, program, report, advise = () => {}, trace = createScenarioTrace(program, options)) {
   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();
@@ -147,10 +148,11 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
     }
     return symbol.declarations?.length ? symbol : null;
   }
-  const identities = new Map();
+  const identities = new Map(), behaviorIdentities = new Set();
   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);
+    if (item.behavioral && !item.renderable) behaviorIdentities.add(item.declaration);
   }
 
   const covered = new Set();
@@ -163,6 +165,7 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
     const exercised = new Set(), referencedApis = new Set();
     const referencedTokens = new Set();
     let samplesPassed = false;
+    const renderLimits = new Set();
     const visited = new Set();
     function visit(node, reached = false) {
       if (!node || visited.has(node)) return;
@@ -177,6 +180,10 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
       if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) expression = node.tagName;
       if (ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement") expression = node.arguments[0];
       if (expression) {
+        const site = ts.isJsxOpeningElement(node) ? node.parent : node;
+        const evidence = trace.traceRenders(site);
+        for (const name of evidence.rendered) rendered.add(name);
+        for (const reason of evidence.limits) renderLimits.add(reason);
         const symbol = canonical(symbolOf(expression));
         const names = identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
         for (const name of names ?? []) { rendered.add(name); exercised.add(name); }
@@ -190,10 +197,19 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
         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);
+        // A call on an attached method exercises its public behavioral receiver.
+        // Follow symbol identities through aliases, namespaces and re-exports;
+        // a property read or an unused callback still does not establish a call.
+        while (ts.isPropertyAccessExpression(expression) || ts.isElementAccessExpression(expression) && expression.argumentExpression && ts.isStringLiteralLike(expression.argumentExpression)) {
+          expression = expression.expression;
+          const receiver = canonical(symbolOf(expression));
+          const owner = receiver?.valueDeclaration ?? receiver?.declarations?.[0];
+          if (behaviorIdentities.has(owner)) for (const name of identities.get(owner) ?? []) 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.
+      // Follow local adapters reachable from the default entry. Production
+      // children get evidence only from bounded returned-JSX tracing above,
+      // never by scanning every reference in their implementation.
       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;
@@ -204,7 +220,7 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
     }
     for (const node of source.statements) if (ts.isExportAssignment(node) || node.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) visit(node, true);
     for (const name of scenario.covers) {
-      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.`);
+      if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no reachable public render reference. Render it directly or through a traced parent with fixture props/defaults selecting that child. Imports, unused JSX and unknown conditional paths do not establish coverage.${renderLimits.size ? ` Source tracing could not establish: ${[...renderLimits].slice(0, 2).join(" ")}` : ""} Review the real scenario in a browser; do not hide a valid public part just to avoid coverage. See ads://guides/scenarios.`);
       else covered.add(name);
     }
     for (const name of scenario.exercises ?? []) {

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

@@ -49,10 +49,18 @@ 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
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, or an
+`atomic-composition-review` / `atomic-composition-limit` advisory, 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
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. 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

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

@@ -81,6 +81,91 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
+## Follow helpers and forwarded classes
+
+Composition can cross a helper or a component boundary. For example, in component
+implementation source:
+
+```tsx
+function baseClasses() { return base; }
+function Primitive({ className, ...props }) {
+  return <button {...props} className={cx(baseClasses(), className)} />;
+}
+function CompactPrimitive(props) {
+  return <Primitive {...props} className={small} />;
+}
+```
+
+The base and small atoms can reach the same button. Inspect both owners when
+correcting their property vocabulary. The wrapper's class does not style every
+descendant: a class on a child or sibling element is a separate composition.
+An imported stylesheet alone does not show that its classes co-apply.
+
+Spread order matters. `<button className={base} {...props} />` can replace the
+entire className; `<button {...props} className={cx(base, className)} />` composes
+it explicitly. Keep the product's intended forwarding behavior when fixing an
+overlap. Do not change the public API simply to make tracing easier.
+
+Warnings include a bounded `composition` path through traced helpers and
+components. A `target` identifies a statically reached DOM element. This
+establishes source composition, not that a scenario mounted it or that its
+computed result is wrong. `writingModeDependent: true` identifies overlaps that
+change with direction or writing mode; evaluate those against supported modes.
+Literal overlaps with provably equal values are omitted where the analyzer can
+expand them safely. Token formulas, inheritance and runtime values still need
+review. A margin shorthand and `margin-inline: auto` may agree horizontally but
+disagree in vertical text, so horizontal equality alone is insufficient.
+
 ## Respond to a warning
 
 1. Follow the warning's related file/line locations and inspect the actual `cx`
@@ -101,6 +186,24 @@ 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.
 
+Use existing behavior contracts and `ads_verify` for important geometry. Register
+a check beside its owner, link its real scenario and use the project's browser
+profile. An assertion can inspect the actual control in the App frame:
+
+```ts
+const frame = await openBehaviorScenario(page, "compact-spacing");
+await expect(frame.getByRole("button", { name: "Compact" }))
+  .toHaveCSS("padding-inline-start", "8px");
+```
+
+The name, check ID and expected value above are examples. Derive assertions from
+the project's intended API and design, with relevant variants, open/hover/focus
+states, themes and supported writing modes. Wait for observable readiness; an
+event-stream connection can prevent `networkidle` from settling. A generic
+overlap scan cannot decide which dimensions the product intended. A failed
+registered geometry assertion is blocking through the existing verification
+contract; an overlap warning remains a review signal.
+
 ## What ADS checks
 
 `atomic-composition-review` is a nonblocking warning, returned under `advisories`
@@ -108,14 +211,26 @@ 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
+`cx` arguments, including aliases, local imports/re-exports, local helper returns,
+arguments/defaults, nested composition, conditional expressions and variant-object
+lookups. It follows explicit `className` forwarding through local function
+components, props/rest spreads and imported React/Preact `memo`/`forwardRef`
+wrappers to an intrinsic JSX element. 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.
+within one conditional or lookup are not assumed to apply together. Matching
+atomic property/selector/condition keys are replaced during traced `cx`
+composition before comparing the surviving declarations.
 
 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.
+does not execute helpers or import project modules, enumerate every external
+class, or model arbitrary runtime mutation, component rendering, selectors or
+overlapping media queries. Recursive calls, unsupported call/control-flow paths,
+unresolved DOM targets and traversal limits produce bounded
+`atomic-composition-limit` informational advisories where known atomic styles
+reach an unresolved composition. Ordinary externally supplied className values
+remain open inputs, not guaranteed safe styles. Depth, work and alternative
+limits keep source inspection bounded; an unreported path or 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/scenarios.md

@@ -0,0 +1,83 @@
+# Scenario render evidence and public class helpers
+
+Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
+
+## Public children can share their parent's scenario
+
+Declare the public parts actually demonstrated in `covers`, even when their
+parent renders them internally:
+
+```tsx
+// Runtime owner
+export function Part() { return <span>Content</span>; }
+export function Frame({ visible = true } = {}) {
+  return <section>{visible && <Part />}</section>;
+}
+
+// Colocated Scenario.tsx
+import { Frame } from "@ds";
+export const scenario = { title: "Frame", covers: ["Frame", "Part"] };
+export default function Scenario() { return <Frame />; }
+```
+
+ADS follows returned JSX through local components/helpers, aliases, registered
+framework factories, memo/ref wrappers and context providers. Fixture props,
+spreads and destructuring defaults select the child path. An explicit
+`visible={false}` does not cover `Part`. When a condition remains unknown, only
+parts returned on every possible path receive transitive credit. Imports, unused
+JSX, event-handler bodies and uncalled functions do not establish child rendering.
+Only the explicitly declared `covers` entries acquire coverage; dependencies are
+not silently added to metadata or the catalogue.
+
+Tracing is bounded and does not execute the project. Recursion, written/escaped inputs,
+opaque external wrappers and unsupported control flow can prevent proof. The
+diagnostic explains known limits. Use meaningful fixture states or another real
+scenario; do not make a valid public part private or duplicate it in a parent
+just to satisfy a guard. Static evidence does not establish successful mounting,
+visibility, interaction, every state or visual parity. Verify those in the built
+App and registered browser checks.
+
+## Scenarios may consume verified public style helpers
+
+A deliberately public helper can expose its owner's Linaria treatment:
+
+```tsx
+// Runtime owner
+const treatment = css`padding-inline: var(--space-4);`;
+export function controlClasses() {
+  return cx("control-hook", treatment);
+}
+
+// Scenario: consume the public API; define no styles here
+<PublicLink className={controlClasses()}>Documentation</PublicLink>
+```
+
+The sample token and APIs are illustrative; use the project's real exports and
+tokens. Import helpers through the public ADS entry. ADS traces helper calls,
+returns, local aliases, finite known selections and Linaria `cx` composition.
+Styling must originate in component/pattern Linaria through a public callable
+helper. A literal stable hook authored in that runtime owner may accompany the
+verified styles. Each nonempty return path needs actual Linaria declarations;
+empty templates and hook-only/string-only returns do not qualify.
+
+These are still rejected:
+
+```tsx
+<PublicLink className="custom-layout" />
+<PublicLink className={arbitraryPublicFunctionReturningAString()} />
+<PublicLink className={controlClasses({ className: "custom-layout" })} />
+```
+
+Scenario-supplied strings, generated styles in fixtures, private style imports,
+spoofed Linaria functions and untraceable results acquire no permission by being
+passed through a public function. Known className values in props/spreads receive
+the same provenance check. Opaque spreads remain outside complete source proof.
+An `exercises` entry records behavioral use; it never grants styling permission.
+
+Keep helper signatures compatible with the product API. Fix ownership/provenance
+in the runtime owner when genuinely wrong; retain intentional public APIs when
+reporting an unsupported trace. Demo-only sizing, framing and arrangement still
+belong in public review/layout patterns. A style helper is not permission to
+author a second design in the scenario. For cascade risks and extraction issues,
+read [atomic-styles.md](atomic-styles.md).

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

@@ -80,10 +80,18 @@ 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
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, or an
+`atomic-composition-review` / `atomic-composition-limit` advisory, 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
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. 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
@@ -327,7 +335,9 @@ Screen reuse remains skill guidance, not a dedicated screen-parity lint.
 Resolve `scenario-contract`, `scenario-render` and `scenario-coverage` findings
 with meaningful entries. Every public renderable component and pattern needs an
 addressable scenario, including unused exports; types/constants/utilities do not.
-Only public render references reachable from the default entry count. Tests and
+Direct and traced parent/child public render references reachable from the default
+entry count. Declared children need returned JSX selected by known props/defaults;
+unresolved branches do not grant speculative coverage. Tests and
 unused imports/functions do not. Static reachability does not prove successful
 mounting, correct content, every branch/state or visual parity: open each affected
 entry independently and verify real behavior at narrow/wide sizes in both themes.

package/dist/skills/ads-designer/assets/bootstrap-ds/scripts/build-mcp-previews.mjs

@@ -4,6 +4,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { build } from "vite";
 import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
 import react from "@vitejs/plugin-react";
 import { runScenarioCompiler } from "@reqvire-org/ads/scenarios/compiler";
 import { createPreviewResources, previewEntriesPlugin } from "@reqvire-org/ads/scenarios/vite";
@@ -22,7 +23,7 @@ await runScenarioCompiler(root, {
   async buildGraph(entries, options, track) {
     const mount = path.join(options.dsRoot, "showcase/mcp/main.tsx");
     const output = await build({ configFile: false, root, base: "./", publicDir: false,
-      plugins: [previewEntriesPlugin(entries.map(entry => ({ ...entry, root })), mount), wyw({ include: ["**/*.{ts,tsx}"], exclude: ["**/node_modules/**"] }), react(), track],
+      plugins: [previewEntriesPlugin(entries.map(entry => ({ ...entry, root })), mount), wyw({ tagResolver: linariaTagResolver, include: ["**/*.{ts,tsx}"], exclude: ["**/node_modules/**"] }), react(), track],
       resolve: { alias: { "@ds": path.join(options.dsRoot, options.config.publicEntry) } },
       worker: { format: "iife" },
       build: { write: false, cssCodeSplit: true, assetsInlineLimit: 0, modulePreload: false,

package/dist/skills/ads-designer/assets/bootstrap-ds/vite.config.ts

@@ -2,9 +2,10 @@ import path from "node:path";
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
 
 export default defineConfig({
-  plugins: [wyw(), react()],
+  plugins: [wyw({ tagResolver: linariaTagResolver }), react()],
   resolve: {
     alias: { "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
   },