@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/vendor/framey/dist/snapshot-TUXL6LBQ.js

@@ -0,0 +1,1515 @@
+import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+import { dirname as __hf_dirname } from "node:path";
+var require = __hf_createRequire(import.meta.url);
+var __filename = __hf_fileURLToPath(import.meta.url);
+var __dirname = __hf_dirname(__filename);
+import {
+  writeCaptureFileSync
+} from "./chunk-GKZEVJIB.js";
+import {
+  toDomNode
+} from "./chunk-LLMSX6V6.js";
+import {
+  parseAngle
+} from "./chunk-KZI44OPA.js";
+import {
+  formatLintFindings
+} from "./chunk-JGXJU5PF.js";
+import {
+  loadInstalledSharp,
+  loadOptionalPackage
+} from "./chunk-VMC4WSH5.js";
+import "./chunk-6BEFEWFB.js";
+import {
+  findFFmpeg,
+  findFFprobe,
+  getFFmpegInstallHint
+} from "./chunk-UMD3V7CU.js";
+import {
+  pngDimensions,
+  reportArtifacts,
+  withProjectLock
+} from "./chunk-3LM6YPBR.js";
+import {
+  captureArtifactRevision
+} from "./chunk-UTEIUGAZ.js";
+import "./chunk-IXU6PQSW.js";
+import "./chunk-X7MTZ4T2.js";
+import {
+  withMeta
+} from "./chunk-O4YRB27L.js";
+import {
+  resolveProject
+} from "./chunk-O7BGSQ5F.js";
+import {
+  serveStaticProjectHtml
+} from "./chunk-C5BO7PMT.js";
+import "./chunk-X7MTZ4T2.js";
+import "./chunk-6DDPOHMK.js";
+import "./chunk-XUHOIDKG.js";
+import "./chunk-THJALHFJ.js";
+import "./chunk-IUONB55J.js";
+import "./chunk-6JR2XUEE.js";
+import "./chunk-MI5FTLYK.js";
+import {
+  artifactDirectory,
+  finishSnapshotRun,
+  forgetRecordedArtifacts,
+  recordArtifacts,
+  retainSnapshotOutput
+} from "./chunk-YPRBGITP.js";
+import "./chunk-7JQFJ6JJ.js";
+import {
+  DEFAULT_ZOOM_SCALE,
+  SCREENSHOT_IMAGE_WAIT_MS,
+  captureRegionCrop,
+  openSettledCompositionPage,
+  parseZoomTarget,
+  resolveCropRegion,
+  runFfmpegOnce,
+  seekCompositionTimelineOnly,
+  settleCompositionSeek
+} from "./chunk-SZNTYTIV.js";
+import "./chunk-YOR4CTCE.js";
+import "./chunk-KXTKKBOC.js";
+import "./chunk-P5ZBLXJ6.js";
+import "./chunk-LEKZNRKI.js";
+import "./chunk-442JNXRM.js";
+import "./chunk-4BNN5FGX.js";
+import "./chunk-XT7X6QCP.js";
+import "./chunk-4YYJOFKS.js";
+import "./chunk-HVW7ABXD.js";
+import "./chunk-DQBY7FRR.js";
+import {
+  resolveLocalBrowserGpuMode
+} from "./chunk-WKBM7NDG.js";
+import "./chunk-XX7LTW5Y.js";
+import {
+  runWithConcurrencyLimit
+} from "./chunk-JHOCK3DG.js";
+import "./chunk-XPTOJZJF.js";
+import "./chunk-RGLQURIX.js";
+import "./chunk-P6LJ4Y32.js";
+import "./chunk-GMECXFAN.js";
+import "./chunk-FLREUEHW.js";
+import "./chunk-EOVYQ3IG.js";
+import "./chunk-GNEFDLFB.js";
+import "./chunk-2UZQHDM7.js";
+import "./chunk-NYEXNSHM.js";
+import {
+  defineCommand
+} from "./chunk-S3S4TGEH.js";
+import "./chunk-54HJ63Q2.js";
+import "./chunk-ISN5GRYI.js";
+import {
+  c
+} from "./chunk-VORQIH64.js";
+import {
+  CliRuntimeError,
+  failCommand
+} from "./chunk-JVBRJMOP.js";
+import "./chunk-KLIKCX6Q.js";
+import "./chunk-EVMY7IPL.js";
+import "./chunk-7FMUTGOH.js";
+import "./chunk-TIQB63MX.js";
+import "./chunk-IZCW2NKT.js";
+import "./chunk-RNV3DM4S.js";
+import {
+  createRuntimeStartTimeResolver,
+  isClipVisibleAt,
+  isInClipWindow
+} from "./chunk-DLA44CMS.js";
+import {
+  readElementRateSpec,
+  sourceTimeAt,
+  timeAtSourceTime
+} from "./chunk-UJZREAV6.js";
+import "./chunk-VC76R6W2.js";
+import "./chunk-X7HBSTCZ.js";
+import {
+  topLevelElements,
+  trackKindOf
+} from "./chunk-B7RJV74O.js";
+import "./chunk-DPVXBVLL.js";
+import "./chunk-OFQWTKPW.js";
+import "./chunk-634HSJ3J.js";
+import "./chunk-FXMKHHPO.js";
+import "./chunk-RQVDTPGD.js";
+import "./chunk-AHX34EFP.js";
+import {
+  runCancellableProcess
+} from "./chunk-BL4U6U52.js";
+import {
+  definitiveEntryMismatchComposition,
+  hasDefinitiveEntryMismatch
+} from "./chunk-Q5X2B5WT.js";
+import {
+  normalizeErrorMessage
+} from "./chunk-T2EUWCJE.js";
+import "./chunk-T6AGUTZJ.js";
+import "./chunk-XT6MXC7A.js";
+import "./chunk-K4MJX7SR.js";
+import "./chunk-4UMPIPCQ.js";
+import {
+  lintProject
+} from "./chunk-4P7NX5BM.js";
+import "./chunk-VAS6HQX3.js";
+import "./chunk-6BNTGNGD.js";
+import "./chunk-CZGHFATT.js";
+import "./chunk-PKZ7RK5N.js";
+import "./chunk-W2LGJSEN.js";
+import "./chunk-MMQ52NIZ.js";
+import "./chunk-BSQ7XANM.js";
+import {
+  parseHTML
+} from "./chunk-SDYDNHEE.js";
+import "./chunk-RXATE6FZ.js";
+import "./chunk-3422KMTD.js";
+import "./chunk-KGPLIH7B.js";
+import "./chunk-3GXQPCJC.js";
+import "./chunk-M2WBOQ2Q.js";
+
+// src/commands/snapshotSampling.ts
+function parseSnapshotRange(value) {
+  const parts = value.split(/[,:]/);
+  const range = parts.map((part) => part.trim() === "" ? NaN : Number(part));
+  if (parts.length !== 2 || !range.every(Number.isFinite) || range[0] < 0 || range[1] <= range[0])
+    throw new Error("--range must be START,END in seconds, with 0 <= START < END");
+  return [range[0], range[1]];
+}
+function parseSnapshotAt(value) {
+  const times = value.split(",").map((part) => part.trim() === "" ? NaN : Number(part));
+  if (!times.every((time) => Number.isFinite(time) && time >= 0))
+    throw new Error("--at must be comma-separated times in seconds, each 0 or more");
+  return times;
+}
+function sampleSnapshotRange([start, end], frames, duration, exclusiveEnd = false) {
+  if (!Number.isInteger(frames) || frames < 1)
+    throw new Error("--frames must be a positive integer");
+  if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start || end > duration)
+    throw new Error(`Snapshot range must satisfy 0 <= START < END <= ${duration}s`);
+  if (frames === 1) return [(start + end) / 2];
+  const last = exclusiveEnd || end === duration ? end - Math.min(1e-3, (end - start) / (frames * 2)) : end;
+  return Array.from({ length: frames }, (_, i) => start + (last - start) * i / (frames - 1));
+}
+function snapshotStartResolver(document2, durations) {
+  return createRuntimeStartTimeResolver({
+    documentRef: document2,
+    timelineRegistry: Object.fromEntries(
+      Object.entries(durations).map(([key, value]) => [key, { duration: () => value }])
+    ),
+    includeAuthoredTimingAttrs: true
+  });
+}
+function resolveSnapshotCompositionRange(html, durations, id, duration) {
+  const { document: document2 } = parseHTML(html);
+  const matches = Array.from(document2.querySelectorAll("[data-composition-id]")).filter(
+    (el) => el.getAttribute("data-composition-id") === id
+  );
+  if (matches.length !== 1)
+    throw new Error(
+      `Composition ID ${JSON.stringify(id)} matched ${matches.length} elements; expected exactly one`
+    );
+  const resolver = snapshotStartResolver(document2, durations);
+  let start = 0, end = duration;
+  for (let el = matches[0]; el; el = el.parentElement) {
+    if (!el.hasAttribute("data-composition-id") && !el.hasAttribute("data-start")) continue;
+    const localStart = resolver.resolveStartForElement(el, 0);
+    const length = resolver.resolveDurationForElement(el);
+    if (!Number.isFinite(localStart))
+      throw new Error(`Cannot resolve start of composition ${JSON.stringify(id)}`);
+    start = Math.max(start, localStart);
+    if (length != null) end = Math.min(end, localStart + length);
+  }
+  if (end <= start)
+    throw new Error(`Composition ${JSON.stringify(id)} has no visible time interval`);
+  return [start, end];
+}
+
+// src/commands/snapshot.ts
+import { randomUUID } from "crypto";
+import { existsSync, mkdtempSync, readFileSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { resolve, join, relative, isAbsolute, basename, posix } from "path";
+
+// src/commands/snapshotReview.ts
+var REVIEW_SETTLE_SEC = 0.3;
+var REVIEW_MID_GAP_SEC = 0.5;
+var REVIEW_SEAM_OFFSETS = [-0.2, -0.1, 0, 0.1, 0.2];
+var REVIEW_PHONE_WIDTH = 360;
+var SAME_TIME_SEC = 0.05;
+var EVEN_BEATS = 5;
+function roundMs(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+function sceneId(el, index) {
+  return el.id || el.getAttribute("data-composition-id") || el.getAttribute("data-layout-name") || `${el.tagName.toLowerCase()}-${index + 1}`;
+}
+function resolveReviewTimeline(html, durations, duration, compositionId) {
+  const bounds = compositionId ? resolveSnapshotCompositionRange(html, durations, compositionId, duration) : [0, duration];
+  const { document: document2 } = parseHTML(html);
+  const target = compositionId ? Array.from(document2.querySelectorAll("[data-composition-id]")).find(
+    (el) => el.getAttribute("data-composition-id") === compositionId
+  ) : document2.querySelector("[data-composition-id]");
+  if (!target) {
+    return { window: bounds, scenes: [], beats: [], notes: ["No composition root found."] };
+  }
+  const resolver = snapshotStartResolver(document2, durations);
+  const span = (el) => {
+    const start = resolver.resolveStartForElement(el, 0);
+    if (!Number.isFinite(start)) return null;
+    const length = resolver.resolveDurationForElement(el);
+    const from = Math.max(bounds[0], start);
+    const to = Math.min(bounds[1], length != null ? start + length : bounds[1]);
+    return to > from ? [roundMs(from), roundMs(to)] : null;
+  };
+  const scenes = [];
+  const rows = topLevelElements(toDomNode(target)).filter((node) => {
+    const kind = trackKindOf(node).kind;
+    return kind === "video" || kind === "graphics";
+  });
+  rows.forEach((node, index) => {
+    const interval = span(node.el);
+    if (interval)
+      scenes.push({ id: sceneId(node.el, index), start: interval[0], end: interval[1] });
+  });
+  const beats = [];
+  const notes = [];
+  for (const el of Array.from(target.querySelectorAll("[data-beat]"))) {
+    const name = el.getAttribute("data-beat")?.trim() || sceneId(el, beats.length);
+    const timed = el.hasAttribute("data-start") || el.hasAttribute("data-composition-id");
+    const interval = timed ? span(el) : null;
+    if (!interval) {
+      notes.push(`data-beat="${name}" was skipped: give it a data-start so the beat has a time.`);
+      continue;
+    }
+    beats.push({ time: settledTime(interval[0], interval[1]), label: `beat:${name}` });
+  }
+  scenes.sort((a, b) => a.start - b.start || a.end - b.end);
+  return { window: bounds, scenes, beats, notes };
+}
+function sceneBeats(scene) {
+  const settled = settledTime(scene.start, scene.end);
+  const middle = roundMs((scene.start + scene.end) / 2);
+  const beats = [{ time: settled, label: scene.id }];
+  return middle - settled >= REVIEW_MID_GAP_SEC ? [...beats, { time: middle, label: `${scene.id} mid` }] : beats;
+}
+function settledTime(start, end) {
+  return roundMs(Math.min(start + REVIEW_SETTLE_SEC, (start + end) / 2));
+}
+function planReview(timeline, lastFrame) {
+  const { window: bounds, scenes } = timeline;
+  const notes = [...timeline.notes];
+  const clamp = (time) => roundMs(Math.min(Math.max(time, bounds[0]), lastFrame));
+  const distinctStarts = mergeBeats(
+    scenes.map((scene) => ({ time: scene.start, label: scene.id }))
+  );
+  const beats = mergeBeats([
+    ...distinctStarts.length >= 2 ? scenes.flatMap(sceneBeats) : evenBeats(bounds, notes),
+    ...timeline.beats
+  ]).map((beat) => ({ ...beat, time: clamp(beat.time) }));
+  const seams = seamTimes(scenes, bounds).map((time) => ({
+    time,
+    ...seamSides(scenes, time),
+    times: REVIEW_SEAM_OFFSETS.map((offset) => clamp(time + offset))
+  }));
+  return { window: bounds, scenes, beats, seams, notes };
+}
+function evenBeats(bounds, notes) {
+  notes.push(
+    `Fewer than two scene starts; ${EVEN_BEATS} beats are spread evenly instead. Time scenes as sub-composition hosts or clips to review each one.`
+  );
+  const [start, end] = bounds;
+  return Array.from({ length: EVEN_BEATS }, (_, index) => {
+    const time = roundMs(start + (index + 0.5) / EVEN_BEATS * (end - start));
+    return { time, label: `t=${time}` };
+  });
+}
+function mergeBeats(beats) {
+  const merged = [];
+  for (const beat of [...beats].sort((a, b) => a.time - b.time)) {
+    const same = merged.find((entry) => Math.abs(entry.time - beat.time) < SAME_TIME_SEC);
+    if (same) same.label = `${same.label} + ${beat.label}`;
+    else merged.push({ ...beat });
+  }
+  return merged;
+}
+function seamTimes(scenes, bounds) {
+  const inside = (time) => time > bounds[0] + SAME_TIME_SEC && time < bounds[1] - SAME_TIME_SEC;
+  const starts = scenes.map((scene) => scene.start).filter(inside);
+  const ends = scenes.map((scene) => scene.end).filter(inside).filter((end) => !starts.some((start) => Math.abs(start - end) < SAME_TIME_SEC));
+  const seams = [];
+  for (const time of [...starts, ...ends].sort((a, b) => a - b)) {
+    if (!seams.some((seam) => Math.abs(seam - time) < SAME_TIME_SEC)) seams.push(time);
+  }
+  return seams;
+}
+function seamSides(scenes, time) {
+  const before = scenes.filter((scene) => scene.start < time - SAME_TIME_SEC && scene.end >= time - SAME_TIME_SEC).sort((a, b) => b.start - a.start)[0];
+  const after = scenes.filter((scene) => Math.abs(scene.start - time) < SAME_TIME_SEC).sort((a, b) => a.end - b.end)[0];
+  const next = after ?? scenes.find((scene) => scene.start > time);
+  return { from: before?.id ?? null, to: next?.id ?? null };
+}
+function pad(index) {
+  return String(index).padStart(2, "0");
+}
+function stamp(time) {
+  return `${Number(time.toFixed(3))}s`;
+}
+var SEAM_TILE_LABELS = ["cut -0.2", "-0.1", "cut", "+0.1", "+0.2"];
+function reviewFrames(plan) {
+  const beats = plan.beats.map((beat, index) => ({
+    role: "beat",
+    index: index + 1,
+    time: beat.time,
+    label: beat.label,
+    file: `beat-${pad(index + 1)}-at-${stamp(beat.time)}.png`
+  }));
+  const seams = plan.seams.flatMap(
+    (seam, index) => seam.times.map((time, slot) => ({
+      role: "seam",
+      index: index + 1,
+      time,
+      label: slot === 2 ? `cut ${seam.from ?? "start"} -> ${seam.to ?? "end"}` : SEAM_TILE_LABELS[slot] ?? "",
+      file: `seam-${pad(index + 1)}-${slot + 1}-at-${stamp(time)}.png`
+    }))
+  );
+  return [...beats, ...seams];
+}
+var BEAT_SHEET_PAGE = 16;
+async function writeReviewSheets(dir, frames, written) {
+  const { createContactSheet } = await import("./contactSheet-7W6GYHBQ.js");
+  const { join: join2 } = await import("path");
+  const captured = frames.flatMap((frame) => {
+    const path = written(frame);
+    return path ? [{ frame, path }] : [];
+  });
+  const beats = captured.filter((entry) => entry.frame.role === "beat");
+  const beatLabel = ({ frame }) => `${stamp(frame.time)} ${frame.label}`;
+  const pages = async (name, cellWidth, colsFor) => {
+    const sheets = [];
+    for (let start = 0; start < beats.length; start += BEAT_SHEET_PAGE) {
+      const page = beats.slice(start, start + BEAT_SHEET_PAGE);
+      const suffix = beats.length > BEAT_SHEET_PAGE ? `-${start / BEAT_SHEET_PAGE + 1}` : "";
+      const sheet = await createContactSheet(
+        page.map((entry) => entry.path),
+        join2(dir, `${name}${suffix}.jpg`),
+        {
+          cols: colsFor(page.length),
+          maxImages: page.length,
+          cellWidth,
+          labelMode: "custom",
+          labels: page.map(beatLabel)
+        }
+      );
+      if (sheet) sheets.push(sheet);
+    }
+    return sheets;
+  };
+  const seams = [];
+  const seamNumbers = [
+    ...new Set(captured.filter((e) => e.frame.role === "seam").map((e) => e.frame.index))
+  ];
+  for (const index of seamNumbers) {
+    const strip = captured.filter((e) => e.frame.role === "seam" && e.frame.index === index);
+    const sheet = await createContactSheet(
+      strip.map((entry) => entry.path),
+      join2(dir, `review-seam-${pad(index)}.jpg`),
+      {
+        cols: strip.length,
+        maxImages: strip.length,
+        cellWidth: 384,
+        labelMode: "custom",
+        labels: strip.map(({ frame }) => `${stamp(frame.time)} ${frame.label}`)
+      }
+    );
+    if (sheet) seams.push(sheet);
+  }
+  return {
+    beats: await pages("review-beats", 480, (count) => count <= 3 ? count : count <= 9 ? 3 : 4),
+    seams,
+    phone: await pages("review-phone", REVIEW_PHONE_WIDTH, (count) => Math.min(4, count))
+  };
+}
+
+// src/commands/snapshot.ts
+function orbitStageSource() {
+  return `function(cam) {
+    var root = document.querySelector("[data-composition-id]")
+      || document.querySelector("#stage")
+      || document.body.firstElementChild
+      || document.body;
+    var n = root;
+    while (n && n !== document.body) {
+      n.style.transformStyle = "preserve-3d";
+      n.style.perspective = "none";
+      n = n.parentElement;
+    }
+    root.style.transformStyle = "preserve-3d";
+    root.style.perspective = "none";
+    root.style.transformOrigin = "50% 50%";
+    root.style.transform = "rotateX(" + cam.pitch + "deg) rotateY(" + cam.yaw + "deg)";
+    var lens = root.parentElement || document.body;
+    lens.style.perspective = "1600px";
+    lens.style.perspectiveOrigin = "50% 50%";
+  }`;
+}
+var FFMPEG_EXTRACT_TIMEOUT_MS = 3e4;
+var VIDEO_FRAME_EXTRACT_CONCURRENCY = 4;
+function formatSnapshotTimestamp(time) {
+  return `${Number(time.toFixed(3))}s`;
+}
+var SNAPSHOT_IMAGE_NAME = /^(?:(?:frame-\d+-|ref-(?:\d+-)?)?at-[\d.]+s\.png|pair-(?:\d+-)?at-[\d.]+s\.jpg|(?:beat-\d+|seam-\d+-\d+)-at-[\d.]+s\.png|(?:contact-sheet|review-beats|review-phone)(?:-\d+)?\.jpg|review-seam-\d+\.jpg)$/;
+function assertDistinctKeepNames(times) {
+  const timeByLabel = /* @__PURE__ */ new Map();
+  for (const time of times) {
+    const label = formatSnapshotTimestamp(time);
+    const other = timeByLabel.get(label);
+    if (other !== void 0 && other !== time) {
+      throw new Error(
+        `--keep would name both ${other} and ${time} at-${label}.png; pass times at least 1 ms apart`
+      );
+    }
+    timeByLabel.set(label, time);
+  }
+}
+function resolveSnapshotVideoFrameTime(input) {
+  const { globalTime, clipStart, clipDuration, sourceDuration, compositionDuration } = input;
+  const clipEnd = clipStart + clipDuration;
+  if (!isClipVisibleAt(globalTime, clipStart, clipEnd, compositionDuration)) return null;
+  const relativeTime = globalTime < clipStart ? Math.max(0, input.relativeTime) : input.relativeTime;
+  if (relativeTime < 0) return null;
+  const pastSource = sourceDuration > 0 && relativeTime >= sourceDuration;
+  if (isInClipWindow(globalTime, clipStart, clipEnd) && !pastSource) return relativeTime;
+  const sourceEnd = sourceDuration > 0 ? sourceDuration : relativeTime;
+  return Math.max(0, Math.min(relativeTime, sourceEnd - 1 / 30));
+}
+function resolveSnapshotVideoClipStart(input) {
+  return input.runtimeResolvedStart ?? input.authoredStart;
+}
+function resolveSnapshotVideoRateSpec(input) {
+  const authoredRate = Number.parseFloat(input.authoredRate ?? "");
+  const attrs = {
+    "data-playback-rate": Number.isFinite(authoredRate) && authoredRate > 0 ? input.authoredRate : String(input.defaultRate),
+    "data-automation": input.authoredAutomation
+  };
+  return readElementRateSpec({ getAttribute: (name) => attrs[name] ?? null });
+}
+function requireSnapshotFfmpeg(ffmpegPath) {
+  if (ffmpegPath) return ffmpegPath;
+  throw new Error(
+    `FFmpeg is required to extract video frames for snapshots. ${getFFmpegInstallHint()}`
+  );
+}
+async function recaptureSnapshotComposite(page) {
+  const hasPageComposite = await page.evaluate(async () => {
+    const runtimeWindow = window;
+    if (typeof runtimeWindow.__hf_page_composite_resolve !== "function") return false;
+    await runtimeWindow.__hf_page_composite_prepare?.();
+    return true;
+  });
+  if (hasPageComposite) {
+    await page.screenshot({
+      type: "jpeg",
+      quality: 1,
+      clip: { x: 0, y: 0, width: 1, height: 1 }
+    });
+    await page.evaluate(() => {
+      const runtimeWindow = window;
+      runtimeWindow.__hf_page_composite_resolve?.();
+    });
+  }
+}
+function containingSourceFrameIndex(timestamps, time) {
+  if (!Number.isFinite(time)) return -1;
+  const tolerance = 16 * Number.EPSILON * Math.max(1, Math.abs(time));
+  let index = -1;
+  for (const [i, timestamp] of timestamps.entries()) {
+    if (timestamp > time + tolerance) break;
+    index = i;
+  }
+  return index;
+}
+async function probeContainingSourceFrameSeek(videoPath, time, holdLastFrame) {
+  const ffprobe = findFFprobe();
+  if (!ffprobe) return { seek: time };
+  const probe = async (readIntervals, entries) => {
+    try {
+      const { stdout } = await runCancellableProcess(
+        ffprobe,
+        [
+          ...["-v", "error", "-select_streams", "v:0", "-read_intervals", readIntervals],
+          ...["-show_entries", entries, "-of", "json", "--", videoPath]
+        ],
+        { timeoutMs: FFMPEG_EXTRACT_TIMEOUT_MS, maxBufferBytes: 32 * 1024 * 1024 }
+      );
+      const parsed = JSON.parse(stdout);
+      return typeof parsed === "object" && parsed !== null ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+  const data = await probe("%+#1", "stream=time_base,start_pts:format=start_time,duration");
+  if (data === null || !Array.isArray(data.streams)) return null;
+  const stream = data.streams[0];
+  if (typeof stream !== "object" || stream === null || !("time_base" in stream) || typeof stream.time_base !== "string")
+    return null;
+  const [numerator, denominator] = stream.time_base.split("/");
+  const timeBase = Number(numerator) / Number(denominator);
+  if (!Number.isFinite(timeBase) || timeBase <= 0) return null;
+  const format = "format" in data ? data.format : null;
+  const start = typeof format === "object" && format !== null && "start_time" in format ? Number(format.start_time) : 0;
+  const duration = typeof format === "object" && format !== null && "duration" in format ? Number(format.duration) : NaN;
+  if (!holdLastFrame && Number.isFinite(duration) && time >= duration) return null;
+  const formatStart = Number.isFinite(start) ? start : 0;
+  const startPts = "start_pts" in stream && typeof stream.start_pts === "number" ? stream.start_pts : NaN;
+  const startTicks = Math.abs(startPts * timeBase - formatStart) <= 1e-6 ? startPts : formatStart / timeBase;
+  const packetData = await probe(`%${startTicks * timeBase + time + 1}`, "packet=pts,dts,flags");
+  if (packetData === null || !Array.isArray(packetData.packets)) return null;
+  const packets = [];
+  for (const packet of packetData.packets) {
+    if (typeof packet !== "object" || packet === null) return null;
+    const pts = "pts" in packet ? packet.pts : "dts" in packet ? packet.dts : void 0;
+    if (typeof pts !== "number") return null;
+    const dts = "dts" in packet && typeof packet.dts === "number" ? packet.dts : pts;
+    const key = "flags" in packet && typeof packet.flags === "string" && packet.flags.includes("K");
+    packets.push({ pts: (pts - startTicks) * timeBase, dts: (dts - startTicks) * timeBase, key });
+  }
+  const timestamps = packets.map((packet) => packet.pts).sort((a, b) => a - b);
+  const index = Math.max(0, containingSourceFrameIndex(timestamps, time));
+  if (timestamps.length === 0 || !Number.isFinite(time)) return null;
+  const frame = timestamps[index];
+  const previous = timestamps[index - 1] ?? frame - 1e-3;
+  const mid = (previous + frame) / 2;
+  const ffmpeg = findFFmpeg();
+  const landing = async (seek) => {
+    const raw = ffmpeg ? await probeSeekLanding(ffmpeg, videoPath, seek) : null;
+    return raw === null ? null : raw - startTicks * timeBase;
+  };
+  const candidates = packets.filter(
+    (packet) => packet.key && packet.pts > 0 && packet.pts <= frame
+  );
+  for (const candidate of candidates.reverse().slice(0, 3)) {
+    const landed = await landing(candidate.pts);
+    if (landed === null) break;
+    if (landed <= 0 || landed > frame) continue;
+    if (landed < candidate.pts - 1e-6) return { seek: candidate.pts, select: mid - candidate.pts };
+    const again = Math.abs(landed - candidate.pts) < 1e-6 ? landed : await landing(landed);
+    if (again !== null && Math.abs(again - landed) < 1e-6)
+      return { seek: landed, select: mid - landed };
+  }
+  return { select: mid - (timestamps.find((t) => t >= 0) ?? frame) };
+}
+async function probeSeekLanding(ffmpeg, videoPath, seek) {
+  try {
+    const { stdout } = await runCancellableProcess(
+      ffmpeg,
+      [
+        ...["-v", "error", "-copyts", "-noaccurate_seek", "-ss", String(seek), "-i", videoPath],
+        ...["-map", "0:v:0", "-c", "copy", "-frames:v", "1", "-f", "framecrc", "-"]
+      ],
+      { timeoutMs: FFMPEG_EXTRACT_TIMEOUT_MS, maxBufferBytes: 1024 * 1024 }
+    );
+    const base = /^#tb 0: (\d+)\/(\d+)/m.exec(stdout);
+    const row = /^0,\s*-?\d+,\s*(-?\d+),/m.exec(stdout);
+    if (!base || !row) return null;
+    return Number(row[1]) * Number(base[1]) / Number(base[2]);
+  } catch {
+    return null;
+  }
+}
+async function extractVideoFrameToBuffer(videoPath, timeSeconds, useVp9AlphaDecoder = false, holdLastFrame = false, displayedPixels = 0) {
+  const tmp = mkdtempSync(join(tmpdir(), "hf-snapshot-frame-"));
+  const outPath = join(tmp, "frame.png");
+  try {
+    const ffmpegPath = requireSnapshotFfmpeg(findFFmpeg());
+    const seek = await probeContainingSourceFrameSeek(
+      videoPath,
+      Math.max(0, timeSeconds),
+      holdLastFrame
+    );
+    if (seek === null) return null;
+    const args = ["-hide_banner", "-loglevel", "error"];
+    if (useVp9AlphaDecoder) args.push("-c:v", "libvpx-vp9");
+    if (seek.seek !== void 0) args.push("-ss", String(seek.seek));
+    args.push("-i", videoPath, "-map", "0:v:0");
+    const filters = [];
+    if (seek.select !== void 0) filters.push(`select=gte(t-start_t\\,${seek.select})`);
+    if (displayedPixels > 0) {
+      filters.push(
+        `scale='min(iw,${displayedPixels})':'min(ih,${displayedPixels})':force_original_aspect_ratio=increase`
+      );
+    }
+    if (filters.length > 0) args.push("-vf", filters.join(","));
+    args.push("-frames:v", "1", "-q:v", "2", "-y", outPath);
+    const result = await runFfmpegOnce(ffmpegPath, args, FFMPEG_EXTRACT_TIMEOUT_MS);
+    if (result.code !== 0 || result.timedOut || !existsSync(outPath)) return null;
+    return readFileSync(outPath);
+  } finally {
+    try {
+      rmSync(tmp, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+var examples = [
+  ["Capture 5 key frames from a composition", "snapshot capture"],
+  ["Capture 10 evenly-spaced frames", "snapshot capture --frames 10"],
+  ["View the 3D stage from an isometric angle", "snapshot capture --angle iso"],
+  ["Zoom into an element for a high-density crop", "snapshot --zoom '#headline'"],
+  [
+    "Zoom into an exact pixel region at 2x density",
+    "snapshot --zoom 100,50,400,300 --zoom-scale 2"
+  ],
+  [
+    "Pair each frame with the reference footage at the same time",
+    "snapshot --at 1.5,4.3,8.1 --against ref.mp4"
+  ]
+];
+function parseZoomScale(value) {
+  const parsed = parseFloat(String(value ?? ""));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_ZOOM_SCALE;
+}
+function tailFrameTime(duration) {
+  return Math.max(0, duration - Math.max(0.05, duration * 0.03));
+}
+function computeSnapshotTimes(duration, opts) {
+  const includeEnd = opts.includeEnd !== false;
+  const tail = tailFrameTime(duration);
+  const round = (t) => Math.round(t * 1e3) / 1e3;
+  if (opts.at?.length) {
+    const times2 = [...opts.at];
+    const hasTail = times2.some((t) => Math.abs(t - tail) < 0.05 || t >= duration);
+    if (includeEnd && duration > 0 && !hasTail) {
+      return { times: [...times2, round(tail)], appendedTail: true };
+    }
+    return { times: times2, appendedTail: false };
+  }
+  const n = opts.frames;
+  if (n <= 1) return { times: [round(duration / 2)], appendedTail: false };
+  const times = Array.from({ length: n }, (_, i) => i / (n - 1) * duration);
+  if (includeEnd) times[times.length - 1] = tail;
+  return { times: times.map(round), appendedTail: false };
+}
+function serveCapturePage(projectDir, html, proxy) {
+  return serveStaticProjectHtml(projectDir, html, void 0, [], proxy === true);
+}
+async function captureSnapshots(projectDir, opts) {
+  const log = opts.log ?? ((message) => console.log(message));
+  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-ALYBQEQT.js");
+  const capture = await captureArtifactRevision(projectDir).catch(warnSnapshotsNotRecorded);
+  const invocation = randomUUID();
+  const artifacts = [];
+  const replaced = [];
+  const warnings = [];
+  let completed = false;
+  const numFrames = opts.frames ?? 5;
+  let review;
+  let reviewList;
+  const reviewPaths = /* @__PURE__ */ new Map();
+  const html = await bundleWithLocalizedFonts(projectDir);
+  const server = await serveCapturePage(projectDir, html, opts.autoProxy);
+  const savedPaths = [];
+  try {
+    const {
+      browser: chromeBrowser,
+      page,
+      renderReadyTimedOut
+    } = await openSettledCompositionPage(html, server.url, {
+      renderReadyTimeoutMs: opts.timeout ?? 5e3,
+      renderReadyWarningSuffix: "snapshots may be inaccurate",
+      browserGpuMode: opts.browserGpuMode
+    });
+    try {
+      if (renderReadyTimedOut) warnings.push("Render readiness timed out");
+      const fontReport = await page.evaluate(() => {
+        const loaded = [];
+        const errored = [];
+        const unused = [];
+        document.fonts.forEach((f) => {
+          const entry = `${f.family} (${f.weight} ${f.style})`;
+          if (f.status === "loaded") loaded.push(entry);
+          else if (f.status === "error") errored.push(entry);
+          else unused.push(entry);
+        });
+        return { loaded, errored, unused };
+      }).catch(() => ({ loaded: [], errored: [], unused: [] }));
+      if (fontReport.loaded.length > 0 || fontReport.errored.length > 0 || fontReport.unused.length > 0) {
+        const parts = [`${fontReport.loaded.length} loaded`];
+        if (fontReport.errored.length > 0) parts.push(`${fontReport.errored.length} failed`);
+        if (fontReport.unused.length > 0) parts.push(`${fontReport.unused.length} unused`);
+        log(`
+   ${c.dim("Fonts:")} ${parts.join(", ")}`);
+        if (fontReport.errored.length > 0) {
+          log(`   ${c.error("Fonts FAILED:")} ${fontReport.errored.join(", ")}`);
+        }
+      }
+      if (fontReport.errored.length)
+        warnings.push(`Fonts failed: ${fontReport.errored.join(", ")}`);
+      const duration = await page.evaluate(() => {
+        const win = window;
+        if (typeof win.__player?.getDuration === "function") {
+          const d = win.__player.getDuration();
+          if (Number.isFinite(d) && d > 0) return d;
+        }
+        const root = document.querySelector("[data-composition-id][data-duration]");
+        if (root) return parseFloat(root.getAttribute("data-duration") ?? "0");
+        return 0;
+      });
+      if (duration <= 0 && !opts.at?.length) {
+        return { paths: [], warnings };
+      }
+      const readTiming = () => page.evaluate(() => ({
+        html: document.documentElement.outerHTML,
+        durations: Object.fromEntries(
+          Object.entries(window.__timelines ?? {}).map(([id, timeline]) => [
+            id,
+            Number(timeline.duration?.())
+          ])
+        )
+      }));
+      let range = opts.range;
+      if (opts.composition && !opts.review) {
+        const timing = await readTiming();
+        range = resolveSnapshotCompositionRange(
+          timing.html,
+          timing.durations,
+          opts.composition,
+          duration
+        );
+      }
+      if (opts.review) {
+        const timing = await readTiming();
+        const timeline = resolveReviewTimeline(
+          timing.html,
+          timing.durations,
+          duration,
+          opts.composition
+        );
+        review = planReview(timeline, Math.min(timeline.window[1], duration) - 1 / 30);
+        reviewList = reviewFrames(review);
+      }
+      const { times: positions, appendedTail } = reviewList ? { times: reviewList.map((frame) => frame.time), appendedTail: false } : range ? {
+        times: sampleSnapshotRange(range, numFrames, duration, !!opts.composition),
+        appendedTail: false
+      } : computeSnapshotTimes(duration, {
+        frames: numFrames,
+        at: opts.at,
+        includeEnd: opts.includeEnd
+      });
+      if (range)
+        log(
+          `   Sampling ${positions.length} frames within ${range[0]}\u2013${range[1]}s${opts.composition ? ` (composition ${opts.composition})` : ""}`
+        );
+      if (review)
+        log(
+          `   Review: ${review.beats.length} beat(s) and ${review.seams.length} seam(s) within ${review.window[0]}\u2013${review.window[1]}s${opts.composition ? ` (composition ${opts.composition})` : ""}`
+        );
+      if (appendedTail) {
+        log(
+          `   ${c.dim(`Note: added an end-of-timeline frame at ${positions[positions.length - 1].toFixed(2)}s. Short beats between your --at times may still be skipped \u2014 pass them explicitly.`)}`
+        );
+      }
+      const cameraExpr = opts.angle && (opts.angle.yaw !== 0 || opts.angle.pitch !== 0) ? `(${orbitStageSource()})(${JSON.stringify(opts.angle)})` : null;
+      const snapshotDir = opts.outputDir ?? artifactDirectory(projectDir, "snapshots");
+      mkdirSync(snapshotDir, { recursive: true });
+      try {
+        const { readdirSync } = await import("fs");
+        for (const file of opts.keep ? [] : readdirSync(snapshotDir)) {
+          if (SNAPSHOT_IMAGE_NAME.test(file)) {
+            const path = resolve(snapshotDir, file);
+            replaced.push(path);
+            rmSync(path, { force: true });
+          }
+        }
+      } catch {
+      }
+      let injectVideoFramesBatch = null;
+      let syncVideoFrameVisibility = null;
+      let extractMediaMetadata = null;
+      try {
+        const engine = await import("./src-Z5PGEMXB.js");
+        injectVideoFramesBatch = engine.injectVideoFramesBatch;
+        syncVideoFrameVisibility = engine.syncVideoFrameVisibility;
+        extractMediaMetadata = engine.extractMediaMetadata;
+      } catch {
+        warnings.push("Video frame extraction engine unavailable");
+        console.warn(
+          `   ${c.warn("\u26A0")} @framey/engine unavailable \u2014 <video> elements will appear black in snapshots. Verify media via a draft render's extracted frames instead.`
+        );
+      }
+      const alphaDecoderCache = /* @__PURE__ */ new Map();
+      const shouldUseVp9AlphaDecoder = (filePath) => {
+        if (!extractMediaMetadata) return Promise.resolve(false);
+        const cached = alphaDecoderCache.get(filePath);
+        if (cached) return cached;
+        const pending = extractMediaMetadata(filePath).then((meta) => meta.hasAlpha && meta.videoCodec === "vp9").catch(() => false);
+        alphaDecoderCache.set(filePath, pending);
+        return pending;
+      };
+      const hasPlayer = await page.evaluate(() => !!window.__player);
+      if (!hasPlayer) {
+        console.warn(`   ${c.warn("\u26A0")} No player API \u2014 seeks will be skipped`);
+      }
+      for (let i = 0; i < positions.length; i++) {
+        const time = positions[i];
+        const seekOptions = { exactTime: true, waitForImagesMs: SCREENSHOT_IMAGE_WAIT_MS };
+        await seekCompositionTimelineOnly(page, time, seekOptions);
+        if (cameraExpr) await page.evaluate(cameraExpr);
+        if (injectVideoFramesBatch && syncVideoFrameVisibility) {
+          const candidates = await page.evaluate(() => {
+            const runtimeWindow = window;
+            return Array.from(document.querySelectorAll("video")).map((el) => {
+              const v = el;
+              const box = v.getBoundingClientRect();
+              const authoredStart = parseFloat(v.dataset.start ?? "0") || 0;
+              const runtimeResolvedStart = runtimeWindow.__hfResolveMediaStartSeconds?.(v);
+              const mediaStart = parseFloat(v.dataset.playbackStart ?? v.dataset.mediaStart ?? "0") || 0;
+              const rawDuration = parseFloat(v.dataset.duration ?? "");
+              const srcDur = Number.isFinite(v.duration) && v.duration > 0 ? v.duration : 0;
+              return {
+                id: runtimeWindow.__hfMediaId?.(v) || v.id,
+                src: v.currentSrc || v.src,
+                authoredStart,
+                authoredRate: v.dataset.playbackRate,
+                authoredAutomation: v.dataset.automation,
+                defaultRate: v.defaultPlaybackRate,
+                runtimeResolvedStart: runtimeResolvedStart !== void 0 && Number.isFinite(runtimeResolvedStart) ? runtimeResolvedStart : null,
+                authoredDuration: Number.isFinite(rawDuration) && rawDuration > 0 ? rawDuration : null,
+                srcDuration: srcDur,
+                mediaStart,
+                loop: v.loop,
+                displayedSize: Math.max(box.width, box.height),
+                devicePixelRatio: window.devicePixelRatio
+              };
+            });
+          });
+          const compositionDuration = duration;
+          const active = candidates.flatMap((candidate) => {
+            const start = resolveSnapshotVideoClipStart(candidate);
+            const playbackRate = resolveSnapshotVideoRateSpec(candidate);
+            const duration2 = candidate.authoredDuration ?? (candidate.srcDuration > 0 ? Math.max(
+              0,
+              timeAtSourceTime(playbackRate, candidate.srcDuration - candidate.mediaStart)
+            ) : Number.POSITIVE_INFINITY);
+            let relTime = sourceTimeAt(playbackRate, time - start) + candidate.mediaStart;
+            if (candidate.loop && candidate.srcDuration > candidate.mediaStart && relTime >= candidate.srcDuration) {
+              relTime = candidate.mediaStart + (relTime - candidate.mediaStart) % (candidate.srcDuration - candidate.mediaStart);
+            }
+            if (!candidate.id || !candidate.src) return [];
+            const frameTime = resolveSnapshotVideoFrameTime({
+              globalTime: time,
+              clipStart: start,
+              clipDuration: duration2,
+              relativeTime: relTime,
+              sourceDuration: candidate.srcDuration,
+              compositionDuration
+            });
+            return frameTime === null ? [] : [{ ...candidate, start, playbackRate, duration: duration2, relTime: frameTime }];
+          });
+          const extracted = await runWithConcurrencyLimit(
+            active,
+            VIDEO_FRAME_EXTRACT_CONCURRENCY,
+            async (v) => {
+              let ffmpegInput = null;
+              let inputIsLocal = false;
+              try {
+                const url = new URL(v.src);
+                const decodedPath = decodeURIComponent(url.pathname).replace(/^\//, "");
+                const candidate = resolve(projectDir, decodedPath);
+                const rel2 = relative(projectDir, candidate);
+                if (!rel2.startsWith("..") && !isAbsolute(rel2) && existsSync(candidate)) {
+                  ffmpegInput = candidate;
+                  inputIsLocal = true;
+                } else if (url.protocol === "http:" || url.protocol === "https:") {
+                  ffmpegInput = url.href;
+                }
+              } catch {
+              }
+              if (!ffmpegInput) return null;
+              const useVp9AlphaDecoder = inputIsLocal ? await shouldUseVp9AlphaDecoder(ffmpegInput) : false;
+              const png = await extractVideoFrameToBuffer(
+                ffmpegInput,
+                Math.max(0, v.relTime),
+                useVp9AlphaDecoder,
+                v.srcDuration > 0 && v.relTime >= v.srcDuration - 1,
+                Math.ceil(
+                  v.displayedSize * (opts.zoom ? opts.zoomScale ?? DEFAULT_ZOOM_SCALE : v.devicePixelRatio)
+                )
+              );
+              if (!png) return null;
+              return { videoId: v.id, dataUri: `data:image/png;base64,${png.toString("base64")}` };
+            }
+          );
+          const updates = extracted.filter((update) => update !== null);
+          if (active.length > 0 && updates.length < active.length) {
+            const missed = active.length - updates.length;
+            warnings.push(`${missed} video frames missing at ${time}s`);
+            console.warn(
+              `   ${c.warn("\u26A0")} ${missed}/${active.length} active <video> frame(s) could not be extracted at ${time.toFixed(1)}s \u2014 those videos will appear black/stale in this snapshot`
+            );
+          }
+          try {
+            if (updates.length > 0) {
+              await injectVideoFramesBatch(page, updates);
+            }
+            await syncVideoFrameVisibility(
+              page,
+              active.map((a) => a.id)
+            );
+          } catch {
+            warnings.push(`Video injection failed at ${time}s`);
+            console.warn(
+              `   ${c.warn("\u26A0")} video frame injection failed at ${time.toFixed(1)}s \u2014 <video> elements will appear black/stale in this snapshot`
+            );
+          }
+        }
+        warnUnsettledImages(await settleCompositionSeek(page, seekOptions), time, warnings);
+        await recaptureSnapshotComposite(page);
+        const timeLabel = formatSnapshotTimestamp(time);
+        const slot = opts.keep ? `at-${timeLabel}` : `${String(i).padStart(2, "0")}-at-${timeLabel}`;
+        const reviewFrame = reviewList?.[i];
+        const filename = reviewFrame ? reviewFrame.file : opts.keep ? `${slot}.png` : `frame-${slot}.png`;
+        const framePath = join(snapshotDir, filename);
+        let crop;
+        if (opts.zoom) {
+          const canvas = await page.evaluate(() => ({
+            width: window.innerWidth,
+            height: window.innerHeight
+          }));
+          const region = await resolveCropRegion(page, opts.zoom, canvas);
+          if (!region) {
+            warnings.push(`Crop target unavailable at ${time}s`);
+            console.error(
+              `   ${c.warn("\u26A0")} --zoom target has no visible box at ${time.toFixed(1)}s \u2014 frame skipped`
+            );
+            continue;
+          }
+          crop = region;
+          const buffer = await captureRegionCrop(
+            page,
+            region,
+            opts.zoomScale ?? DEFAULT_ZOOM_SCALE
+          );
+          writeCaptureFileSync(framePath, buffer);
+        } else {
+          writeCaptureFileSync(
+            framePath,
+            await page.screenshot({ type: "png", omitBackground: true })
+          );
+        }
+        artifacts.push({
+          id: `${invocation}-${i}`,
+          image: resolve(framePath),
+          time,
+          metadata: {
+            ...pngDimensions(framePath),
+            crop,
+            zoom: opts.zoom,
+            zoomScale: opts.zoom ? opts.zoomScale ?? DEFAULT_ZOOM_SCALE : 1,
+            angle: opts.angle,
+            browserGpuMode: opts.browserGpuMode,
+            ...reviewFrame ? { review: { role: reviewFrame.role, label: reviewFrame.label } } : {}
+          }
+        });
+        if (reviewFrame) reviewPaths.set(reviewFrame, framePath);
+        if (opts.against) {
+          const refPng = await extractVideoFrameToBuffer(opts.against, time);
+          if (!refPng) {
+            console.error(
+              `   ${c.warn("\u26A0")} --against has no frame at ${timeLabel} \u2014 reference pair skipped`
+            );
+          } else {
+            const refPath = join(snapshotDir, `ref-${slot}.png`);
+            writeCaptureFileSync(refPath, refPng);
+            const pairPath = join(snapshotDir, `pair-${slot}.jpg`);
+            const { createContactSheet } = await import("./contactSheet-7W6GYHBQ.js");
+            await createContactSheet([framePath, refPath], pairPath, {
+              cols: 2,
+              maxImages: 2,
+              cellWidth: 960,
+              labelMode: "custom",
+              labels: ["render", "reference"]
+            });
+          }
+        }
+        const rel = relative(projectDir, framePath);
+        savedPaths.push(rel.startsWith("..") || isAbsolute(rel) ? framePath : rel);
+      }
+      completed = true;
+    } finally {
+      await chromeBrowser.close();
+    }
+  } finally {
+    await server.close();
+    const recorded = capture ? await recordSnapshotArtifacts(
+      projectDir,
+      capture,
+      artifacts,
+      opts.zoom,
+      warnings,
+      completed,
+      log
+    ) : false;
+    if (!recorded) {
+      const paths = [...replaced, ...artifacts.map((artifact) => artifact.image)];
+      if (paths.length > 0) await forgetRecordedArtifacts(projectDir, paths).catch(() => void 0);
+    }
+  }
+  return {
+    paths: savedPaths,
+    warnings,
+    ...review && reviewList ? {
+      review: {
+        plan: review,
+        frames: reviewList.flatMap((frame) => {
+          const path = reviewPaths.get(frame);
+          return path ? [{ ...frame, path }] : [];
+        })
+      }
+    } : {}
+  };
+}
+function warnUnsettledImages(images, time, warnings) {
+  const groups = [
+    [images.pending, `did not finish loading within ${SCREENSHOT_IMAGE_WAIT_MS} ms`],
+    [images.failed, "failed to load"]
+  ];
+  for (const [sources, what] of groups) {
+    if (sources.length === 0) continue;
+    const message = `${sources.length} image(s) ${what} at ${time}s, so the frame may be missing them: ${sources.join(", ")}`;
+    warnings.push(message);
+    console.warn(`   ${c.warn("\u26A0")} ${message}`);
+  }
+}
+function warnSnapshotsNotRecorded(error) {
+  console.warn(`   ${c.warn("\u26A0")} Snapshots were not recorded: ${normalizeErrorMessage(error)}`);
+  return void 0;
+}
+async function recordSnapshotArtifacts(projectDir, capture, artifacts, zoom, warnings, completed, log) {
+  const records = await recordArtifacts(
+    projectDir,
+    capture,
+    artifacts.map((artifact) => ({
+      kind: "snapshot",
+      scope: zoom ? "crop" : "full",
+      ...artifact,
+      metadata: { ...artifact.metadata, warnings, partial: !completed || warnings.length > 0 }
+    }))
+  ).catch(warnSnapshotsNotRecorded);
+  const record = records?.[0];
+  if (!record) return false;
+  log(`   Revision: ${record.revision ?? "none"} (${record.attribution})`);
+  log(`   State: ${join(projectDir, ".hyperframes", "video-state.json")}`);
+  return true;
+}
+function snapshotEnvelope(projectDir, outputDir, captured, extra) {
+  const review = captured.review;
+  const frames = review ? review.frames.map((frame) => ({
+    path: frame.path,
+    time: frame.time,
+    role: frame.role,
+    label: frame.label
+  })) : captured.paths.map((path) => ({ path: resolve(projectDir, path), time: timeFromName(path) }));
+  return {
+    ok: true,
+    outputDir,
+    frames,
+    contactSheets: extra.contactSheets.map((sheet) => resolve(sheet)),
+    ...captured.warnings.length > 0 ? { warnings: captured.warnings } : {},
+    ...extra.describedPath ? { descriptions: extra.describedPath } : {},
+    ...review ? {
+      review: {
+        window: review.plan.window,
+        scenes: review.plan.scenes,
+        beats: review.plan.beats.map((beat, index) => ({
+          ...beat,
+          path: review.frames.find(
+            (frame) => frame.role === "beat" && frame.index === index + 1
+          )?.path
+        })),
+        seams: review.plan.seams.map((seam, index) => ({
+          ...seam,
+          paths: review.frames.filter((frame) => frame.role === "seam" && frame.index === index + 1).map((frame) => frame.path),
+          sheet: extra.reviewSheets?.seams[index]
+        })),
+        sheets: extra.reviewSheets ?? { beats: [], seams: [], phone: [] },
+        notes: review.plan.notes
+      }
+    } : {}
+  };
+}
+function timeFromName(path) {
+  const match = /at-([\d.]+)s\.png$/.exec(path);
+  return match ? Number(match[1]) : null;
+}
+function printReview(review, sheets, log) {
+  const beats = review.plan.beats.map(
+    (beat) => `${formatSnapshotTimestamp(beat.time)} ${beat.label}`
+  );
+  log(`   Beat sheet (settled frame per scene): ${sheets.beats.join(", ") || "none"}`);
+  log(`     ${c.dim(beats.join(" \xB7 "))}`);
+  review.plan.seams.forEach((seam, index) => {
+    const sides = `${seam.from ?? "start"} -> ${seam.to ?? "end"}`;
+    const strip = sheets.seams[index] ?? "not written";
+    log(`   Seam ${index + 1} at ${formatSnapshotTimestamp(seam.time)} (${sides}): ${strip}`);
+  });
+  log(
+    `   Phone sheet (beats at ${REVIEW_PHONE_WIDTH} px wide): ${sheets.phone.join(", ") || "none"}`
+  );
+  for (const note of review.plan.notes) log(`   ${c.dim(note)}`);
+}
+var snapshot_default = defineCommand({
+  meta: {
+    name: "snapshot",
+    description: "Capture key frames from a composition as PNG screenshots for visual verification"
+  },
+  args: {
+    dir: {
+      type: "positional",
+      description: "Project directory",
+      required: false
+    },
+    output: {
+      type: "string",
+      alias: "o",
+      description: "Directory to write snapshots into (default: unique directory under <project>/.hyperframes/artifacts/snapshots)"
+    },
+    frames: {
+      type: "string",
+      description: "Number of evenly-spaced frames to capture (default: 5)",
+      default: "5"
+    },
+    at: {
+      type: "string",
+      description: "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0). Each is captured at that exact instant, not snapped to a frame."
+    },
+    range: {
+      type: "string",
+      description: "Root-timeline range START,END in seconds; sample --frames evenly within it, without adding the full-video tail"
+    },
+    composition: {
+      type: "string",
+      description: "data-composition-id to sample; take --frames within its effective root-timeline interval, without adding the full-video tail"
+    },
+    timeout: {
+      type: "string",
+      description: "Ms to wait for runtime to initialize (default: 5000)",
+      default: "5000"
+    },
+    angle: {
+      type: "string",
+      description: "Orthogonal 3D camera for depth/occlusion checks: a preset (front|iso|top|side) or 'yaw,pitch' degrees. Tilts the whole stage before screenshotting (real pixels, not bbox markers)."
+    },
+    end: {
+      type: "boolean",
+      description: "Always include a readable end-of-timeline frame (default: true). Pass --no-end to capture only your exact --at times.",
+      default: true
+    },
+    keep: {
+      type: "boolean",
+      description: "Add to --output instead of clearing it, naming each still at-<seconds>s.png (at-0s, at-1.5s, at-12.25s: no trailing zeros), so snapshotting one moment again replaces only that still. Times less than 1 ms apart share a name, so one run may not pass two of them. No contact sheet.",
+      default: false
+    },
+    zoom: {
+      type: "string",
+      description: "Zoom into a CSS selector or an exact pixel region 'x,y,w,h'. Crops a high-density screenshot instead of the full frame \u2014 a raised deviceScaleFactor, never CSS zoom or viewport resizing, so layout stays identical. A selector matching nothing is an error, not a silent full-frame shot."
+    },
+    "zoom-scale": {
+      type: "string",
+      description: "Device-scale-factor density for --zoom crops (default: 3)",
+      default: "3"
+    },
+    against: {
+      type: "string",
+      description: "Reference video (e.g. footage being rebuilt): also save its frame at each captured time and a render|reference pair sheet"
+    },
+    review: {
+      type: "boolean",
+      description: "Capture the review set instead of evenly spaced frames: each scene at its start + 0.3 s and its middle, and each data-beat at its start + 0.3 s, on review-beats.jpg, a 5-frame strip around every cut (review-seam-NN.jpg), and the beat frames at phone width (review-phone.jpg). Scopes to --composition; ignores --frames.",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Print one JSON envelope (paths, times, sheets; the review plan under --review)",
+      default: false
+    },
+    describe: {
+      type: "string",
+      description: "Gemini vision frame analysis. Runs by default when GEMINI_API_KEY is set. Pass a custom question (e.g. --describe 'Is the logo visible in every beat?') to override the default prompt, or --describe false to opt out."
+    },
+    proxy: {
+      type: "boolean",
+      description: "Serve browser-playable copies of hostile video codecs to the snapshot page (default: off; frames come from FFmpeg, and each copy transcodes the whole clip)",
+      default: void 0
+    },
+    "browser-gpu": {
+      type: "boolean",
+      description: "Use hardware browser GPU capture; pass --no-browser-gpu for deterministic SwiftShader (default: auto-detect, PRODUCER_BROWSER_GPU_MODE overrides)",
+      default: void 0
+    }
+  },
+  async run({ args }) {
+    const asJson = args.json === true;
+    const log = (message) => asJson ? console.error(message) : console.log(message);
+    const fail = (message) => {
+      if (asJson) console.log(JSON.stringify(withMeta({ ok: false, error: message }), null, 2));
+      else log(message);
+      failCommand();
+    };
+    if ([args.at, args.range, args.composition].filter((value) => value !== void 0).length > 1)
+      throw new Error("Use only one of --at, --range, or --composition");
+    const reviewMode = args.review === true;
+    if (reviewMode) {
+      const clash = ["at", "range", "zoom", "keep", "against"].find(
+        (flag) => args[flag] !== void 0 && args[flag] !== false
+      );
+      if (clash) throw new Error(`--review picks its own frames; drop --${clash}`);
+    }
+    const frames = parseInt(args.frames, 10) || 5;
+    const range = args.range === void 0 ? void 0 : parseSnapshotRange(String(args.range));
+    const atTimestamps = args.at === void 0 ? void 0 : parseSnapshotAt(String(args.at));
+    if (args.keep === true && atTimestamps) assertDistinctKeepNames(atTimestamps);
+    const composition = args.composition === void 0 ? void 0 : String(args.composition).trim();
+    if (composition === "") throw new Error("--composition requires a composition ID");
+    const project = resolveProject(args.dir);
+    const lintResult = await lintProject(project.dir);
+    if (hasDefinitiveEntryMismatch(lintResult)) {
+      const candidate = definitiveEntryMismatchComposition(lintResult);
+      log("");
+      for (const line of formatLintFindings(lintResult, { errorsFirst: true })) {
+        log(line);
+      }
+      log("");
+      log(c.error("  Aborting snapshot because the default index.html entry is blank."));
+      if (candidate && posix.basename(candidate) === "index.html") {
+        const candidateDir = posix.dirname(candidate);
+        const target = `<project>/${candidateDir}`;
+        log(
+          c.dim(
+            `  Move or mount the authored file, or snapshot its directory directly: framey snapshot ${target}. Only use the directory form when its assets are self-contained under that directory; otherwise mount it from the project root.`
+          )
+        );
+      } else if (candidate) {
+        log(
+          c.dim(
+            `  Move or mount ${candidate} as a project index.html before snapshotting; snapshot accepts project directories, not individual HTML files.`
+          )
+        );
+      }
+      log("");
+      if (asJson) {
+        const error = "The default index.html entry is blank; see the lint findings on stderr.";
+        console.log(JSON.stringify(withMeta({ ok: false, error }), null, 2));
+      }
+      failCommand();
+    }
+    const timeout = parseInt(args.timeout, 10) || 5e3;
+    const describeArg = args.describe === void 0 ? "true" : String(args.describe) === "false" ? null : String(args.describe);
+    const camera = args.angle ? parseAngle(String(args.angle)) : void 0;
+    const zoomTarget = args.zoom ? parseZoomTarget(String(args.zoom)) : void 0;
+    const zoomScale = parseZoomScale(args["zoom-scale"]);
+    const against = args.against ? resolve(String(args.against)) : void 0;
+    if (against && !existsSync(against))
+      fail(`${c.error("\u2717")} --against video not found: ${against}`);
+    const label = reviewMode ? "review frames (beats, seams, phone)" : atTimestamps ? `${atTimestamps.length} frames at [${atTimestamps.map(formatSnapshotTimestamp).join(", ")}]` : `${frames} frames`;
+    const angleLabel = camera && (camera.yaw !== 0 || camera.pitch !== 0) ? ` ${c.dim(`(angle yaw ${camera.yaw}\xB0 pitch ${camera.pitch}\xB0)`)}` : "";
+    log(`${c.accent("\u25C6")}  Capturing ${label} from ${c.accent(project.name)}${angleLabel}`);
+    let managedSnapshotDir;
+    try {
+      const snapshotDir = args.output ? resolve(String(args.output)) : artifactDirectory(project.dir, "snapshots");
+      if (!args.output) managedSnapshotDir = snapshotDir;
+      if (args.output) retainSnapshotOutput(project.dir, snapshotDir);
+      await withProjectLock(project.dir, "snapshot", async () => {
+        const captured = await captureSnapshots(project.dir, {
+          frames,
+          range,
+          composition,
+          timeout,
+          at: atTimestamps,
+          outputDir: snapshotDir,
+          angle: camera,
+          includeEnd: args.end !== false,
+          zoom: zoomTarget,
+          zoomScale,
+          autoProxy: args.proxy,
+          browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"]),
+          against,
+          keep: args.keep === true,
+          review: reviewMode,
+          log
+        });
+        const paths = captured.paths;
+        const framePaths = paths.map((path) => resolve(project.dir, path));
+        reportArtifacts("snapshot", "frame", framePaths);
+        if (paths.length === 0) {
+          fail(`
+${c.error("\u2717")} Could not determine composition duration \u2014 no frames captured`);
+        }
+        log(`
+${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
+        for (const p of paths) {
+          log(`   ${p}`);
+        }
+        if (against) {
+          log(
+            `   ${c.dim("ref-*.png + pair-*.jpg")} beside each frame (reference frame, render | reference sheet)`
+          );
+        }
+        let contactSheets = [];
+        let reviewSheets;
+        try {
+          const { createSnapshotContactSheet } = await import("./contactSheet-7W6GYHBQ.js");
+          if (captured.review) {
+            const written = new Map(
+              captured.review.frames.map((frame) => [frame.file, frame.path])
+            );
+            reviewSheets = await writeReviewSheets(
+              snapshotDir,
+              captured.review.frames,
+              (frame) => written.get(frame.file) ?? null
+            );
+            contactSheets = [...reviewSheets.beats, ...reviewSheets.seams, ...reviewSheets.phone];
+            printReview(captured.review, reviewSheets, log);
+          } else if (args.keep !== true) {
+            contactSheets = await createSnapshotContactSheet(
+              framePaths,
+              join(snapshotDir, "contact-sheet.jpg")
+            );
+          }
+          reportArtifacts("snapshot", "contact-sheet", contactSheets);
+          if (!captured.review) {
+            for (const sheet of contactSheets) {
+              log(`   ${resolve(sheet)} (grid view for AI review)`);
+            }
+          }
+        } catch (err) {
+          console.warn(
+            `   ${c.warn("\u26A0")} Contact sheet skipped: ${normalizeErrorMessage(err)}. Individual snapshot PNGs are still available.`
+          );
+        }
+        let describedPath;
+        if (describeArg !== null) {
+          try {
+            const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+            if (!geminiKey) {
+              if (args.describe !== void 0)
+                log(`   ${c.dim("--describe: GEMINI_API_KEY not set, skipping")}`);
+            } else if (paths.length > 0) {
+              log(`   ${c.dim("Describing frames with Gemini vision...")}`);
+              const { GoogleGenAI } = await loadOptionalPackage("@google/genai", "--describe");
+              const ai = new GoogleGenAI({ apiKey: geminiKey });
+              const model = process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview";
+              const customQuestion = describeArg === "true" ? "Describe this video composition frame in 1-2 sentences. Be specific and factual: what elements are visible, what text appears, is the frame blank/black/loading, what is the composition. Flag any obvious problems." : describeArg;
+              const descriptions = [
+                `# Snapshot Frame Descriptions`,
+                ``,
+                `**Question asked:** ${customQuestion}`,
+                ``,
+                `Compare each description against your storyboard spec. A "black frame" or "loading screen" for a content beat is a bug.`,
+                ``
+              ];
+              let sharp = null;
+              try {
+                sharp = loadInstalledSharp("--describe");
+              } catch {
+              }
+              const results = await Promise.allSettled(
+                paths.map(async (p) => {
+                  const filename = basename(p);
+                  const filePath = join(snapshotDir, filename);
+                  if (!existsSync(filePath)) return { filename, desc: "file not found" };
+                  const raw = readFileSync(filePath);
+                  let imageData;
+                  let mimeType = "image/png";
+                  if (sharp) {
+                    imageData = await sharp(raw).resize(960).jpeg().toBuffer();
+                    mimeType = "image/jpeg";
+                  } else {
+                    if (raw.length > 38e5)
+                      return {
+                        filename,
+                        desc: "file too large for Gemini \u2014 install sharp to enable auto-resize"
+                      };
+                    imageData = raw;
+                  }
+                  const base64 = imageData.toString("base64");
+                  const response = await ai.models.generateContent({
+                    model,
+                    contents: [
+                      {
+                        role: "user",
+                        parts: [
+                          { inlineData: { mimeType, data: base64 } },
+                          { text: customQuestion }
+                        ]
+                      }
+                    ],
+                    config: { maxOutputTokens: 250 }
+                  });
+                  return { filename, desc: response.text?.trim() || "no description" };
+                })
+              );
+              for (const result of results) {
+                if (result.status === "fulfilled") {
+                  descriptions.push(`## ${result.value.filename}`, `${result.value.desc}`, ``);
+                } else {
+                  const errMsg = normalizeErrorMessage(result.reason);
+                  descriptions.push(
+                    `## (error)`,
+                    `Gemini call failed: ${errMsg.slice(0, 120)}`,
+                    ``
+                  );
+                }
+              }
+              const descPath = join(snapshotDir, "descriptions.md");
+              writeFileSync(descPath, descriptions.join("\n"));
+              describedPath = descPath;
+              log(`   ${c.dim("descriptions.md")} (Gemini frame analysis)`);
+            }
+          } catch (descErr) {
+            const msg = normalizeErrorMessage(descErr);
+            log(`   ${c.dim(`--describe failed: ${msg}`)}`);
+          }
+        }
+        if (asJson) {
+          const envelope = snapshotEnvelope(project.dir, snapshotDir, captured, {
+            contactSheets,
+            reviewSheets,
+            describedPath
+          });
+          console.log(JSON.stringify(withMeta(envelope), null, 2));
+        }
+      });
+    } catch (err) {
+      if (err instanceof CliRuntimeError && err.result.presented) throw err;
+      const msg = normalizeErrorMessage(err);
+      if (asJson) console.log(JSON.stringify(withMeta({ ok: false, error: msg }), null, 2));
+      else console.error(`
+${c.error("\u2717")} Snapshot failed: ${msg}`);
+      failCommand();
+    } finally {
+      if (managedSnapshotDir)
+        await finishSnapshotRun(project.dir, managedSnapshotDir).catch(warnSnapshotsNotRecorded);
+    }
+  }
+});
+export {
+  SNAPSHOT_IMAGE_NAME,
+  computeSnapshotTimes,
+  containingSourceFrameIndex,
+  snapshot_default as default,
+  examples,
+  extractVideoFrameToBuffer,
+  formatSnapshotTimestamp,
+  parseZoomScale,
+  probeContainingSourceFrameSeek,
+  recaptureSnapshotComposite,
+  requireSnapshotFfmpeg,
+  resolveSnapshotVideoClipStart,
+  resolveSnapshotVideoFrameTime,
+  resolveSnapshotVideoRateSpec,
+  serveCapturePage,
+  tailFrameTime
+};