@reqvire-org/ads 0.3.7 → 0.3.9

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

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

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

@@ -66,10 +66,18 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
-For atomic base/variant styling or an `atomic-composition-review` warning, read
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, or an
+`atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
-matching-property fixes. Review warnings in the real `cx` composition and verify
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. Review warnings in the real `cx` composition and verify
 computed styles across affected sizes/states; retain intentional product behavior.
 
 Controllers are UI behavior owners: private helpers stay with their component or

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

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

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

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

package/dist/source-values.mjs

@@ -0,0 +1,247 @@
+import ts from "typescript";
+import { isInside } from "./config.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+export const unknown = reason => ({ kind: "unknown", reason });
+export const literal = value => ({ kind: "literal", value });
+export const reference = (node, env = new Map(), via = []) => node ? { kind: "node", node, env, via } : literal(undefined);
+export const union = values => values.length === 1 ? values[0] : { kind: "union", values };
+export 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;
+export 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 createSourceValues(program, options, { preserveCall = () => false, strict = false } = {}) {
+  const checker = program.getTypeChecker();
+  const symbol = node => {
+    const value = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+    return value?.valueDeclaration && ts.isShorthandPropertyAssignment(value.valueDeclaration) ? checker.getShorthandAssignmentValueSymbol(value.valueDeclaration) ?? value : value;
+  };
+  function declaration(node) {
+    let value = symbol(node);
+    if (value?.flags & ts.SymbolFlags.Alias) value = checker.getAliasedSymbol(value);
+    return value?.valueDeclaration;
+  }
+  const writes = new Set(), escapes = new Set(), aliases = [];
+  if (strict) {
+    function root(node) {
+      node = unwrap(node);
+      while (node && (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node))) node = unwrap(node.expression);
+      return node && ts.isIdentifier(node) ? symbol(node) : null;
+    }
+    function scan(node) {
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment) writes.add(root(node.left));
+      if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)) writes.add(root(node.operand));
+      if (ts.isDeleteExpression(node)) writes.add(root(node.expression));
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) for (const argument of node.arguments ?? []) {
+        const value = unwrap(argument);
+        if (ts.isIdentifier(value)) escapes.add(symbol(value));
+      }
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && root(node.initializer)) aliases.push([symbol(node.name), root(node.initializer)]);
+      ts.forEachChild(node, scan);
+    }
+    for (const file of program.getSourceFiles()) if (isInside(options.dsRoot, file.fileName)) scan(file);
+    const targets = new Map();
+    for (const [alias, target] of aliases) { if (!targets.has(alias)) targets.set(alias, []); targets.get(alias).push(target); }
+    for (const affected of [writes, escapes]) {
+      const queue = [...affected];
+      for (let index = 0; index < queue.length; ++index) for (const target of targets.get(queue[index]) ?? []) if (!affected.has(target)) { affected.add(target); queue.push(target); }
+    }
+  }
+  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 (strict && value.kind === "context" && key === "Provider") return { kind: "provider" };
+    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, strict && (ts.isGetAccessorDeclaration(property) || ts.isSetAccessorDeclaration(property)) ? unknown("An accessor is not a statically known property.") : reference(ts.isShorthandPropertyAssignment(property) ? property.name : ts.isMethodDeclaration(property) ? property : property.initializer, value.env, value.via)]]));
+          else if (strict) layers.push(unknown("A computed object key may replace the selected property."));
+        }
+      }
+    } 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)) { if (strict) outputs.push(unknown("A throwing branch does not establish a returned value.")); 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)) { if (!statement(fn.node.body) && strict) outputs.push(literal(undefined)); }
+    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), ...(strict ? { origin: node, via } : {}) };
+    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 (strict && writes.has(symbol(node))) return unknown("A written binding or object is not a statically known value.");
+      if (strict && ["Fragment", "StrictMode"].includes(uiOperation(node, checker))) return { kind: "provider" };
+      if (env.has(symbol(node))) {
+        const result = resolve(env.get(symbol(node)), next(context));
+        return strict && escapes.has(symbol(node)) && (result.kind === "object" || result.kind === "array" || result.kind === "node" && (ts.isObjectLiteralExpression(result.node) || ts.isArrayLiteralExpression(result.node))) ? unknown("An object passed to another call may have been mutated.") : result;
+      }
+      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) {
+          const result = resolve(reference(owner.initializer, env, via), next(context));
+          return strict && escapes.has(symbol(node)) && (result.kind === "object" || result.kind === "array" || result.kind === "node" && (ts.isObjectLiteralExpression(result.node) || ts.isArrayLiteralExpression(result.node))) ? unknown("An object passed to another call may have been mutated.") : result;
+        }
+        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));
+      if (strict) return unknown("A dynamic property selection is not a statically known value.");
+      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) && !preserveCall(node.expression)) {
+      if (strict && uiOperation(node.expression, checker) === "createContext") return { kind: "context" };
+      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;
+  }
+
+  function props(node, env = new Map(), 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)]])) };
+  }
+  return { state, next, at, resolve, get, arrays, returns, props, declaration };
+}

package/dist/verification/browser.mjs

@@ -11,17 +11,26 @@ export async function openBehaviorScenario(page, checkId, { timeout = 30000 } =
   const check = request.checks.find(check => check.id === checkId);
   const url = check && request.scenarios[check.scenario];
   if (!url) throw new Error("This check has no managed browser scenario. StrictMode profiles must supply a project development harness; production preview bundles do not replay React development effects.");
-  await page.goto(url, { waitUntil: "load", timeout });
-  const end = Date.now() + timeout;
-  while (Date.now() < end) {
-    for (const frame of page.frames().filter(frame => frame !== page.mainFrame())) {
-      const state = await frame.evaluate(() => ({ state: document.documentElement.dataset.adsPreviewState, id: document.documentElement.dataset.adsScenario, message: document.getElementById("ads-preview-status")?.textContent })).catch(() => ({}));
-      if (state.id === check.scenario && state.state === "ready") return frame;
-      if (state.state === "error") throw new Error(state.message || "The MCP App failed before verification.");
+  const failures = [];
+  const failed = request => {
+    if (failures.length < 5) failures.push(`${request.method()} ${request.url().slice(0, 300)}: ${request.failure()?.errorText ?? "request failed"}`);
+  };
+  page.on("requestfailed", failed);
+  try {
+    await page.goto(url, { waitUntil: "load", timeout });
+    const end = Date.now() + timeout;
+    while (Date.now() < end) {
+      for (const frame of page.frames().filter(frame => frame !== page.mainFrame())) {
+        const state = await frame.evaluate(() => ({ state: document.documentElement.dataset.adsPreviewState, id: document.documentElement.dataset.adsScenario, message: document.getElementById("ads-preview-status")?.textContent })).catch(() => ({}));
+        if (state.id === check.scenario && state.state === "ready") return frame;
+        if (state.id === check.scenario && state.state === "error") throw new Error(state.message || "The MCP App failed before verification.");
+      }
+      const error = await page.evaluate(() => document.querySelector('#status[data-error="true"]')?.textContent).catch(() => null);
+      if (error) throw new Error(error);
+      await page.waitForTimeout(50);
     }
-    const error = await page.evaluate(() => document.querySelector('#status[data-error="true"]')?.textContent).catch(() => null);
-    if (error) throw new Error(error);
-    await page.waitForTimeout(50);
-  }
-  throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
+    throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
+  } catch (error) {
+    throw new Error(`Scenario ${check.scenario}: ${error.message}${failures.length ? `\nFailed browser requests:\n${failures.join("\n")}` : ""}`, { cause: error });
+  } finally { page.off("requestfailed", failed); }
 }