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

package/src/lib/record-cdp.js

@@ -2,6 +2,9 @@
 const { chromium } = require("playwright");
 const chalk = require("chalk");
 const http = require("http");
+const fs = require("fs-extra");
+const path = require("path");
+const os = require("os");
 
 /**
  * Check if Chrome CDP endpoint is available
@@ -418,15 +421,14 @@ async function saveSessionState(outputPath) {
       console.log(chalk.gray(`    Sanitized cookies: ${stats.fixed} fixed, ${stats.removed} removed, ${stats.stripped} stripped`));
     }
 
-    // Ensure directory exists
-    const fs = require("fs-extra");
-    const path = require("path");
-    fs.ensureDirSync(path.dirname(outputPath));
-
-    // Write storage state to file
-    fs.writeJsonSync(outputPath, storageState, { spaces: 2 });
+    const activePageUrl = page?.url?.() || null;
+    const artifactInfo = writeSessionArtifacts(outputPath, storageState, {
+      pageUrl: activePageUrl,
+      baseUrl: activePageUrl,
+    });
 
     console.log(chalk.green(`  ✔ Session saved to: ${outputPath}`));
+    console.log(chalk.gray(`    Metadata: ${artifactInfo.metadataPath}`));
     console.log(chalk.gray(`    Cookies: ${storageState.cookies?.length || 0}`));
     console.log(chalk.gray(`    Origins with localStorage: ${storageState.origins?.length || 0}`));
     
@@ -445,11 +447,249 @@ async function saveSessionState(outputPath) {
  * @returns {string}
  */
 function getDefaultSessionPath() {
-  const path = require("path");
-  const os = require("os");
   return path.join(os.homedir(), ".reshot", "session-state.json");
 }
 
+function getSessionMetadataPath(sessionPath = getDefaultSessionPath()) {
+  if (sessionPath.endsWith(".json")) {
+    return sessionPath.replace(/\.json$/i, ".meta.json");
+  }
+
+  return `${sessionPath}.meta.json`;
+}
+
+function normalizeOrigin(value) {
+  if (!value || typeof value !== "string") {
+    return null;
+  }
+
+  try {
+    return new URL(value).origin.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeCookieDomain(domain) {
+  if (!domain || typeof domain !== "string") {
+    return null;
+  }
+
+  return domain.replace(/^\./, "").toLowerCase();
+}
+
+function extractSessionEvidence(storageState) {
+  const storageOrigins = Array.from(
+    new Set(
+      (storageState?.origins || [])
+        .map((origin) => normalizeOrigin(origin?.origin))
+        .filter(Boolean),
+    ),
+  );
+
+  const cookieDomains = Array.from(
+    new Set(
+      (storageState?.cookies || [])
+        .map((cookie) => normalizeCookieDomain(cookie?.domain))
+        .filter(Boolean),
+    ),
+  );
+
+  return { storageOrigins, cookieDomains };
+}
+
+function buildSessionMetadata(options = {}) {
+  const {
+    baseUrl = null,
+    pageUrl = null,
+    storageState = null,
+    capturedAt = new Date().toISOString(),
+  } = options;
+  const evidence = extractSessionEvidence(storageState);
+
+  return {
+    version: 1,
+    capturedAt,
+    sourceUrl: pageUrl || baseUrl || null,
+    sourceOrigin:
+      normalizeOrigin(pageUrl) ||
+      normalizeOrigin(baseUrl) ||
+      evidence.storageOrigins[0] ||
+      null,
+    storageOrigins: evidence.storageOrigins,
+    cookieDomains: evidence.cookieDomains,
+  };
+}
+
+function writeSessionArtifacts(sessionPath, storageState, options = {}) {
+  const metadataPath = getSessionMetadataPath(sessionPath);
+  const metadata = buildSessionMetadata({ ...options, storageState });
+
+  fs.ensureDirSync(path.dirname(sessionPath));
+  fs.writeJsonSync(sessionPath, storageState, { spaces: 2 });
+  fs.writeJsonSync(metadataPath, metadata, { spaces: 2 });
+
+  return { sessionPath, metadataPath, metadata };
+}
+
+function readSessionMetadata(sessionPath = getDefaultSessionPath()) {
+  const metadataPath = getSessionMetadataPath(sessionPath);
+
+  if (!fs.existsSync(metadataPath)) {
+    return {
+      exists: false,
+      metadataPath,
+      metadata: null,
+      error: null,
+    };
+  }
+
+  try {
+    return {
+      exists: true,
+      metadataPath,
+      metadata: fs.readJsonSync(metadataPath),
+      error: null,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      metadataPath,
+      metadata: null,
+      error: error.message,
+    };
+  }
+}
+
+function sessionHostMatchesCookieDomains(hostname, cookieDomains) {
+  if (!hostname) {
+    return false;
+  }
+
+  return cookieDomains.some(
+    (domain) => hostname === domain || hostname.endsWith(`.${domain}`),
+  );
+}
+
+function assessSessionHealth(
+  sessionPath = getDefaultSessionPath(),
+  baseUrl = null,
+  options = {},
+) {
+  const maxAgeMinutes = Number.isFinite(options.maxAgeMinutes)
+    ? options.maxAgeMinutes
+    : 360;
+  const expectedOrigin = normalizeOrigin(baseUrl);
+  const result = {
+    ok: false,
+    exists: fs.existsSync(sessionPath),
+    sessionPath,
+    metadataPath: getSessionMetadataPath(sessionPath),
+    expectedOrigin,
+    compatible: true,
+    stale: false,
+    ageMinutes: null,
+    metadata: null,
+    warnings: [],
+    issues: [],
+    evidence: {
+      sourceOrigin: null,
+      storageOrigins: [],
+      cookieDomains: [],
+      matchSource: null,
+    },
+  };
+
+  if (!result.exists) {
+    return result;
+  }
+
+  let storageState = null;
+  try {
+    storageState = fs.readJsonSync(sessionPath);
+  } catch (error) {
+    result.compatible = false;
+    result.issues.push(`Cached session file is unreadable: ${error.message}`);
+    return result;
+  }
+
+  const metadataInfo = readSessionMetadata(sessionPath);
+  if (metadataInfo.error) {
+    result.warnings.push(`Session metadata is unreadable: ${metadataInfo.error}`);
+  } else if (!metadataInfo.exists) {
+    result.warnings.push(
+      "Session metadata is missing; compatibility was inferred from stored cookies and origins.",
+    );
+  }
+
+  const inferredEvidence = extractSessionEvidence(storageState);
+  const metadata = metadataInfo.metadata || null;
+  const storageOrigins =
+    metadata?.storageOrigins
+      ?.map((origin) => normalizeOrigin(origin))
+      .filter(Boolean) || inferredEvidence.storageOrigins;
+  const cookieDomains =
+    metadata?.cookieDomains
+      ?.map((domain) => normalizeCookieDomain(domain))
+      .filter(Boolean) || inferredEvidence.cookieDomains;
+  const sourceOrigin =
+    normalizeOrigin(metadata?.sourceOrigin) ||
+    normalizeOrigin(metadata?.sourceUrl) ||
+    inferredEvidence.storageOrigins[0] ||
+    null;
+
+  result.metadata = metadata;
+  result.evidence = {
+    sourceOrigin,
+    storageOrigins,
+    cookieDomains,
+    matchSource: null,
+  };
+
+  const capturedAtMs = Date.parse(metadata?.capturedAt || "");
+  const sessionStat = fs.statSync(sessionPath);
+  const referenceTime = Number.isFinite(capturedAtMs)
+    ? capturedAtMs
+    : sessionStat.mtimeMs;
+  result.ageMinutes = Math.max(
+    0,
+    Math.round((Date.now() - referenceTime) / 60000),
+  );
+  result.stale = result.ageMinutes >= maxAgeMinutes;
+
+  if (expectedOrigin) {
+    const expectedHost = new URL(baseUrl).hostname.toLowerCase();
+    const matchesSourceOrigin = sourceOrigin === expectedOrigin;
+    const matchesStorageOrigin = storageOrigins.includes(expectedOrigin);
+    const matchesCookieDomain = sessionHostMatchesCookieDomains(
+      expectedHost,
+      cookieDomains,
+    );
+
+    result.evidence.matchSource = matchesSourceOrigin
+      ? "sourceOrigin"
+      : matchesStorageOrigin
+        ? "storageOrigins"
+        : matchesCookieDomain
+          ? "cookieDomains"
+          : null;
+
+    const hasEvidence =
+      Boolean(sourceOrigin) ||
+      storageOrigins.length > 0 ||
+      cookieDomains.length > 0;
+    if (hasEvidence && !result.evidence.matchSource) {
+      result.compatible = false;
+      result.issues.push(
+        `Cached session targets ${sourceOrigin || storageOrigins[0] || cookieDomains[0]}, not ${expectedOrigin}.`,
+      );
+    }
+  }
+
+  result.ok = result.compatible && result.issues.length === 0;
+  return result;
+}
+
 /**
  * Quietly check if CDP is available and sync the session if so.
  * This is called automatically before captures to use the live browser session.
@@ -459,13 +699,24 @@ function getDefaultSessionPath() {
  */
 async function autoSyncSessionFromCDP(outputPath = null, logger = null) {
   const log = logger || (() => {}); // Quiet by default
-  const fs = require("fs-extra");
-  const path = require("path");
-  const os = require("os");
-  
+
+  // Allow disabling CDP sync via env var (useful when session was created programmatically)
+  if (process.env.RESHOT_SKIP_CDP_SYNC === "1") {
+    return { synced: false, reason: "disabled" };
+  }
+
   const sessionPath = outputPath || path.join(os.homedir(), ".reshot", "session-state.json");
-  
+
   try {
+    // Skip sync if cached session is very recent (likely just generated programmatically)
+    if (fs.existsSync(sessionPath)) {
+      const cachedAge = Date.now() - fs.statSync(sessionPath).mtimeMs;
+      if (cachedAge < 5 * 60 * 1000) {
+        log(chalk.gray("  → Cached session is fresh (<5min), skipping CDP sync"));
+        return { synced: false, reason: "cached_fresh" };
+      }
+    }
+
     // Step 1: Check if CDP endpoint is available (quietly)
     const endpointCheck = await checkCdpEndpoint("localhost", 9222);
     
@@ -513,9 +764,25 @@ async function autoSyncSessionFromCDP(outputPath = null, logger = null) {
         return { synced: false, reason: "empty_session" };
       }
 
+      const activePage =
+        context
+          .pages()
+          .find((candidate) => {
+            const currentUrl = candidate.url();
+            return (
+              currentUrl &&
+              !currentUrl.startsWith("chrome://") &&
+              !currentUrl.startsWith("devtools://") &&
+              !currentUrl.startsWith("chrome-extension://")
+            );
+          }) || context.pages()[0] || null;
+      const activePageUrl = activePage?.url?.() || null;
+
       // Step 4: Save to file
-      fs.ensureDirSync(path.dirname(sessionPath));
-      fs.writeJsonSync(sessionPath, storageState, { spaces: 2 });
+      writeSessionArtifacts(sessionPath, storageState, {
+        pageUrl: activePageUrl,
+        baseUrl: activePageUrl,
+      });
 
       log(chalk.green(`  ✔ Auto-synced session from CDP browser`));
       log(chalk.gray(`    Cookies: ${storageState.cookies?.length || 0}, localStorage origins: ${storageState.origins?.length || 0}`));
@@ -607,6 +874,11 @@ module.exports = {
   printChromeInstructions,
   saveSessionState,
   getDefaultSessionPath,
+  getSessionMetadataPath,
   autoSyncSessionFromCDP,
   sanitizeStorageState,
+  buildSessionMetadata,
+  writeSessionArtifacts,
+  readSessionMetadata,
+  assessSessionHealth,
 };

package/src/lib/record-clip.js

@@ -8,13 +8,27 @@ const { chromium } = require('playwright');
 const { updateBrowserMode } = require('./record-browser-injection');
 const { runPolishedClip } = require('./polished-clip');
 const { saveScenarioProgress } = require('./record-config');
+const { resolveTargets } = require('./resolve-targets');
+const { captureDomArtifact } = require('./dom-capture');
 
 /**
  * Start clip recording flow
  * @param {Object} sessionState - Recording session state
  * @param {Page} page - Playwright page object
  */
-async function startClipRecording(sessionState, page) {
+async function startClipRecording(sessionState, page, config = {}) {
+  const metadataRecorder = config.emitMetadata
+    ? createClipMetadataRecorder({
+        slug: config.slug || sessionState.visualKey,
+        captureSize: config.captureSize || { width: 1280, height: 720 },
+      })
+    : null;
+
+  if (metadataRecorder) {
+    sessionState.logEvent = metadataRecorder.logEvent;
+    metadataRecorder.logEvent('workflow_start');
+  }
+
   // Ask about container element
   const { useContainer } = await inquirer.prompt([
     {
@@ -127,6 +141,10 @@ async function startClipRecording(sessionState, page) {
   
   // Set up action replay handler to sync video with real user actions
   sessionState.replayActionToRecording = async (action, selector, text) => {
+    if (metadataRecorder) {
+      metadataRecorder.logEvent(action, { selector, text });
+    }
+
     try {
       if (action === 'click') {
         await recordingPage.click(selector);
@@ -233,6 +251,17 @@ async function startClipRecording(sessionState, page) {
   
   sessionState.capturedSteps.push(clipStep);
   await saveScenarioProgress(sessionState, page, { finalize: false });
+
+  if (metadataRecorder) {
+    await writeClipMetadata({
+      page,
+      outputDir: config.outputDir || sessionState.outputDir || process.cwd(),
+      slug: metadataRecorder.slug,
+      captureSize: metadataRecorder.captureSize,
+      timeline: metadataRecorder.timeline,
+      targets: config.targets,
+    });
+  }
   
   // Clean up temp video
   fs.removeSync(rawVideoPath);
@@ -242,6 +271,9 @@ async function startClipRecording(sessionState, page) {
   sessionState.clipEvents = null;
   sessionState.recordingStart = null;
   sessionState.stopClipRecording = false;
+  if (metadataRecorder) {
+    delete sessionState.logEvent;
+  }
   
   console.log(
     chalk.green(
@@ -250,6 +282,53 @@ async function startClipRecording(sessionState, page) {
   );
 }
 
+function createClipMetadataRecorder({ slug, captureSize }) {
+  const startedAt = Date.now();
+  const timeline = [];
+
+  return {
+    slug,
+    captureSize,
+    timeline,
+    logEvent(type, payload = {}) {
+      timeline.push({
+        tMs: Date.now() - startedAt,
+        type,
+        payload,
+      });
+    },
+  };
+}
+
+async function writeClipMetadata({
+  page,
+  outputDir,
+  slug,
+  captureSize,
+  timeline,
+  targets,
+}) {
+  const resolvedTargets = targets ? await resolveTargets(page, targets) : {};
+
+  // Tier-3: alongside the video, emit a self-contained DOM reconstruction
+  // artifact (<slug>.dom.html + sidecars) for eligible screens. Additive and
+  // best-effort — it must never break the video path, so failures are swallowed.
+  await fs.ensureDir(outputDir);
+  const domArtifact = await captureDomArtifact({ page, outputDir, slug });
+
+  const metadata = {
+    slug,
+    version: 1,
+    captureSize,
+    timeline,
+    targets: resolvedTargets,
+    ...(domArtifact ? { domArtifact } : {}),
+  };
+  const metadataPath = path.join(outputDir, `${slug}.metadata.json`);
+  await fs.writeJson(metadataPath, metadata, { spaces: 2 });
+  return metadataPath;
+}
+
 /**
  * Run subtitle editor mini-server
  * @param {Array} events - Clip events with timestamps
@@ -338,6 +417,7 @@ function buildClipKey(visualKey, filename) {
 }
 
 module.exports = {
-  startClipRecording
+  createClipMetadataRecorder,
+  startClipRecording,
+  writeClipMetadata
 };
-

package/src/lib/record-config.js

@@ -492,10 +492,6 @@ async function persistFinalScenario(sessionState, page, options = {}) {
   // Default output configuration for automatic step-by-step image generation
   const defaultOutput = {
     format: "step-by-step-images",
-    highlight: {
-      color: "rgba(255, 255, 0, 0.5)",
-      style: "box",
-    },
   };
 
   // Parse groupPath from session state or existing scenario
@@ -600,7 +596,7 @@ async function finalizeScenarioAndWriteConfig(
 
   console.log(
     chalk.green(
-      "\n✔ docsync.config.json has been updated. Please review and commit the changes to your repository.\n"
+      "\n✔ reshot.config.json has been updated. Please review and commit the changes to your repository.\n"
     )
   );
   console.log(chalk.gray(`Scenario: ${result.scenarioName}`));