@reshotdev/screenshot 0.0.1-beta.2 → 0.0.1-beta.21

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,
@@ -30,6 +61,8 @@ const {
   getDefaultSessionPath,
   autoSyncSessionFromCDP,
   sanitizeStorageState,
+  assessSessionHealth,
+  writeSessionArtifacts,
 } = require("./record-cdp");
 const config = require("./config");
 const {
@@ -135,6 +168,178 @@ 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, " ")
+    .trim()
+    .toLowerCase();
+}
+
+function collectForbiddenText(globalQuality = null, scenario = {}) {
+  const merged = [
+    ...(globalQuality?.forbidText || []),
+    ...(scenario.quality?.forbidText || []),
+  ]
+    .map((value) => String(value || "").trim())
+    .filter(Boolean);
+
+  return [
+    ...new Map(
+      merged.map((value) => [normalizeVisibleText(value), value]),
+    ).values(),
+  ];
+}
+
+async function assertForbiddenTextAbsent(page, forbidText = []) {
+  if (!Array.isArray(forbidText) || forbidText.length === 0) {
+    return null;
+  }
+
+  const visibleText = normalizeVisibleText(
+    await page.evaluate(() => {
+      const isElementVisibleInViewport = (element) => {
+        if (!(element instanceof Element)) {
+          return false;
+        }
+
+        const style = window.getComputedStyle(element);
+        if (
+          style.display === "none" ||
+          style.visibility === "hidden" ||
+          Number(style.opacity || "1") === 0
+        ) {
+          return false;
+        }
+
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) {
+          return false;
+        }
+
+        return (
+          rect.bottom > 0 &&
+          rect.right > 0 &&
+          rect.top < window.innerHeight &&
+          rect.left < window.innerWidth
+        );
+      };
+
+      const walker = document.createTreeWalker(
+        document.body,
+        NodeFilter.SHOW_TEXT,
+        {
+          acceptNode(node) {
+            const text = node.textContent?.replace(/\s+/g, " ").trim();
+            if (!text) {
+              return NodeFilter.FILTER_REJECT;
+            }
+
+            const parent = node.parentElement;
+            if (!parent || !isElementVisibleInViewport(parent)) {
+              return NodeFilter.FILTER_REJECT;
+            }
+
+            return NodeFilter.FILTER_ACCEPT;
+          },
+        },
+      );
+
+      const textParts = [];
+      while (walker.nextNode()) {
+        textParts.push(walker.currentNode.textContent || "");
+      }
+
+      return textParts.join(" ");
+    }),
+  );
+  const matched = forbidText.find((candidate) =>
+    visibleText.includes(normalizeVisibleText(candidate)),
+  );
+
+  if (!matched) {
+    return null;
+  }
+
+  throw new Error(`Forbidden visible text detected during capture: "${matched}"`);
+}
+
 /**
  * Execute a page load with retry logic on error/timeout
  * Uses the capture engine's error detection to identify failures and retry
@@ -251,13 +456,42 @@ async function executeWithRetry(engine, readySelector, options = {}) {
  * @returns {Promise<{ok: boolean, message?: string}>}
  */
 async function preflightAuthCheck(baseUrl, options = {}) {
-  const { storageStatePath, viewport = { width: 1280, height: 720 } } = options;
+  const {
+    storageStatePath,
+    viewport = { width: 1280, height: 720 },
+    authCheckUrl = "/app/projects",
+  } = options;
 
   if (!storageStatePath || !fs.existsSync(storageStatePath)) {
     return { ok: true }; // No session to verify
   }
 
+  const sessionHealth = assessSessionHealth(storageStatePath, baseUrl);
+  if (!sessionHealth.compatible) {
+    const mismatchSummary =
+      sessionHealth.evidence.sourceOrigin ||
+      sessionHealth.evidence.storageOrigins[0] ||
+      sessionHealth.evidence.cookieDomains[0] ||
+      "another environment";
+    return {
+      ok: false,
+      message:
+        `Cached auth session does not match this environment (${mismatchSummary} -> ${sessionHealth.expectedOrigin || baseUrl}). ` +
+        "Run `reshot record` against this target to capture a fresh session.",
+    };
+  }
+
   console.log(chalk.gray("  → Running auth pre-flight check..."));
+  if (sessionHealth.stale) {
+    console.log(
+      chalk.yellow(
+        `  ⚠ Cached auth session is ${sessionHealth.ageMinutes}m old; verifying it before capture...`,
+      ),
+    );
+  }
+  for (const warning of sessionHealth.warnings) {
+    console.log(chalk.gray(`    ${warning}`));
+  }
 
   const engine = new CaptureEngine({
     baseUrl,
@@ -272,38 +506,97 @@ async function preflightAuthCheck(baseUrl, options = {}) {
   try {
     await engine.init();
 
-    // Navigate to projects page (a page that requires auth + data)
-    await engine.page.goto(`${baseUrl}/app/projects`, {
-      waitUntil: "domcontentloaded",
-      timeout: 15000,
-    });
+    const authCheckTargets = Array.isArray(authCheckUrl)
+      ? authCheckUrl
+      : [authCheckUrl];
 
-    // Check for auth redirect using shared utility
-    const currentUrl = engine.page.url();
-    const isAuthRedirect = isAuthRedirectUrl(currentUrl);
+    for (const authTarget of authCheckTargets) {
+      const preflightPath = authTarget.startsWith("http")
+        ? authTarget
+        : `${baseUrl}${authTarget}`;
 
-    if (isAuthRedirect) {
-      return {
-        ok: false,
-        message:
-          "Auth session expired. Run `reshot record` to capture a fresh session.",
-      };
-    }
+      // Navigate to a known authenticated page and validate session/data loading.
+      await engine.page.goto(preflightPath, {
+        waitUntil: "domcontentloaded",
+        timeout: 15000,
+      });
 
-    // Wait for data to settle
-    await engine.page.waitForTimeout(3000);
-    await engine._waitForStability();
+      // Check for auth redirect using shared utility
+      const currentUrl = engine.page.url();
+      const isAuthRedirect = isAuthRedirectUrl(currentUrl);
 
-    // Check for error state
-    const errorState = await engine._detectErrorState();
-    if (errorState.hasError) {
-      return {
-        ok: false,
-        message: `Auth session appears valid but data fetching failed (${errorState.errorType}). This usually means your JWT has expired. Run \`reshot record\` to refresh.`,
-      };
+      if (isAuthRedirect) {
+        return {
+          ok: false,
+          message:
+            "Auth session expired. Run `reshot record` to capture a fresh session.",
+        };
+      }
+
+      // Also detect login page via DOM (catches SPA redirects where URL hasn't changed)
+      const hasLoginForm = 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 (hasLoginForm) {
+        return {
+          ok: false,
+          message:
+            "Auth session expired (login form detected). Run `reshot record` to refresh.",
+        };
+      }
+
+      // Wait for data to settle
+      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) {
+        return {
+          ok: false,
+          message: `Auth session appears valid but data fetching failed (${errorState.errorType}). This usually means your JWT has expired. Run \`reshot record\` to refresh.`,
+        };
+      }
     }
 
-    console.log(chalk.green("  ✔ Auth pre-flight check passed"));
+    // Save refreshed session back so scenarios use fresh cookies
+    if (storageStatePath && engine.context) {
+      try {
+        const refreshedState = await engine.context.storageState();
+        writeSessionArtifacts(storageStatePath, refreshedState, {
+          baseUrl,
+          pageUrl: engine.page?.url?.() || baseUrl,
+        });
+        console.log(chalk.green("  ✔ Auth pre-flight check passed (session refreshed)"));
+      } catch (_saveErr) {
+        console.log(chalk.green("  ✔ Auth pre-flight check passed"));
+      }
+    } else {
+      console.log(chalk.green("  ✔ Auth pre-flight check passed"));
+    }
     return { ok: true };
   } catch (e) {
     // If the error is an auth redirect thrown by the engine, handle gracefully
@@ -407,6 +700,14 @@ async function retryInteractiveStep(engine, action, params, context) {
   }
 }
 
+function promoteLastGotoUrl(lastGotoUrl, currentUrl) {
+  if (!currentUrl || currentUrl === "about:blank") {
+    return lastGotoUrl;
+  }
+
+  return currentUrl !== lastGotoUrl ? currentUrl : lastGotoUrl;
+}
+
 /**
  * Calculate a perceptual hash for an image buffer
  * This is a simple hash based on resizing the image to a small grid
@@ -768,6 +1069,7 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
     scenarioTimeout: scenario.scenarioTimeout,
     errorSelectors: scenario.errorSelectors,
   });
+  const forbidText = collectForbiddenText(options.globalQuality, scenario);
 
   // Extract readySelector: prefer scenario-level, fall back to first waitForSelector step
   let readySelector = scenario.readySelector || null;
@@ -793,8 +1095,21 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
   const sessionPath = getDefaultSessionPath();
   const hasSession = fs.existsSync(sessionPath);
   if (!quiet) {
+    let sessionIsEmpty = false;
     if (hasSession) {
-      // Validate session freshness with graduated warnings
+      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 && scenario.requiresAuth) {
+      // Validate session freshness with graduated warnings.
+      // Only relevant when this scenario actually requires auth — a leftover
+      // session file should not trigger staleness warnings for public scenarios.
       const sessionStats = fs.statSync(sessionPath);
       const sessionAgeHours =
         (Date.now() - sessionStats.mtimeMs) / (1000 * 60 * 60);
@@ -843,6 +1158,7 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
     waitForReady: scenario.waitForReady || null, // Custom loading-state hook
     privacyConfig: hasPrivacy ? scenarioPrivacyConfig : null, // Privacy masking
     styleConfig: hasStyle ? scenarioStyleConfig : null, // Image beautification
+    injectWorkspaceStore: scenario.needsWorkspaceInjection !== false,
     logger: quiet ? () => {} : (msg) => console.log(msg),
   });
 
@@ -946,6 +1262,7 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
       });
       // Brief wait for CSS to apply
       await engine.page.waitForTimeout(50);
+      await assertForbiddenTextAbsent(engine.page, forbidText);
 
       let buffer = await engine.page.screenshot();
 
@@ -1056,9 +1373,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,
@@ -1133,11 +1459,25 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
               `Page error detected: ${errMsg}. The page rendered an error UI instead of expected content.`
             );
           } else if (retryResult.status === "timeout") {
+            const currentUrl = engine.page.url();
             console.log(
               chalk.yellow(
-                `  ⚠ Ready selector not found after ${retryResult.attempts} attempt(s), proceeding with current state`
+                `  ⚠ Ready selector not found after ${retryResult.attempts} attempt(s): ${readySelector}`
               )
             );
+            console.log(
+              chalk.gray(`    URL: ${currentUrl}`)
+            );
+            console.log(
+              chalk.gray(
+                `    Hint: The page loaded but this selector does not exist. Check your readySelector in reshot.config.json.`
+              )
+            );
+            throw new Error(
+              `Scenario readySelector "${readySelector}" not found after ${retryResult.attempts} attempt(s). ` +
+              `The page loaded at ${currentUrl} but the selector does not exist. ` +
+              `Update readySelector in reshot.config.json or remove it to skip this check.`
+            );
           } else if (retryResult.attempts > 1) {
             console.log(
               chalk.green(
@@ -1203,6 +1543,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;
           }
 
@@ -1253,6 +1600,11 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
           }
         }
 
+        // Promote the current page URL after successful interactive steps so
+        // retries restore the page we actually navigated to, not the last
+        // explicit goto target.
+        lastGotoUrl = promoteLastGotoUrl(lastGotoUrl, engine.page.url());
+
         // Wait for animations/transitions - longer wait for multi-step flows
         const isMultiStep = script.length > 3;
         await engine.page.waitForTimeout(isMultiStep ? 500 : 150);
@@ -1296,6 +1648,12 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
                 `    Hint: If data isn't loading, run 'reshot record' to refresh your session`
               )
             );
+            failedSteps.push({
+              stepIndex: stepIndex + 1,
+              action: "waitFor",
+              target: params.target,
+              error: errMsg,
+            });
           }
         } else if (waitResult.status === "timeout") {
           if (!isOptional) {
@@ -1309,9 +1667,14 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
                 `    Hint: If content isn't loading, run 'reshot record' to refresh your session`
               )
             );
+            failedSteps.push({
+              stepIndex: stepIndex + 1,
+              action: "waitFor",
+              target: params.target,
+              error: `Element not found within ${waitTimeout}ms`,
+            });
           }
         }
-        // Continue with next steps - the scenario may still capture partial state
         continue;
       }
 
@@ -1407,7 +1770,17 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
       // Non-critical — don't fail the capture
     }
 
-    return { success: failedSteps.length === 0, assets, skippedSteps, duplicatesSkipped, failedSteps, retriedSteps, privacy: privacyMeta, style: styleMeta };
+    return {
+      success: failedSteps.length === 0,
+      assets,
+      skippedSteps,
+      duplicatesSkipped,
+      failedSteps,
+      retriedSteps,
+      privacy: privacyMeta,
+      style: styleMeta,
+      diagnostics: engine.getDiagnostics(),
+    };
     })(); // End of scenarioExecution async IIFE
 
     // Race scenario execution against timeout
@@ -1436,14 +1809,22 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
       // Ignore
     }
 
-    return { success: false, error: error.message, assets, skippedSteps, failedSteps, retriedSteps };
+    return {
+      success: false,
+      error: error.message,
+      assets,
+      skippedSteps,
+      failedSteps,
+      retriedSteps,
+      diagnostics: engine.getDiagnostics(),
+    };
   } finally {
     await engine.close();
   }
 }
 
 /**
- * Capture screenshot with highlight box around element
+ * Capture screenshot without interaction overlays.
  */
 async function captureWithHighlight(
   engine,
@@ -1451,63 +1832,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)
  */
@@ -1518,21 +1848,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);
@@ -1595,8 +1940,10 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
   // Check for saved session state (auth cookies) - CRITICAL for authenticated scenarios
   const sessionPath = getDefaultSessionPath();
   const hasSession = fs.existsSync(sessionPath);
-  if (hasSession) {
-    // Validate session freshness
+  if (hasSession && scenario.requiresAuth) {
+    // Validate session freshness. Only relevant when this scenario actually
+    // requires auth — a leftover session file should not trigger staleness
+    // warnings for public scenarios.
     const sessionStats = fs.statSync(sessionPath);
     const sessionAgeHours = (Date.now() - sessionStats.mtimeMs) / (1000 * 60 * 60);
     if (sessionAgeHours > 24) {
@@ -1609,6 +1956,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
   }
 
   const { chromium } = require("playwright");
+  const { launchChromium } = require("./ensure-browser");
   // Use a unique temp directory for this recording to avoid conflicts
   const recordingId = `recording-${Date.now()}-${Math.random()
     .toString(36)
@@ -1635,7 +1983,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
     debug("Launching browser...");
 
     // Launch browser with video recording
-    browser = await chromium.launch(buildLaunchOptions({ headless }));
+    browser = await launchChromium(chromium, buildLaunchOptions({ headless }));
     debug("Browser launched successfully");
 
     // Build context options with variant support using universal injector
@@ -1684,6 +2032,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
@@ -1803,10 +2152,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 };
@@ -1818,7 +2168,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           }
           if (!found) {
             localStorage.setItem(
-              "workspace-store-1",
+              "reshot-store-workspace",
               JSON.stringify({ state: storeState, version: 0 })
             );
           }
@@ -1842,6 +2192,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
@@ -1931,12 +2289,17 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
 
       await fs.writeFile(sentinelPath, buffer);
       sentinelPaths.push({ index: sentinelIndex, label, path: sentinelPath });
+      if (firstSentinelTimestamp === null) {
+        firstSentinelTimestamp = (Date.now() - startTime) / 1000;
+        debug(`First sentinel captured at ${firstSentinelTimestamp.toFixed(2)}s`);
+      }
       sentinelIndex++;
       return sentinelPath;
     }
 
     // Capture initial state BEFORE first navigation (placeholder - actual capture after goto)
     let hasNavigated = false;
+    let firstSentinelTimestamp = null;
 
     // Execute all steps and capture timeline
     for (let stepIndex = 0; stepIndex < script.length; stepIndex++) {
@@ -1977,14 +2340,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) {
@@ -1992,11 +2402,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 });
         }
 
@@ -2045,43 +2456,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,
           });
@@ -2091,6 +2472,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}`)
           );
@@ -2114,41 +2500,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,
           });
@@ -2158,6 +2517,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}`)
           );
@@ -2180,8 +2544,9 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           });
         } catch (e) {
           if (!isOptional) {
-            console.warn(
-              chalk.yellow(`    ⚠ Wait for ${params.target} timed out`)
+            const currentUrl = page.url();
+            throw new Error(
+              `Required selector not found in video capture: ${params.target} (URL: ${currentUrl}, timeout: ${waitTimeout}ms)`
             );
           }
         }
@@ -2199,11 +2564,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}`)
           );
@@ -2292,26 +2664,40 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
       )
     );
 
-    // Convert to MP4 with ffmpeg, trimming to actual content duration
-    // Add a small buffer (0.5s) after the final action
-    const trimDuration = finalTimestamp + 0.5;
-    console.log(
-      chalk.cyan(
-        `  📹 Converting to MP4 (trimmed to ${trimDuration.toFixed(1)}s)...`
-      )
-    );
-    debug(`Running ffmpeg conversion with trim to ${trimDuration}s...`);
+    // 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.25;
+    const contentDuration = endTimestamp - startOffset;
+    if (startOffset > 0) {
+      console.log(
+        chalk.cyan(
+          `  📹 Converting to MP4 (${startOffset.toFixed(1)}s–${endTimestamp.toFixed(1)}s, ${contentDuration.toFixed(1)}s content)...`
+        )
+      );
+    } else {
+      console.log(
+        chalk.cyan(
+          `  📹 Converting to MP4 (trimmed to ${contentDuration.toFixed(1)}s)...`
+        )
+      );
+    }
+    debug(`Running ffmpeg: start=${startOffset}s, duration=${contentDuration}s`);
     await runFFmpegConvert([
+      "-ss",
+      startOffset.toFixed(2),
       "-i",
       recordedVideoPath,
       "-t",
-      trimDuration.toFixed(2),
+      contentDuration.toFixed(2),
       "-c:v",
       "libx264",
       "-preset",
       "fast",
       "-pix_fmt",
       "yuv420p",
+      "-r",
+      String(videoFrameRate),
       "-movflags",
       "+faststart",
       "-y",
@@ -2330,33 +2716,6 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
       )
     );
 
-    // Extract poster frame from the video (first frame at 0.5s for non-blank content)
-    const posterPath = finalVideoPath.replace(/\.mp4$/, "-poster.png");
-    try {
-      await runFFmpegConvert([
-        "-i",
-        finalVideoPath,
-        "-ss",
-        "0.5",
-        "-frames:v",
-        "1",
-        "-q:v",
-        "2",
-        "-y",
-        posterPath,
-      ]);
-      if (fs.existsSync(posterPath)) {
-        const posterSize = fs.statSync(posterPath).size;
-        console.log(
-          chalk.green(
-            `  ✔ Poster frame: ${posterPath} (${(posterSize / 1024).toFixed(1)} KB)`
-          )
-        );
-      }
-    } catch (e) {
-      debug(`Poster frame extraction failed: ${e.message}`);
-    }
-
     // Save timeline for reference
     const timelinePath = path.join(
       outputDir || path.join(".reshot/output", scenario.key, "default"),
@@ -2381,6 +2740,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);
@@ -2398,6 +2765,7 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           path: finalVideoPath,
           type: "video",
           duration: (Date.now() - startTime) / 1000,
+          metadataPath,
         },
       ],
       sentinels: sentinelPaths.map((s) => ({
@@ -2496,6 +2864,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
     timeout = 30000,
     variantsConfig = {}, // Universal variant configuration
     storageStateData = null,
+    globalQuality = null,
     quiet = false,
   } = options;
 
@@ -2506,6 +2875,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
     return runScenarioWithStepByStepCapture(scenario, {
       ...options,
       variantsConfig,
+      globalQuality,
     });
   }
 
@@ -2520,6 +2890,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
   // Legacy behavior: only capture explicit screenshot steps
   // Resolve variant configuration for this scenario
   const variantConfig = resolveVariantConfig(scenario, variantsConfig);
+  const forbidText = collectForbiddenText(globalQuality, scenario);
 
   // Extract crop configuration from scenario output settings
   const outputConfig = scenario.output || {};
@@ -2572,18 +2943,20 @@ async function runScenarioWithEngine(scenario, options = {}) {
     storageStatePath: hasSession ? sessionPath : null, // Use saved session if available
     storageStateData, // Pre-loaded auth state
     hideDevtools: true, // Always hide dev overlays in captures
+    injectWorkspaceStore: scenario.needsWorkspaceInjection !== false,
     logger: quiet ? () => {} : (msg) => console.log(msg),
   });
 
   try {
     await engine.init();
+    await assertForbiddenTextAbsent(engine.page, forbidText);
     const assets = await engine.runScript(script);
 
     if (!quiet) console.log(
       chalk.green(`\n  ✔ Scenario completed: ${assets.length} assets captured`)
     );
 
-    return { success: true, assets };
+    return { success: true, assets, diagnostics: engine.getDiagnostics() };
   } catch (error) {
     console.error(chalk.red(`\n  ❌ Scenario failed: ${error.message}`));
 
@@ -2603,7 +2976,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
       // Ignore screenshot errors
     }
 
-    return { success: false, error: error.message };
+    return { success: false, error: error.message, diagnostics: engine.getDiagnostics() };
   } finally {
     await engine.close();
   }
@@ -2791,6 +3164,47 @@ function detectOptimalConcurrency() {
   return Math.max(1, optimal);
 }
 
+function normalizeAuthPreflightTargets(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || "").trim()).filter(Boolean);
+  }
+
+  const normalized = String(value || "").trim();
+  return normalized ? [normalized] : [];
+}
+
+function resolveAuthPreflightTargets(config, options = {}) {
+  const { scenarioKeys = null } = options;
+  const scenarios = config.scenarios || [];
+  const selectedScenarios =
+    Array.isArray(scenarioKeys) && scenarioKeys.length > 0
+      ? scenarios.filter((scenario) => scenarioKeys.includes(scenario.key))
+      : scenarios;
+  const liveAuthScenarios = selectedScenarios.filter(
+    (scenario) => scenario.captureClass === "live-auth",
+  );
+  const configuredTargets = normalizeAuthPreflightTargets(
+    config.target?.authPreflightUrls || config.target?.authPreflightUrl,
+  );
+  const scenarioTargets = liveAuthScenarios
+    .map((scenario) => scenario.authPreflightUrl || scenario.url)
+    .filter(Boolean);
+  const targets = Array.from(
+    new Set([
+      ...configuredTargets,
+      ...scenarioTargets,
+    ]),
+  );
+
+  return {
+    selectedScenarioKeys: selectedScenarios.map((scenario) => scenario.key),
+    liveAuthScenarioKeys: liveAuthScenarios.map((scenario) => scenario.key),
+    targets: targets.length > 0 || liveAuthScenarios.length === 0
+      ? targets
+      : ["/app/projects"],
+  };
+}
+
 /**
  * Run all scenarios from config
  */
@@ -2806,6 +3220,17 @@ async function runAllScenarios(config, options = {}) {
 
   console.log(chalk.cyan("🎬 Running capture scenarios...\n"));
 
+  const scenarios = config.scenarios || [];
+  const toRun =
+    scenarioKeys?.length > 0
+      ? scenarios.filter((scenario) => scenarioKeys.includes(scenario.key))
+      : scenarios;
+
+  if (toRun.length === 0) {
+    console.log(chalk.yellow("No scenarios to run"));
+    return { success: true, results: [] };
+  }
+
   // Auto-sync session from CDP browser if available
   // This allows captures to use the authenticated session from a running Chrome instance
   try {
@@ -2847,10 +3272,10 @@ async function runAllScenarios(config, options = {}) {
 
   // Run auth pre-flight check if any scenario requires auth
   const captureConfig = getCaptureConfig(config.capture || {});
-  const scenarios = config.scenarios || [];
-  const hasAuthScenarios = scenarios.some((s) => s.requiresAuth);
+  const authPreflight = resolveAuthPreflightTargets(config, { scenarioKeys });
+  const hasLiveAuthScenarios = authPreflight.liveAuthScenarioKeys.length > 0;
 
-  if (captureConfig.preflightCheck && hasAuthScenarios) {
+  if (captureConfig.preflightCheck && hasLiveAuthScenarios) {
     const sessionPath = getDefaultSessionPath();
     const hasSession = fs.existsSync(sessionPath);
     if (hasSession) {
@@ -2859,6 +3284,7 @@ async function runAllScenarios(config, options = {}) {
         {
           storageStatePath: sessionPath,
           viewport: config.viewport || { width: 1280, height: 720 },
+          authCheckUrl: authPreflight.targets,
         }
       );
       if (!preflightResult.ok) {
@@ -2868,17 +3294,6 @@ async function runAllScenarios(config, options = {}) {
     }
   }
 
-  // Filter scenarios if keys provided
-  const toRun =
-    scenarioKeys?.length > 0
-      ? scenarios.filter((s) => scenarioKeys.includes(s.key))
-      : scenarios;
-
-  if (toRun.length === 0) {
-    console.log(chalk.yellow("No scenarios to run"));
-    return { success: true, results: [] };
-  }
-
   // Use shared timestamp if provided (for variant expansion), otherwise generate new one
   const runTimestamp = sharedTimestamp || generateVersionTimestamp();
 
@@ -2974,6 +3389,7 @@ async function runAllScenarios(config, options = {}) {
       runTimestamp, // Pass timestamp for templating
       storageStateData: ssData,
       quiet,
+      globalQuality: config.quality || null,
       noPrivacy: options.noPrivacy,
       noStyle: options.noStyle,
     });
@@ -3126,9 +3542,11 @@ async function runAllScenarios(config, options = {}) {
 
 module.exports = {
   convertLegacySteps,
+  substituteUrlVariables,
   runScenarioWithEngine,
   runScenarioWithStepByStepCapture,
   runScenarioWithVideoCapture,
+  buildVideoMetadata,
   captureWithHighlight,
   checkFFmpeg,
   runAllScenarios,
@@ -3137,11 +3555,18 @@ module.exports = {
   waitForVisualStability,
   // Error detection & retry
   retryInteractiveStep,
+  promoteLastGotoUrl,
   executeWithRetry,
   preflightAuthCheck,
+  resolveAuthPreflightTargets,
+  collectForbiddenText,
+  assertForbiddenTextAbsent,
+  normalizeVisibleText,
   // New exports for output templating
   resolveScenarioOutputDir,
   generateVersionTimestamp,
   // Concurrency
   detectOptimalConcurrency,
+  installVisibleCursor,
+  normalizeVideoTargetName,
 };