@reshotdev/screenshot 0.0.1-beta.1 → 0.0.1-beta.10

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

@@ -30,6 +30,8 @@ const {
   getDefaultSessionPath,
   autoSyncSessionFromCDP,
   sanitizeStorageState,
+  assessSessionHealth,
+  writeSessionArtifacts,
 } = require("./record-cdp");
 const config = require("./config");
 const {
@@ -135,6 +137,47 @@ function debug(...args) {
   }
 }
 
+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(() => document.body?.innerText || ""),
+  );
+  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 +294,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 +344,75 @@ 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();
+
+      // 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 +516,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 +885,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;
@@ -843,6 +961,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 +1065,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();
 
@@ -1133,11 +1253,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(
@@ -1253,6 +1387,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 +1435,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 +1454,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 +1557,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,7 +1596,15 @@ 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();
   }
@@ -1931,12 +2099,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++) {
@@ -2180,8 +2353,16 @@ async function runScenarioWithVideoCapture(scenario, options = {}) {
           });
         } catch (e) {
           if (!isOptional) {
+            const currentUrl = page.url();
             console.warn(
-              chalk.yellow(`    ⚠ Wait for ${params.target} timed out`)
+              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.`
+              )
             );
           }
         }
@@ -2292,20 +2473,32 @@ 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.5;
+    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",
@@ -2469,6 +2662,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
     timeout = 30000,
     variantsConfig = {}, // Universal variant configuration
     storageStateData = null,
+    globalQuality = null,
     quiet = false,
   } = options;
 
@@ -2479,6 +2673,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
     return runScenarioWithStepByStepCapture(scenario, {
       ...options,
       variantsConfig,
+      globalQuality,
     });
   }
 
@@ -2493,6 +2688,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 || {};
@@ -2545,18 +2741,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}`));
 
@@ -2576,7 +2774,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();
   }
@@ -2764,6 +2962,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
  */
@@ -2779,6 +3018,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 {
@@ -2820,10 +3070,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) {
@@ -2832,6 +3082,7 @@ async function runAllScenarios(config, options = {}) {
         {
           storageStatePath: sessionPath,
           viewport: config.viewport || { width: 1280, height: 720 },
+          authCheckUrl: authPreflight.targets,
         }
       );
       if (!preflightResult.ok) {
@@ -2841,17 +3092,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();
 
@@ -2947,6 +3187,7 @@ async function runAllScenarios(config, options = {}) {
       runTimestamp, // Pass timestamp for templating
       storageStateData: ssData,
       quiet,
+      globalQuality: config.quality || null,
       noPrivacy: options.noPrivacy,
       noStyle: options.noStyle,
     });
@@ -3099,6 +3340,7 @@ async function runAllScenarios(config, options = {}) {
 
 module.exports = {
   convertLegacySteps,
+  substituteUrlVariables,
   runScenarioWithEngine,
   runScenarioWithStepByStepCapture,
   runScenarioWithVideoCapture,
@@ -3110,8 +3352,13 @@ module.exports = {
   waitForVisualStability,
   // Error detection & retry
   retryInteractiveStep,
+  promoteLastGotoUrl,
   executeWithRetry,
   preflightAuthCheck,
+  resolveAuthPreflightTargets,
+  collectForbiddenText,
+  assertForbiddenTextAbsent,
+  normalizeVisibleText,
   // New exports for output templating
   resolveScenarioOutputDir,
   generateVersionTimestamp,