@reqvire-org/ads 0.3.7 → 0.3.9

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
@@ -373,6 +382,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
@@ -397,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

@@ -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
@@ -143,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
 
@@ -283,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

@@ -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.
@@ -136,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,33 @@
 # 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
+
+- 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
 

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
 
@@ -435,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
@@ -551,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.7",
+  "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",