@reqvire-org/ads 0.3.13 → 0.3.15

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

@@ -1,6 +1,6 @@
 # Scenario rendering, token previews and public class helpers
 
-Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+Use this reference for `scenario-render`, `scenario-coverage`, `showcase-control` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
 All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
@@ -23,6 +23,17 @@ on-demand element screenshots. It grants no render/behavior coverage and no extr
 styling permission. Use [captures.md](captures.md) for current/candidate review,
 target selection, resource reads and storage lifecycle.
 
+## Fragment links inside Apps
+
+Keep intended `href="#"` and named fragments in the project API and fixtures.
+ADS's inline-document loader supplies an `about:srcdoc` base when the App has no
+explicit base, preserving native scrolling, events and state. If a fragment
+replaces the App with a sandbox URL or browser error, inspect `location.href`,
+`document.baseURI` and the resolved anchor URL. Report a host loading defect;
+do not add scenario `preventDefault` handlers merely to hide it. Explicit App
+bases retain their declared behavior and CSP requirements; external hosts own
+their document-loading policy. Verify link activation as well as rendering.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
@@ -90,6 +101,40 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through a public runtime slot
+
+A native element can be the direct child of a public runtime component that
+actually clones that child with its own props:
+
+```tsx
+<Action asChild>
+  <a href={fixture.destination}>Documentation</a>
+</Action>
+```
+
+`Action` and the fixture are illustrative; use the project's intended public API.
+The runtime owner supplies presentation and interaction; the anchor supplies link
+semantics. Keep this composition when it is the product contract. Do not replace
+the anchor with an unrelated styled link, add a demo-only prop, disable the guard
+or write outside MCP merely to silence a diagnostic.
+
+ADS follows the selected runtime render path, the exact child and real imported
+React/Preact `cloneElement` operations, including local slot/prop-merging helpers.
+The prop need not be named `asChild`; the spelling alone grants no permission.
+JSX and recognized framework factories follow the same rule. The native element
+must be the single direct child: another native control nested inside it remains
+subject to the ordinary ownership rule. Passing children through a container,
+a scenario-local wrapper or an opaque component does not establish a slot.
+
+This grants no scenario styling permission. Inline styles and arbitrary class
+names remain rejected, including on the slotted child. Public style helpers retain
+their own provenance checks. Unknown branches that could render the native child
+directly, multiple children and untraceable replacement props remain blocked.
+If a valid slot contract cannot be traced, keep the intended API and report a
+small reproduction rather than inventing a product workaround. Static proof
+establishes ownership, not correct prop merging, focus, keyboard or navigation
+behavior; verify those in the built App and registered checks.
+
 ## Scenarios may consume verified public style helpers
 
 A deliberately public helper can expose its owner's Linaria treatment:

package/dist/source-values.mjs

@@ -131,6 +131,7 @@ export function createSourceValues(program, options, { preserveCall = () => fals
   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 === "rest") return keys(value.value, next(context)).filter(key => !value.excluded.has(key));
     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 [];
@@ -243,5 +244,5 @@ export function createSourceValues(program, options, { preserveCall = () => fals
   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 };
+  return { state, next, at, resolve, get, keys, arrays, returns, props, declaration };
 }

package/dist/verification.mjs

@@ -289,15 +289,20 @@ export function createVerificationController(root, { reportRoot = root, onProgre
             diagnostics.push({ rule: "behavior-runner", message: `${runnerError.message} ${detail}`, reason: runnerError.reason, elapsedMs: runnerError.elapsedMs ?? Date.now() - startedAt, progress, output: runnerError.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 || reportValue?.complete === false) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : reportValue?.complete === false ? "left an incomplete report" : "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;
+          const incompleteReport = reportValue?.complete === false || progress.pending > 0 || progress.active.length > 0;
+          // Exit 1 is the normal test-failure exit. A complete report with actual
+          // assertion failures still contains independent, valid passing outcomes.
+          // Unexplained exits, suite errors and interrupted reports grant no pass.
+          const caseFailureExit = run?.code === 1 && !runnerError && !suiteErrors.length && !incompleteReport && reportValue?.cases.some(item => item?.status === "failed");
+          const runnerFailure = run && (run.code !== 0 || suiteErrors.length || incompleteReport) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : incompleteReport ? "left an incomplete report" : "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) ?? [];
             const reportedStatus = matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
-            const interrupted = !!runnerError && !!reportValue;
-            let status = interrupted ? matches.some(item => item.status === "failed") ? "failed" : "incomplete" : !run || runnerError || runnerFailure ? "failed" : reportedStatus;
+            const blockedRun = !!runnerError || !!runnerFailure && !caseFailureExit;
+            let status = matches.some(item => item.status === "failed") ? "failed" : !matches.length || blockedRun ? reportValue ? "incomplete" : "failed" : reportedStatus;
             if (runnerError?.code === "ENOENT") status = "unavailable";
             const current = behaviorInputs(afterOptions, check.contract, check, afterContext).revision === check.inputRevision;
             if (!current) status = "stale";

package/docs/ADS.md

@@ -164,7 +164,10 @@ 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.
+code defines no CSS, custom classes or standalone native controls; use public ADS
+APIs. A single direct native child can supply semantics to a public runtime slot
+when source tracing proves that owner clones the exact child with its own props.
+An `asChild` flag alone is not evidence; scenario styling remains forbidden.
 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.
@@ -383,7 +386,7 @@ The checks enforce the architecture's ownership boundaries:
 | Public API and dependencies | Consumers use public ADS imports; ADS implementations and showcase do not import application source; runtime code does not import showcase fixtures |
 | Interaction policy | Primitive state variables stay inside components; non-state customization hooks require explicit registration |
 | Renderer exceptions | Inline styles and imperative writes require used, narrow configured boundaries; stale entries fail; public props omit inherited style and reject open-ended visual strings |
-| Preview ownership | Scenarios define no CSS, custom classes, or native controls; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
+| Preview ownership | Scenarios define no CSS, custom classes, or standalone native controls; native slot children require public runtime cloning evidence; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
 | Assets | Source/public collisions and configured generated artifacts in source are rejected |
 
 Pointer capture without locally visible capture-loss cleanup produces a

package/docs/ARCHITECTURE.md

@@ -213,6 +213,13 @@ Project JavaScript, styles, fonts and UI run only inside that App; the outer
 shell forwards resource bytes without applying project styles or executing its
 runtime. This keeps the host neutral while compositions retain their full skin.
 
+The ADS host gives inline App documents an `about:srcdoc` base when the App
+provides no explicit base URL. Fragment links then stay inside their own document
+with native scrolling, history and events. The sandbox permits this local base;
+external bases still require declared CSP origins. This belongs to document
+loading and changes no project link or scenario handler. External hosts control
+their own document-loading and CSP behavior.
+
 The project compiler publishes a versioned dependency graph: shared runtime and
 foundation assets, plus independently addressable scenario modules. Inside the
 App, a resource loader obtains the selected dependency closure through MCP,
@@ -303,6 +310,10 @@ 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.
+A native element may provide semantics as the single direct child of a public
+runtime slot when source tracing proves it is cloned with that owner's props.
+This preserves polymorphic composition without allowing standalone scenario
+controls, scenario styling or name-based exceptions.
 The skill-local [scenario guide](../skills/ads-designer/references/scenarios.md)
 explains evidence, limits and diagnostics.
 

package/docs/BEHAVIORS.md

@@ -159,9 +159,14 @@ Prefer readiness/assertion polling over arbitrary sleeps. Timer-only guarantees
 may use [Playwright's clock](https://playwright.dev/docs/clock); retain real time
 when browser motion, pointer gestures or layout timing are what the check verifies.
 
-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
+An ordinary test-failure exit (code 1) with a complete report and actual failing
+cases preserves independent case outcomes: passing checks stay `passed`, failed
+checks stay `failed`, and overall verification still blocks the mutation. The
+report must account for every selected check, with no active cases or suite errors.
+The same rule supports older custom reports without an explicit `complete` field
+after normal process completion. An unexplained nonzero exit cannot certify a
+pass, even if all reported cases claim success. Results retain `reportedStatus`
+and `runnerExitCode` and explain the overall failure. 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

package/docs/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.15
+
+- Keep fragment links inside inline preview documents by supplying a local
+  `about:srcdoc` base in the sandbox host and legacy nested widget. Preserve
+  explicit App bases, native link events and opaque origins; retain CSP gates
+  for external bases. Verify scrolling, state and bridge continuity in browsers.
+
+## 0.3.14
+
+- Preserve independent passing behavior outcomes in complete runs with failed
+  assertions while keeping overall verification and mutations blocked. Retain
+  incomplete status for missing results, suite errors and unexplained exits.
+- Recognize native scenario children through source-verified public runtime slot
+  composition, including React/Preact cloning and local prop mergers. Keep
+  standalone controls, custom scenario styling and unproven slot paths rejected;
+  update diagnostics, architecture and portable skill guidance generically.
+
 ## 0.3.13
 
 - Add on-demand scenario/named-element PNG captures and screenshot-enabled guarded

package/docs/MCP.md

@@ -270,6 +270,11 @@ retain partial outcomes and reports under `.ds/verification/`, but incomplete
 runs still block application and cannot establish passing guarantees. See the
 [runner and evidence details](BEHAVIORS.md#register-execution-profiles).
 
+A complete ordinary failed run preserves the actual mixed case outcomes; a
+single failed assertion does not turn the other checks into failures. Overall
+verification and guarded application still fail. Suite errors, unexplained exits,
+missing results and interrupted reports cannot certify passing checks.
+
 Browser profiles start an isolated showcase and verify its sandboxed App using
 the selected candidate's sources. StrictMode profiles need a project React
 development harness. Profiles describe the execution environment, not a proof
@@ -588,6 +593,13 @@ origin hosts the sandbox proxy; that proxy creates an opaque inner App iframe
 and forwards the standard Apps bridge messages. The diagnostic explorer follows
 the same sandbox model. Only the App materializes and executes project resources.
 
+For inline documents without an explicit App base URL, ADS supplies
+`<base href="about:srcdoc">` and permits the local `about:` base scheme in CSP.
+Bare and named fragment links retain native in-document navigation and state.
+Explicit App bases remain subject to declared CSP origins. The legacy nested
+widget uses the same document preparation. External hosts own this behavior in
+their loaders; adding scenario click handlers would conceal a host defect.
+
 Hosts need Apps support, server resource forwarding, native ESM/import maps and
 a CSP permitting declared `blob:` script/style/font/worker resources. Project
 previews declare no network connections. The host may enforce stricter policy;

package/package.json

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

package/dist/showcase/sandbox.js

@@ -1,30 +0,0 @@
-const parentOrigin = new URL(location.href).searchParams.get("parent");
-let view;
-function domains(values = []) {
-  return values.filter(value => /^(?:https?:\/\/[a-z0-9.*:[\]-]+(?::\d+)?|data:|blob:|about:)$/i.test(value)).join(" ");
-}
-function policy(csp = {}) {
-  const resources = domains(csp.resourceDomains);
-  return `default-src 'none';script-src 'unsafe-inline' ${resources};style-src 'unsafe-inline' ${resources};img-src data: ${resources};font-src ${resources || "'none'"};media-src ${resources || "'none'"};worker-src ${resources || "'none'"};connect-src ${domains(csp.connectDomains) || "'none'"};frame-src ${domains(csp.frameDomains) || "'none'"};base-uri ${domains(csp.baseUriDomains) || "'none'"};object-src 'none'`;
-}
-window.addEventListener("message", event => {
-  if (event.source === parent && event.origin === parentOrigin) {
-    const message = event.data;
-    if (message?.method === "ui/notifications/sandbox-resource-ready") {
-      const { html, csp } = message.params ?? {};
-      if (typeof html !== "string") return;
-      const document = new DOMParser().parseFromString(html, "text/html");
-      const meta = document.createElement("meta");
-      meta.httpEquiv = "Content-Security-Policy";
-      meta.content = policy(csp);
-      document.head.prepend(meta);
-      view?.remove();
-      view = window.document.createElement("iframe");
-      view.title = "Design-system App";
-      view.setAttribute("sandbox", "allow-scripts");
-      window.document.body.append(view);
-      view.srcdoc = "<!doctype html>" + document.documentElement.outerHTML;
-    } else if (message?.jsonrpc === "2.0" && !message.method?.startsWith("ui/notifications/sandbox-")) view?.contentWindow.postMessage(message, "*");
-  } else if (event.source === view?.contentWindow && event.data?.jsonrpc === "2.0" && !event.data.method?.startsWith("ui/notifications/sandbox-")) parent.postMessage(event.data, parentOrigin);
-});
-parent.postMessage({ jsonrpc: "2.0", method: "ui/notifications/sandbox-proxy-ready", params: {} }, parentOrigin);