@reqvire-org/ads 0.3.8 → 0.3.9

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); }
 }

package/dist/verification/playwright-reporter.cjs

@@ -6,15 +6,19 @@ module.exports = class AdsBehaviorReporter {
   constructor() {
     this.request = JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
     this.cases = [];
+    this.errors = [];
   }
   onTestEnd(test, result) {
     const file = path.relative(this.request.projectRoot, test.location.file).replaceAll("\\", "/");
     for (const tag of test.tags ?? []) {
       if (!tag.startsWith("@ads:")) continue;
-      this.cases.push({ id: tag.slice(5), file, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", message: result.errors?.map(error => error.message).join("\n").slice(0, 4000) });
+      this.cases.push({ id: tag.slice(5), file, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 4000) });
     }
   }
+  onError(error) {
+    if (this.errors.length < 5) this.errors.push(String(error.message || error.stack || error.value || "The browser runner reported a suite error without details.").slice(0, 4000));
+  }
   onEnd() {
-    writeFileSync(process.env.ADS_VERIFY_REPORT, JSON.stringify({ schemaVersion: 1, runId: this.request.runId, cases: this.cases.slice(0, 500) }));
+    writeFileSync(process.env.ADS_VERIFY_REPORT, JSON.stringify({ schemaVersion: 1, runId: this.request.runId, cases: this.cases.slice(0, 500), errors: this.errors }));
   }
 };

package/dist/verification.mjs

@@ -182,19 +182,24 @@ export function createVerificationController(root) {
             if (!existsSync(report) || realpathSync(report) !== report || lstatSync(report).size > 1024 * 1024) throw new Error("Runner produced no valid bounded verification report. A successful exit alone is not passing evidence.");
             reportValue = JSON.parse(readFileSync(report, "utf8"));
             if (reportValue.schemaVersion !== 1 || reportValue.runId !== runId || !Array.isArray(reportValue.cases) || reportValue.cases.length > 500) throw new Error("Runner report has the wrong run ID/schema or too many cases.");
-          } catch (error) { runnerError = error; diagnostics.push({ rule: "behavior-runner", message: error.message, output: error.output?.slice(-4000), profile: profileName }); }
+          } catch (error) { runnerError = error; reportValue = undefined; diagnostics.push({ rule: "behavior-runner", message: error.message, output: error.output?.slice(-4000), profile: profileName }); }
+          const suiteErrors = Array.isArray(reportValue?.errors) ? reportValue.errors.slice(0, 5).map(error => String(error).slice(0, 1000)) : [];
+          const runnerFailure = run && (run.code !== 0 || suiteErrors.length) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : "reported a suite error"}. ${suiteErrors.join("; ") || reportValue?.cases.filter(item => item?.status === "failed").slice(0, 3).map(item => `${item.id}: ${item.message || "failed without a case diagnostic"}`).join("; ") || "Inspect the runner output and verification report."}`.slice(0, 3000) : undefined;
+          if (runnerFailure) diagnostics.push({ rule: "behavior-runner", message: runnerFailure, output: run.output?.slice(-4000), profile: profileName });
           const afterOptions = loadConfig(root), afterContext = inputContext(afterOptions);
           for (const check of group) {
             const file = slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file)));
             const matches = reportValue?.cases.filter(item => item && item.id === check.case && item.file === file) ?? [];
-            let status = !run || run.code !== 0 ? "failed" : matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
+            const reportedStatus = matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
+            let status = !run || runnerFailure ? "failed" : reportedStatus;
             if (runnerError?.code === "ENOENT") status = "unavailable";
             const current = behaviorInputs(afterOptions, check.contract, check, afterContext).revision === check.inputRevision;
             if (!current) status = "stale";
             if (signal.aborted) status = "cancelled";
             results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
               previewRevision: profile.mode === "browser" ? host?.previewRevision() ?? readPreviewManifest(options)?.revision ?? null : null,
-              message: runnerError?.message ?? (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : matches.filter(item => item.status !== "passed").map(item => String(item.message ?? item.status).slice(0, 2000)).join("\n")), report: slash(path.relative(root, report)) });
+              ...(runnerFailure ? { reportedStatus, runnerExitCode: run.code } : {}),
+              message: runnerError?.message ?? (matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n") || (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : runnerFailure ? `This case reported ${reportedStatus}, but the complete run did not pass. ${runnerFailure}` : "")), report: slash(path.relative(root, report)) });
           }
           if (signal.aborted) break;
         }

package/docs/ADS.md

@@ -141,7 +141,11 @@ TSX or JSON equivalents are supported. An empty fixture is valid without inputs.
 `scenario-contract`, `scenario-render` and `scenario-coverage` checks require valid
 entries and reachable public render references for every public renderable
 component/pattern, including unused exports and Linaria styled exports. Types, constants and utility functions
-are excluded. Coverage is a static source policy; it does not prove runtime
+are excluded. Explicit `covers` entries can receive transitive evidence through a
+rendered parent's returned JSX, fixture props/defaults and known framework
+wrappers/providers. Unknown branches contribute only their common public parts;
+unused JSX and callbacks contribute none. Bounded tracing does not automatically
+add dependency APIs to `covers`. Coverage is a static source policy; it does not prove runtime
 mounting, correct props, every branch/state or visual parity. The older
 `showcase-coverage` policy also checks application render references.
 
@@ -156,6 +160,11 @@ or applies the right CSS property. Browser review still verifies the samples.
 Scenarios and fixture helpers are development-only wherever colocated. Runtime
 source and the public barrel cannot import or re-export them. Showcase/scenario
 code defines no CSS, custom classes or native controls; use public ADS APIs.
+Scenarios may consume public class helpers whose returned styles trace to owned
+Linaria. Stable hooks in that owner may accompany real styles; strings forwarded
+from scenarios, hook-only returns and untraceable outputs remain invalid.
+`exercises` does not authorize classes. See the skill-local
+[scenario contract guide](../skills/ads-designer/references/scenarios.md).
 Neither ADS implementations nor scenarios import application code. Live business
 data belongs to application adapters; ADS receives inputs or injected callbacks.
 Direct global `fetch`, XHR, WebSocket and EventSource use is rejected. Renderer
@@ -400,10 +409,11 @@ Validate accepted and rejected cases, configuration, and false-positive limits.
 
 ## Bootstrap and updates
 
-The atomic composition guide lives in each skill's `references/atomic-styles.md`.
-The maintained copy is in `skills/ads-designer/references/atomic-styles.md`;
-MCP serves that packaged skill reference. `npm run sync:skill-references` copies
-it to the other skills for standalone use; `npm run check:skill-references`
+The atomic composition and scenario contract guides live in each skill's
+`references/atomic-styles.md` and `references/scenarios.md`. The maintained copies
+are in `skills/ads-designer/references/`; MCP serves those packaged references.
+`npm run sync:skill-references` copies them to the other skills for standalone use;
+`npm run check:skill-references`
 rejects drift during the tool build. Published packages include these references
 under `dist/skills/`.
 

package/docs/ARCHITECTURE.md

@@ -146,6 +146,14 @@ of every unused variant. Atomic composition still requires care with the cascade
 Apply extraction to application and project preview builds, preserve intentional
 foundation CSS, and inspect compiled output when performance matters. The
 [implementation guide](../design-system/README.md#bundling-notes) covers these details.
+Both extraction pipelines use the build-only `@reqvire-org/ads/linaria` tag
+resolver. It delegates atomization and nesting to the project's installed Linaria
+processor while preserving custom-property token streams around that pass.
+Arithmetic becomes meaningful after `var()` substitution, so stripping whitespace
+can invalidate otherwise valid source. Verify emitted CSS and computed browser
+values; source guards alone cannot establish extraction correctness. The
+skill-local [atomic styling guide](../skills/ads-designer/references/atomic-styles.md#preserve-custom-property-arithmetic-during-extraction)
+documents integration and source-workaround semantics.
 
 ## Public APIs preserve the boundary
 
@@ -286,6 +294,14 @@ their required parent. Every declared token and every public renderable componen
 and pattern needs addressable coverage. Token references must exist in the real
 foundation; claimed token/UI coverage must be reachable from the scenario entry.
 Types, constants and utilities do not require UI scenarios.
+Explicitly declared public children can share a parent's scenario when bounded
+source tracing reaches them through its returned JSX and selected props/defaults.
+Opaque conditional branches do not grant speculative coverage. Scenarios may
+consume deliberate public class helpers when their returned styles retain
+runtime-owned Linaria provenance; stable owner-authored hooks may accompany real
+styles. This preserves ownership rather than granting scenario styling freedom.
+The skill-local [scenario guide](../skills/ads-designer/references/scenarios.md)
+explains evidence, limits and diagnostics.
 
 After source changes, validation and compilation must both succeed before a new
 graph becomes current. MCP announces build/resource updates. The built-in client

package/docs/BEHAVIORS.md

@@ -140,7 +140,17 @@ and any required test setup in that project. The ADS tooling host gains no
 framework or browser dependency from a profile.
 
 The Playwright adapter appends selected file paths, its reporter and a generated
-artifact directory. Use native test tags for stable case identity:
+artifact directory.
+
+Runner failures remain blocking even when some selected cases reported passed.
+Those results retain `reportedStatus` and `runnerExitCode`, and explain the suite
+failure rather than returning an empty message. Suite-level browser errors and
+bounded runner output appear in diagnostics. `openBehaviorScenario` includes the
+scenario ID and failed browser requests in startup failures; App resource errors
+identify the resource URI. Failed assertions and startup errors are not retried
+automatically. Fix or investigate the failure before explicitly verifying again.
+
+Use native test tags for stable case identity:
 
 ```ts
 import { test, expect } from "@playwright/test";

package/docs/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## Unreleased
+## 0.3.9
+
+- Credit explicitly declared public child renders reached through parents,
+  fixture props/defaults and known framework wrappers/providers. Share bounded
+  source evaluation with atomic review; unresolved paths, unused JSX and
+  callbacks do not manufacture child coverage.
+- Allow scenario class helpers with proven runtime Linaria provenance and stable
+  owner-authored hooks alongside real styles. Reject consumer strings, private
+  styles, empty templates and untraceable returns; document the contract in all
+  five portable skills and `ads://guides/scenarios`.
+- Preserve custom-property token streams through Linaria atomic extraction with
+  the build-only `@reqvire-org/ads/linaria` resolver. Integrate the resolver in
+  product and MCP preview starter builds; verify extracted arithmetic and real
+  browser transforms using generic fixtures with and without CSS minification.
+- Explain suite-wide verification failures on otherwise passing cases, retain
+  their reported status, and surface runner-level errors. Include scenario IDs,
+  failed requests and App resource URIs in startup diagnostics without retrying
+  failed checks automatically.
 
 ## 0.3.8
 

package/docs/MCP.md

@@ -441,6 +441,12 @@ project's normal lint/build gates.
 
 `ads_scenarios` discovers path-derived IDs for token, component, pattern and
 composition scenarios. `ads_catalog` links public exports to their coverage.
+`covers` can include public children reached through the rendered parent's
+returned JSX with known props/defaults. Public class helpers require verified
+runtime Linaria provenance; `exercises` alone grants no class permission. The
+`ads://guides/scenarios` resource and each skill's
+[local scenario reference](../skills/ads-designer/references/scenarios.md) describe
+the bounded checks and diagnostics.
 `ads_show_scenario({id})` selects an independently mountable entry with its own
 fixtures. `ads_show_tokens({category})` selects a discovered token scenario;
 omitting category selects the first token entry. The tool contains no project
@@ -557,6 +563,12 @@ framework compilation and Linaria extraction. The starter's
 - Keep `preserveEntrySignatures: "strict"`, `cssCodeSplit: true`,
   `assetsInlineLimit: 0`, `modulePreload: false`, and `write: false`. Include the
   supplied dependency-tracking plugin and the project's Linaria/framework plugins.
+- Use `linariaTagResolver` from `@reqvire-org/ads/linaria` in WyW's `tagResolver`
+  option in both the product build and preview builder. It preserves opaque
+  custom-property values through atomic extraction, including whitespace needed
+  by arithmetic later substituted into `calc()`. Existing custom builders need
+  this integration explicitly; disabling minification does not fix extraction.
+  See the skill-local [atomic styling guide](../skills/ads-designer/references/atomic-styles.md#preserve-custom-property-arithmetic-during-extraction).
 - `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and returns
   an unmount callback. It imports the same project foundation used in production.
   It creates no App bridge; ADS supplies that bridge once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -87,6 +87,14 @@
     "vite": "^6.0.7"
   },
   "license": "MIT",
+  "peerDependencies": {
+    "@linaria/atomic": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@linaria/atomic": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22.12.0"
   },
@@ -96,6 +104,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./oxlint": "./dist/oxlint.mjs",
+    "./linaria": "./dist/linaria.mjs",
     "./tokens": "./dist/contracts/tokens.json",
     "./mcp": "./dist/mcp/server.mjs",
     "./mcp/build": "./dist/mcp/build-status.mjs",