@reqvire-org/ads 0.3.8 → 0.3.10

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");
 
@@ -109,12 +110,13 @@ export function inspectScenarios(options, suppliedProgram) {
       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("\\", "/") });
+    const stylesheets = kind === "tokens" ? scoped.definitions.filter(entry => entry.unit === scoped.inventory.owner(relative)).map(entry => entry.file) : [];
+    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 } : {}), ...(stylesheets.length ? { stylesheets } : {}), 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, 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();
@@ -164,6 +166,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;
@@ -178,6 +181,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); }
@@ -201,9 +208,9 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
           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;
@@ -214,7 +221,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,11 +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, helper/wrapper class composition, or an
+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,56 @@ 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

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

@@ -0,0 +1,98 @@
+# Scenario rendering, token previews 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`.
+
+## Owner-local token previews load their own definitions
+
+Keep the registered token sheet imported by its runtime owner for product use.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
+## 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,11 +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, helper/wrapper class composition, or an
+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
@@ -328,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") },
   },

package/dist/skills/ads-designer/references/atomic-styles.md

@@ -81,6 +81,56 @@ 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

package/dist/skills/ads-designer/references/scenarios.md

@@ -0,0 +1,98 @@
+# Scenario rendering, token previews 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`.
+
+## Owner-local token previews load their own definitions
+
+Keep the registered token sheet imported by its runtime owner for product use.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
+## 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).