@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/scenario-check.js

@@ -161,6 +161,7 @@ const {
 const {
   attachHttpMocks,
   isDeclaredErrorMock,
+  unmockedRouteFrom,
 } = require("./scenario-mocks");
 
 const {
@@ -175,11 +176,112 @@ const {
   scrollThroughDocument,
   collectVisibleTextLength,
   forceFinalVisualState,
+  centerCaptureWrapper,
   performInteraction,
   waitForPredicate,
   performInteractionSequence,
 } = require("./scenario-playwright");
 
+// Name of the cookie the editor's control-API accepts the session token in —
+// must match `SESSION_COOKIE` in crates/control-api/src/origin_guard.rs. On a
+// non-loopback (cloud) bind the control-API requires this token on the harness
+// route (`/__codeyam_harness`); without it the top-level harness navigation 401s
+// and `#scenario-frame` never attaches, so EVERY capture times out. The browser
+// UI carries this cookie automatically; the headless capturer does not, so we
+// inject it here from the on-box 0600 token file.
+const SESSION_COOKIE = "cy_session";
+
+// The loopback names the editor can be addressed by. A cookie is scoped by
+// HOST, and the jar does NOT treat these as interchangeable: a cookie stored for
+// `localhost` is simply not sent to `127.0.0.1`. That matters because the two
+// token-gated capture routes resolve their origin differently — the harness
+// route via `resolveHarnessOrigin()` (typically `localhost`), the preview-proxy
+// route via `PROXY_CAPTURE_LOOPBACK` in handlers.rs, which is deliberately
+// IPv4-pinned to `127.0.0.1` so it matches the forwarder's own pinning. Scoping
+// the cookie to `localhost` alone therefore authenticated the harness route and
+// left every `/__codeyam_preview` capture with no credential, so `preview-verify`
+// / `preview-interact` / `preview-flow` all 401'd on a non-loopback bind.
+// Emitting one cookie per alias is the fix: same token, same on-box editor,
+// whichever name the capture URL happens to use.
+const LOOPBACK_COOKIE_DOMAINS = ["localhost", "127.0.0.1"];
+
+// Extract the host from an origin string, or null when it is unparseable.
+function originHost(origin) {
+  try {
+    return new URL(origin).hostname;
+  } catch (_) {
+    return null;
+  }
+}
+
+// Build the Playwright cookie array that authenticates the capture context to
+// the editor's token-gated control-API. Reads the on-box `.codeyam/session-token`
+// (0600) and emits a `cy_session` cookie for every host the capture might address
+// the editor by (see `LOOPBACK_COOKIE_DOMAINS`); cookies are port-agnostic, so
+// one per host covers the harness origin on the control port, the preview-proxy
+// route, and any `/api` call on the app-proxy port. A non-loopback harness origin
+// (a cloud tunnel domain) additionally gets its own host, since no loopback alias
+// would match it. Returns `[]` — a no-op — when there is no token file (a
+// loopback bind that never persisted one) or no resolvable harness origin, so a
+// laptop capture is completely unaffected. `deps` is injectable so the builder is
+// unit-testable without disk.
+function buildSessionTokenCookies({
+  readTokenFile = () => {
+    const p = path.join(process.cwd(), ".codeyam", "session-token");
+    return fs.existsSync(p) ? fs.readFileSync(p, "utf8").trim() : null;
+  },
+  harnessOrigin = resolveHarnessOrigin(),
+} = {}) {
+  try {
+    const token = readTokenFile();
+    if (!token || !harnessOrigin) return [];
+    const host = originHost(harnessOrigin);
+    const domains = [...LOOPBACK_COOKIE_DOMAINS];
+    // A tunnelled/cloud harness origin is not a loopback alias, so it needs its
+    // own entry or the harness navigation goes out uncredentialed.
+    if (host && !domains.includes(host)) domains.push(host);
+    return domains.map((domain) => ({
+      name: SESSION_COOKIE,
+      value: token,
+      domain,
+      path: "/",
+      httpOnly: true,
+      sameSite: "Lax",
+    }));
+  } catch (_) {
+    // A missing/unreadable token file must never break capture on a loopback
+    // bind where the token isn't required anyway — degrade to no cookie.
+    return [];
+  }
+}
+
+// True when a non-empty on-box `.codeyam/session-token` exists (the same
+// 0600 file `buildSessionTokenCookies` reads). Used by the capability-skew
+// guard to tell "no token, loopback bind, nothing to inject" (fine) apart from
+// "a token exists but the capture produced no cookie" (a stale capture script
+// heading into a guaranteed 401). Never throws — an unreadable file reports
+// absent, degrading to today's behavior.
+function onBoxSessionTokenExists() {
+  try {
+    const p = path.join(process.cwd(), ".codeyam", "session-token");
+    return fs.existsSync(p) && fs.readFileSync(p, "utf8").trim().length > 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+// Pure predicate behind the capability-skew guard: true when the capture WILL
+// use the token-gated harness route (an origin resolved) yet produced NO
+// `cy_session` cookie despite an on-box token existing — the signature of a
+// generated `.codeyam/capture.js` stale relative to the harness route, heading
+// into a guaranteed 401. Separated from the throw so the decision is
+// unit-testable without a browser context. Returns false the moment any leg is
+// absent (loopback bind with no harness origin, no token, or a cookie was
+// produced), so a healthy capture never trips it.
+function captureAuthSkewDetected({ harnessOrigin, cookieCount, tokenExists }) {
+  return Boolean(harnessOrigin) && cookieCount === 0 && Boolean(tokenExists);
+}
+
 const {
   getInitScript,
   handleConsoleMessage,
@@ -188,7 +290,7 @@ const {
 } = require("./scenario-handlers");
 
 const {
-  probeInteractivity,
+  waitForHydration,
 } = require("./scenario-interactivity");
 
 // Read project-specific loading markers from `.codeyam/stack.json`
@@ -237,6 +339,27 @@ function scenarioScriptsLiveSocket(config) {
   }
 }
 
+// Classify what a driven interaction actually did, from the DOM fingerprint on
+// either side of it plus the page's hydration state. Pure, so the distinction
+// this encodes is unit-tested without a browser.
+//
+// A click that changed nothing has two very different causes, and reporting both
+// as "none" is what let a dead page masquerade as a flaky harness: a page that
+// NEVER HYDRATED could not have responded to ANY interaction (no client JS is
+// running), whereas a hydrated page with an unchanged DOM really does mean the
+// control is inert. Keeping them apart is what tells a reader whether to go look
+// at their component or at the environment.
+//
+// `hydrated` is the three-valued signal from `waitForHydration`: only a PROVEN
+// dead page (`false`) earns "unhydrated". `null` means the wait could not judge
+// (unknown framework, no controls, probe threw) and must keep reporting "none" —
+// never invent a hydration fault we cannot prove.
+function classifyInteractionEffect(beforeFingerprint, afterFingerprint, hydrated) {
+  if (beforeFingerprint !== afterFingerprint) return "changed";
+  if (hydrated === false) return "unhydrated";
+  return "none";
+}
+
 async function getDOMFingerprint(frame) {
   try {
     return await frame.evaluate(() => {
@@ -635,8 +758,24 @@ async function verifySeededStorageLanded(frame, config) {
 // Returns the frame the flow ended on, so the caller's final screenshot and
 // result URL reflect the last navigated route.
 async function runFlowSteps(page, initialFrame, steps, ctx) {
-  const { url, loadingMarkers, navigation, iframeBackground, preflight, harnessOrigin } =
-    ctx;
+  const {
+    url,
+    loadingMarkers,
+    navigation,
+    iframeBackground,
+    preflight,
+    harnessOrigin,
+    hydrationTimeoutMs = 10000,
+    settleMs,
+  } = ctx;
+  // Honor a caller-supplied `settleMs` for the in-flow stability windows,
+  // falling back to today's hardcoded defaults (5s for interaction steps, 10s
+  // for a navigate). This stops the field from being silently dropped — the
+  // exact trap that made a reporter's `settleMs: 8000` a no-op.
+  const navigateSettleMs =
+    typeof settleMs === "number" && settleMs > 0 ? settleMs : 10000;
+  const interactionSettleMs =
+    typeof settleMs === "number" && settleMs > 0 ? settleMs : 5000;
   let frame = initialFrame;
 
   for (let i = 0; i < steps.length; i++) {
@@ -655,14 +794,22 @@ async function runFlowSteps(page, initialFrame, steps, ctx) {
                   harnessOrigin,
                 });
           frame = loadResult.frame;
-          await waitForStablePage(page, frame, 10000, loadingMarkers);
+          await waitForStablePage(page, frame, navigateSettleMs, loadingMarkers);
+          // A navigate loads a fresh route that must re-hydrate before the next
+          // fill/click, or the interaction lands on inert SSR markup (the same
+          // bug the top-level wait fixes, one route deeper). Bounded and
+          // stack-gated exactly like the top-level wait.
+          await waitForHydration(frame, {
+            url: target,
+            timeoutMs: hydrationTimeoutMs,
+          });
           break;
         }
         case "click":
         case "fill":
         case "press":
           await performInteraction(frame, step);
-          await waitForStablePage(page, frame, 5000, loadingMarkers);
+          await waitForStablePage(page, frame, interactionSettleMs, loadingMarkers);
           break;
         case "waitFor":
           await waitForPredicate(frame, step);
@@ -699,9 +846,14 @@ async function runScenarioCheck(
   config,
   { preflight = assertAppPortReachable, harnessOrigin } = {},
 ) {
-  const resolvedHarnessOrigin =
-    harnessOrigin !== undefined ? harnessOrigin : resolveHarnessOrigin();
   const { url, outputPath, width, height, httpMocks = {} } = config;
+  // The harness host mirrors the capture target's host so the framed load stays
+  // SAME-SITE — see `resolveHarnessOrigin`. A cross-site frame withholds the
+  // SameSite=Lax `cy_session` cookie and every token-gated route 401s.
+  const resolvedHarnessOrigin =
+    harnessOrigin !== undefined
+      ? harnessOrigin
+      : resolveHarnessOrigin({ targetUrl: url });
   // Per-scenario capture-check allowances (see `CaptureAllowances` /
   // `ScenarioDefinition` on the Rust side). Default false so the guards keep
   // their strict behavior for every scenario that does not opt in.
@@ -709,7 +861,20 @@ async function runScenarioCheck(
   const expectedConsoleErrors = !!(config && config.expectedConsoleErrors);
   let interactionEffect = null;
   let interactionRetried = false;
+  // Non-fatal warnings raised while resolving interaction/flow targets — e.g. a
+  // substring text match that hit more than one element. Surfaced on the result
+  // so the agent sees the ambiguity instead of a silently-wrong first-match.
+  const interactionWarnings = [];
   const issues = [];
+  // Actionable set for self-healing: same-origin routes that returned 4xx with
+  // no scenario mock. A hermetic-proxy/upstream 404 is a *successful* HTTP
+  // response with status 404 (not a Playwright `requestfailed`), so the only
+  // place with method + path + status together is the `page.on("response")`
+  // collector below. De-duped by `"<METHOD> <path>"`; surfaced through
+  // `buildResult` so the Rust failure message can name each unmocked route and
+  // `stub-unmocked-routes` can add stub mocks for them.
+  const unmockedRoutes = [];
+  const unmockedRouteKeys = new Set();
   // Origin of the captured page, used to classify failed requests: only a
   // failure on the page's OWN origin should fail the capture (see
   // `isCaptureFatalRequestFailure`). Derived from `config.url` exactly as
@@ -742,6 +907,45 @@ async function runScenarioCheck(
   }
   const context = await browser.newContext(contextOptions);
 
+  // Authenticate the capture context to the editor's token-gated control-API
+  // BEFORE any navigation. On a non-loopback bind the harness route requires the
+  // session token; the browser UI carries it as a cookie automatically but the
+  // headless capturer does not, so inject it from the on-box token file. Scoped
+  // to the SAME resolved harness origin the capture navigates to: when no harness
+  // origin resolves (missing server-state, or a test that passes
+  // `harnessOrigin: null`) there is nothing to authenticate to, so no cookie is
+  // added. The `addCookies` guard keeps a mock context that doesn't implement it
+  // from throwing (a real Playwright context always has it).
+  const sessionCookies = buildSessionTokenCookies({
+    harnessOrigin: resolvedHarnessOrigin,
+  });
+  // Capability-skew guard. When the capture WILL use the token-gated harness
+  // route (a harness origin resolved) AND an on-box session token exists, but no
+  // `cy_session` cookie was produced, the token injection is broken — the
+  // generated `.codeyam/capture.js` is stale relative to the harness route it
+  // must authenticate to. Proceeding would hit a guaranteed 401 and strand every
+  // component capture on a `#scenario-frame` timeout. Fail loudly at the source
+  // instead, naming the version skew and its fix — closing the gap between the
+  // harness route (present) and the capture-side auth (absent).
+  if (
+    captureAuthSkewDetected({
+      harnessOrigin: resolvedHarnessOrigin,
+      cookieCount: sessionCookies.length,
+      tokenExists: onBoxSessionTokenExists(),
+    })
+  ) {
+    throw new Error(
+      `The capture harness origin ${resolvedHarnessOrigin} is token-gated and an ` +
+        `on-box \`.codeyam/session-token\` exists, but the capture produced no ` +
+        `\`cy_session\` cookie — the generated \`.codeyam/capture.js\` is stale ` +
+        `relative to the harness route (its session-token injection is missing or ` +
+        `broken). Regenerate the capture script / refresh the editor binary on this VM.`,
+    );
+  }
+  if (sessionCookies.length > 0 && typeof context.addCookies === "function") {
+    await context.addCookies(sessionCookies);
+  }
+
   // Apply the scenario's merged `browserState` (cookies + request
   // headers) to the capture context BEFORE the first navigation.
   // Belt-and-suspenders with the proxy's `Set-Cookie` injection: the
@@ -793,6 +997,30 @@ async function runScenarioCheck(
     pushIssue(issues, issue);
   });
 
+  page.on("response", (response) => {
+    // Collect same-origin 4xx responses that no scenario mock covers — the set
+    // a stub mock would fix. Mirrors the console-guard predicates exactly so the
+    // reported set matches the guard's tolerances: a scenario that provokes
+    // errors by design (`expectedConsoleErrors`) reports none, and a route the
+    // scenario already declares an error mock for is the mock's intended 4xx,
+    // not a missing mock.
+    if (expectedConsoleErrors) return;
+    const req = response.request();
+    const reqUrl = req.url();
+    // Same-origin only — mirror the console/requestfailed origin gate so a
+    // cross-origin sub-resource 4xx is never reported as an unmocked route.
+    if (!isCaptureFatalRequestFailure(reqUrl, appOrigin)) return;
+    // The status-threshold, declared-mock, and path-extraction decision is the
+    // pure `unmockedRouteFrom` helper; the listener keeps only the stateful
+    // same-origin gate above and the dedup below.
+    const route = unmockedRouteFrom(req.method(), reqUrl, response.status(), httpMocks);
+    if (!route) return;
+    const key = `${route.method} ${route.path}`;
+    if (unmockedRouteKeys.has(key)) return;
+    unmockedRouteKeys.add(key);
+    unmockedRoutes.push(route);
+  });
+
   page.on("requestfailed", (request) => {
     // Per-scenario allowance: the broken-image fallback scenario's `<img>` 404
     // is a SAME-origin request failure it exists to demonstrate, so
@@ -843,6 +1071,21 @@ async function runScenarioCheck(
           status: response.status(),
         }),
       );
+    } else if (!response && config.navigation === "topLevel") {
+      // A real top-level document load always yields a response. A null one
+      // means the status could never be checked — and an unverified status is
+      // not a passing status: a 500 whose error body renders text would
+      // otherwise satisfy `hasContent` and pass as `ok`. Fail loudly instead.
+      // The iframe path stays tolerant: there the app response is matched by
+      // exact URL and is legitimately allowed to miss.
+      pushIssue(
+        issues,
+        createIssue(
+          "navigation",
+          "Navigation response unavailable — could not verify the HTTP status of the top-level document",
+          { url },
+        ),
+      );
     }
 
     pushRedirectMismatchIssue(issues, url, frame, response, config);
@@ -862,6 +1105,15 @@ async function runScenarioCheck(
       typeof config.stableTimeoutMs === "number" && config.stableTimeoutMs > 0
         ? config.stableTimeoutMs
         : 10000;
+    // Hydration wait cap. Mirrors `stableTimeoutMs`: defaults to 10s, but a slow
+    // Turbopack cold-compile route can extend it via `config.hydrationTimeoutMs`
+    // without a code change. Bounded and near-zero on a healthy page (attaches in
+    // a poll or two); only a genuinely dead page pays the full cap.
+    const hydrationTimeoutMs =
+      typeof config.hydrationTimeoutMs === "number" &&
+      config.hydrationTimeoutMs > 0
+        ? config.hydrationTimeoutMs
+        : 10000;
     const stableOutcome = await waitForStablePage(
       page,
       frame,
@@ -988,11 +1240,28 @@ async function runScenarioCheck(
     // to run before the screenshot. Stack-gated and fail-safe — see
     // scenario-interactivity.js — so backend / static / unknown-framework
     // captures are an automatic pass.
-    const hydrationIssue = await probeInteractivity(frame, {
+    // `hydration.hydrated` is also consulted below to classify interactionEffect:
+    // the wait runs BEFORE any interaction, which is exactly the reading we want
+    // — "was this page alive when we found it," not "did our click revive it."
+    //
+    // WAIT for hydration (not just detect it): the one-shot probe read the
+    // attachment state before React had a chance to hydrate SSR markup, so the
+    // subsequent fill/click landed on inert controls and the submit handler
+    // never fired — yet the run reported success. Waiting here gates the
+    // screenshot AND every interaction branch below (steps / interaction /
+    // interactions[] all run after this line) on the client runtime actually
+    // attaching. Stack-gated and fail-safe: a timed-out wait yields
+    // `hydrated: false` (so a truly dead page still classifies `unhydrated`),
+    // and a non-interactive stack returns instantly.
+    const hydration = await waitForHydration(frame, {
       url: page.url() || url,
+      timeoutMs: hydrationTimeoutMs,
+      // `undefined` in production → waitForHydration reads .codeyam/stack.json;
+      // a test injects a stack to force the interactive path without a real file.
+      stack: config.stack,
     });
-    if (hydrationIssue) {
-      pushIssue(issues, hydrationIssue);
+    if (hydration.issue) {
+      pushIssue(issues, hydration.issue);
     }
 
     // Assert the injected seed actually landed in the capture browser, at rest
@@ -1020,6 +1289,9 @@ async function runScenarioCheck(
         iframeBackground: config.iframeBackground,
         preflight,
         harnessOrigin: resolvedHarnessOrigin,
+        warnings: interactionWarnings,
+        hydrationTimeoutMs,
+        settleMs: config.settleMs,
       });
     } else if (config.interaction) {
       // Record fingerprint before interaction
@@ -1030,7 +1302,9 @@ async function runScenarioCheck(
       // fill / press (expanded accordion, open modal) without editing app
       // source. A no-match target throws here and is caught below as a failed
       // capture with the candidate-labels hint — never a silent blank shot.
-      await performInteraction(frame, config.interaction);
+      await performInteraction(frame, config.interaction, {
+        warnings: interactionWarnings,
+      });
       await waitForStablePage(page, frame, 5000, loadingMarkers);
 
       // Record fingerprint after interaction
@@ -1040,12 +1314,18 @@ async function runScenarioCheck(
       if (beforeFingerprint === afterFingerprint && config.interaction.action === "click") {
         interactionRetried = true;
         await new Promise((resolve) => setTimeout(resolve, 500));
+        // The retry re-resolves the same target; suppress its ambiguity warning
+        // (already captured on the first attempt) to avoid a duplicate.
         await performInteraction(frame, config.interaction);
         await waitForStablePage(page, frame, 5000, loadingMarkers);
         afterFingerprint = await getDOMFingerprint(frame);
       }
 
-      interactionEffect = beforeFingerprint === afterFingerprint ? "none" : "changed";
+      interactionEffect = classifyInteractionEffect(
+        beforeFingerprint,
+        afterFingerprint,
+        hydration.hydrated,
+      );
     }
 
     // Replay the scenario's PERSISTED interaction sequence (if any) in order,
@@ -1058,6 +1338,7 @@ async function runScenarioCheck(
       await performInteractionSequence(page, frame, config.interactions, {
         settleMs: 5000,
         loadingMarkers,
+        warnings: interactionWarnings,
       });
     }
 
@@ -1074,6 +1355,17 @@ async function runScenarioCheck(
       await forceFinalVisualState(frame).catch(() => {});
     }
 
+    // Center an isolated-component wrapper that is not already centered. The
+    // shot below is full-viewport with no element clip, so an isolation page
+    // that does not center itself lands in the top-left corner. Unlike
+    // forceFinalVisualState this is NOT gated on hasDeclaredInteractiveState:
+    // an isolation page with a declared interaction still needs to be centered,
+    // and moving the wrapper does not clobber its contents the way
+    // animation-forcing does — so a replayed interaction sequence stays valid.
+    if (outputPath && loaded) {
+      await centerCaptureWrapper(frame).catch(() => {});
+    }
+
     if (outputPath && loaded) {
       fs.mkdirSync(path.dirname(outputPath), { recursive: true });
       await page.screenshot({ path: outputPath, fullPage: false });
@@ -1085,6 +1377,7 @@ async function runScenarioCheck(
       issues,
       outputPath,
       url: frame.url() || url,
+      unmockedRoutes,
     });
 
     if (config.interaction) {
@@ -1092,6 +1385,14 @@ async function runScenarioCheck(
       result.interactionRetried = interactionRetried;
     }
 
+    // Surface any non-fatal interaction/flow warnings (e.g. an ambiguous
+    // substring text match) so the CLI can print them and the agent can switch
+    // to a precise selector. Only attached when present — a clean run is
+    // byte-for-byte unchanged.
+    if (interactionWarnings.length > 0) {
+      result.warnings = interactionWarnings.slice();
+    }
+
     // `capture-state` mode: attach the read-only page-state snapshot so the
     // backend can report localStorage + rendered text. Off by default, so a
     // normal error-check capture is byte-for-byte unchanged.
@@ -1119,6 +1420,7 @@ async function runScenarioCheck(
       issues,
       outputPath,
       url,
+      unmockedRoutes,
     });
   } finally {
     await browser.close();
@@ -1146,6 +1448,7 @@ async function main() {
 
 module.exports = {
   runScenarioCheck,
+  classifyInteractionEffect,
   mergeVisibleTextLength,
   runFlowSteps,
   dumpPageState,
@@ -1153,6 +1456,9 @@ module.exports = {
   readStackLoadingMarkers,
   scenarioScriptsLiveSocket,
   applyBrowserState,
+  buildSessionTokenCookies,
+  captureAuthSkewDetected,
+  SESSION_COOKIE,
   isCrossOriginRequest,
   isCaptureFatalRequestFailure,
   stripMarkerHeaders,

package/npm/scenario-handlers.js

@@ -39,44 +39,90 @@ function insecureContextAdvisory(text) {
   });
 }
 
+// The pathname suffix identifying the editor's OWN terminal socket. Matched by
+// suffix rather than full URL because the terminal is proxied through varying
+// origins (localhost, a container IP, a tunnel host) and varying ports.
+const TERMINAL_SOCKET_PATH_SUFFIX = "/ws/terminal";
+
 // `allowWebSocket` keeps the real `WebSocket` for scenarios that script a
 // `/ws/terminal` transcript (or a WS stream): those captures NEED the socket to
 // connect so the server replays the scripted agent state into the frame. The
-// stub below exists to silence the live terminal's reconnect loop on EVERY
-// OTHER capture (a component that opens `/ws/terminal` with no scripted
+// interception below exists to silence the live terminal's reconnect loop on
+// EVERY OTHER capture (a component that opens `/ws/terminal` with no scripted
 // playback would otherwise screenshot the "Reconnecting…" overlay); for a
 // scripted scenario the server holds the socket open after replay, so there is
 // no reconnect spam to silence and stubbing only hides the very state we are
 // trying to capture. The flag is computed by the capture orchestrator from the
 // scenario's `mocks.transcripts` / `mocks.streams` — see
 // `scenarioScriptsLiveSocket` in scenario-check.js.
+//
+// The interception is SCOPED BY URL and never blanket-replaces the global
+// constructor. A dead global `WebSocket` also kills the framework's HMR socket,
+// and on a dev-mode client bootstrap that runs through that socket (validated on
+// Next.js 16 + turbopack) React then never hydrates in the capture browser —
+// silently, with no console error. Every interactive capture of such an app
+// reads as inert: clicks land on un-hydrated SSR markup and `interactionEffect`
+// comes back `none`/`unhydrated`. Letting HMR connect costs nothing in capture
+// noise, because `handleConsoleMessage` below already drops
+// "WebSocket connection to" errors.
 function getInitScript(allowWebSocket = false) {
   const webSocketStub = allowWebSocket
     ? ""
     : `
-    // Stub WebSocket during capture to prevent terminal reconnection spam.
-    window.WebSocket = class StubWebSocket {
-      static CONNECTING = 0;
-      static OPEN = 1;
-      static CLOSING = 2;
-      static CLOSED = 3;
-      readyState = 3;
-      onopen = null;
-      onclose = null;
-      onerror = null;
-      onmessage = null;
-      send() {}
-      close() {}
-      addEventListener() {}
-      removeEventListener() {}
-      dispatchEvent() { return false; }
-      constructor() {
-        setTimeout(() => {
-          if (this.onerror) this.onerror(new Event("error"));
-          if (this.onclose) this.onclose(new CloseEvent("close"));
-        }, 0);
+    // Intercept ONLY the editor's own terminal socket during capture, to
+    // prevent terminal reconnection spam. Every other URL — notably the
+    // framework's HMR socket, which dev-mode hydration depends on — gets the
+    // real WebSocket.
+    (() => {
+      const RealWebSocket = window.WebSocket;
+      if (!RealWebSocket) return;
+      class StubWebSocket {
+        static CONNECTING = 0;
+        static OPEN = 1;
+        static CLOSING = 2;
+        static CLOSED = 3;
+        readyState = 3;
+        url = "";
+        onopen = null;
+        onclose = null;
+        onerror = null;
+        onmessage = null;
+        send() {}
+        close() {}
+        addEventListener() {}
+        removeEventListener() {}
+        dispatchEvent() { return false; }
+        constructor(url) {
+          this.url = String(url);
+          setTimeout(() => {
+            if (this.onerror) this.onerror(new Event("error"));
+            if (this.onclose) this.onclose(new CloseEvent("close"));
+          }, 0);
+        }
+      }
+      const isTerminalSocket = (url) => {
+        const raw = String(url);
+        try {
+          return new URL(raw, window.location.href).pathname.endsWith(
+            ${JSON.stringify(TERMINAL_SOCKET_PATH_SUFFIX)}
+          );
+        } catch (_) {
+          return raw.includes(${JSON.stringify(TERMINAL_SOCKET_PATH_SUFFIX)});
+        }
+      };
+      function CodeyamWebSocket(url, protocols) {
+        if (isTerminalSocket(url)) return new StubWebSocket(url);
+        return protocols === undefined
+          ? new RealWebSocket(url)
+          : new RealWebSocket(url, protocols);
       }
-    };`;
+      CodeyamWebSocket.prototype = RealWebSocket.prototype;
+      CodeyamWebSocket.CONNECTING = 0;
+      CodeyamWebSocket.OPEN = 1;
+      CodeyamWebSocket.CLOSING = 2;
+      CodeyamWebSocket.CLOSED = 3;
+      window.WebSocket = CodeyamWebSocket;
+    })();`;
   return `
     window.__codeyamUnhandledRejections = [];
     window.addEventListener("unhandledrejection", (event) => {
@@ -98,10 +144,16 @@ function handleConsoleMessage(message) {
   const advisory = insecureContextAdvisory(text);
   if (advisory) return advisory;
 
-  // Ignore known dev-server WebSocket/HMR errors from Vite proxy
+  // Ignore known dev-server WebSocket/HMR errors from Vite proxy, plus the
+  // crxjs/Vite dynamic-import reload race: dev loaders `import()` the app entry
+  // with a `?t=<timestamp>` cache-buster, and a rapid scenario-reactivation
+  // reload aborts the in-flight import, logging "TypeError: Failed to fetch
+  // dynamically imported module" (Chrome) or "error loading dynamically
+  // imported module" (Vite). Benign — the entry reloads on the next nav.
   if (
     text.includes("WebSocket connection to") ||
-    text.includes("Unsupported Media Type")
+    text.includes("Unsupported Media Type") ||
+    text.includes("dynamically imported module")
   ) {
     return null;
   }
@@ -122,7 +174,13 @@ function handleConsoleMessage(message) {
     return null;
   }
 
-  return createIssue("console", text);
+  // Attach the offending resource URL the console message already exposes, so
+  // the capture-failure message can name the unmocked route (e.g.
+  // `GET /api/questions/<id>/research`) instead of an opaque "Failed to load
+  // resource". `message.location().url` is the resource that produced the
+  // error; `format_issue` renders it as `[<url>]` when populated.
+  const url = message.location && message.location().url;
+  return createIssue("console", text, url ? { url } : {});
 }
 
 function handlePageError(error) {