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

package/src/lib/compose-context.js

@@ -0,0 +1,156 @@
+"use strict";
+
+const path = require("path");
+const fs = require("fs-extra");
+
+const DEFAULT_FORMATS = ["mp4", "webm", "poster"];
+const VALID_FORMATS = new Set(["mp4", "webm", "poster", "gif"]);
+
+async function resolveComposeContext(file, options = {}) {
+  const compositionPath = path.resolve(process.cwd(), file);
+  if (!(await fs.pathExists(compositionPath))) {
+    throw new Error(
+      `Composition file not found: ${compositionPath}\n` +
+        "Pass the path to a .compose.tsx file.",
+    );
+  }
+
+  const slug = options.slug || deriveSlug(compositionPath);
+  const compositionDir = path.dirname(compositionPath);
+  const metadataPath = resolveMetadataPath(compositionDir, slug);
+  const metadata = await readMetadata(metadataPath, slug);
+  const capturePath = resolveCapturePath({
+    metadata,
+    compositionDir,
+    slug,
+  });
+  await assertCaptureExists(capturePath, slug);
+
+  return {
+    compositionPath,
+    slug,
+    compositionDir,
+    metadataPath,
+    metadata,
+    capturePath,
+  };
+}
+
+function deriveSlug(filePath) {
+  const filename = path.basename(filePath);
+  const withoutKnownSuffix = filename.replace(/\.(compose\.)?[cm]?[tj]sx?$/i, "");
+  return withoutKnownSuffix || path.basename(filePath, path.extname(filePath));
+}
+
+function resolveOutBase(compositionPath, out) {
+  return path.resolve(
+    process.cwd(),
+    out || path.join(path.dirname(compositionPath), `${deriveSlug(compositionPath)}.composed`),
+  );
+}
+
+function resolveMetadataPath(compositionDir, slug) {
+  return path.join(compositionDir, `${slug}.metadata.json`);
+}
+
+async function readMetadata(metadataPath, slug) {
+  if (!(await fs.pathExists(metadataPath))) {
+    throw new Error(
+      `Missing metadata file for slug "${slug}": ${metadataPath}\n` +
+        `Expected a sibling ${slug}.metadata.json file. Re-record the clip with metadata enabled or pass --slug matching an existing metadata file.`,
+    );
+  }
+
+  try {
+    const metadata = await fs.readJson(metadataPath);
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      throw new Error("metadata must be a JSON object");
+    }
+    return metadata;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not read metadata file: ${metadataPath}\n${message}`);
+  }
+}
+
+function resolveCapturePath({ metadata, compositionDir, slug }) {
+  const declaredPath =
+    metadata.capturePath ||
+    metadata.workflowCapturePath ||
+    metadata.capture?.path ||
+    metadata.source?.capturePath ||
+    metadata.source?.path;
+
+  if (typeof declaredPath === "string" && declaredPath.trim()) {
+    return path.resolve(compositionDir, declaredPath);
+  }
+
+  return path.join(compositionDir, `workflow-capture-${slug}.mp4`);
+}
+
+async function assertCaptureExists(capturePath, slug) {
+  if (await fs.pathExists(capturePath)) {
+    return;
+  }
+
+  throw new Error(
+    `Missing workflow capture for slug "${slug}": ${capturePath}\n` +
+      `Expected workflow-capture-${slug}.mp4 next to the composition, or a capturePath in ${slug}.metadata.json.`,
+  );
+}
+
+function parseSize(value) {
+  const match = /^(\d+)x(\d+)$/i.exec(String(value || "").trim());
+  if (!match) {
+    throw new Error(`Invalid --size "${value}". Use WIDTHxHEIGHT, for example 1440x900.`);
+  }
+
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
+    throw new Error(`Invalid --size "${value}". Width and height must be positive integers.`);
+  }
+
+  return { width, height };
+}
+
+function parseFormats(value, includeGif = false) {
+  const rawFormats = value == null || value === "" ? DEFAULT_FORMATS : String(value).split(",");
+  const formats = [];
+
+  for (const rawFormat of rawFormats) {
+    const format = rawFormat.trim().toLowerCase();
+    if (!format) continue;
+    if (!VALID_FORMATS.has(format)) {
+      throw new Error(
+        `Unknown compose format "${rawFormat}". Supported formats: ${Array.from(VALID_FORMATS).join(", ")}.`,
+      );
+    }
+    if (!formats.includes(format)) {
+      formats.push(format);
+    }
+  }
+
+  if (includeGif && !formats.includes("gif")) {
+    formats.push("gif");
+  }
+
+  if (formats.length === 0) {
+    throw new Error(`No compose formats selected. Use --formats=${DEFAULT_FORMATS.join(",")}.`);
+  }
+
+  return formats;
+}
+
+module.exports = {
+  DEFAULT_FORMATS,
+  assertCaptureExists,
+  deriveSlug,
+  parseFormats,
+  parseSize,
+  readMetadata,
+  resolveCapturePath,
+  resolveComposeContext,
+  resolveMetadataPath,
+  resolveOutBase,
+};

package/src/lib/compose-pack.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const fs = require("fs-extra");
+
+async function packFromExistingOutputs(outBase) {
+  const pack = {
+    mp4: `${outBase}.mp4`,
+    webm: `${outBase}.webm`,
+    poster: `${outBase}.webp`,
+  };
+  const gifPath = `${outBase}.gif`;
+  if (await fs.pathExists(gifPath)) {
+    pack.gif = gifPath;
+  }
+  return pack;
+}
+
+async function assertUploadPackExists(pack, skipRender) {
+  const required = [
+    ["rendered_mp4", pack.mp4],
+    ["rendered_webm", pack.webm],
+    ["rendered_poster", pack.poster],
+  ];
+
+  for (const [field, filePath] of required) {
+    if (!filePath || !(await fs.pathExists(filePath))) {
+      const rerenderHint = skipRender
+        ? " Run `reshot compose <file>` first or remove --skip-render."
+        : "";
+      throw new Error(`Missing ${field} output: ${filePath || "(not produced)"}.${rerenderHint}`);
+    }
+  }
+
+  if (pack.gif && !(await fs.pathExists(pack.gif))) {
+    throw new Error(`Missing rendered_gif output: ${pack.gif}.`);
+  }
+}
+
+module.exports = {
+  assertUploadPackExists,
+  packFromExistingOutputs,
+};

package/src/lib/compose-runtime.js

@@ -0,0 +1,34 @@
+// compose-runtime.js — locate the @reshot/compose build the CLI ships with.
+//
+// The compose engine is vendored (self-contained: motion-core and the pure-JS
+// image deps are inlined; only esbuild + playwright-core stay external and are
+// declared as CLI dependencies). The published package ships vendor/compose/dist;
+// when developing inside the monorepo we fall back to the live package build.
+
+const path = require("path");
+const fs = require("fs-extra");
+
+let cached;
+
+/** Absolute path to the compose dist directory (capture.cjs, render.mjs, …). */
+function composeDistDir() {
+  if (cached) return cached;
+  const candidates = [
+    // Shipped with the published CLI (also present in the standalone repo).
+    path.resolve(__dirname, "../../vendor/compose/dist"),
+    // Monorepo development: packages/compose/dist.
+    path.resolve(__dirname, "../../../../packages/compose/dist"),
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) {
+      cached = dir;
+      return dir;
+    }
+  }
+  throw new Error(
+    "@reshot/compose build not found. Expected vendor/compose/dist " +
+      "(shipped with the CLI) or packages/compose/dist (monorepo dev).",
+  );
+}
+
+module.exports = { composeDistDir };

package/src/lib/compose-upload.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const fs = require("fs-extra");
+const axios = require("axios");
+const FormData = require("form-data");
+const config = require("./config");
+const apiClient = require("./api-client");
+
+function resolveComposeProjectContext({ projectOption, settings }) {
+  const resolvedSettings =
+    settings !== undefined ? settings : readSettingsSafe();
+  const apiKey = process.env.RESHOT_API_KEY || resolvedSettings?.apiKey;
+  const projectId =
+    projectOption ||
+    process.env.RESHOT_PROJECT_ID ||
+    resolvedSettings?.projectId;
+
+  if (!apiKey) {
+    throw new Error(
+      "No API key found. Set RESHOT_API_KEY or run `reshot auth` to create .reshot/settings.json.",
+    );
+  }
+
+  if (!projectId) {
+    throw new Error(
+      "No project ID found. Pass --project, set RESHOT_PROJECT_ID, or authenticate with `reshot auth`.",
+    );
+  }
+
+  return { apiKey, projectId };
+}
+
+function readSettingsSafe() {
+  try {
+    return config.readSettings();
+  } catch {
+    return null;
+  }
+}
+
+async function uploadComposition({
+  apiBaseUrl,
+  apiKey,
+  projectId,
+  name,
+  slug,
+  sourceTsx,
+  metadataJson,
+  pack,
+  autoApprove = false,
+  httpClient = axios,
+}) {
+  const formData = new FormData();
+  formData.append("name", name);
+  formData.append("slug", slug);
+  formData.append("source_tsx", sourceTsx);
+  formData.append("metadata_json", metadataJson);
+  if (autoApprove) {
+    formData.append("auto_approve", "true");
+  }
+  formData.append("rendered_mp4", fs.createReadStream(pack.mp4));
+  formData.append("rendered_webm", fs.createReadStream(pack.webm));
+  formData.append("rendered_poster", fs.createReadStream(pack.poster));
+  if (pack.gif) {
+    formData.append("rendered_gif", fs.createReadStream(pack.gif));
+  }
+
+  const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/projects/${encodeURIComponent(projectId)}/compositions`;
+  const response = await httpClient.post(endpoint, formData, {
+    headers: {
+      ...formData.getHeaders(),
+      Authorization: `Bearer ${apiKey}`,
+    },
+    timeout: 180000,
+    maxBodyLength: Infinity,
+    maxContentLength: Infinity,
+  });
+
+  const data = unwrapApiResponse(response.data);
+  const attributionWarning = readResponseHeader(
+    response.headers,
+    "x-reshot-attribution-warning",
+  );
+
+  if (attributionWarning) {
+    return { ...data, attributionWarning };
+  }
+
+  return data;
+}
+
+function unwrapApiResponse(body) {
+  if (body && typeof body === "object" && body.success && body.data !== undefined) {
+    return body.data;
+  }
+  return body;
+}
+
+function readResponseHeader(headers, name) {
+  if (!headers) return null;
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  return headers[name] || headers[name.toLowerCase()] || null;
+}
+
+function buildDashboardUrl(response, apiBaseUrl, projectId) {
+  const platformUrl = apiBaseUrl.replace(/\/api\/?$/, "");
+  const dashboardUrl =
+    response?.dashboardUrl ||
+    response?.composition?.dashboardUrl ||
+    response?.render?.dashboardUrl;
+  if (dashboardUrl) {
+    return dashboardUrl;
+  }
+
+  const compositionId = response?.composition?.id || response?.id;
+  const base = `${platformUrl}/app/projects/${encodeURIComponent(projectId)}/compositions`;
+  return compositionId ? `${base}/${encodeURIComponent(compositionId)}` : base;
+}
+
+function humanizeName(slug) {
+  return String(slug)
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .trim() || slug;
+}
+
+function getComposeApiBaseUrl(explicitApiBaseUrl) {
+  return explicitApiBaseUrl || apiClient.getApiBaseUrl();
+}
+
+module.exports = {
+  buildDashboardUrl,
+  getComposeApiBaseUrl,
+  humanizeName,
+  readResponseHeader,
+  readSettingsSafe,
+  resolveComposeProjectContext,
+  unwrapApiResponse,
+  uploadComposition,
+};

package/src/lib/config.js

@@ -330,9 +330,9 @@ function readConfig() {
     if (!scenario.key) {
       throw new Error(`Scenario "${scenario.name}" must have a "key" field`);
     }
-    if (!/^[a-z0-9-]+$/i.test(scenario.key)) {
+    if (!/^[a-z0-9]([a-z0-9\-_/]*[a-z0-9])?$/i.test(scenario.key)) {
       throw new Error(
-        `Scenario "${scenario.name}" has invalid key "${scenario.key}". Keys must be alphanumeric with hyphens only.`
+        `Scenario "${scenario.name}" has invalid key "${scenario.key}". Keys must start and end alphanumeric; hyphens, underscores, and slashes are allowed in between.`
       );
     }
     if (!scenario.url) {

package/src/lib/dom-capture.js

@@ -0,0 +1,64 @@
+// dom-capture.js — CLI integration layer for the Tier-3 DOM-capture engine.
+//
+// The capture techniques (m7 hybrid primary, m4 CDP DOMSnapshot fallback) live in
+// @reshot/compose/capture so they can reuse the deterministic renderer + the
+// calibrated verify evaluator and be gated under `pnpm --dir packages/compose
+// test`. This module is the thin CLI-side wrapper: it loads that engine (with a
+// monorepo dist fallback, mirroring commands/compose.js) and exposes the two
+// entry points the CLI needs.
+
+const path = require("path");
+const fs = require("fs-extra");
+const { composeDistDir } = require("./compose-runtime");
+
+function loadCaptureEngine() {
+  return require(path.join(composeDistDir(), "capture.cjs"));
+}
+
+/**
+ * Capture a DOM artifact from an ALREADY-NAVIGATED live page and write it next to
+ * the other capture outputs. Returns the metadata.domArtifact block (or null if
+ * capture failed — capture is additive and must never break the video path).
+ *
+ * @param {object} args
+ * @param {import('playwright').Page} args.page  live page (capture as-is)
+ * @param {string} args.outputDir
+ * @param {string} args.slug
+ * @param {string|null} [args.csp]
+ */
+async function captureDomArtifact({ page, outputDir, slug, csp = null }) {
+  try {
+    const { captureDom, writeArtifact } = loadCaptureEngine();
+    const snapshot = await captureDom(page, { csp });
+    const base = path.join(outputDir, slug);
+    const paths = await writeArtifact(snapshot, base);
+    return { path: paths.html, method: snapshot.method, sidecars: snapshot.surfaces };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`  ⚠ DOM capture skipped: ${message}`);
+    return null;
+  }
+}
+
+/**
+ * Standalone capture of a URL: navigates, captures, remounts, and writes the
+ * artifact + remounted.png + live.png into outDir. Returns a result summary.
+ */
+async function captureDomFromUrl({ url, outDir, slug = "capture", settings }) {
+  const { captureUrl, writeArtifact } = loadCaptureEngine();
+  await fs.ensureDir(outDir);
+  const result = await captureUrl(url, settings ? { settings } : {});
+  const paths = await writeArtifact(result.snapshot, path.join(outDir, slug));
+  await fs.writeFile(path.join(outDir, "remounted.png"), result.remountPng);
+  await fs.writeFile(path.join(outDir, "live.png"), result.livePng);
+  return {
+    method: result.method,
+    artifact: paths.html,
+    meta: paths.meta,
+    remounted: path.join(outDir, "remounted.png"),
+    live: path.join(outDir, "live.png"),
+    sidecars: result.snapshot.surfaces,
+  };
+}
+
+module.exports = { loadCaptureEngine, captureDomArtifact, captureDomFromUrl };

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

package/src/lib/resolve-targets.js

@@ -0,0 +1,60 @@
+// resolve-targets.js - Resolve compose target coordinates from a Playwright page
+
+async function resolveTargets(page, targets = {}) {
+  const resolved = {};
+
+  for (const [name, config] of Object.entries(targets || {})) {
+    const target = normalizeTarget(config);
+
+    for (const step of target.navigate) {
+      if (step.clickText) {
+        await page.getByText(step.clickText, { exact: true }).first().click();
+      } else if (step.selector) {
+        await page.locator(step.selector).first().click();
+      }
+      if (step.waitMs) {
+        await page.waitForTimeout(step.waitMs);
+      }
+    }
+
+    const locator = page.locator(target.selector).first();
+    await locator.waitFor({ state: 'visible', timeout: target.timeoutMs });
+    const box = await locator.boundingBox();
+    if (!box) {
+      throw new Error(`Could not resolve target "${name}"`);
+    }
+
+    resolved[name] = {
+      x: Math.round(box.x),
+      y: Math.round(box.y),
+      w: Math.round(box.width),
+      h: Math.round(box.height),
+    };
+  }
+
+  return resolved;
+}
+
+function normalizeTarget(config) {
+  if (typeof config === 'string') {
+    return {
+      selector: config,
+      navigate: [],
+      timeoutMs: 10000,
+    };
+  }
+
+  if (!config || typeof config !== 'object' || !config.selector) {
+    throw new Error('Target config must be a selector string or an object with selector');
+  }
+
+  return {
+    selector: config.selector,
+    navigate: Array.isArray(config.navigate) ? config.navigate : [],
+    timeoutMs: config.timeoutMs || 10000,
+  };
+}
+
+module.exports = {
+  resolveTargets,
+};