@reqvire-org/ads 0.3.15 → 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/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-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-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-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-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/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

@@ -229,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,13 @@
 # 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

package/package.json

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