hyperframes 0.8.184 → 0.8.185

package/dist/{snapshot-M4NUUSNU.js → snapshot-WDQ6S7CJ.js}

@@ -7,6 +7,9 @@ var __dirname = __hf_dirname(__filename);
 import {
   writeCaptureFileSync
 } from "./chunk-MRF4AMKD.js";
+import {
+  toDomNode
+} from "./chunk-LLMSX6V6.js";
 import {
   parseAngle
 } from "./chunk-KZI44OPA.js";
@@ -22,7 +25,7 @@ import {
   findFFmpeg,
   findFFprobe,
   getFFmpegInstallHint
-} from "./chunk-7HJALUIO.js";
+} from "./chunk-K2ZKXTVL.js";
 import {
   pngDimensions,
   reportArtifacts,
@@ -30,20 +33,20 @@ import {
 } from "./chunk-57GN6KWT.js";
 import {
   captureArtifactRevision
-} from "./chunk-VDM3FEDP.js";
-import "./chunk-FGJEUV4S.js";
+} from "./chunk-OAG47RE6.js";
+import "./chunk-PHMBMOXF.js";
 import "./chunk-X7MTZ4T2.js";
 import {
   resolveProject
-} from "./chunk-LRGYPXHF.js";
+} from "./chunk-5GUKZRQN.js";
 import {
   serveStaticProjectHtml
-} from "./chunk-4KKKBEP3.js";
-import "./chunk-YWNJTZGN.js";
+} from "./chunk-J5XEZ24I.js";
+import "./chunk-H6UY725W.js";
 import "./chunk-X7MTZ4T2.js";
 import "./chunk-XUHOIDKG.js";
-import "./chunk-3QVMJ7GX.js";
-import "./chunk-ZRHO6YMM.js";
+import "./chunk-KQ4JEJLF.js";
+import "./chunk-SKYPMHQC.js";
 import "./chunk-6JR2XUEE.js";
 import "./chunk-TTVHYD5R.js";
 import {
@@ -53,7 +56,7 @@ import {
   recordArtifacts,
   retainSnapshotOutput
 } from "./chunk-U6RXZNZE.js";
-import "./chunk-SN7KI5JA.js";
+import "./chunk-6GPR3G3C.js";
 import "./chunk-ALVXFXUG.js";
 import {
   DEFAULT_ZOOM_SCALE,
@@ -63,43 +66,44 @@ import {
   resolveCropRegion,
   runFfmpegOnce,
   seekCompositionTimeline
-} from "./chunk-ICJEAFPD.js";
+} from "./chunk-IDFNKFPL.js";
 import "./chunk-FH7WODJH.js";
-import "./chunk-KN46TGHV.js";
+import "./chunk-TOI35GN2.js";
 import "./chunk-MOEGCMKI.js";
-import "./chunk-ES426XRJ.js";
+import "./chunk-SQVRXHOW.js";
 import "./chunk-DKPNNYBZ.js";
-import "./chunk-PSKEKWVU.js";
+import "./chunk-G2UANIDX.js";
 import "./chunk-K2FLNJVB.js";
 import "./chunk-442JNXRM.js";
 import "./chunk-EHSBBBR2.js";
 import "./chunk-DQBY7FRR.js";
 import {
   resolveLocalBrowserGpuMode
-} from "./chunk-UNNXFKVG.js";
-import "./chunk-PFYWVUHA.js";
+} from "./chunk-EMSDWBG3.js";
+import "./chunk-HDIRZGK4.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import "./chunk-HVW7ABXD.js";
-import "./chunk-ZOCHDXDG.js";
+import "./chunk-RTBSA3EA.js";
 import {
   runWithConcurrencyLimit
 } from "./chunk-JHOCK3DG.js";
-import "./chunk-LLC4CS6I.js";
-import "./chunk-7MB2ZAQF.js";
+import "./chunk-HXUTX5GR.js";
+import "./chunk-PMMQRJDE.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-5CS4T6C6.js";
+import "./chunk-7L37AB57.js";
 import "./chunk-EOVYQ3IG.js";
-import "./chunk-JIUTXKWA.js";
-import "./chunk-UKOTVJFV.js";
+import "./chunk-WQLKDL35.js";
+import "./chunk-H5SM5PJI.js";
 import "./chunk-VWG7OQKU.js";
 import {
   defineCommand
 } from "./chunk-S3S4TGEH.js";
 import "./chunk-54HJ63Q2.js";
 import {
+  CliRuntimeError,
   failCommand
 } from "./chunk-JVBRJMOP.js";
 import {
@@ -108,23 +112,26 @@ import {
 import "./chunk-KLIKCX6Q.js";
 import "./chunk-EVMY7IPL.js";
 import "./chunk-7FMUTGOH.js";
-import "./chunk-RGXVEYHI.js";
+import "./chunk-I3IH5MV5.js";
 import "./chunk-IZCW2NKT.js";
 import {
   createRuntimeStartTimeResolver,
   isClipVisibleAt,
   isInClipWindow
-} from "./chunk-J3QM7AHP.js";
+} from "./chunk-KROXPHXX.js";
 import "./chunk-RQVDTPGD.js";
-import "./chunk-YALM6XN4.js";
+import "./chunk-Q47FAYYK.js";
 import {
   readElementRateSpec,
   sourceTimeAt,
   timeAtSourceTime
-} from "./chunk-R2SQBPMH.js";
+} from "./chunk-3NPOFC43.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
-import "./chunk-YMS5FOMC.js";
+import {
+  topLevelElements,
+  trackKindOf
+} from "./chunk-B2A56S5C.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-3GXQPCJC.js";
@@ -142,23 +149,26 @@ import "./chunk-XT6MXC7A.js";
 import "./chunk-4UMPIPCQ.js";
 import {
   lintProject
-} from "./chunk-ADDHW2FS.js";
+} from "./chunk-Q447CX26.js";
 import "./chunk-VAS6HQX3.js";
 import "./chunk-6BNTGNGD.js";
-import "./chunk-OYLO6TYK.js";
+import "./chunk-RUOG4VB7.js";
 import "./chunk-MMQ52NIZ.js";
 import "./chunk-BSQ7XANM.js";
 import {
   parseHTML
 } from "./chunk-SDYDNHEE.js";
 import "./chunk-IXLUTE6N.js";
-import "./chunk-TYXH3EKP.js";
+import "./chunk-I5JRXMCV.js";
 import "./chunk-W2LGJSEN.js";
+import {
+  withMeta
+} from "./chunk-ISTRDGIX.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-4N4P3ZWL.js";
+import "./chunk-I7QMXZSB.js";
 import {
   normalizeErrorMessage
 } from "./chunk-KNU5COPB.js";
@@ -182,6 +192,15 @@ function sampleSnapshotRange([start, end], frames, duration, exclusiveEnd = fals
   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(
@@ -191,14 +210,7 @@ function resolveSnapshotCompositionRange(html, durations, id, duration) {
     throw new Error(
       `Composition ID ${JSON.stringify(id)} matched ${matches.length} elements; expected exactly one`
     );
-  const registry = Object.fromEntries(
-    Object.entries(durations).map(([key, value]) => [key, { duration: () => value }])
-  );
-  const resolver = createRuntimeStartTimeResolver({
-    documentRef: document2,
-    timelineRegistry: registry,
-    includeAuthoredTimingAttrs: true
-  });
+  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;
@@ -219,6 +231,208 @@ 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-CAGMKI3E.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]")
@@ -479,7 +693,8 @@ function serveCapturePage(projectDir, html, proxy) {
   return serveStaticProjectHtml(projectDir, html, void 0, [], proxy === true);
 }
 async function captureSnapshots(projectDir, opts) {
-  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-2EGPA5ZO.js");
+  const log = opts.log ?? ((message) => console.log(message));
+  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-67MLTHKM.js");
   const capture = await captureArtifactRevision(projectDir).catch(warnSnapshotsNotRecorded);
   const invocation = randomUUID();
   const artifacts = [];
@@ -487,6 +702,9 @@ async function captureSnapshots(projectDir, opts) {
   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 = [];
@@ -518,10 +736,10 @@ async function captureSnapshots(projectDir, opts) {
         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`);
-        console.log(`
+        log(`
    ${c.dim("Fonts:")} ${parts.join(", ")}`);
         if (fontReport.errored.length > 0) {
-          console.log(`   ${c.error("Fonts FAILED:")} ${fontReport.errored.join(", ")}`);
+          log(`   ${c.error("Fonts FAILED:")} ${fontReport.errored.join(", ")}`);
         }
       }
       if (fontReport.errored.length)
@@ -537,19 +755,20 @@ async function captureSnapshots(projectDir, opts) {
         return 0;
       });
       if (duration <= 0 && !opts.at?.length) {
-        return [];
+        return { paths: [] };
       }
+      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) {
-        const timing = await page.evaluate(() => ({
-          html: document.documentElement.outerHTML,
-          durations: Object.fromEntries(
-            Object.entries(window.__timelines ?? {}).map(([id, timeline]) => [
-              id,
-              Number(timeline.duration?.())
-            ])
-          )
-        }));
+      if (opts.composition && !opts.review) {
+        const timing = await readTiming();
         range = resolveSnapshotCompositionRange(
           timing.html,
           timing.durations,
@@ -557,7 +776,18 @@ async function captureSnapshots(projectDir, opts) {
           duration
         );
       }
-      const { times: positions, appendedTail } = range ? {
+      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, {
@@ -566,11 +796,15 @@ async function captureSnapshots(projectDir, opts) {
         includeEnd: opts.includeEnd
       });
       if (range)
-        console.log(
+        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) {
-        console.log(
+        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.`)}`
         );
       }
@@ -592,7 +826,7 @@ async function captureSnapshots(projectDir, opts) {
       let syncVideoFrameVisibility = null;
       let extractMediaMetadata = null;
       try {
-        const engine = await import("./src-4UYM2K3S.js");
+        const engine = await import("./src-RZ574OKP.js");
         injectVideoFramesBatch = engine.injectVideoFramesBatch;
         syncVideoFrameVisibility = engine.syncVideoFrameVisibility;
         extractMediaMetadata = engine.extractMediaMetadata;
@@ -730,7 +964,8 @@ async function captureSnapshots(projectDir, opts) {
         await recaptureSnapshotComposite(page);
         const timeLabel = formatSnapshotTimestamp(time);
         const slot = opts.keep ? `at-${timeLabel}` : `${String(i).padStart(2, "0")}-at-${timeLabel}`;
-        const filename = opts.keep ? `${slot}.png` : `frame-${slot}.png`;
+        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) {
@@ -769,9 +1004,11 @@ async function captureSnapshots(projectDir, opts) {
             zoom: opts.zoom,
             zoomScale: opts.zoom ? opts.zoomScale ?? DEFAULT_ZOOM_SCALE : 1,
             angle: opts.angle,
-            browserGpuMode: opts.browserGpuMode
+            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) {
@@ -807,20 +1044,32 @@ async function captureSnapshots(projectDir, opts) {
       artifacts,
       opts.zoom,
       warnings,
-      completed
+      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 savedPaths;
+  return {
+    paths: savedPaths,
+    ...review && reviewList ? {
+      review: {
+        plan: review,
+        frames: reviewList.flatMap((frame) => {
+          const path = reviewPaths.get(frame);
+          return path ? [{ ...frame, path }] : [];
+        })
+      }
+    } : {}
+  };
 }
 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) {
+async function recordSnapshotArtifacts(projectDir, capture, artifacts, zoom, warnings, completed, log) {
   const records = await recordArtifacts(
     projectDir,
     capture,
@@ -833,10 +1082,65 @@ async function recordSnapshotArtifacts(projectDir, capture, artifacts, zoom, war
   ).catch(warnSnapshotsNotRecorded);
   const record = records?.[0];
   if (!record) return false;
-  console.log(`   Revision: ${record.revision ?? "none"} (${record.attribution})`);
-  console.log(`   State: ${join(projectDir, ".hyperframes", "video-state.json")}`);
+  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)),
+    ...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",
@@ -902,6 +1206,16 @@ var snapshot_default = defineCommand({
       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."
@@ -918,8 +1232,22 @@ var snapshot_default = defineCommand({
     }
   },
   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 composition = args.composition === void 0 ? void 0 : String(args.composition).trim();
@@ -928,28 +1256,32 @@ var snapshot_default = defineCommand({
     const lintResult = await lintProject(project.dir);
     if (hasDefinitiveEntryMismatch(lintResult)) {
       const candidate = definitiveEntryMismatchComposition(lintResult);
-      console.log("");
+      log("");
       for (const line of formatLintFindings(lintResult, { errorsFirst: true })) {
-        console.log(line);
+        log(line);
       }
-      console.log("");
-      console.log(c.error("  Aborting snapshot because the default index.html entry is blank."));
+      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}`;
-        console.log(
+        log(
           c.dim(
             `  Move or mount the authored file, or snapshot its directory directly: hyperframes 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) {
-        console.log(
+        log(
           c.dim(
             `  Move or mount ${candidate} as a project index.html before snapshotting; snapshot accepts project directories, not individual HTML files.`
           )
         );
       }
-      console.log("");
+      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;
@@ -960,20 +1292,18 @@ var snapshot_default = defineCommand({
     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)) {
-      console.log(`${c.error("\u2717")} --against video not found: ${against}`);
-      failCommand();
-    }
-    const label = atTimestamps ? `${atTimestamps.length} frames at [${atTimestamps.map(formatSnapshotTimestamp).join(", ")}]` : `${frames} frames`;
+    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)`)}` : "";
-    console.log(`${c.accent("\u25C6")}  Capturing ${label} from ${c.accent(project.name)}${angleLabel}`);
+    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 paths = await captureSnapshots(project.dir, {
+        const captured = await captureSnapshots(project.dir, {
           frames,
           range,
           composition,
@@ -987,53 +1317,71 @@ var snapshot_default = defineCommand({
           autoProxy: args.proxy,
           browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"]),
           against,
-          keep: args.keep === true
+          keep: args.keep === true,
+          review: reviewMode,
+          log
         });
+        const paths = captured.paths;
         reportArtifacts(
           "snapshot",
           "frame",
           paths.map((path) => resolve(project.dir, path))
         );
         if (paths.length === 0) {
-          console.log(
-            `
-${c.error("\u2717")} Could not determine composition duration \u2014 no frames captured`
-          );
-          failCommand();
+          fail(`
+${c.error("\u2717")} Could not determine composition duration \u2014 no frames captured`);
         }
-        console.log(`
+        log(`
 ${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
         for (const p of paths) {
-          console.log(`   ${p}`);
+          log(`   ${p}`);
         }
         if (against) {
-          console.log(
+          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-CAGMKI3E.js");
-          const sheets = args.keep === true ? [] : await createSnapshotContactSheet(
-            snapshotDir,
-            join(snapshotDir, "contact-sheet.jpg")
-          );
-          reportArtifacts("snapshot", "contact-sheet", sheets);
-          for (const sheet of sheets) {
-            console.log(`   ${resolve(sheet)} (grid view for AI review)`);
+          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(
+              snapshotDir,
+              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)
-                console.log(`   ${c.dim("--describe: GEMINI_API_KEY not set, skipping")}`);
+                log(`   ${c.dim("--describe: GEMINI_API_KEY not set, skipping")}`);
             } else if (paths.length > 0) {
-              console.log(`   ${c.dim("Describing frames with Gemini vision...")}`);
+              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";
@@ -1101,17 +1449,28 @@ ${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
               }
               const descPath = join(snapshotDir, "descriptions.md");
               writeFileSync(descPath, descriptions.join("\n"));
-              console.log(`   ${c.dim("descriptions.md")} (Gemini frame analysis)`);
+              describedPath = descPath;
+              log(`   ${c.dim("descriptions.md")} (Gemini frame analysis)`);
             }
           } catch (descErr) {
             const msg = normalizeErrorMessage(descErr);
-            console.log(`   ${c.dim(`--describe failed: ${msg}`)}`);
+            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);
-      console.error(`
+      if (asJson) console.log(JSON.stringify(withMeta({ ok: false, error: msg }), null, 2));
+      else console.error(`
 ${c.error("\u2717")} Snapshot failed: ${msg}`);
       failCommand();
     } finally {