@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/scenario-handlers.js

@@ -1,6 +1,128 @@
 const { createIssue } = require("./scenario-issues");
 
-function getInitScript() {
+// Known substrings that mean the app refused to initialize because it was loaded
+// from an *insecure context* — a bare dotted-quad IP rather than HTTPS or the
+// hostname `localhost`. This is a whole CLASS of failure (Sveltia CMS's
+// "only works with HTTPS or localhost", anything gating on `isSecureContext`,
+// `crypto.subtle`, service workers, `Secure` cookies, WebAuthn), not one app.
+// Matching reclassifies the error as an actionable `insecure-host` advisory
+// instead of a generic console/page failure that surfaces as a bare
+// `screenshot=null` with no explanation. Substrings are matched
+// case-insensitively; keep the set small and well-known.
+const INSECURE_CONTEXT_SIGNATURES = [
+  "only works with https or localhost",
+  "issecurecontext",
+  "secure context",
+  "requires https",
+];
+
+// The single actionable message the `insecure-host` advisory carries. Names the
+// class of failure and the fix (the preview origin is `localhost` by default;
+// stubborn apps can opt into HTTPS) rather than echoing one app's raw error.
+const INSECURE_HOST_ADVISORY_MESSAGE =
+  "The app refused to run because it was loaded from an insecure context " +
+  "(a bare IP). It requires a secure context — HTTPS or the hostname " +
+  "`localhost`. The preview origin is `localhost` by default; if this persists, " +
+  "the app may require HTTPS even on localhost — enable `proxy.httpsPreview` in " +
+  ".codeyam/editor.json.";
+
+// Reclassify an error string as an `insecure-host` advisory when it matches a
+// known insecure-context signature, else null. Pure; the original text is kept
+// as the `contextSnippet` so the operator can still see what the app logged.
+function insecureContextAdvisory(text) {
+  if (typeof text !== "string" || text.length === 0) return null;
+  const lower = text.toLowerCase();
+  const matched = INSECURE_CONTEXT_SIGNATURES.some((sig) => lower.includes(sig));
+  if (!matched) return null;
+  return createIssue("insecure-host", INSECURE_HOST_ADVISORY_MESSAGE, {
+    contextSnippet: 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
+// 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
+    ? ""
+    : `
+    // 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) => {
@@ -9,41 +131,29 @@ function getInitScript() {
         reason instanceof Error ? reason.message : String(reason);
       window.__codeyamUnhandledRejections.push(message);
     });
-
-    // 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);
-      }
-    };
+${webSocketStub}
   `;
 }
 
 function handleConsoleMessage(message) {
   if (message.type() !== "error") return null;
   const text = message.text();
-  
-  // Ignore known dev-server WebSocket/HMR errors from Vite proxy
+
+  // An insecure-context refusal wins over the generic `console` classification:
+  // it is the targeted, actionable signal for the secure-context app class.
+  const advisory = insecureContextAdvisory(text);
+  if (advisory) return advisory;
+
+  // 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;
   }
@@ -64,11 +174,22 @@ 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) {
-  return createIssue("pageerror", error.message || String(error));
+  const text = error.message || String(error);
+  // A secure-context guard often throws at boot rather than logging — surface
+  // the same actionable advisory for the pageerror path.
+  const advisory = insecureContextAdvisory(text);
+  if (advisory) return advisory;
+  return createIssue("pageerror", text);
 }
 
 function handleRequestFailed(request) {
@@ -95,4 +216,7 @@ module.exports = {
   handleConsoleMessage,
   handlePageError,
   handleRequestFailed,
+  insecureContextAdvisory,
+  INSECURE_CONTEXT_SIGNATURES,
+  INSECURE_HOST_ADVISORY_MESSAGE,
 };

package/npm/scenario-interactivity.js

@@ -19,13 +19,36 @@ const { createIssue } = require("./scenario-issues");
 // reliable in-page attachment signal are ALSO a conservative pass: we never
 // flag a page we cannot prove is dead, so a healthy Svelte / Solid / vanilla
 // page is never a false negative. A new framework detector is a new entry in
-// `detectors` below plus a `KNOWN_FRAMEWORKS` mapping — not an edit here.
+// `detectors` below plus a `KNOWN_FRAMEWORKS` mapping — not an edit here; a
+// meta-framework that hydrates an already-detected runtime is a new row in
+// `META_FRAMEWORK_ALIASES`.
 
 // Frameworks we have an in-page attachment detector for. Inference only
 // resolves to one of these; an unrecognised framework yields `null`, which
 // the caller treats as "cannot determine" (conservative pass).
 const KNOWN_FRAMEWORKS = ["react", "vue"];
 
+// Meta-frameworks mapped to the underlying runtime whose hydration detector
+// applies. These do not carry their runtime's name in their stack identity: a
+// Next.js app is `id: "nextjs-prisma-sqlite"`, `name: "Next.js + Prisma +
+// SQLite"` — nothing contains the literal "react". Without this map the
+// substring scan below returns `null`, the capture skips the hydration gate,
+// and a genuinely un-hydrated page is reported as an inert control rather than
+// as hydration never having run.
+//
+// Saying "Next hydrates React" is a fact about the runtime, not a framework
+// assumption, so this stays consistent with the data-driven design above: a new
+// meta-framework is a new row here, not a new branch in the capture flow.
+//
+// Matched with word boundaries rather than bare substrings so an unrelated name
+// like "NextGen CLI" or "Remixer" cannot masquerade as a meta-framework.
+const META_FRAMEWORK_ALIASES = [
+  { pattern: /\bnext(\.js|js)?\b/, framework: "react" },
+  { pattern: /\bremix\b/, framework: "react" },
+  { pattern: /\bgatsby\b/, framework: "react" },
+  { pattern: /\bnuxt(\.js|js)?\b/, framework: "vue" },
+];
+
 // Read `.codeyam/stack.json` relative to the capture script's cwd (the project
 // dir — `scenario_check.rs` sets `.current_dir(project_dir)`). Never throws: a
 // missing or malformed file yields `null` so the probe degrades to a no-op
@@ -51,6 +74,9 @@ function inferFramework(stack) {
     .filter((s) => typeof s === "string")
     .join(" ")
     .toLowerCase();
+  for (const { pattern, framework } of META_FRAMEWORK_ALIASES) {
+    if (pattern.test(haystack)) return framework;
+  }
   for (const fw of KNOWN_FRAMEWORKS) {
     if (haystack.includes(fw)) return fw;
   }
@@ -214,24 +240,136 @@ function interpretHydration({
 // project's stack.json unless the caller injects a `stack`), short-circuit when
 // no client runtime is expected, collect the in-page state, and interpret it.
 // Never throws — a probe failure must not break an otherwise-good capture.
-async function probeInteractivity(frame, { url, stack } = {}) {
+//
+// Returns `{ hydrated, issue }`:
+//   hydrated — `true` (runtime demonstrably attached), `false` (PROVEN dead:
+//     framework-owned controls rendered but nothing attached), or `null`
+//     ("cannot determine" — no client runtime expected, no control to probe, no
+//     detector for the framework, or the probe threw).
+//   issue — the `hydration` issue to surface, or `null` to pass.
+//
+// `hydrated` is deliberately three-valued rather than a bare boolean: the
+// capture flow branches a page to `interactionEffect: "unhydrated"` ONLY on a
+// proven `false`. A `null` must never be read as "dead" — that would turn every
+// unknown-framework page into a false hydration failure.
+async function probeHydrationState(frame, { url, stack } = {}) {
   const descriptor = stack !== undefined ? stack : readStackJson();
   const { expectInteractive, framework } =
     resolveInteractivityExpectation(descriptor);
-  if (!expectInteractive) return null;
+  if (!expectInteractive) return { hydrated: null, issue: null };
   let state;
   try {
     state = await collectHydrationState(frame, { framework });
   } catch (_) {
-    return null;
+    return { hydrated: null, issue: null };
   }
-  return interpretHydration({
+  const issue = interpretHydration({
     expectInteractive: true,
     controlCount: state.controlCount,
     frameworkAttached: state.frameworkAttached,
     framework,
     url,
   });
+  // `frameworkAttached` is already the three-valued signal `hydrated` needs —
+  // pass it through rather than re-deriving it from the presence of an issue,
+  // which would conflate "no issue" (a pass) with "hydrated" (a positive).
+  return { hydrated: state.frameworkAttached, issue };
+}
+
+// Sleep for `ms` — a promisified `setTimeout`, so the poll loop yields the
+// event loop between ticks instead of spinning.
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Bounded WAIT for hydration — the polling generalization of
+// `probeHydrationState`. Where the probe reads the attachment state once,
+// this re-polls `collectHydrationState` until the framework demonstrably
+// attaches, the state becomes unjudgeable, or a wall-clock cap elapses. It is
+// the seam the capture flow calls so that every screenshot and every driven
+// interaction happens AFTER the client runtime has attached, not on inert SSR
+// markup (the bug where a fill/click landed before React hydrated, the handler
+// never fired, yet the run reported success).
+//
+// Stack-agnostic by construction: it resolves the same expectation as the
+// probe, so a non-interactive stack (backend/static/CLI, or an explicit
+// `capture.interactivity === false`) returns immediately with `hydrated: null`
+// and never waits. An unknown framework (no detector) reads
+// `frameworkAttached === null` on the first poll and also passes instantly — we
+// never block on a page we cannot judge.
+//
+// Never fails closed: a timeout yields `hydrated: false` and lets the existing
+// `interpretHydration` path decide whether to surface the loud `hydration`
+// issue; a thrown probe (detached frame mid-nav) is caught and treated as a
+// pass. The wait can never hang a capture (hard cap) and never turns a page we
+// cannot prove dead into a failure.
+//
+// Honest limitation: the poll can only judge a page that has already rendered
+// framework-owned controls. `waitForStablePage` runs first (its `rootUnpainted`
+// guard waits for the SPA root to paint), so by the time this runs, content is
+// present for the SSR case this guards; a pure-CSR shell that renders zero
+// controls reads `null` and passes instantly, unchanged from today.
+//
+// Returns `{ hydrated, issue, timedOut, waitedMs }` where `hydrated` is the
+// same three-valued signal `probeHydrationState` returns.
+async function waitForHydration(
+  frame,
+  { url, stack, framework, timeoutMs = 10000, pollIntervalMs = 150 } = {},
+) {
+  let resolvedFramework;
+  let expectInteractive;
+  if (typeof framework === "string" && framework.length > 0) {
+    expectInteractive = true;
+    resolvedFramework = framework.toLowerCase();
+  } else {
+    const descriptor = stack !== undefined ? stack : readStackJson();
+    const resolution = resolveInteractivityExpectation(descriptor);
+    expectInteractive = resolution.expectInteractive;
+    resolvedFramework = resolution.framework;
+  }
+  if (!expectInteractive) {
+    return { hydrated: null, issue: null, timedOut: false, waitedMs: 0 };
+  }
+
+  const start = Date.now();
+  let state = { controlCount: 0, frameworkAttached: null };
+  let timedOut = false;
+  for (;;) {
+    try {
+      state = await collectHydrationState(frame, {
+        framework: resolvedFramework,
+      });
+    } catch (_) {
+      // Detached frame mid-navigation (or any probe throw): treat as "cannot
+      // determine" and pass — a probe failure must never fail a capture.
+      state = { controlCount: 0, frameworkAttached: null };
+      break;
+    }
+    // `true` (attached) and `null` (cannot judge) are both terminal — the
+    // conservative "can't prove dead" signal the probe already trusts. Only a
+    // proven `false` keeps us waiting.
+    if (state.frameworkAttached !== false) break;
+    // Stop before a sleep that would overrun the cap, so the wait stays bounded.
+    if (Date.now() - start + pollIntervalMs >= timeoutMs) {
+      timedOut = true;
+      break;
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  const issue = interpretHydration({
+    expectInteractive: true,
+    controlCount: state.controlCount,
+    frameworkAttached: state.frameworkAttached,
+    framework: resolvedFramework,
+    url,
+  });
+  return {
+    hydrated: state.frameworkAttached,
+    issue,
+    timedOut,
+    waitedMs: Date.now() - start,
+  };
 }
 
 module.exports = {
@@ -241,5 +379,6 @@ module.exports = {
   resolveInteractivityExpectation,
   collectHydrationState,
   interpretHydration,
-  probeInteractivity,
+  probeHydrationState,
+  waitForHydration,
 };

package/npm/scenario-issues.js

@@ -17,7 +17,14 @@ function pushIssue(issues, issue) {
   }
 }
 
-function buildResult({ loaded, hasContent, issues, outputPath, url }) {
+function buildResult({
+  loaded,
+  hasContent,
+  issues,
+  outputPath,
+  url,
+  unmockedRoutes = [],
+}) {
   return {
     ok: loaded && hasContent && issues.length === 0,
     loaded,
@@ -25,6 +32,11 @@ function buildResult({ loaded, hasContent, issues, outputPath, url }) {
     url,
     outputPath: outputPath ?? null,
     issues,
+    // Diagnostic-only: same-origin 4xx routes with no scenario mock. Does NOT
+    // affect `ok` — the paired console error already fails the capture; this is
+    // the actionable route list the failure message and `stub-unmocked-routes`
+    // consume. Defaults to `[]` so callers that omit it are unchanged.
+    unmockedRoutes,
   };
 }
 

package/npm/scenario-metrics.js

@@ -25,6 +25,34 @@ function hasLoadingMarkers(text, extraMarkers = []) {
 
 function hasRenderableContent(state) {
   if (!state) return false;
+
+  // Reveal-suppression guard. A scroll-gated entrance animation starts its
+  // content at `opacity:0` and reveals it via an IntersectionObserver wired
+  // from the app shell. Captured in isolation (no shell), the observer never
+  // fires, so the text renders into the DOM — `bodyTextLength`/`rootTextLength`
+  // are non-zero — yet stays visually invisible and the screenshot is blank.
+  // `visibleTextLength` is the length of text actually PAINTED to the frame
+  // (computed-style opacity/visibility aware). When the DOM carries text but
+  // none of it is visible AND there is no visible media, the frame is
+  // near-blank: report no content so the blank gate rejects it instead of
+  // waving through an empty shell. `visibleTextLength` is optional — older
+  // capture configs (and stubbed test targets) omit it, in which case the
+  // original DOM-presence behavior below is preserved byte-for-byte.
+  const domTextLength = Math.max(
+    state.bodyTextLength || 0,
+    state.rootTextLength || 0,
+  );
+  const hasVisibleMedia =
+    (state.loadedImageCount || 0) > 0 || (state.mediaBboxCount || 0) > 0;
+  if (
+    typeof state.visibleTextLength === "number" &&
+    domTextLength > 0 &&
+    state.visibleTextLength === 0 &&
+    !hasVisibleMedia
+  ) {
+    return false;
+  }
+
   if (
     state.rootChildCount > 0 ||
     state.rootTextLength > 0 ||
@@ -40,7 +68,17 @@ function hasRenderableContent(state) {
 function describeBlankReason(state) {
   if (!state) return "no content state collected";
   const parts = [];
-  if (!(state.bodyTextLength > 0)) {
+  // Distinguish "no text in the DOM at all" from "text rendered but nothing is
+  // visible" — the latter is the reveal-suppression symptom (opacity:0
+  // entrance content whose observer never fired in isolation), which points
+  // the author at a different fix than a genuinely empty page.
+  if (
+    typeof state.visibleTextLength === "number" &&
+    state.bodyTextLength > 0 &&
+    state.visibleTextLength === 0
+  ) {
+    parts.push("text rendered but not visible (reveal-suppressed?)");
+  } else if (!(state.bodyTextLength > 0)) {
     parts.push("no text");
   }
   const imageCount = state.imageCount || 0;
@@ -69,6 +107,16 @@ const ERROR_PATTERNS = [
   "Scenario Error",
 ];
 
+// The DOM attribute codeyam's own ScenarioRenderer stamps on its error and
+// seed-error fallback frames. Error detection anchors on this marker rather
+// than scanning the whole page body for ERROR_PATTERNS: a legitimately-mocked
+// scenario whose *content* quotes one of those harness phrases (a journal entry
+// describing the error component, say) must not be flagged as a failed capture.
+// Arbitrary client apps that never render a codeyam ScenarioRenderer never emit
+// the marker, so their pages are treated as healthy regardless of body text —
+// these patterns were always codeyam-harness-specific, never generic.
+const SCENARIO_ERROR_MARKER = "data-codeyam-scenario-error";
+
 function hasErrorPatterns(text) {
   return ERROR_PATTERNS.some((pattern) => text.includes(pattern));
 }
@@ -95,14 +143,81 @@ function buildErrorContextSnippet(text, pattern) {
   return `${prefix}${slice}${suffix}`;
 }
 
+// Classify a scenario-error fallback into a `{ matchedPattern, contextSnippet }`
+// from the marker info collected off the page. `marker` is the
+// `{ reason, text }` read from the `[data-codeyam-scenario-error]` element, or
+// null when no such element is present. Returns null when there is no marked
+// fallback — the page is healthy and no error-content failure is raised.
+//
+// When the marked fallback text contains a known ERROR_PATTERN (the render-error
+// path renders `Component "X" not found in registry`), that pattern is named so
+// the downstream Rust classifier can still extract the component; otherwise the
+// marker's `reason` attribute classifies it (the seed-error fallback, whose
+// "Seed Error" copy is intentionally not an ERROR_PATTERN). Because the text is
+// scoped to the fallback element — not the whole body — content elsewhere on the
+// page can quote these phrases freely without tripping detection.
+function findScenarioError(marker) {
+  // The capture passes the `frame.evaluate` result of querying the marker
+  // element: either null (no fallback rendered) or a `{reason, text}` object.
+  // Anything else (a bare string, a primitive) is not a marked error — guard
+  // so a non-object never reads as a present marker and false-flags the page.
+  if (!marker || typeof marker !== "object") return null;
+  const text = marker.text || "";
+  const reason = marker.reason || "";
+  const matchedPattern = findErrorPattern(text) || reason || "scenario error";
+  const contextSnippet =
+    buildErrorContextSnippet(text, matchedPattern) ||
+    (text ? text.replace(/\s+/g, " ").trim().slice(0, 200) : null);
+  return { matchedPattern, contextSnippet };
+}
+
+// Build the non-blocking "this page looks client-fetched" advisory from the two
+// settle signals the capture already computes: `stableOutcome` from
+// waitForStablePage (did the page settle, and was a loading marker still up at
+// the cap?) and `networkOutcome` from waitForNetworkQuiet (did in-flight network
+// go quiet, or did the bounded wait cap out?). Captures settle within a bounded
+// window so a never-idle stream can't hang them — which means a slower
+// client-side fetch lands AFTER the window and the screenshot catches the
+// loading/initial state instead of the populated one. When either signal fires,
+// name the cause and the two reliable fixes (server-render the data, or drive a
+// props-driven isolated component scenario) so the agent reaches for those up
+// front instead of rediscovering the constraint by trial and error. Returns the
+// advisory string, or null when the page settled cleanly (the SSR / props-driven
+// happy path — no advisory, so a healthy capture stays noise-free).
+function buildSettleAdvisory(stableOutcome, networkOutcome) {
+  const causes = [];
+  if (
+    stableOutcome &&
+    stableOutcome.stabilized === false &&
+    stableOutcome.hadLoadingMarkers === true
+  ) {
+    causes.push("a loading marker was still on the page");
+  }
+  if (networkOutcome && networkOutcome.quiet === false) {
+    causes.push("network requests were still in flight");
+  }
+  if (causes.length === 0) return null;
+  return (
+    `When this page was captured, ${causes.join(" and ")} — it likely fetches ` +
+    `its data on the client. Captures settle within a bounded window, so data ` +
+    `that arrives via a client-side fetch after that window renders as the ` +
+    `loading/initial state, not the populated state. To capture a populated ` +
+    `state, server-render the data (SSR/RSC) or drive a props-driven isolated ` +
+    `component scenario.`
+  );
+}
+
 module.exports = {
   hasLoadingMarkers,
   hasRenderableContent,
+  buildSettleAdvisory,
   describeBlankReason,
   shouldStopWaitingForImages,
   hasErrorPatterns,
   findErrorPattern,
+  findScenarioError,
   buildErrorContextSnippet,
   ERROR_PATTERNS,
+  SCENARIO_ERROR_MARKER,
   ERROR_CONTEXT_RADIUS,
 };