@reshotdev/screenshot 0.0.1-beta.12 → 0.0.1-beta.13

package/src/lib/capture-script-runner.js

@@ -1,5 +1,36 @@
 // capture-script-runner.js - Run capture scripts with the new robust engine
 const { CaptureEngine, isAuthRedirectUrl } = require("./capture-engine");
+
+/**
+ * Capture a self-contained MHTML bundle of the page at the same moment as
+ * a screenshot. The bundle re-renders in any Chromium browser without
+ * network access and is the source of truth for variations — marketing
+ * can mutate the captured DOM (swap copy, hide chrome, recrop, rebrand)
+ * and render new outputs without re-running Playwright against the live
+ * app.
+ *
+ * Best-effort: failures are logged via `logger` but never bubble up.
+ * Returns `{ path, bytes }` on success, `null` otherwise.
+ *
+ * Opt out per-call via `enabled=false` (typically driven from scenario
+ * config). Defaults ON.
+ */
+async function captureDomScene(page, pngOutputPath, { enabled = true, logger = () => {} } = {}) {
+  if (!enabled) return null;
+  try {
+    const cdp = await page.context().newCDPSession(page);
+    const { data: mhtml } = await cdp.send("Page.captureSnapshot", {
+      format: "mhtml",
+    });
+    const mhtmlPath = pngOutputPath.replace(/\.png$/i, ".mhtml");
+    const fsmod = require("fs-extra");
+    await fsmod.writeFile(mhtmlPath, mhtml);
+    return { path: mhtmlPath, bytes: Buffer.byteLength(mhtml, "utf8") };
+  } catch (err) {
+    logger(`  ⚠ DOM scene capture skipped: ${err && err.message ? err.message : err}`);
+    return null;
+  }
+}
 const { buildLaunchOptions } = require("./ci-detect");
 const {
   resolveVariantConfig,
@@ -137,6 +168,83 @@ function debug(...args) {
   }
 }
 
+function normalizeVideoTargetName(selector) {
+  return String(selector || "")
+    .replace(/^\[data-testid=['"]?([^'"\]]+)['"]?\]$/, "$1")
+    .replace(/[^a-z0-9]+/gi, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+}
+
+function buildVideoMetadata(events, sentinels, viewport, frameRate) {
+  const targets = {};
+  const timeline = events.map((event, index) => {
+    const targetName = event.target ? normalizeVideoTargetName(event.target) : null;
+    if (targetName && event.elementBox) {
+      targets[targetName] = event.elementBox;
+    }
+    return {
+      type: event.action,
+      tMs: Math.round(event.timestamp * 1000),
+      label: event.subtitle || event.action,
+      target: targetName || undefined,
+      elementBox: event.elementBox || undefined,
+      index,
+    };
+  });
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    frameRate,
+    viewport,
+    timeline,
+    targets,
+    sentinels: sentinels.map((sentinel) => ({
+      index: sentinel.index,
+      label: sentinel.label,
+      filename: path.basename(sentinel.path),
+    })),
+  };
+}
+
+async function installVisibleCursor(page) {
+  await page.addInitScript(() => {
+    const install = () => {
+      if (document.querySelector("[data-reshot-cursor]")) return;
+      const cursor = document.createElement("div");
+      cursor.setAttribute("data-reshot-cursor", "true");
+      cursor.style.cssText = [
+        "position:fixed",
+        "left:0",
+        "top:0",
+        "width:18px",
+        "height:18px",
+        "z-index:2147483647",
+        "pointer-events:none",
+        "transform:translate(-100px,-100px)",
+        "filter:drop-shadow(0 2px 4px rgba(0,0,0,.35))",
+      ].join(";");
+      cursor.innerHTML = '<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true"><path d="M4 3.5 19.5 14l-7.2 1.1 4.2 5.3-2.7 2.1-4.1-5.3-3.2 6.8L4 3.5Z" fill="white" stroke="rgba(15,23,42,.9)" stroke-width="1.4"/></svg>';
+      document.documentElement.appendChild(cursor);
+      window.addEventListener("mousemove", (event) => {
+        cursor.style.transform = `translate(${event.clientX}px, ${event.clientY}px)`;
+      }, { passive: true });
+      window.addEventListener("mousedown", () => {
+        cursor.style.scale = "0.82";
+      }, { passive: true });
+      window.addEventListener("mouseup", () => {
+        cursor.style.scale = "1";
+      }, { passive: true });
+    };
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", install, { once: true });
+    } else {
+      install();
+    }
+  });
+}
+
 function normalizeVisibleText(value) {
   return String(value || "")
     .replace(/\s+/g, " ")
@@ -442,6 +550,28 @@ async function preflightAuthCheck(baseUrl, options = {}) {
       await engine.page.waitForTimeout(3000);
       await engine._waitForStability();
 
+      // Post-stability auth redirect check: catches SPA redirects that
+      // complete after JS has finished executing (client-side routing)
+      const postStabilityUrl = engine.page.url();
+      if (isAuthRedirectUrl(postStabilityUrl)) {
+        return {
+          ok: false,
+          message:
+            "Auth session expired (redirect detected after page load). Run `reshot record` to capture a fresh session.",
+        };
+      }
+      const hasLoginFormPostStability = await engine.page.evaluate(() => {
+        const h = document.querySelector("h1, h2");
+        return h && /sign\s*in|log\s*in/i.test(h.textContent);
+      }).catch(() => false);
+      if (hasLoginFormPostStability) {
+        return {
+          ok: false,
+          message:
+            "Auth session expired (login form detected after page load). Run `reshot record` to refresh.",
+        };
+      }
+
       // Check for error state
       const errorState = await engine._detectErrorState();
       if (errorState.hasError) {
@@ -965,7 +1095,18 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
   const sessionPath = getDefaultSessionPath();
   const hasSession = fs.existsSync(sessionPath);
   if (!quiet) {
+    let sessionIsEmpty = false;
     if (hasSession) {
+      try {
+        const sessionContents = JSON.parse(fs.readFileSync(sessionPath, "utf8"));
+        const noCookies = !Array.isArray(sessionContents.cookies) || sessionContents.cookies.length === 0;
+        const noOrigins = !Array.isArray(sessionContents.origins) || sessionContents.origins.length === 0;
+        sessionIsEmpty = noCookies && noOrigins;
+      } catch {
+        // Malformed JSON — fall through and treat as non-empty so the warning still fires.
+      }
+    }
+    if (hasSession && !sessionIsEmpty) {
       // Validate session freshness with graduated warnings
       const sessionStats = fs.statSync(sessionPath);
       const sessionAgeHours =
@@ -1230,9 +1371,18 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
       await fs.writeFile(filePath, buffer);
       lastScreenshotHash = currentHash;
 
+      // Capture sidecar MHTML so variations can be rendered from the
+      // captured DOM (one CDP call; failures are non-fatal).
+      const domScene = await captureDomScene(engine.page, filePath, {
+        enabled: scenario.domScene !== false && options.domScene !== false,
+        logger: quiet ? () => {} : (msg) => console.log(chalk.gray(msg)),
+      });
+
       const asset = {
         name,
         path: filePath,
+        domScenePath: domScene ? domScene.path : null,
+        domSceneBytes: domScene ? domScene.bytes : null,
         description,
         captureIndex,
         type,
@@ -1391,6 +1541,13 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
 
           if (!elementExists) {
             skippedSteps++;
+            if (!quiet) {
+              console.log(
+                chalk.dim(
+                  `   → ${action}(selector=${JSON.stringify(target)}) matched 0 elements (optional, skipped)`
+                )
+              );
+            }
             continue;
           }
 
@@ -1665,7 +1822,7 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
 }
 
 /**
- * Capture screenshot with highlight box around element
+ * Capture screenshot without interaction overlays.
  */
 async function captureWithHighlight(
   engine,
@@ -1673,63 +1830,12 @@ async function captureWithHighlight(
   outputPath,
   highlight = {}
 ) {
-  const { color = "rgba(255, 255, 0, 0.5)", style = "box" } = highlight;
-
-  // Try to find the element
-  const element = await engine._findElement(target, {
-    mustBeVisible: false,
-    timeout: 2000,
-  });
-  const box = await element.boundingBox();
-
-  if (box) {
-    // Inject highlight overlay
-    await engine.page.evaluate(
-      ({ box, color, style }) => {
-        const existingHighlight = document.getElementById("reshot-highlight");
-        if (existingHighlight) existingHighlight.remove();
-
-        const div = document.createElement("div");
-        div.id = "reshot-highlight";
-        div.style.cssText = `
-        position: fixed;
-        left: ${box.x}px;
-        top: ${box.y}px;
-        width: ${box.width}px;
-        height: ${box.height}px;
-        background: ${style === "box" ? color : "transparent"};
-        border: ${
-          style === "outline"
-            ? `3px solid ${color.replace("0.5", "1")}`
-            : "none"
-        };
-        pointer-events: none;
-        z-index: 999999;
-        box-sizing: border-box;
-        border-radius: 4px;
-      `;
-        document.body.appendChild(div);
-      },
-      { box, color, style }
-    );
-
-    // Wait for highlight to render
-    await engine.page.waitForTimeout(50);
-  }
-
-  // Capture screenshot
   await engine.page.screenshot({ path: outputPath });
-
-  // Remove highlight overlay
-  await engine.page.evaluate(() => {
-    const highlight = document.getElementById("reshot-highlight");
-    if (highlight) highlight.remove();
-  });
 }
 
 /**
  * Run a scenario with video capture (summary-video format)
- * Records the entire flow as a single video with optional highlights and subtitles
+ * Records the entire flow as a single video without interaction overlays
  * Supports graceful handling of permission-restricted steps
  * Supports cropping for sentinel frames (same config as step-by-step-images)
  */
@@ -1740,21 +1846,36 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
     headless = true,
     viewport = { width: 1280, height: 720 },
     variantsConfig = {}, // Global variant configuration (new format with dimensions)
+    globalQuality = null,
   } = options;
 
   const outputConfig = scenario.output || { format: "summary-video" };
-  const highlight = outputConfig.highlight || {
-    color: "rgba(255, 255, 0, 0.5)",
-    style: "box",
-  };
   const subtitles = outputConfig.subtitles || { enabled: false };
+  const videoFrameRate = Number(outputConfig.frameRate || 24);
+  const typeDelayMs = Number(outputConfig.typeDelayMs || 20);
 
   // Extract crop configuration from scenario output settings
   // This persists across all variations and applies to sentinel frames
   const scenarioCropConfig = outputConfig.crop || null;
+  const scenarioCaptureConfig = getCaptureConfig({
+    retryOnError: scenario.retryOnError,
+    readyTimeout: scenario.readyTimeout,
+    scenarioTimeout: scenario.scenarioTimeout,
+    errorSelectors: scenario.errorSelectors,
+  });
+  const forbidText = collectForbiddenText(globalQuality, scenario);
 
   // Resolve variant configuration using new universal variant system
   const variantConfig = resolveVariantConfig(scenario, variantsConfig);
+  let readySelector = scenario.readySelector || null;
+  if (!readySelector && scenario.steps) {
+    const firstWaitFor = scenario.steps.find(
+      (s) => s.action === "waitForSelector"
+    );
+    if (firstWaitFor) {
+      readySelector = firstWaitFor.selector;
+    }
+  }
 
   // Resolve privacy configuration for video (CSS masking persists through entire video)
   const videoPrivacyConfig = config.getPrivacyConfig(scenario.privacy);
@@ -1906,6 +2027,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
     debug("Browser context created");
     page = await context.newPage();
     debug("Page created");
+    await installVisibleCursor(page);
 
     // CRITICAL: Hide development overlays (Next.js devtools, Vercel toolbar, etc.)
     // This prevents dev tools from intercepting clicks during video capture
@@ -2025,10 +2147,11 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
             storeState.activeWorkspace = { id: ws.id, name: ws.name, slug: ws.slug };
           }
 
+          const storePrefixes = ["reshot-store-", "workspace-store-"];
           let found = false;
           for (let i = 0; i < localStorage.length; i++) {
             const key = localStorage.key(i);
-            if (key && key.startsWith("workspace-store-")) {
+            if (key && storePrefixes.some((prefix) => key.startsWith(prefix))) {
               try {
                 const data = JSON.parse(localStorage.getItem(key) || "{}");
                 data.state = { ...data.state, ...storeState };
@@ -2040,7 +2163,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           }
           if (!found) {
             localStorage.setItem(
-              "workspace-store-1",
+              "reshot-store-workspace",
               JSON.stringify({ state: storeState, version: 0 })
             );
           }
@@ -2064,6 +2187,14 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
     let sentinelIndex = 0;
     let hasAppliedStorageReload = false; // Track if we've reloaded for localStorage
 
+    async function moveMouseToBox(box) {
+      if (!box) return;
+      const x = Math.round(box.x + box.width / 2);
+      const y = Math.round(box.y + box.height / 2);
+      await page.mouse.move(x, y, { steps: 18 });
+      await page.waitForTimeout(120);
+    }
+
     /**
      * Capture a sentinel frame (full page screenshot)
      * Applies scenario-level cropping if configured
@@ -2204,14 +2335,61 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
         } catch (e) {
           // Okay if timeout
         }
-        await page.waitForTimeout(800); // Extra time for i18n/translations to render
+        await page.waitForTimeout(300); // Extra time for i18n/translations to render
+        await waitForLoadingComplete(page, 5000);
+
+        if (readySelector) {
+          let readyError = null;
+          const maxAttempts = 1 + scenarioCaptureConfig.retryOnError;
+
+          for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+              await page.locator(readySelector).first().waitFor({
+                state: "visible",
+                timeout: scenarioCaptureConfig.readyTimeout,
+              });
+              readyError = null;
+              break;
+            } catch (error) {
+              readyError = error;
+              if (attempt === maxAttempts) {
+                break;
+              }
+
+              const delay =
+                scenarioCaptureConfig.retryDelay * Math.pow(2, attempt - 1);
+              console.log(
+                chalk.yellow(
+                  `  ⚠ Attempt ${attempt}/${maxAttempts} failed (ready selector timeout). Retrying in ${delay}ms...`
+                )
+              );
+              await page.waitForTimeout(delay);
+              await page.reload({ waitUntil: "domcontentloaded" });
+              await page.waitForTimeout(300);
+              await waitForLoadingComplete(page, 5000);
+            }
+          }
+
+          if (readyError) {
+            const currentUrl = page.url();
+            throw new Error(
+              `Scenario readySelector "${readySelector}" not found in video capture mode at ${currentUrl}. ${
+                readyError instanceof Error ? readyError.message : String(readyError)
+              }`
+            );
+          }
+        }
+
+        await assertForbiddenTextAbsent(page, forbidText);
 
         // Re-inject workspace store after navigation to handle Zustand hydration resets
         if (_activeProjectId) {
           await page.evaluate(({ pid, ws }) => {
+            const storePrefixes = ["reshot-store-", "workspace-store-"];
+            let foundKey = null;
             for (let i = 0; i < localStorage.length; i++) {
               const key = localStorage.key(i);
-              if (key && key.startsWith("workspace-store-")) {
+              if (key && storePrefixes.some((prefix) => key.startsWith(prefix))) {
                 try {
                   const data = JSON.parse(localStorage.getItem(key) || "{}");
                   if (data.state) {
@@ -2219,11 +2397,12 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
                     if (ws) data.state.activeWorkspace = data.state.activeWorkspace || { id: ws.id, name: ws.name, slug: ws.slug };
                     data.version = data.version ?? 0;
                     localStorage.setItem(key, JSON.stringify(data));
+                    foundKey = key;
                   }
                 } catch (e) {}
               }
             }
-            window.dispatchEvent(new StorageEvent("storage", { key: null }));
+            window.dispatchEvent(new StorageEvent("storage", { key: foundKey || "reshot-store-workspace" }));
           }, { pid: _activeProjectId, ws: _activeWorkspace });
         }
 
@@ -2272,43 +2451,13 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           await element.waitFor({ state: "visible", timeout: clickTimeout });
           const box = await element.boundingBox();
 
-          // Add highlight before click
-          if (box) {
-            await page.evaluate(
-              ({ box, color }) => {
-                const div = document.createElement("div");
-                div.id = "reshot-video-highlight";
-                div.style.cssText = `
-                position: fixed;
-                left: ${box.x}px;
-                top: ${box.y}px;
-                width: ${box.width}px;
-                height: ${box.height}px;
-                background: ${color};
-                pointer-events: none;
-                z-index: 999999;
-                border-radius: 4px;
-                transition: opacity 0.3s;
-              `;
-                document.body.appendChild(div);
-              },
-              { box, color: highlight.color }
-            );
-
-            await page.waitForTimeout(300);
-          }
-
+          await moveMouseToBox(box);
           await element.click();
 
-          // Remove highlight after click
-          await page.evaluate(() => {
-            const h = document.getElementById("reshot-video-highlight");
-            if (h) h.remove();
-          });
-
           events.push({
             action: "click",
             timestamp,
+            target,
             subtitle: subtitles.enabled ? `Click on ${target}` : "",
             elementBox: box,
           });
@@ -2318,6 +2467,11 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           // Capture sentinel after click
           await captureSentinel(`after-click-${stepIndex}`);
         } catch (e) {
+          if (!isOptional) {
+            throw new Error(
+              `Required click target not found: ${target}. ${e instanceof Error ? e.message : String(e)}`
+            );
+          }
           console.warn(
             chalk.yellow(`    ⚠ Could not click ${target}: ${e.message}`)
           );
@@ -2341,41 +2495,14 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           await element.waitFor({ state: "visible", timeout: typeTimeout });
           const box = await element.boundingBox();
 
-          // Add highlight before typing
-          if (box) {
-            await page.evaluate(
-              ({ box, color }) => {
-                const div = document.createElement("div");
-                div.id = "reshot-video-highlight";
-                div.style.cssText = `
-                position: fixed;
-                left: ${box.x}px;
-                top: ${box.y}px;
-                width: ${box.width}px;
-                height: ${box.height}px;
-                background: ${color};
-                pointer-events: none;
-                z-index: 999999;
-                border-radius: 4px;
-              `;
-                document.body.appendChild(div);
-              },
-              { box, color: highlight.color }
-            );
-          }
-
+          await moveMouseToBox(box);
           await element.fill("");
-          await element.type(text, { delay: 50 }); // Visible typing effect
-
-          // Remove highlight
-          await page.evaluate(() => {
-            const h = document.getElementById("reshot-video-highlight");
-            if (h) h.remove();
-          });
+          await element.type(text, { delay: typeDelayMs }); // Visible typing effect
 
           events.push({
             action: "type",
             timestamp,
+            target,
             subtitle: subtitles.enabled ? `Entering "${text}"` : "",
             elementBox: box,
           });
@@ -2385,6 +2512,11 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           // Capture sentinel after type
           await captureSentinel(`after-type-${stepIndex}`);
         } catch (e) {
+          if (!isOptional) {
+            throw new Error(
+              `Required input target not found: ${target}. ${e instanceof Error ? e.message : String(e)}`
+            );
+          }
           console.warn(
             chalk.yellow(`    ⚠ Could not type into ${target}: ${e.message}`)
           );
@@ -2408,15 +2540,8 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
         } catch (e) {
           if (!isOptional) {
             const currentUrl = page.url();
-            console.warn(
-              chalk.yellow(`    ⚠ Element not found: ${params.target}`)
-            );
-            console.warn(chalk.gray(`      URL: ${currentUrl}`));
-            console.warn(chalk.gray(`      Timeout: ${waitTimeout}ms`));
-            console.warn(
-              chalk.gray(
-                `      Hint: Verify the selector exists on the page. Run 'reshot record' to inspect.`
-              )
+            throw new Error(
+              `Required selector not found in video capture: ${params.target} (URL: ${currentUrl}, timeout: ${waitTimeout}ms)`
             );
           }
         }
@@ -2434,11 +2559,18 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
         try {
           const element = await page.locator(params.target).first();
           await element.waitFor({ state: "visible", timeout: hoverTimeout });
+          const box = await element.boundingBox();
+          await moveMouseToBox(box);
           await element.hover();
           await page.waitForTimeout(300);
           // Capture sentinel after hover (state may have changed with tooltips/dropdowns)
           await captureSentinel(`after-hover-${stepIndex}`);
         } catch (e) {
+          if (!isOptional) {
+            throw new Error(
+              `Required hover target not found: ${params.target}. ${e instanceof Error ? e.message : String(e)}`
+            );
+          }
           console.warn(
             chalk.yellow(`    ⚠ Could not hover ${params.target}: ${e.message}`)
           );
@@ -2530,7 +2662,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
     // Convert to MP4 with ffmpeg, trimming blank loading frames from start
     // and excess frames from end
     const startOffset = Math.max(0, (firstSentinelTimestamp || 0) - 0.3);
-    const endTimestamp = finalTimestamp + 0.5;
+    const endTimestamp = finalTimestamp + 0.25;
     const contentDuration = endTimestamp - startOffset;
     if (startOffset > 0) {
       console.log(
@@ -2559,6 +2691,8 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
       "fast",
       "-pix_fmt",
       "yuv420p",
+      "-r",
+      String(videoFrameRate),
       "-movflags",
       "+faststart",
       "-y",
@@ -2601,6 +2735,14 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
     );
     debug(`Sentinel manifest saved to: ${sentinelManifestPath}`);
 
+    const metadataPath = path.join(actualOutputDir, "summary-video.metadata.json");
+    fs.writeJSONSync(
+      metadataPath,
+      buildVideoMetadata(events, sentinelPaths, viewport, videoFrameRate),
+      { spaces: 2 },
+    );
+    debug(`Video metadata saved to: ${metadataPath}`);
+
     // Cleanup temp directory (unique per recording)
     try {
       fs.removeSync(tempDir);
@@ -2618,6 +2760,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           path: finalVideoPath,
           type: "video",
           duration: (Date.now() - startTime) / 1000,
+          metadataPath,
         },
       ],
       sentinels: sentinelPaths.map((s) => ({
@@ -3398,6 +3541,7 @@ module.exports = {
   runScenarioWithEngine,
   runScenarioWithStepByStepCapture,
   runScenarioWithVideoCapture,
+  buildVideoMetadata,
   captureWithHighlight,
   checkFFmpeg,
   runAllScenarios,
@@ -3418,4 +3562,6 @@ module.exports = {
   generateVersionTimestamp,
   // Concurrency
   detectOptimalConcurrency,
+  installVisibleCursor,
+  normalizeVideoTargetName,
 };

package/src/lib/certification.js

@@ -372,7 +372,12 @@ async function runDoctorTarget(options = {}) {
   const docSyncConfig = config.readConfig();
   const target = docSyncConfig.target;
   const scenarios = getSelectedScenarios(docSyncConfig, options.scenarioKeys);
-  const timeoutMs = options.timeoutMs || 30_000;
+  const timeoutMs = options.timeoutMs || 15_000;
+  // Overall budget so the command fails fast instead of grinding through every
+  // scenario at the full per-step timeout (which read as an indefinite hang).
+  const overallTimeoutMs = options.overallTimeoutMs || Math.max(timeoutMs * 4, 60_000);
+  const startedAt = Date.now();
+  const overBudget = () => Date.now() - startedAt > overallTimeoutMs;
   const onProgress =
     typeof options.onProgress === "function" ? options.onProgress : null;
 
@@ -402,7 +407,23 @@ async function runDoctorTarget(options = {}) {
   const advisories = [];
   const info = [];
 
+  let budgetExceeded = false;
   for (const scenario of scenarios) {
+    if (overBudget()) {
+      budgetExceeded = true;
+      onProgress?.(
+        `Overall doctor budget (${overallTimeoutMs}ms) exceeded — stopping before "${scenario.key}".`,
+      );
+      blockingIssues.push(
+        createIssue(
+          "blocking",
+          "doctor_timeout",
+          `Target doctor exceeded its overall time budget of ${overallTimeoutMs}ms. Remaining scenarios were not audited.`,
+          { auditedScenarios: readinessAudits.length, totalScenarios: scenarios.length },
+        ),
+      );
+      break;
+    }
     onProgress?.(`Auditing routes for ${scenario.key}...`);
     const routeResults = [];
     for (const route of scenario.requiredRoutes || []) {
@@ -544,6 +565,7 @@ async function runDoctorTarget(options = {}) {
   }
 
   const ok =
+    !budgetExceeded &&
     requiredEnv.every((item) => item.present) &&
     (fixture.skipped || fixture.ok) &&
     captureSafe.ok &&