@codeyam-editor/codeyam-editor 0.1.15 → 0.1.16

package/npm/scenario-check.js

@@ -11,29 +11,7 @@
 
 const fs = require("fs");
 const path = require("path");
-const { execSync } = require("child_process");
-const { chromium } = require("playwright");
-
-// Substring Playwright has emitted across every 1.x release when the
-// browser cache is empty. Match the substring (not the full string)
-// because Playwright includes the offending path inline.
-const PLAYWRIGHT_MISSING_BROWSER_PATTERN = "Executable doesn't exist";
-const PLAYWRIGHT_INSTALL_COMMAND = "npx playwright install chromium";
-
-// Substrings Playwright/Chromium emit when the browser process dies on a
-// transient launch crash. On the cloud VM the base image has no dbus session,
-// so Chromium intermittently aborts at launch with `Received signal 11`
-// (SIGSEGV) — an environmental fault, not a scenario fault. Match either form
-// because the wording varies across Playwright releases and the OS signal
-// reporter.
-const PLAYWRIGHT_LAUNCH_CRASH_PATTERNS = ["SIGSEGV", "Received signal 11"];
-// A transient SIGSEGV launch crash is environmental, so a bounded retry clears
-// it. Keep it small — a genuinely broken environment must still surface loudly
-// rather than spin.
-const CAPTURE_LAUNCH_SIGSEGV_RETRIES = 2;
-// Short backoff between SIGSEGV retries so the transient fault has a moment to
-// clear; small enough not to eat the per-slug recapture budget.
-const CAPTURE_LAUNCH_SIGSEGV_BACKOFF_MS = 250;
+const { launchChromiumWithSelfHeal } = require("./scenario-launch");
 
 // The sentinel the reverse proxy stamps on its dev-server-down placeholder —
 // the other half of this contract is
@@ -44,306 +22,6 @@ const CAPTURE_LAUNCH_SIGSEGV_BACKOFF_MS = 250;
 // the moment `render_placeholder` is reworded.
 const DEV_SERVER_DOWN_HEADER = "x-codeyam-dev-server-down";
 
-// Pin the headless capture browser's `localhost` resolution to the IPv4
-// loopback the editor's listeners bind. The browser-facing preview origin is
-// now `localhost` (secure-context apps refuse a bare IP — see
-// `BROWSER_FACING_HOST`), but on a dual-stack host `localhost` can resolve to
-// `::1` first, which nothing answers on — stalling the capture or paying a
-// happy-eyeballs fallback delay. Forcing the map removes that intermittency
-// deterministically for capture. The operator's OWN preview browser is covered
-// separately by the editor binding `::1` alongside `127.0.0.1` (see start.rs).
-const CAPTURE_HOST_RESOLVER_RULES = "MAP localhost 127.0.0.1";
-const CAPTURE_LAUNCH_ARGS = [
-  `--host-resolver-rules=${CAPTURE_HOST_RESOLVER_RULES}`,
-  // Cloud-VM-no-dbus / containerized-launch hardening. Each flag below is
-  // inert on a healthy desktop, so the laptop capture path is unchanged; on
-  // the dbus-less cloud base image they stop Chromium from SIGSEGV-ing at
-  // launch (signal 11). See plan chromium-capture-dbus-crash-hardening.
-  // No setuid sandbox in the container (the cloud VM runs capture without the
-  // kernel namespaces the sandbox needs).
-  "--no-sandbox",
-  // /dev/shm is tiny in many containers; route shared memory to /tmp so the
-  // renderer doesn't crash allocating it.
-  "--disable-dev-shm-usage",
-  // No GPU on the headless cloud VM — avoid the GL init path that aborts.
-  "--disable-gpu",
-  // Software WebGL2, asked for EXPLICITLY rather than inherited. Playwright
-  // adds this itself on Linux, which is why `--disable-gpu` left canvas apps
-  // with working WebGL2 there — and why it did not on macOS, where Playwright
-  // does not add it: `getContext("webgl2")` returned null and the WebGL2
-  // capture test failed on every mac dev machine while passing in CI. That is
-  // the host-capability dependency CLAUDE.md forbids, so the flag is now
-  // stated here for every platform. A duplicate on Linux is harmless
-  // (last-wins, same value). WebGPU is still unavailable either way.
-  "--enable-unsafe-swiftshader",
-];
-// Features the capture browser disables on top of Playwright's own list.
-// DBus: stub out the dbus integration Chromium reaches for at launch; the cloud
-// base image has no dbus session bus, which is the proximate cause of the
-// signal-11 abort.
-//
-// These are NOT a second `--disable-features=` switch. Chromium keeps only the
-// LAST value of a repeated switch (verified empirically: `--disable-features=
-// WebHID` hides `navigator.hid`, and a later `--disable-features=DBus` brings it
-// back), so appending our own switch silently re-enabled every feature
-// Playwright disables. `captureLaunchOptions` merges them into one value.
-const CAPTURE_DISABLED_FEATURES = ["DBus"];
-const DISABLE_FEATURES_PREFIX = "--disable-features=";
-
-// Playwright's own default `--disable-features=<list>` switch, exactly as it
-// will pass it, or null when it cannot be read. Read from playwright-core's
-// switch table (not part of its public exports, so it is required by file path
-// and any failure degrades to null rather than throwing).
-function playwrightDefaultDisableFeaturesArg() {
-  try {
-    const playwrightDir = path.dirname(require.resolve("playwright/package.json"));
-    const coreDir = path.dirname(
-      require.resolve("playwright-core/package.json", { paths: [playwrightDir] }),
-    );
-    const { chromiumSwitches } = require(
-      path.join(coreDir, "lib", "server", "chromium", "chromiumSwitches.js"),
-    );
-    const found = chromiumSwitches(false).find(
-      (arg) => typeof arg === "string" && arg.startsWith(DISABLE_FEATURES_PREFIX),
-    );
-    return found || null;
-  } catch (_) {
-    return null;
-  }
-}
-
-// One `--disable-features=` value carrying the default list plus `extra`,
-// de-duplicated and order-preserving.
-function mergeDisableFeaturesArg(defaultArg, extra) {
-  const base =
-    typeof defaultArg === "string" && defaultArg.startsWith(DISABLE_FEATURES_PREFIX)
-      ? defaultArg.slice(DISABLE_FEATURES_PREFIX.length).split(",")
-      : [];
-  const merged = [];
-  for (const feature of base.concat(extra)) {
-    if (feature && !merged.includes(feature)) merged.push(feature);
-  }
-  return DISABLE_FEATURES_PREFIX + merged.join(",");
-}
-
-// The `chromium.launch` args for capture. Playwright's default
-// `--disable-features` switch is suppressed via `ignoreDefaultArgs` and
-// re-supplied merged with ours. Should the suppression ever miss (its match is
-// exact-string), our merged switch is still the later one and a superset, so
-// the last-wins rule still lands every feature.
-function captureLaunchOptions({
-  defaultDisableFeaturesArg = playwrightDefaultDisableFeaturesArg(),
-} = {}) {
-  const args = [
-    ...CAPTURE_LAUNCH_ARGS,
-    mergeDisableFeaturesArg(defaultDisableFeaturesArg, CAPTURE_DISABLED_FEATURES),
-  ];
-  return defaultDisableFeaturesArg
-    ? { args, ignoreDefaultArgs: [defaultDisableFeaturesArg] }
-    : { args };
-}
-// Point Chromium's dbus client at a dead address so it never blocks on (or
-// crashes against) a missing session bus. Spread over the real env in the
-// default launcher so the laptop path keeps its normal environment.
-const CAPTURE_LAUNCH_DBUS_ENV = { DBUS_SESSION_BUS_ADDRESS: "/dev/null" };
-
-// Does this launch error look like a transient SIGSEGV browser crash?
-// (environmental — e.g. the cloud VM's missing dbus session bus — not a
-// scenario fault, so it is safe to retry).
-function isTransientLaunchCrash(error) {
-  return (
-    error &&
-    typeof error.message === "string" &&
-    PLAYWRIGHT_LAUNCH_CRASH_PATTERNS.some((pattern) =>
-      error.message.includes(pattern),
-    )
-  );
-}
-
-// Stable first token of the error a missing-system-library launch failure is
-// rethrown as. The Rust side keys on it (`scenario_check.rs`
-// `CAPTURE_BROWSER_DEPS_MISSING_MARKER`) to turn the failure into a blocked
-// precondition, so the two spellings must stay greppable from each other.
-const CAPTURE_BROWSER_DEPS_MISSING_MARKER = "CODEYAM_CAPTURE_BROWSER_DEPS_MISSING";
-// The two shapes a missing shared library takes in a launch error: the dynamic
-// loader's own line (Chromium starts and dies), and Playwright's host
-// validation box listing every missing library before it even spawns.
-const MISSING_SHARED_LIBRARY_PATTERNS = [
-  "error while loading shared libraries",
-  "Host system is missing dependencies",
-];
-const SHARED_LIBRARY_NAME_PATTERN = /\blib[\w+-]+(?:\.[\w+-]+)*?\.so(?:\.\d+)*/g;
-const PLAYWRIGHT_INSTALL_DEPS_COMMAND = "npx playwright install-deps chromium";
-// Nix package for the libraries Chromium most often lacks on Replit, keyed by
-// the stem before `.so`. A library outside this map still gets a remedy — it is
-// just named without a package suggestion.
-const REPLIT_NIX_PACKAGE_FOR_LIBRARY = {
-  "libglib-2.0": "pkgs.glib",
-  "libgobject-2.0": "pkgs.glib",
-  "libgio-2.0": "pkgs.glib",
-  libnss3: "pkgs.nss",
-  libnssutil3: "pkgs.nss",
-  libsmime3: "pkgs.nss",
-  libnspr4: "pkgs.nspr",
-  "libatk-1.0": "pkgs.atk",
-  "libatk-bridge-2.0": "pkgs.at-spi2-atk",
-  "libatspi": "pkgs.at-spi2-core",
-  libcups: "pkgs.cups",
-  "libdbus-1": "pkgs.dbus",
-  libdrm: "pkgs.libdrm",
-  libgbm: "pkgs.mesa",
-  libxkbcommon: "pkgs.libxkbcommon",
-  libasound: "pkgs.alsa-lib",
-  "libpango-1.0": "pkgs.pango",
-  libcairo: "pkgs.cairo",
-  libexpat: "pkgs.expat",
-  libX11: "pkgs.xorg.libX11",
-  libXcomposite: "pkgs.xorg.libXcomposite",
-  libXdamage: "pkgs.xorg.libXdamage",
-  libXext: "pkgs.xorg.libXext",
-  libXfixes: "pkgs.xorg.libXfixes",
-  libXrandr: "pkgs.xorg.libXrandr",
-  libxcb: "pkgs.xorg.libxcb",
-};
-
-// Does this launch error say the host is missing a shared library Chromium
-// needs? Not retryable and not fixed by downloading the browser again.
-function isMissingSystemLibrary(error) {
-  return (
-    !!error &&
-    typeof error.message === "string" &&
-    MISSING_SHARED_LIBRARY_PATTERNS.some((pattern) =>
-      error.message.includes(pattern),
-    )
-  );
-}
-
-// Every distinct `lib*.so*` name a missing-library launch error mentions, in
-// first-seen order. Covers both the loader line and Playwright's list.
-function missingLibraryNames(error) {
-  const message = (error && error.message) || "";
-  return [...new Set(message.match(SHARED_LIBRARY_NAME_PATTERN) || [])];
-}
-
-// The fix for the platform the capture is running on. Replit is detected by the
-// same env signals `preview_host_provider/replit.rs` uses; there system
-// packages come from replit.nix. Any other Linux host gets Playwright's own
-// dependency installer; anything else gets the library names and a hint.
-function missingLibraryRemedy(libraries, { env = process.env, platform = process.platform } = {}) {
-  const named = libraries.length > 0 ? libraries.join(", ") : "the missing libraries";
-  if (env.REPL_ID || env.REPLIT_DEV_DOMAIN) {
-    const packages = [
-      ...new Set(
-        libraries
-          .map((lib) => REPLIT_NIX_PACKAGE_FOR_LIBRARY[lib.split(".so")[0]])
-          .filter(Boolean),
-      ),
-    ];
-    const suggestion =
-      packages.length > 0 ? ` (${packages.join(", ")})` : "";
-    return `add the Nix package(s) providing ${named}${suggestion} to the \`deps\` list in replit.nix, then restart the Repl and re-run the capture`;
-  }
-  if (platform === "linux") {
-    return `install Chromium's system libraries with \`${PLAYWRIGHT_INSTALL_DEPS_COMMAND}\` (may need sudo), then re-run the capture`;
-  }
-  return `install the system package(s) that provide ${named} for this OS, then re-run the capture`;
-}
-
-// The rethrown error for a missing-library launch failure: marker line naming
-// the libraries, a `remedy:` line, then the original Playwright message as
-// diagnostic. Line-oriented so the Rust side can lift each part out.
-function missingSystemLibraryError(error, { env, platform } = {}) {
-  const libraries = missingLibraryNames(error);
-  const remedy = missingLibraryRemedy(libraries, { env, platform });
-  const wrapped = new Error(
-    `${CAPTURE_BROWSER_DEPS_MISSING_MARKER} ${libraries.join(",")}\n` +
-      `remedy: ${remedy}\n` +
-      error.message,
-  );
-  wrapped.cause = error;
-  return wrapped;
-}
-
-// Self-heal around `chromium.launch()`. Two recoverable classes:
-//
-//   1. "missing browser" — run `npx playwright install chromium` synchronously
-//      (with `stdio: "inherit"` so the user sees progress) and retry once.
-//   2. transient SIGSEGV launch crash — retry the launch up to
-//      `CAPTURE_LAUNCH_SIGSEGV_RETRIES` times with a short backoff, since the
-//      crash is environmental (dbus-less cloud VM) and clears on a retry.
-//
-// A third class is diagnosed but deliberately NOT healed: a host missing a
-// system library Chromium links against. Installing system packages changes
-// the user's environment (replit.nix, apt, often root), so it is rethrown —
-// with no retry and no browser install — as `missingSystemLibraryError`,
-// naming the library and the platform's remedy.
-//
-// For any unrecognized error, or after exhausting retries, rethrow the
-// ORIGINAL Playwright error so the existing `Scenario check failed: <stderr>`
-// path keeps showing the actionable message — looping would hide a real ops
-// failure under a slow timeout.
-async function launchChromiumWithSelfHeal({
-  launch = () =>
-    chromium.launch({
-      ...captureLaunchOptions(),
-      env: { ...process.env, ...CAPTURE_LAUNCH_DBUS_ENV },
-    }),
-  install = () => execSync(PLAYWRIGHT_INSTALL_COMMAND, { stdio: "inherit" }),
-  stderr = process.stderr,
-  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-  env = process.env,
-  platform = process.platform,
-} = {}) {
-  try {
-    return await launch();
-  } catch (error) {
-    if (isMissingSystemLibrary(error)) {
-      throw missingSystemLibraryError(error, { env, platform });
-    }
-    const isMissingBrowser =
-      error &&
-      typeof error.message === "string" &&
-      error.message.includes(PLAYWRIGHT_MISSING_BROWSER_PATTERN);
-    const isTransientCrash = isTransientLaunchCrash(error);
-    if (!isMissingBrowser && !isTransientCrash) throw error;
-
-    if (isTransientCrash) {
-      for (let attempt = 1; attempt <= CAPTURE_LAUNCH_SIGSEGV_RETRIES; attempt++) {
-        stderr.write(
-          `Chromium crashed at launch (transient, likely a dbus-less environment) — retry ${attempt}/${CAPTURE_LAUNCH_SIGSEGV_RETRIES}.\n`,
-        );
-        await sleep(CAPTURE_LAUNCH_SIGSEGV_BACKOFF_MS);
-        try {
-          return await launch();
-        } catch (retryError) {
-          if (!isTransientLaunchCrash(retryError)) throw retryError;
-        }
-      }
-      throw error;
-    }
-
-    stderr.write(
-      "Playwright's Chromium browser is missing — installing it now (one-time ~150 MB download). Subsequent runs will be instant.\n",
-    );
-    try {
-      install();
-    } catch (_installError) {
-      throw error;
-    }
-    try {
-      return await launch();
-    } catch (retryError) {
-      // A fresh download onto a host without Chromium's system libraries
-      // (the common first-capture shape on Replit) fails HERE, and the
-      // original "missing browser" error would now be a lie.
-      if (isMissingSystemLibrary(retryError)) {
-        throw missingSystemLibraryError(retryError, { env, platform });
-      }
-      throw error;
-    }
-  }
-}
-
 const {
   findScenarioError,
   SCENARIO_ERROR_MARKER,
@@ -378,6 +56,8 @@ const {
   createIssue,
   pushIssue,
   buildResult,
+  RELOADED_AFTER_READY,
+  retryOnLiveReload,
 } = require("./scenario-issues");
 
 const {
@@ -394,6 +74,7 @@ const {
   resolveHarnessOrigin,
   waitForStablePage,
   waitForReadySignal,
+  watchNavigationAfterReady,
   createNetworkTracker,
   waitForNetworkQuiet,
   collectContentState,
@@ -402,7 +83,6 @@ const {
   forceFinalVisualState,
   centerCaptureWrapper,
   isCanvasInteraction,
-  devicePixelRatioOf,
   resolveInteractionTarget,
   performInteraction,
   pixelSnapshot,
@@ -412,6 +92,7 @@ const {
   performInteractionSequence,
   logCaptureTiming,
 } = require("./scenario-playwright");
+const { devicePixelRatioOf } = require("./scenario-targeting");
 
 // 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
@@ -2046,6 +1727,48 @@ async function closeBrowserBounded(browser, boundMs = 5000) {
   return outcome;
 }
 
+// A flow's `navigate` step: load `stepPath` (resolved relative to the flow's
+// initial url) with the same loader strategy as the initial load, re-settle,
+// and re-wait for hydration. Returns the new content frame and its hydration
+// verdict, which later steps target and classify against.
+async function navigateFlowStep(page, stepPath, ctx) {
+  const { url, navigation, preflight, iframeBackground, harnessOrigin } = ctx;
+  const target = new URL(stepPath, url).href;
+  const loadResult =
+    navigation === "topLevel"
+      ? await loadScenarioTopLevel(page, target, { preflight })
+      : await loadScenarioInIframe(page, target, {
+          background: iframeBackground,
+          preflight,
+          harnessOrigin,
+        });
+  const frame = loadResult.frame;
+  await waitForStablePage(page, frame, ctx.settleMs, ctx.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.
+  const navHydration = await waitForHydration(frame, {
+    // `target` is only where we aimed; the frame's own URL is where we
+    // landed, so a redirect during the step is followed. Falls back to
+    // `target` when a detached frame cannot answer.
+    url: safeFrameUrl(frame) || target,
+    timeoutMs: ctx.hydrationTimeoutMs,
+    probeCounterpart: ctx.probeCounterpart,
+  });
+  // The mount that breaks a top-level load breaks it here too, and
+  // before this a route that died one navigation deep got no
+  // attribution at all. Report it so the editor can escalate the
+  // preview off the subpath for the rest of the session.
+  //
+  // The returned issue is deliberately NOT pushed: this wait exists to
+  // gate the next interaction, and adding an issue here would give a
+  // flow that passes today a new way to fail. Computing a verdict and
+  // not raising it reads as a bug otherwise — it is the point.
+  await escalateSubpathHydration(navHydration);
+  return { frame, hydrated: navHydration.hydrated };
+}
+
 // Drive an ordered list of flow steps against ONE already-loaded browser
 // session so a scripted multi-step demo (`editor preview-flow`) is captured as
 // the real round-trip — click state and client transients persist across
@@ -2066,15 +1789,9 @@ async function closeBrowserBounded(browser, boundMs = 5000) {
 // result URL reflect the last navigated route.
 async function runFlowSteps(page, initialFrame, steps, ctx) {
   const {
-    url,
     loadingMarkers,
-    navigation,
-    iframeBackground,
-    preflight,
-    harnessOrigin,
     hydrationTimeoutMs = 10000,
     settleMs,
-    probeCounterpart,
     stepEffects,
     downloads,
     downloadDir,
@@ -2111,43 +1828,13 @@ async function runFlowSteps(page, initialFrame, steps, ctx) {
     logCaptureTiming("flow-step", { step: n, action: step.action, outcome: "started" });
     try {
       switch (step.action) {
-        case "navigate": {
-          const target = new URL(step.path, url).href;
-          const loadResult =
-            navigation === "topLevel"
-              ? await loadScenarioTopLevel(page, target, { preflight })
-              : await loadScenarioInIframe(page, target, {
-                  background: iframeBackground,
-                  preflight,
-                  harnessOrigin,
-                });
-          frame = loadResult.frame;
-          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.
-          const navHydration = await waitForHydration(frame, {
-            // `target` is only where we aimed; the frame's own URL is where we
-            // landed, so a redirect during the step is followed. Falls back to
-            // `target` when a detached frame cannot answer.
-            url: safeFrameUrl(frame) || target,
-            timeoutMs: hydrationTimeoutMs,
-            probeCounterpart,
-          });
-          // The mount that breaks a top-level load breaks it here too, and
-          // before this a route that died one navigation deep got no
-          // attribution at all. Report it so the editor can escalate the
-          // preview off the subpath for the rest of the session.
-          //
-          // The returned issue is deliberately NOT pushed: this wait exists to
-          // gate the next interaction, and adding an issue here would give a
-          // flow that passes today a new way to fail. Computing a verdict and
-          // not raising it reads as a bug otherwise — it is the point.
-          await escalateSubpathHydration(navHydration);
-          hydrated = navHydration.hydrated;
+        case "navigate":
+          ({ frame, hydrated } = await navigateFlowStep(page, step.path, {
+            ...ctx,
+            settleMs: navigateSettleMs,
+            hydrationTimeoutMs,
+          }));
           break;
-        }
         case "click":
         case "fill":
         case "press":
@@ -2244,6 +1931,14 @@ async function runFlowSteps(page, initialFrame, steps, ctx) {
   return frame;
 }
 
+// One capture, retried once if a dev server's live reload interrupted it (see
+// `retryOnLiveReload`).
+async function runScenarioCheck(config, options = {}) {
+  return retryOnLiveReload(() => runScenarioCheckOnce(config, options), {
+    onRetry: (firstError) => logCaptureTiming("live-reload-retry", { firstError }),
+  });
+}
+
 // `preflight` is injectable (defaulting to the real app-port reachability
 // check) so unit tests that mock the browser can stay network-free.
 // `harnessOrigin` is likewise injectable: it defaults to resolving the editor's
@@ -2251,7 +1946,7 @@ async function runFlowSteps(page, initialFrame, steps, ctx) {
 // explicit value (e.g. `null` to force the legacy `setContent` harness) so the
 // iframe-load path never silently depends on a server-state file in cwd.
 // Resolved ONCE here and threaded into every iframe load below.
-async function runScenarioCheck(
+async function runScenarioCheckOnce(
   config,
   { preflight = assertAppPortReachable, harnessOrigin } = {},
 ) {
@@ -2603,6 +2298,9 @@ async function runScenarioCheck(
     if (!readyOutcome.ready) {
       pushIssue(issues, readySignalTimeoutIssue(readiness, page.url() || url));
     }
+    // Checked before the screenshot below; a declared interaction may navigate
+    // on purpose, so it is only acted on for a static capture.
+    const reloadWatch = watchNavigationAfterReady(page, frame);
     // Held here — after stability, before the content/hydration assertions and
     // the screenshot — so every downstream check sees the same frame the
     // scenario asked for rather than an earlier one.
@@ -2898,6 +2596,9 @@ async function runScenarioCheck(
       !!config.interaction ||
       (Array.isArray(config.interactions) && config.interactions.length > 0) ||
       (Array.isArray(config.steps) && config.steps.length > 0);
+    if (reloadWatch.navigated() && !hasDeclaredInteractiveState) {
+      throw new Error(RELOADED_AFTER_READY);
+    }
     if (outputPath && loaded && !hasDeclaredInteractiveState) {
       await forceFinalVisualState(frame).catch(() => {});
     }
@@ -3126,17 +2827,6 @@ module.exports = {
   DEV_SERVER_DOWN_HEADER,
   stripMarkerHeaders,
   main,
-  launchChromiumWithSelfHeal,
-  isTransientLaunchCrash,
-  isMissingSystemLibrary,
-  missingLibraryNames,
-  missingLibraryRemedy,
-  CAPTURE_BROWSER_DEPS_MISSING_MARKER,
-  CAPTURE_LAUNCH_ARGS,
-  CAPTURE_DISABLED_FEATURES,
-  captureLaunchOptions,
-  mergeDisableFeaturesArg,
-  playwrightDefaultDisableFeaturesArg,
   DEFAULT_READY_TIMEOUT_MS,
   resolveReadySignal,
   readStackReadySignal,
@@ -3149,11 +2839,6 @@ module.exports = {
   readySignalTimeoutIssue,
   canvasBlankIssue,
   decodeScreenshotPng,
-  CAPTURE_HOST_RESOLVER_RULES,
-  CAPTURE_LAUNCH_SIGSEGV_RETRIES,
-  PLAYWRIGHT_INSTALL_COMMAND,
-  PLAYWRIGHT_MISSING_BROWSER_PATTERN,
-  PLAYWRIGHT_LAUNCH_CRASH_PATTERNS,
 };
 
 if (require.main === module) {

package/npm/scenario-issues.js

@@ -111,9 +111,56 @@ function buildResult({
   };
 }
 
+// The message a capture fails with when the scenario frame navigated after its
+// ready signal arrived — a dev server's live reload swapping the page under the
+// shot.
+const RELOADED_AFTER_READY =
+  "The scenario page navigated after it signalled ready (a dev-server live reload)";
+
+// Failure messages that mean the page was reloaded mid-capture rather than that
+// the app is broken: Playwright's destroyed-context and detached-frame errors,
+// and the marker above. Any dev server with live reload (Vite full reload,
+// trunk, Flutter) produces them, so the match names no stack.
+const LIVE_RELOAD_FAILURE_PATTERNS = [
+  /Execution context was destroyed/i,
+  /Frame was detached/i,
+  /navigated after it signalled ready/,
+];
+
+// The first issue of a failed capture whose message names a mid-capture
+// reload, or null. A capture that passed, or failed for any other reason, is
+// never a reload candidate.
+function liveReloadIssue(result) {
+  if (!result || result.ok) return null;
+  return (
+    (result.issues || []).find((issue) =>
+      LIVE_RELOAD_FAILURE_PATTERNS.some((re) => re.test(String(issue.message || ""))),
+    ) || null
+  );
+}
+
+// Run a capture `attempt`, and run it ONCE more when a dev server's live reload
+// interrupted it: the reload is a temporary condition, and the second attempt
+// waits for the ready signal on the reloaded page from scratch. The retry is
+// recorded on the returned result (`reloadRetry`) so it is visible rather than
+// silently absorbed, and a second failure is returned as-is, with its own
+// reason. `onRetry` is told the first failure before the retry starts.
+async function retryOnLiveReload(attempt, { onRetry = () => {} } = {}) {
+  const first = await attempt();
+  const reload = liveReloadIssue(first);
+  if (!reload) return first;
+  onRetry(reload.message);
+  const second = await attempt();
+  second.reloadRetry = { retried: true, firstError: reload.message };
+  return second;
+}
+
 module.exports = {
   createIssue,
   pushIssue,
   buildResult,
   deriveOriginSplit,
+  RELOADED_AFTER_READY,
+  liveReloadIssue,
+  retryOnLiveReload,
 };