@reqvire-org/ads 0.3.14 → 0.3.16

package/dist/showcase/resource-reader.js

@@ -0,0 +1,37 @@
+const retryDelays = [200, 800];
+const networkFailure = error => error?.name === "TypeError" && /^(Failed to fetch|fetch failed|Load failed|NetworkError when attempting to fetch resource\.)$/.test(error.message);
+
+function pause(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+    const finish = () => { signal?.removeEventListener("abort", abort); resolve(); };
+    const timer = setTimeout(finish, milliseconds);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+/** Only resources/read is repeatable here; never wrap tool calls or assertions. */
+export function resourceReader(read, { signal, onDiagnostic, wait = pause } = {}) {
+  return async input => {
+    for (let attempt = 1; ; attempt++) {
+      signal?.throwIfAborted();
+      try {
+        const response = await read(input);
+        signal?.throwIfAborted();
+        if (attempt > 1) onDiagnostic?.({ state: "recovered", uri: input.uri, attempt });
+        return response;
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (!networkFailure(error)) throw error;
+        if (attempt > retryDelays.length) {
+          onDiagnostic?.({ state: "exhausted", uri: input.uri, attempt, message: error.message });
+          throw Object.assign(new Error(`MCP resource transport failed for ${input.uri} after ${attempt} attempts: ${error.message}. Inspect the host connection and browser network diagnostics; this resource-loading error does not establish a component assertion failure.`, { cause: error }), { code: "ADS_RESOURCE_TRANSPORT" });
+        }
+        const delayMs = retryDelays[attempt - 1];
+        onDiagnostic?.({ state: "retry", uri: input.uri, attempt, nextAttempt: attempt + 1, delayMs, message: error.message });
+        await wait(delayMs, signal);
+      }
+    }
+  };
+}

package/dist/showcase/sandbox.bundle.js

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

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

@@ -55,8 +55,8 @@ For on-demand current/candidate screenshots and visual dry-run review, read
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use in scenarios, or `scenario-render` / `showcase-class`
-findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, fragment-link navigation, or `scenario-render` /
+`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
 examples explain API visibility, reference baselines and state-transition checks.
 Traced parents can cover declared public children; verified public Linaria
 helpers do not grant custom scenario CSS.

package/dist/skills/ads-break-ui/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

package/dist/skills/ads-break-ui/references/scenarios.md

@@ -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.

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

@@ -86,8 +86,8 @@ For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use in scenarios, or `scenario-render` / `showcase-class`
-findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, fragment-link navigation, or `scenario-render` /
+`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
 examples explain API visibility, reference baselines and state-transition checks.
 Traced parents can cover declared public children; verified public Linaria
 helpers do not grant custom scenario CSS.

package/dist/skills/ads-designer/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

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

@@ -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.

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

@@ -50,8 +50,8 @@ For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use in scenarios, or `scenario-render` / `showcase-class`
-findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, fragment-link navigation, or `scenario-render` /
+`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
 examples explain API visibility, reference baselines and state-transition checks.
 Traced parents can cover declared public children; verified public Linaria
 helpers do not grant custom scenario CSS.

package/dist/skills/ads-import/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

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

@@ -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.

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

@@ -52,8 +52,8 @@ For on-demand current/candidate screenshots and visual dry-run review, read
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use in scenarios, or `scenario-render` / `showcase-class`
-findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, fragment-link navigation, or `scenario-render` /
+`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
 examples explain API visibility, reference baselines and state-transition checks.
 Traced parents can cover declared public children; verified public Linaria
 helpers do not grant custom scenario CSS.

package/dist/skills/ads-migrate/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

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

@@ -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.

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

@@ -72,8 +72,8 @@ For on-demand current/candidate screenshots and visual dry-run review, read
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use in scenarios, or `scenario-render` / `showcase-class`
-findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, fragment-link navigation, or `scenario-render` /
+`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
 examples explain API visibility, reference baselines and state-transition checks.
 Traced parents can cover declared public children; verified public Linaria
 helpers do not grant custom scenario CSS.

package/dist/skills/ads-motion/references/guarded-editing.md

@@ -51,6 +51,18 @@ blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actua
 gesture/motion/layout guarantees. Project settings belong in guarded configuration
 changes; ADS does not silently raise budgets or override the worker count.
 
+If a check cannot load its MCP preview, preserve the draft and inspect the exact
+resource URI and failed browser requests before changing component code. The ADS
+showcase retries a fetch transport failure on `resources/read` at most twice
+(200/800 ms backoff); recovered startup reads remain visible in
+`startupDiagnostics`. It never retries tool calls, assertions or complete checks,
+and persistent failures still block application. HTTP/protocol/content errors,
+integrity failures and cancellation do not retry. External hosts own their
+transport behavior. Chrome's `ERR_NETWORK_CHANGED` does not prove an ADS restart
+or identify Docker/VPN churn: correlate failure timestamps with live interface
+events, Chrome network logs and server availability. Do not weaken checks or
+rewrite a valid API to hide infrastructure failures.
+
 Named barrel imports can narrow affected checks when the project accurately
 declares package `sideEffects`; retain CSS/global effects in that policy. Missing
 or unsupported policies and dynamic/wildcard dependencies stay conservative.

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

@@ -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.

package/dist/verification/browser.mjs

@@ -27,7 +27,11 @@ export async function openPreviewScenario(page, url, scenario, { timeout = 30000
     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 === scenario && state.state === "ready") return frame;
+        if (state.id === scenario && state.state === "ready") {
+          const retries = await page.evaluate(() => Number(document.documentElement.dataset.adsResourceRetries ?? 0)).catch(() => 0);
+          if (retries > 0) console.warn(JSON.stringify({ adsPreviewDiagnostic: { kind: "resource-read-recovery", scenario, retries, failedRequests: failures } }));
+          return frame;
+        }
         if (state.id === 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);

package/dist/verification/playwright-reporter.cjs

@@ -8,6 +8,8 @@ module.exports = class AdsBehaviorReporter {
     this.cases = [];
     this.errors = [];
     this.active = new Map();
+    this.diagnostics = new Map();
+    this.diagnosticBuffers = new Map();
     this.startedAt = Date.now();
     this.totalTests = 0;
   }
@@ -22,9 +24,27 @@ module.exports = class AdsBehaviorReporter {
   }
   onTestEnd(test, result) {
     this.active.delete(test.id);
-    for (const entry of this.entries(test)) this.cases.push({ ...entry, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", durationMs: result.duration, workerIndex: result.workerIndex, retry: result.retry, completedAt: new Date().toISOString(), message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 1000) });
+    const diagnostics = this.diagnostics.get(test.id);
+    for (const entry of this.entries(test)) this.cases.push({ ...entry, status: result.status === "passed" && test.expectedStatus === "passed" ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", durationMs: result.duration, workerIndex: result.workerIndex, retry: result.retry, completedAt: new Date().toISOString(), ...(diagnostics?.length ? { diagnostics } : {}), message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 1000) });
+    this.diagnostics.delete(test.id);
+    this.diagnosticBuffers.delete(test.id);
     this.publish();
   }
+  onStdErr(chunk, test) {
+    if (!test) return;
+    const lines = ((this.diagnosticBuffers.get(test.id) ?? "") + String(chunk)).split("\n");
+    this.diagnosticBuffers.set(test.id, lines.pop().slice(-4000));
+    for (const line of lines) {
+      if (line.length > 4000) continue;
+      try {
+        const diagnostic = JSON.parse(line).adsPreviewDiagnostic;
+        if (diagnostic?.kind !== "resource-read-recovery" || typeof diagnostic.scenario !== "string" || !Number.isSafeInteger(diagnostic.retries) || diagnostic.retries < 1) continue;
+        const collected = this.diagnostics.get(test.id) ?? [];
+        if (collected.length < 5) collected.push({ kind: diagnostic.kind, scenario: diagnostic.scenario.slice(0, 300), retries: diagnostic.retries, failedRequests: (Array.isArray(diagnostic.failedRequests) ? diagnostic.failedRequests : []).slice(0, 5).map(value => String(value).slice(0, 500)) });
+        this.diagnostics.set(test.id, collected);
+      } catch { /* Ordinary test output is not an ADS startup diagnostic. */ }
+    }
+  }
   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));
     this.publish();

package/dist/verification.mjs

@@ -310,6 +310,7 @@ export function createVerificationController(root, { reportRoot = root, onProgre
             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,
               ...(matches.length ? { reportedStatus, durationMs: matches.reduce((sum, item) => sum + (Number.isFinite(item.durationMs) ? Math.max(0, item.durationMs) : 0), 0) } : {}),
+              ...(matches.some(item => item.diagnostics?.length) ? { startupDiagnostics: matches.flatMap(item => Array.isArray(item.diagnostics) ? item.diagnostics.slice(0, 5) : []).slice(0, 10) } : {}),
               ...(runnerFailure ? { runnerExitCode: run.code } : {}),
               execution: progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state,
               message: [matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n"), runnerError ? `${runnerError.message} This check ${matches.length ? `reported ${reportedStatus}` : `was ${progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state ?? "not reported"}`}; the complete run did not pass.` : !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}` : ""].filter(Boolean).join("\n"), report: slash(path.relative(reportRoot, report)) });

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,
@@ -222,6 +229,15 @@ scenarios unmounts the previous view while keeping unchanged dependencies cached
 Persistence is a host lifecycle choice; a new external widget loads the same
 resources independently. Resource sharing is scoped to an App instance.
 
+The showcase's resource bridge can recover a transient fetch failure with at most
+three read attempts and bounded backoff. This applies only to `resources/read`;
+tool calls, assertions and whole checks are never replayed. Cancellation,
+HTTP/protocol/content errors and integrity failures remain failures. Browser
+diagnostics record retries, and verification retains recovered startup reads in
+its case results. Persistent transport failures still block a mutation. External
+hosts own their transport recovery; the reusable App's integrity checks remain
+the same.
+
 Managed graph builders publish into a private session directory beside the
 configured manifest. Logical scenario IDs and resource URIs stay unchanged;
 standalone builds retain the configured output and cannot overwrite a live

package/docs/BEHAVIORS.md

@@ -169,8 +169,23 @@ 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
-automatically. Fix or investigate the failure before explicitly verifying again.
+identify the resource URI. The ADS showcase retries only `resources/read` fetch
+transport failures, with at most three attempts and 200/800 ms backoff. Recovered
+startup reads appear in `startupDiagnostics` with retry counts and failed browser
+requests; each retry is also logged in the browser console. This does not retry a
+tool call, assertion, check or complete startup. HTTP/protocol/content errors,
+integrity failures and cancellations do not retry. Persistent loading failures
+still fail the check and block mutations. External hosts control their own
+transport recovery.
+
+`net::ERR_NETWORK_CHANGED` reports Chrome's network-change error, not proof that
+the MCP endpoint restarted or that a particular interface changed. To investigate
+an intermittent failure, correlate the saved case timestamps with Chrome's
+network log, server availability and live interface monitoring (for example,
+`ip -ts monitor link address route` on Linux). Interfaces being present, or stable
+after a failure, does not establish the cause. Preserve the draft and original
+diagnostic; do not change a component API, reference example or verification
+policy to compensate for a resource-loading failure.
 
 The reporter atomically publishes partial snapshots at test start/end. While a
 run is active, `ads_status.behaviors.progress` exposes the profile, runner budget,

package/docs/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.16
+
+- Recover transient showcase MCP resource fetch failures with bounded read-only
+  retries. Keep tool calls, assertions, checks and non-transport failures outside
+  recovery; expose recovered startup reads in verification diagnostics and keep
+  persistent loading failures blocking. Verify interrupted resource delivery and
+  failed delivery against a dummy App, without changing project verification policy.
+
+## 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

package/docs/MCP.md

@@ -593,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.14",
+  "version": "0.3.16",
   "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);