@reqvire-org/ads 0.3.7 → 0.3.8

package/dist/atomic-composition.mjs

@@ -1,7 +1,9 @@
 import path from "node:path";
 import ts from "typescript";
 import postcss from "postcss";
+import valueParser from "postcss-value-parser";
 import { isInside } from "./config.mjs";
+import { createAtomicTrace } from "./atomic-trace.mjs";
 
 export const atomicStyleGuide = "ads://guides/atomic-styles";
 
@@ -62,6 +64,67 @@ function overlaps(a, b) {
   return intersects(longhands.get(a) ?? [a], longhands.get(b) ?? [b]);
 }
 
+const modes = ["horizontal-tb", "vertical-rl", "vertical-lr"].flatMap(mode => ["ltr", "rtl"].map(direction => ({ mode, direction })));
+function physicalSlots(property, { mode, direction }) {
+  const value = footprint(property);
+  if (!value) return null;
+  if (value.whole) return sides;
+  const horizontal = mode === "horizontal-tb";
+  const axes = {
+    "block-start": horizontal ? "top" : mode === "vertical-rl" ? "right" : "left",
+    "block-end": horizontal ? "bottom" : mode === "vertical-rl" ? "left" : "right",
+    "inline-start": horizontal ? direction === "ltr" ? "left" : "right" : direction === "ltr" ? "top" : "bottom",
+    "inline-end": horizontal ? direction === "ltr" ? "right" : "left" : direction === "ltr" ? "bottom" : "top",
+    "inline-size": horizontal ? "width" : "height", "block-size": horizontal ? "height" : "width",
+    inline: horizontal ? "x" : "y", block: horizontal ? "y" : "x",
+  };
+  return value.slots.map(slot => value.family === "radius" && slot ? (/^(start|end)-/.test(slot) ? [axes[`block-${slot.split("-")[0]}`], axes[`inline-${slot.split("-")[1]}`]] : slot.split("-")).sort().join("-") : axes[slot] ?? slot);
+}
+function writingModeDependent(a, b) {
+  const first = footprint(a), second = footprint(b);
+  if (!first || !second || first.family !== second.family || first.whole || second.whole || first.logical === second.logical) return false;
+  const matches = modes.map(mode => intersects(physicalSlots(a, mode), physicalSlots(b, mode)));
+  return matches.some(Boolean) && !matches.every(Boolean);
+}
+function words(value) {
+  const nodes = valueParser(value).nodes;
+  return nodes.every(node => ["word", "space", "comment"].includes(node.type)) ? nodes.filter(node => node.type === "word").map(node => node.value.toLowerCase()) : null;
+}
+function boxValues(entry, mode) {
+  const value = footprint(entry.property), parts = words(entry.value);
+  if (!value || !["padding", "margin", "scroll-padding", "scroll-margin", "inset"].includes(value.family) || !parts?.length || parts.length > 4 || parts.some(part => ["inherit", "initial", "unset", "revert", "revert-layer"].includes(part))) return null;
+  const slots = physicalSlots(entry.property, mode);
+  if (!value.whole && parts.length > slots.length) return null;
+  const expanded = value.whole ? [parts[0], parts[1] ?? parts[0], parts[2] ?? parts[0], parts[3] ?? parts[1] ?? parts[0]] : slots.map((_slot, index) => parts[index] ?? parts[0]);
+  return new Map(slots.map((slot, index) => [slot, expanded[index]]));
+}
+function equivalent(a, b) {
+  // Only suppress values whose overlap can be established from literal source.
+  // var(), calc(), inheritance and token aliases still need rendered review.
+  const first = footprint(a.property), second = footprint(b.property);
+  if (first && second && first.family === second.family && ["padding", "margin", "scroll-padding", "scroll-margin", "inset"].includes(first.family)) {
+    return modes.every(mode => {
+      const left = boxValues(a, mode), right = boxValues(b, mode);
+      return left && right && [...left].every(([slot, value]) => !right.has(slot) || right.get(slot) === value);
+    });
+  }
+  const flex = a.property === "flex" ? a : b.property === "flex" ? b : null;
+  const field = flex === a ? b : a;
+  if (flex && ["flex-grow", "flex-shrink", "flex-basis"].includes(field.property)) {
+    const parts = words(flex.value);
+    return parts?.length === 3 && /^\d+(?:\.\d+)?$/.test(parts[0]) && /^\d+(?:\.\d+)?$/.test(parts[1]) && /^(?:auto|0|\d+(?:\.\d+)?(?:px|rem|em|%))$/.test(parts[2]) && parts[["flex-grow", "flex-shrink", "flex-basis"].indexOf(field.property)] === field.value.trim().toLowerCase();
+  }
+  return false;
+}
+
+function valueModeDependent(a, b) {
+  const equal = modes.map(mode => {
+    const left = boxValues(a, mode), right = boxValues(b, mode);
+    return left && right ? [...left].every(([slot, value]) => !right.has(slot) || right.get(slot) === value) : null;
+  });
+  return !equal.includes(null) && equal.some(Boolean) && !equal.every(Boolean);
+}
+
 function unwrap(node) {
   while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
   return node;
@@ -70,11 +133,6 @@ function unwrap(node) {
 /** Review only: valid CSS can intentionally overlap. Never rewrite project CSS. */
 export function createAtomicCompositionReview(program, options) {
   const checker = program.getTypeChecker(), templates = new Map();
-  function declaration(node) {
-    let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
-    if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
-    return symbol?.valueDeclaration;
-  }
   function imported(node, names, modules, seen = new Set()) {
     node = unwrap(node);
     if (!node || seen.has(node)) return false;
@@ -117,67 +175,40 @@ export function createAtomicCompositionReview(program, options) {
     } catch { /* The core CSS syntax diagnostic owns malformed templates. */ }
     return result;
   }
-  function object(node, seen = new Set()) {
-    node = unwrap(node);
-    if (!node || seen.has(node)) return null;
-    if (ts.isObjectLiteralExpression(node) || ts.isArrayLiteralExpression(node)) return node;
-    const owner = declaration(node);
-    return owner?.initializer ? object(owner.initializer, new Set([...seen, node])) : null;
-  }
-  function styles(node, seen = new Set()) {
-    node = unwrap(node);
-    if (!node || seen.has(node)) return [];
-    seen = new Set([...seen, node]);
-    if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) return entries(node);
-    if (ts.isConditionalExpression(node)) return [...styles(node.whenTrue, seen), ...styles(node.whenFalse, seen)];
-    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return [...(node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ? [] : styles(node.left, seen)), ...styles(node.right, seen)];
-    if (ts.isCallExpression(node) && isCx(node.expression)) return node.arguments.flatMap(argument => styles(argument, seen));
-    if (ts.isSpreadElement(node)) {
-      const value = object(node.expression);
-      return value && ts.isArrayLiteralExpression(value) ? value.elements.flatMap(element => styles(element, seen)) : [];
-    }
-    const owner = declaration(node);
-    if (owner?.initializer) return styles(owner.initializer, seen);
-    if (ts.isElementAccessExpression(node) || ts.isPropertyAccessExpression(node)) {
-      const value = object(node.expression);
-      if (!value || !ts.isObjectLiteralExpression(value)) return [];
-      const key = ts.isPropertyAccessExpression(node) ? node.name.text : node.argumentExpression && ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
-      return value.properties.flatMap(property => {
-        const name = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
-        return key !== null && name !== key ? [] : ts.isPropertyAssignment(property) ? styles(property.initializer, seen) : ts.isShorthandPropertyAssignment(property) ? styles(property.name, seen) : [];
-      });
-    }
-    return [];
-  }
+  const trace = createAtomicTrace(program, options, { entries, isAtomic, isCx });
   return source => {
-    const warnings = [], seen = new Set();
-    function compare(first, second, location) {
+    const warnings = new Map(), limits = new Map();
+    const relative = entry => ({ ...entry, file: path.relative(options.root, entry.file).replaceAll("\\", "/") });
+    function compare(first, second, location, context = {}) {
       for (const a of first) for (const b of second) {
-        if (a === b || a.selectors !== b.selectors || a.conditions !== b.conditions || a.important !== b.important || a.value === "0" && b.value === "0" || !overlaps(a.property, b.property)) continue;
+        if (a === b || a.selectors !== b.selectors || a.conditions !== b.conditions || a.important !== b.important || !overlaps(a.property, b.property) || equivalent(a, b)) continue;
         const key = JSON.stringify([a, b].map(entry => [entry.file, entry.line, entry.column]).sort());
-        if (seen.has(key)) continue;
-        seen.add(key);
+        const composition = [...new Map([...(context.path ?? []), ...(a.via ?? []), ...(b.via ?? [])].map(entry => [JSON.stringify(entry), relative(entry)])).values()].slice(0, 16);
+        const previous = warnings.get(key);
+        if (previous && (previous.target || !context.target) && previous.composition.length >= composition.length) continue;
         const position = source.getLineAndCharacterOfPosition(location.getStart(source));
-        warnings.push({ rule: "atomic-composition-review", severity: "warning", line: position.line + 1, column: position.character + 1,
-          message: `Atomic declarations ${a.property}: ${previewValue(a.value)} and ${b.property}: ${previewValue(b.value)} may overlap without matching cx merge keys. Their winner can depend on extraction order, specificity or writing mode. Use consistent property names/granularity across the base and variants, compose with Linaria cx, and verify computed styles in the built preview. Review all affected variants; valid tokens do not establish cascade correctness. See ${atomicStyleGuide}.`,
-          guidanceUri: atomicStyleGuide, related: [a, b].map(({ selectors: _selectors, conditions: _conditions, important: _important, ...entry }) => ({...entry,value:previewValue(entry.value)})) });
+        const dependent = writingModeDependent(a.property, b.property) || valueModeDependent(a, b);
+        warnings.set(key, { rule: "atomic-composition-review", severity: "warning", line: position.line + 1, column: position.character + 1,
+          message: `Atomic declarations ${a.property}: ${previewValue(a.value)} and ${b.property}: ${previewValue(b.value)} may overlap without matching cx merge keys.${context.target ? ` Source tracing reaches the same <${context.target.name}> className.` : " This is a source composition risk, not a confirmed rendered conflict."}${dependent ? " The overlap depends on writing mode or direction." : ""} Their winner can depend on extraction order, specificity or writing mode. Use consistent property names/granularity across the base and variants, compose with Linaria cx, and verify computed styles in the built preview. Review all affected variants; valid tokens do not establish cascade correctness. See ${atomicStyleGuide}.`,
+          guidanceUri: atomicStyleGuide, writingModeDependent: dependent, composition, ...(context.target ? { target: relative(context.target) } : {}), ...(context.limits?.length ? { analysisLimits: [...new Set(context.limits)].slice(0, 5) } : {}),
+          related: [a, b].map(({ selectors: _selectors, conditions: _conditions, important: _important, via: _via, ...entry }) => ({...entry,value:previewValue(entry.value)})) });
       }
     }
+    function limit(node, reasons, composition) {
+      const key = reasons.join("\n");
+      if (limits.has(key) || limits.size >= 5) return;
+      const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+      limits.set(key, { rule: "atomic-composition-limit", severity: "info", line: position.line + 1, column: position.character + 1,
+        message: `Atomic source review is incomplete: ${[...new Set(reasons)].slice(0, 3).join(" ")} Review the actual DOM classes and computed styles in a built scenario. An unresolved path is not evidence that composition is safe. See ${atomicStyleGuide}.`, guidanceUri: atomicStyleGuide, composition: composition.slice(0, 16).map(relative) });
+    }
     function visit(node) {
       if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) {
         const declarations = entries(node);
         for (let index = 0; index < declarations.length; index++) compare([declarations[index]], declarations.slice(index + 1), node);
       }
-      if (ts.isCallExpression(node) && isCx(node.expression)) {
-        const groups = node.arguments.flatMap(argument => {
-          const value = ts.isSpreadElement(argument) ? object(argument.expression) : null;
-          return value && ts.isArrayLiteralExpression(value) ? value.elements.map(element => styles(element)) : [styles(argument)];
-        });
-        for (let index = 0; index < groups.length; index++) for (let next = index + 1; next < groups.length; next++) compare(groups[index], groups[next], node);
-      }
       ts.forEachChild(node, visit);
     }
-    if (isInside(options.dsRoot, source.fileName)) visit(source);
-    return warnings;
+    if (isInside(options.dsRoot, source.fileName)) { visit(source); trace(source, { compare, limit }); }
+    return [...warnings.values(), ...limits.values()];
   };
 }

package/dist/atomic-trace.mjs

@@ -0,0 +1,287 @@
+import ts from "typescript";
+import { isInside } from "./config.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+const unknown = reason => ({ kind: "unknown", reason });
+const literal = value => ({ kind: "literal", value });
+const reference = (node, env = new Map(), via = []) => node ? { kind: "node", node, env, via } : literal(undefined);
+const union = values => values.length === 1 ? values[0] : { kind: "union", values };
+const isFunction = node => node && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node));
+const nameOf = node => node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) ? node.text : undefined;
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+  return node;
+}
+
+/** Bounded symbolic source traversal. No project code is imported or executed. */
+export function createAtomicTrace(program, options, { entries, isAtomic, isCx }) {
+  const checker = program.getTypeChecker();
+  const symbol = node => checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+  function declaration(node) {
+    let value = symbol(node);
+    if (value?.flags & ts.SymbolFlags.Alias) value = checker.getAliasedSymbol(value);
+    return value?.valueDeclaration;
+  }
+  const state = () => ({ budget: { steps: 0 }, depth: 0, calls: new Set() });
+  function next(context) { return { ...context, depth: context.depth + 1 }; }
+  function exhausted(context) { return ++context.budget.steps > 4000 || context.depth > 48; }
+  function at(node, kind, name) {
+    const source = node.getSourceFile(), position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return { file: source.fileName, line: position.line + 1, column: position.character + 1, kind, name: name.slice(0, 100) };
+  }
+  function withVia(value, via) {
+    if (value.kind === "union") return { ...value, values: value.values.map(item => withVia(item, via)) };
+    return value.kind === "node" ? { ...value, via: [...new Map([...via, ...value.via].map(item => [JSON.stringify(item), item])).values()].slice(0, 16) } : value;
+  }
+  function withDefault(value, fallback, context) {
+    if (!fallback) return value;
+    value = resolve(value, next(context));
+    if (value.kind === "literal") return value.value === undefined ? fallback : value;
+    if (value.kind === "unknown") return union([value, fallback]);
+    if (value.kind === "union") return union(value.values.map(item => withDefault(item, fallback, next(context))));
+    return value;
+  }
+  function bind(pattern, value, env, via, context) {
+    if (ts.isIdentifier(pattern)) { env.set(symbol(pattern), value); return; }
+    if (ts.isObjectBindingPattern(pattern)) {
+      const excluded = new Set();
+      for (const part of pattern.elements) {
+        const key = nameOf(part.propertyName ?? part.name);
+        if (part.dotDotDotToken) bind(part.name, { kind: "rest", value, excluded: new Set(excluded) }, env, via, next(context));
+        else {
+          if (key === undefined) continue;
+          excluded.add(key);
+          bind(part.name, withDefault(get(value, key, next(context)), part.initializer && reference(part.initializer, env, via), context), env, via, next(context));
+        }
+      }
+    } else if (ts.isArrayBindingPattern(pattern)) {
+      pattern.elements.forEach((part, index) => {
+        if (ts.isBindingElement(part) && !part.dotDotDotToken) bind(part.name, withDefault(get(value, String(index), next(context)), part.initializer && reference(part.initializer, env, via), context), env, via, next(context));
+      });
+    }
+  }
+  function boundElement(node, env, via, context) {
+    let owner = node;
+    while (ts.isBindingElement(owner) || ts.isObjectBindingPattern(owner) || ts.isArrayBindingPattern(owner)) owner = owner.parent;
+    if (!ts.isVariableDeclaration(owner) || !owner.initializer || !(owner.parent.flags & ts.NodeFlags.Const)) return unknown();
+    const local = new Map(env);
+    bind(owner.name, reference(owner.initializer, env, via), local, via, next(context));
+    return local.get(symbol(node.name)) ?? unknown();
+  }
+  function get(value, key, context) {
+    value = resolve(value, next(context));
+    if (value.kind === "union") return union(value.values.map(item => get(item, key, next(context))));
+    if (value.kind === "rest") return value.excluded.has(key) ? literal(undefined) : get(value.value, key, next(context));
+    const layers = value.kind === "object" ? value.layers : [];
+    if (value.kind === "node" && ts.isObjectLiteralExpression(value.node)) {
+      for (const property of value.node.properties) {
+        if (ts.isSpreadAssignment(property)) layers.push(reference(property.expression, value.env, value.via));
+        else {
+          const name = nameOf(property.name);
+          if (name !== undefined) layers.push(new Map([[name, reference(ts.isShorthandPropertyAssignment(property) ? property.name : ts.isMethodDeclaration(property) ? property : property.initializer, value.env, value.via)]]));
+        }
+      }
+    } else if (value.kind === "node" && ts.isArrayLiteralExpression(value.node)) {
+      return reference(value.node.elements[Number(key)], value.env, value.via);
+    } else if (value.kind !== "object") return unknown(value.reason);
+    for (let index = layers.length - 1; index >= 0; index--) {
+      const layer = layers[index];
+      if (layer instanceof Map) { if (layer.has(key)) return layer.get(key); }
+      else {
+        const selected = get(layer, key, next(context));
+        if (selected.kind === "literal" && selected.value === undefined) continue;
+        // An opaque later spread may replace an earlier explicit property.
+        if (selected.kind === "unknown" || selected.kind === "union") return union([selected, get({ kind: "object", layers: layers.slice(0, index) }, key, next(context))]);
+        return selected;
+      }
+    }
+    return literal(undefined);
+  }
+  function keys(value, context) {
+    value = resolve(value, next(context));
+    if (value.kind === "union") return [...new Set(value.values.flatMap(item => keys(item, next(context))))];
+    if (value.kind === "node" && ts.isObjectLiteralExpression(value.node)) return value.node.properties.flatMap(property => ts.isSpreadAssignment(property) ? keys(reference(property.expression, value.env, value.via), next(context)) : nameOf(property.name) ?? []);
+    if (value.kind === "object") return [...new Set(value.layers.flatMap(layer => layer instanceof Map ? [...layer.keys()] : keys(layer, next(context))))];
+    return [];
+  }
+  function returns(fn, args, context, kind = "helper") {
+    if (context.calls.has(fn.node)) return [unknown("Recursive local call could not be fully traced.")];
+    if (!fn.node.body || fn.node.asteriskToken || fn.node.modifiers?.some(item => item.kind === ts.SyntaxKind.AsyncKeyword)) return [unknown("Async, generator or declaration-only calls are outside atomic source tracing.")];
+    const env = new Map(fn.env), via = [...fn.via, at(fn.node, kind, fn.node.name?.getText() ?? "local function")];
+    const inner = { ...next(context), calls: new Set([...context.calls, fn.node]) };
+    for (const [index, parameter] of fn.node.parameters.entries()) {
+      if (parameter.dotDotDotToken) { bind(parameter.name, { kind: "array", values: args.slice(index) }, env, via, inner); break; }
+      bind(parameter.name, withDefault(resolve(args[index] ?? literal(undefined), inner), parameter.initializer && reference(parameter.initializer, env, via), inner), env, via, inner);
+    }
+    const outputs = [];
+    function statement(node) {
+      if (ts.isReturnStatement(node)) { outputs.push(reference(node.expression, env, via)); return true; }
+      if (ts.isBlock(node)) { for (const child of node.statements) if (statement(child)) return true; }
+      else if (ts.isIfStatement(node)) {
+        const condition = resolve(reference(node.expression, env, via), inner);
+        if (condition.kind === "literal") return condition.value ? statement(node.thenStatement) : node.elseStatement ? statement(node.elseStatement) : false;
+        const left = statement(node.thenStatement), right = node.elseStatement ? statement(node.elseStatement) : false;
+        return left && right;
+      } else if (ts.isThrowStatement(node)) return true;
+      else if (ts.isIterationStatement(node, false) || ts.isSwitchStatement(node) || ts.isTryStatement(node)) outputs.push(unknown("Loop, switch or try control flow could not be fully traced."));
+      return false;
+    }
+    if (ts.isBlock(fn.node.body)) statement(fn.node.body);
+    else outputs.push(reference(fn.node.body, env, via));
+    // Keep call stacks with lazy return references, including nested helpers.
+    return outputs.length ? outputs.map(value => ({ ...value, context: inner })) : [literal(undefined)];
+  }
+  function resolve(value, context) {
+    if (!value) return literal(undefined);
+    context = value.context ?? context;
+    if (exhausted(context)) return unknown("Atomic source tracing reached its depth or work limit.");
+    if (value.kind !== "node") return value;
+    const node = unwrap(value.node), { env, via } = value;
+    if (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) return literal(ts.isNumericLiteral(node) ? Number(node.text) : node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) return literal(node.kind === ts.SyntaxKind.TrueKeyword);
+    if (node.kind === ts.SyntaxKind.NullKeyword) return literal(null);
+    if (ts.isIdentifier(node)) {
+      if (env.has(symbol(node))) return resolve(env.get(symbol(node)), next(context));
+      const owner = declaration(node);
+      if (owner && isInside(options.dsRoot, owner.getSourceFile().fileName)) {
+        if (isFunction(owner)) return reference(owner, env, via);
+        if (ts.isVariableDeclaration(owner) && owner.initializer && owner.parent.flags & ts.NodeFlags.Const) return resolve(reference(owner.initializer, env, via), next(context));
+        if (ts.isBindingElement(owner)) return resolve(boundElement(owner, env, via, context), next(context));
+      }
+      return node.text === "undefined" && !owner ? literal(undefined) : unknown();
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      const key = ts.isPropertyAccessExpression(node) ? literal(node.name.text) : resolve(reference(node.argumentExpression, env, via), next(context));
+      const object = reference(node.expression, env, via);
+      if (key.kind === "literal") {
+        const selected = get(object, String(key.value), next(context));
+        const owner = declaration(node);
+        if (selected.kind === "unknown" && owner && isInside(options.dsRoot, owner.getSourceFile().fileName)) {
+          if (isFunction(owner)) return reference(owner, env, via);
+          if (ts.isVariableDeclaration(owner) && owner.initializer && owner.parent.flags & ts.NodeFlags.Const) return resolve(reference(owner.initializer, env, via), next(context));
+        }
+        return resolve(selected, next(context));
+      }
+      const names = keys(object, next(context));
+      return names.length ? union(names.map(name => get(object, name, next(context)))) : unknown();
+    }
+    if (ts.isConditionalExpression(node)) {
+      const condition = resolve(reference(node.condition, env, via), next(context));
+      return condition.kind === "literal" ? resolve(reference(condition.value ? node.whenTrue : node.whenFalse, env, via), next(context)) : union([reference(node.whenTrue, env, via), reference(node.whenFalse, env, via)]);
+    }
+    if (ts.isBinaryExpression(node)) {
+      const left = resolve(reference(node.left, env, via), next(context)), right = reference(node.right, env, via), operator = node.operatorToken.kind;
+      if (operator === ts.SyntaxKind.AmpersandAmpersandToken) return left.kind === "literal" ? left.value ? right : literal(undefined) : union([literal(undefined), right]);
+      if (operator === ts.SyntaxKind.BarBarToken) return left.kind === "literal" ? left.value ? left : right : union([left, right]);
+      if (operator === ts.SyntaxKind.QuestionQuestionToken) return left.kind === "literal" ? left.value == null ? right : left : union([left, right]);
+      const other = resolve(right, next(context));
+      if (left.kind === "literal" && other.kind === "literal" && [ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(operator)) return literal(operator === ts.SyntaxKind.EqualsEqualsEqualsToken ? left.value === other.value : left.value !== other.value);
+    }
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
+      const operand = resolve(reference(node.operand, env, via), next(context));
+      return operand.kind === "literal" ? literal(!operand.value) : unknown();
+    }
+    if (ts.isCallExpression(node) && !isCx(node.expression)) {
+      if (["memo", "forwardRef"].includes(uiOperation(node.expression, checker))) return resolve(reference(node.arguments[0], env, via), next(context));
+      const fn = resolve(reference(node.expression, env, via), next(context));
+      if (fn.kind === "node" && isFunction(fn.node)) {
+        const outputs = returns(fn, node.arguments.map(argument => reference(argument, env, via)), next(context));
+        return withVia(resolve(union(outputs), next(context)), outputs.flatMap(item => item.via ?? []));
+      }
+      return unknown(`Call ${node.expression.getText().slice(0, 80)} could not be traced to a local function.`);
+    }
+    return { ...value, node };
+  }
+  function arrays(value, context) {
+    value = resolve(value, next(context));
+    if (value.kind === "array") return value.values;
+    if (value.kind === "node" && ts.isArrayLiteralExpression(value.node)) return value.node.elements.map(node => reference(node, value.env, value.via));
+    return null;
+  }
+
+  return function review(source, { compare, limit }) {
+    const maxBranches = 32;
+    const unique = branches => [...new Map(branches.map(branch => [JSON.stringify(branch.map(entry => [entry.file, entry.line, entry.column])), branch])).values()];
+    function styles(input, context) {
+      const value = resolve(input, next(context));
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "unknown") return { branches: [[]], limits: value.reason ? [value.reason] : [] };
+      if (value.kind === "union") {
+        const results = value.values.slice(0, maxBranches).map(item => styles(item, next(context)));
+        const branches = unique(results.flatMap(item => item.branches));
+        return { branches: branches.slice(0, maxBranches), limits: [...results.flatMap(item => item.limits), ...(value.values.length > maxBranches || branches.length > maxBranches ? ["Atomic source tracing reached its alternative limit."] : [])] };
+      }
+      if (value.kind !== "node") return { branches: [[]], limits: [] };
+      const { node, env, via } = value;
+      if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) return { branches: [entries(node).map(entry => ({ ...entry, via }))], limits: [] };
+      if (ts.isCallExpression(node) && isCx(node.expression)) {
+        const inputs = node.arguments.flatMap(argument => ts.isSpreadElement(argument) ? arrays(reference(argument.expression, env, via), context) ?? [unknown("A dynamic class argument spread could not be traced.")] : [reference(argument, env, via)]);
+        let branches = [[]]; const limits = [];
+        for (const argument of inputs) {
+          const result = styles(argument, next(context));
+          limits.push(...result.limits);
+          const combined = new Map(); let truncated = false;
+          for (const first of branches) for (const second of result.branches) {
+            // cx replaces exact property/selector/condition keys; shorthand
+            // expansion remains the CSS overlap review's responsibility.
+            const merged = new Map([...first, ...second.map(entry => ({ ...entry, via: [...via, ...(entry.via ?? [])] }))].map(entry => [JSON.stringify([entry.property, entry.selectors, entry.conditions]), entry]));
+            const branch = [...merged.values()], key = JSON.stringify(branch.map(entry => [entry.file, entry.line, entry.column]));
+            if (!combined.has(key) && combined.size >= maxBranches) { truncated = true; continue; }
+            combined.set(key, branch);
+          }
+          if (truncated) limits.push("Atomic source tracing reached its alternative limit.");
+          branches = [...combined.values()];
+        }
+        return { branches, limits };
+      }
+      return { branches: [[]], limits: [] };
+    }
+    function inspect(value, node, context, target, path = []) {
+      const result = styles(value, context);
+      for (const branch of result.branches) for (let index = 0; index < branch.length; index++) compare([branch[index]], branch.slice(index + 1), node, { target, path, limits: result.limits });
+      if (result.limits.length && (result.branches.some(branch => branch.length) || ts.isCallExpression(node) && node.arguments.some(argument => styles(reference(argument), next(context)).branches.some(branch => branch.length)))) limit(node, result.limits, path);
+      return result;
+    }
+    function props(node, env, via) {
+      return { kind: "object", layers: node.attributes.properties.map(attribute => ts.isJsxSpreadAttribute(attribute) ? reference(attribute.expression, env, via) : new Map([[attribute.name.text, attribute.initializer ? ts.isJsxExpression(attribute.initializer) ? reference(attribute.initializer.expression, env, via) : reference(attribute.initializer, env, via) : literal(true)]])) };
+    }
+    function render(input, location, context, path = [], pendingStyles = false) {
+      const value = resolve(input, next(context));
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "union") { for (const item of value.values.slice(0, maxBranches)) render(item, location, next(context), path, pendingStyles); return; }
+      if (value.kind !== "node") { if (value.reason && pendingStyles) limit(location, [value.reason], path); return; }
+      const { node, env, via } = value;
+      if (ts.isJsxExpression(node)) { render(reference(node.expression, env, via), location, next(context), path, pendingStyles); return; }
+      if (ts.isJsxFragment(node)) { for (const child of node.children) render(reference(child, env, via), location, next(context), path); return; }
+      if (ts.isArrayLiteralExpression(node)) { for (const child of node.elements) render(reference(child, env, via), location, next(context), path); return; }
+      if (!ts.isJsxElement(node) && !ts.isJsxSelfClosingElement(node)) return;
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const attributes = props(opening, env, via), classValue = get(attributes, "className", next(context));
+      const tag = opening.tagName.getText();
+      if (/^[a-z]/.test(tag) && !tag.includes(".")) {
+        inspect(classValue, location, context, at(opening, "element", tag), [...path, ...via]);
+        if (ts.isJsxElement(node)) for (const child of node.children) render(reference(child, env, via), location, next(context), path);
+        return;
+      }
+      function componentTarget(component) {
+        if (component.kind === "union") { for (const alternative of component.values.slice(0, maxBranches)) componentTarget(resolve(alternative, next(context))); return; }
+        if (component.kind === "literal" && typeof component.value === "string") {
+          inspect(classValue, location, context, at(opening, "element", component.value), [...path, ...via]);
+        } else if (component.kind === "node" && isFunction(component.node)) {
+          const passed = pendingStyles || styles(classValue, context).branches.some(branch => branch.length);
+          for (const output of returns(component, [attributes], next(context), "component")) render(output, location, output.context ?? next(context), [...path, at(opening, "component", tag)], passed);
+        } else {
+          const passed = styles(classValue, context);
+          if (passed.branches.some(branch => branch.length)) limit(location, [`Component ${tag.slice(0, 80)} could not be traced to its DOM className target.`, ...passed.limits], path);
+        }
+      }
+      componentTarget(resolve(reference(opening.tagName, env, via), next(context)));
+    }
+    function visit(node) {
+      if (ts.isCallExpression(node)) inspect(reference(node), node, state());
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) render(reference(node), node, state());
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  };
+}

package/dist/check.mjs

@@ -262,5 +262,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     visit(source);
   }
+  // Bounded clients should see actionable warnings before source-analysis limits.
+  advisories.sort((first, second) => Number(first.severity === "info") - Number(second.severity === "info"));
   return { ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) };
 }

package/dist/mcp/server.mjs

@@ -205,7 +205,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/scenarios.mjs

@@ -147,10 +147,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();
@@ -190,6 +191,15 @@ 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

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

@@ -49,7 +49,8 @@ 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 atomic base/variant styling, helper/wrapper class composition, 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

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

@@ -81,6 +81,41 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## 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 +136,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 +161,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-designer/SKILL.md

@@ -80,7 +80,8 @@ 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 atomic base/variant styling, helper/wrapper class composition, 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

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

@@ -81,6 +81,41 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## 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 +136,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 +161,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-import/SKILL.md

@@ -44,7 +44,8 @@ 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 atomic base/variant styling, helper/wrapper class composition, 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

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

@@ -81,6 +81,41 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## 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 +136,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 +161,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-migrate/SKILL.md

@@ -46,7 +46,8 @@ 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 atomic base/variant styling, helper/wrapper class composition, 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

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

@@ -81,6 +81,41 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## 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 +136,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 +161,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-motion/SKILL.md

@@ -66,7 +66,8 @@ 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 atomic base/variant styling, helper/wrapper class composition, 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

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

@@ -81,6 +81,41 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## 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 +136,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 +161,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/docs/ADS.md

@@ -373,6 +373,9 @@ guarded mutations: valid CSS can intentionally overlap. Read
 [atomic style composition](../skills/ads-designer/references/atomic-styles.md) for causes, matching-property fixes
 and the source review's limits. Registered rendered checks can enforce a
 project's intended computed geometry; token validity alone cannot establish it.
+Bounded tracing follows local helpers and explicit `className` forwarding;
+diagnostics distinguish a reached DOM target from informational analysis limits.
+Neither a trace nor an absent warning establishes the intended rendered result.
 
 Document a new ownership exception with its guard/configuration change and
 tests. Passing static checks establishes only the policies and source formats

package/docs/ARCHITECTURE.md

@@ -127,6 +127,9 @@ every shorthand/logical-property overlap. ADS reports detectable composition
 risks as nonblocking warnings with guidance, while registered rendered checks
 can enforce actual geometry. See the skill-local
 [atomic style composition guide](../skills/ads-designer/references/atomic-styles.md).
+Bounded source tracing follows local class helpers and explicit component
+`className` forwarding to DOM targets. Separate elements remain separate;
+unsupported paths are informational limits, not evidence of safe composition.
 
 Airbnb's 2022 [migration report](https://medium.com/airbnb-engineering/airbnbs-trip-to-linaria-dc169230bd12)
 provides practical evidence for this choice: performance was its leading

package/docs/BEHAVIORS.md

@@ -103,6 +103,10 @@ values lazily and shares that type discovery within the check. Untyped `any`
 values and objects containing methods do not establish a callable API.
 An invalid `exercises` entry names the offending value and fails validation while
 retaining independent render evidence for `covers`.
+Calls to a callable's attached methods also exercise that public receiver,
+including statically named member calls inside reachable event-handler closures.
+Aliases, namespace access and re-exports retain the receiver identity. Reading a
+method or defining an unused callback does not establish an invocation.
 
 Public APIs appear in `ads_catalog` with `apiKind: "ui"` or `"behavior"` and their
 scenario links. `ads_behaviors` joins contracts to demonstrations and evidence.

package/docs/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.3.8
+
+- Trace local atomic class helpers and explicit component class forwarding,
+  preserving alternatives and spread order. Report composition paths, DOM
+  targets, writing-mode risks and bounded informational analysis limits;
+  suppress safely established literal-equivalent overlaps. Keep review warnings
+  nonblocking and use registered rendered checks for intended geometry.
+- Count calls to attached methods of public callable behavioral APIs through
+  aliases, namespace imports and re-exports, including mounted event handlers.
+
 ## 0.3.7
 
 - Warn about statically traceable atomic CSS property overlaps without blocking

package/docs/MCP.md

@@ -197,6 +197,12 @@ component-level fixes. The full guide lives in every ADS skill as
 Guarded mutation results preserve these warnings without rejecting valid source.
 An overlap warning is a review signal; failed registered rendered checks remain
 blocking.
+Warnings can carry a `composition` source path, a statically reached DOM `target`
+and `writingModeDependent`. Unresolved paths appear as bounded
+`atomic-composition-limit` advisories with `severity: "info"`; neither an
+informational limit nor a traced target proves a rendered failure or success.
+Bounded check results put warnings before informational limits; the checks
+resource retains complete results.
 
 ### Behavioral verification
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {