hyperframes 0.8.150 → 0.8.152

package/dist/{snapshot-Y3I76OIZ.js → snapshot-D5BBFXOS.js}

@@ -7,11 +7,20 @@ var __dirname = __hf_dirname(__filename);
 import {
   parseAngle
 } from "./chunk-KZI44OPA.js";
+import {
+  pngDimensions,
+  reportArtifacts,
+  withProjectLock
+} from "./chunk-57GN6KWT.js";
+import {
+  captureArtifactRevision
+} from "./chunk-KCFF4ENE.js";
+import "./chunk-7TASSBN2.js";
 import {
   serveStaticProjectHtml
-} from "./chunk-S5F26DUL.js";
+} from "./chunk-GQETH4PE.js";
 import "./chunk-XUHOIDKG.js";
-import "./chunk-A6ZO4BX7.js";
+import "./chunk-XEFFJRYX.js";
 import "./chunk-X7MTZ4T2.js";
 import {
   DEFAULT_ZOOM_SCALE,
@@ -21,41 +30,46 @@ import {
   resolveCropRegion,
   runFfmpegOnce,
   seekCompositionTimeline
-} from "./chunk-UAIUVPZE.js";
+} from "./chunk-SWCSL6WS.js";
 import "./chunk-FH7WODJH.js";
-import "./chunk-AXPNVC3N.js";
-import "./chunk-423DJVX2.js";
+import "./chunk-4UMKAUZI.js";
+import "./chunk-PKO2EWO7.js";
 import "./chunk-WPNE5NEP.js";
-import "./chunk-UVVI2NJQ.js";
-import "./chunk-ZNHAJCEA.js";
-import "./chunk-FJWEYVEM.js";
-import "./chunk-XXPYZBZ3.js";
-import "./chunk-EL5QVJEG.js";
-import "./chunk-AIJS74LG.js";
+import "./chunk-HBCRRCTX.js";
+import "./chunk-PRXAOZWZ.js";
+import "./chunk-C6TPGUWD.js";
+import {
+  artifactDirectory,
+  forgetRecordedArtifacts,
+  recordArtifacts
+} from "./chunk-7FYFEXD2.js";
+import "./chunk-XINGD6MS.js";
+import "./chunk-FFDC5OWV.js";
 import {
   resolveProject
-} from "./chunk-NFQY7EIC.js";
+} from "./chunk-IBYC3VUA.js";
 import {
   formatLintFindings
 } from "./chunk-6CSYCFQV.js";
 import "./chunk-K2FLNJVB.js";
+import "./chunk-DQBY7FRR.js";
 import {
   resolveLocalBrowserGpuMode
-} from "./chunk-AKYQGZLU.js";
+} from "./chunk-EVTHG34H.js";
 import "./chunk-442JNXRM.js";
-import "./chunk-XQMEGSHG.js";
+import "./chunk-D6RJXQLD.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import "./chunk-HVW7ABXD.js";
-import "./chunk-BLRJKBKP.js";
-import "./chunk-M6UDJ2E7.js";
-import "./chunk-OQ7XMM3S.js";
+import "./chunk-QESSGUKX.js";
+import "./chunk-6Z4YJ5Q3.js";
+import "./chunk-3HPJM5IQ.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-374QQGBQ.js";
-import "./chunk-3UAIVF4L.js";
-import "./chunk-6KWA3XPS.js";
+import "./chunk-5CS4T6C6.js";
+import "./chunk-H2SGM2V2.js";
+import "./chunk-KZ3L3W4Q.js";
 import "./chunk-VWG7OQKU.js";
 import "./chunk-XBSPQ52S.js";
 import {
@@ -78,7 +92,7 @@ import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-I6DATIHC.js";
+import "./chunk-IZIRIDJH.js";
 import {
   loadOptionalPackage
 } from "./chunk-3DKN5WKL.js";
@@ -88,24 +102,25 @@ import {
   findFFmpeg,
   findFFprobe,
   getFFmpegInstallHint
-} from "./chunk-DUUFDLC4.js";
+} from "./chunk-4MLYMDQ4.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-5NAYNDBT.js";
-import "./chunk-WLIUULZQ.js";
+import "./chunk-EXH6L2XZ.js";
+import "./chunk-RN5I2DP5.js";
 import "./chunk-NE55C6S5.js";
 import "./chunk-JYVGYKXG.js";
 import {
+  createRuntimeStartTimeResolver,
   isClipVisibleAt,
   isInClipWindow
-} from "./chunk-PCWOSS7G.js";
+} from "./chunk-5ERVRJMV.js";
 import {
   readElementRateSpec,
   sourceTimeAt,
   timeAtSourceTime
-} from "./chunk-CEND6BLF.js";
+} from "./chunk-S3RCK56N.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
-import "./chunk-LFNQDTSH.js";
+import "./chunk-VYKPBRCB.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
@@ -113,18 +128,20 @@ import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
 import {
   runCancellableProcess
-} from "./chunk-XPQSL5VS.js";
+} from "./chunk-54DMWFQZ.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-JDB65PPT.js";
+} from "./chunk-YOEGUBBY.js";
 import "./chunk-IWFLMU2N.js";
-import "./chunk-APDLWWFG.js";
+import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
-import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import {
+  parseHTML
+} from "./chunk-SDYDNHEE.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import {
   normalizeErrorMessage
@@ -133,7 +150,57 @@ 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 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 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 registry = Object.fromEntries(
+    Object.entries(durations).map(([key, value]) => [key, { duration: () => value }])
+  );
+  const resolver = createRuntimeStartTimeResolver({
+    documentRef: document2,
+    timelineRegistry: registry,
+    includeAuthoredTimingAttrs: true
+  });
+  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";
@@ -373,18 +440,29 @@ function computeSnapshotTimes(duration, opts) {
   return { times: times.map(round), appendedTail: false };
 }
 async function captureSnapshots(projectDir, opts) {
-  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-I4CWOXLK.js");
+  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-76DMCRIW.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;
   const html = await bundleWithLocalizedFonts(projectDir);
   const server = await serveStaticProjectHtml(projectDir, html, void 0, [], opts.autoProxy);
   const savedPaths = [];
   try {
-    const { browser: chromeBrowser, page } = await openSettledCompositionPage(html, server.url, {
+    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 = [];
@@ -407,6 +485,8 @@ async function captureSnapshots(projectDir, opts) {
           console.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") {
@@ -420,24 +500,51 @@ async function captureSnapshots(projectDir, opts) {
       if (duration <= 0 && !opts.at?.length) {
         return [];
       }
-      const { times: positions, appendedTail } = computeSnapshotTimes(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?.())
+            ])
+          )
+        }));
+        range = resolveSnapshotCompositionRange(
+          timing.html,
+          timing.durations,
+          opts.composition,
+          duration
+        );
+      }
+      const { times: positions, appendedTail } = range ? {
+        times: sampleSnapshotRange(range, numFrames, duration, !!opts.composition),
+        appendedTail: false
+      } : computeSnapshotTimes(duration, {
         frames: numFrames,
         at: opts.at,
         includeEnd: opts.includeEnd
       });
+      if (range)
+        console.log(
+          `   Sampling ${positions.length} frames within ${range[0]}\u2013${range[1]}s${opts.composition ? ` (composition ${opts.composition})` : ""}`
+        );
       if (appendedTail) {
         console.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 ?? join(projectDir, "snapshots");
+      const snapshotDir = opts.outputDir ?? artifactDirectory(projectDir, "snapshots");
       mkdirSync(snapshotDir, { recursive: true });
       try {
         const { readdirSync } = await import("fs");
         for (const file of readdirSync(snapshotDir)) {
           if (/\.(png|jpg|jpeg)$/i.test(file)) {
-            rmSync(join(snapshotDir, file), { force: true });
+            const path = resolve(snapshotDir, file);
+            replaced.push(path);
+            rmSync(path, { force: true });
           }
         }
       } catch {
@@ -446,11 +553,12 @@ async function captureSnapshots(projectDir, opts) {
       let syncVideoFrameVisibility = null;
       let extractMediaMetadata = null;
       try {
-        const engine = await import("./src-7V6LBC56.js");
+        const engine = await import("./src-AVQBAECC.js");
         injectVideoFramesBatch = engine.injectVideoFramesBatch;
         syncVideoFrameVisibility = engine.syncVideoFrameVisibility;
         extractMediaMetadata = engine.extractMediaMetadata;
       } catch {
+        warnings.push("Video frame extraction engine unavailable");
         console.warn(
           `   ${c.warn("\u26A0")} @hyperframes/engine unavailable \u2014 <video> elements will appear black in snapshots. Verify media via a draft render's extracted frames instead.`
         );
@@ -553,6 +661,7 @@ async function captureSnapshots(projectDir, opts) {
           }
           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`
             );
@@ -566,6 +675,7 @@ async function captureSnapshots(projectDir, opts) {
               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`
             );
@@ -576,6 +686,7 @@ async function captureSnapshots(projectDir, opts) {
         const index = String(i).padStart(2, "0");
         const filename = `frame-${index}-at-${timeLabel}.png`;
         const framePath = join(snapshotDir, filename);
+        let crop;
         if (opts.zoom) {
           const canvas = await page.evaluate(() => ({
             width: window.innerWidth,
@@ -583,11 +694,13 @@ async function captureSnapshots(projectDir, opts) {
           }));
           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,
@@ -597,6 +710,19 @@ async function captureSnapshots(projectDir, opts) {
         } else {
           await page.screenshot({ path: framePath, 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
+          }
+        });
         if (opts.against) {
           const refPng = await extractVideoFrameToBuffer(opts.against, time);
           if (!refPng) {
@@ -620,14 +746,48 @@ async function captureSnapshots(projectDir, opts) {
         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
+    ) : false;
+    if (!recorded) {
+      const paths = [...replaced, ...artifacts.map((artifact) => artifact.image)];
+      if (paths.length > 0) await forgetRecordedArtifacts(projectDir, paths).catch(() => void 0);
+    }
   }
   return savedPaths;
 }
+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) {
+  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;
+  console.log(`   Revision: ${record.revision ?? "none"} (${record.attribution})`);
+  console.log(`   State: ${join(projectDir, ".hyperframes", "video-state.json")}`);
+  return true;
+}
 var snapshot_default = defineCommand({
   meta: {
     name: "snapshot",
@@ -642,7 +802,7 @@ var snapshot_default = defineCommand({
     output: {
       type: "string",
       alias: "o",
-      description: "Directory to write snapshots into (default: <project>/snapshots)"
+      description: "Directory to write snapshots into (default: unique directory under <project>/.hyperframes/artifacts/snapshots)"
     },
     frames: {
       type: "string",
@@ -653,6 +813,14 @@ var snapshot_default = defineCommand({
       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)",
@@ -696,6 +864,12 @@ var snapshot_default = defineCommand({
     }
   },
   async run({ args }) {
+    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 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();
+    if (composition === "") throw new Error("--composition requires a composition ID");
     const project = resolveProject(args.dir);
     const lintResult = await lintProject(project.dir);
     if (hasDefinitiveEntryMismatch(lintResult)) {
@@ -724,7 +898,6 @@ var snapshot_default = defineCommand({
       console.log("");
       failCommand();
     }
-    const frames = parseInt(args.frames, 10) || 5;
     const timeout = parseInt(args.timeout, 10) || 5e3;
     const atTimestamps = args.at ? String(args.at).split(",").map((s) => parseFloat(s.trim())).filter((n) => !isNaN(n)) : void 0;
     const describeArg = args.describe === void 0 ? "true" : String(args.describe) === "false" ? null : String(args.describe);
@@ -740,129 +913,144 @@ var snapshot_default = defineCommand({
     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}`);
     try {
-      const snapshotDir = args.output ? resolve(String(args.output)) : join(project.dir, "snapshots");
-      const paths = await captureSnapshots(project.dir, {
-        frames,
-        timeout,
-        at: atTimestamps,
-        outputDir: snapshotDir,
-        angle: camera,
-        includeEnd: args.end !== false,
-        zoom: zoomTarget,
-        zoomScale,
-        autoProxy: args.proxy,
-        browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"]),
-        against
-      });
-      if (paths.length === 0) {
-        console.log(
-          `
-${c.error("\u2717")} Could not determine composition duration \u2014 no frames captured`
-        );
-        failCommand();
-      }
-      console.log(
-        `
-${c.success("\u25C7")}  ${paths.length} snapshots saved to ${args.output ? snapshotDir : "snapshots/"}`
-      );
-      for (const p of paths) {
-        console.log(`   ${p}`);
-      }
-      if (against) {
-        console.log(
-          `   ${c.dim("ref-*.png + pair-*.jpg")} beside each frame (reference frame, render | reference sheet)`
-        );
-      }
-      try {
-        const { createSnapshotContactSheet } = await import("./contactSheet-27SRU7A4.js");
-        const sheets = await createSnapshotContactSheet(
-          snapshotDir,
-          join(snapshotDir, "contact-sheet.jpg")
+      const snapshotDir = args.output ? resolve(String(args.output)) : artifactDirectory(project.dir, "snapshots");
+      await withProjectLock(project.dir, "snapshot", async () => {
+        const paths = 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
+        });
+        reportArtifacts(
+          "snapshot",
+          "frame",
+          paths.map((path) => resolve(project.dir, path))
         );
-        if (sheets.length > 0) {
-          const label2 = sheets.length === 1 ? "contact-sheet.jpg" : `contact-sheet-1..${sheets.length}.jpg`;
-          console.log(`   ${c.dim(label2)} (grid view for AI review)`);
+        if (paths.length === 0) {
+          console.log(
+            `
+${c.error("\u2717")} Could not determine composition duration \u2014 no frames captured`
+          );
+          failCommand();
+        }
+        console.log(`
+${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
+        for (const p of paths) {
+          console.log(`   ${p}`);
+        }
+        if (against) {
+          console.log(
+            `   ${c.dim("ref-*.png + pair-*.jpg")} beside each frame (reference frame, render | reference sheet)`
+          );
         }
-      } catch (err) {
-        console.warn(
-          `   ${c.warn("\u26A0")} Contact sheet skipped: ${normalizeErrorMessage(err)}. Individual snapshot PNGs are still available.`
-        );
-      }
-      if (describeArg !== null) {
         try {
-          const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
-          if (!geminiKey) {
-            console.log(`   ${c.dim("--describe: GEMINI_API_KEY not set, skipping")}`);
-          } else if (paths.length > 0) {
-            console.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 sharpFn = null;
-            try {
-              const s = await import("sharp");
-              sharpFn = s.default ?? s;
-            } 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 (sharpFn) {
-                  imageData = await sharpFn(raw).resize(960).jpeg().toBuffer();
-                  mimeType = "image/jpeg";
+          const { createSnapshotContactSheet } = await import("./contactSheet-27SRU7A4.js");
+          const sheets = 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)`);
+          }
+        } catch (err) {
+          console.warn(
+            `   ${c.warn("\u26A0")} Contact sheet skipped: ${normalizeErrorMessage(err)}. Individual snapshot PNGs are still available.`
+          );
+        }
+        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")}`);
+            } else if (paths.length > 0) {
+              console.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 sharpFn = null;
+              try {
+                const s = await import("sharp");
+                sharpFn = s.default ?? s;
+              } 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 (sharpFn) {
+                    imageData = await sharpFn(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 {
-                  if (raw.length > 38e5)
-                    return {
-                      filename,
-                      desc: "file too large for Gemini \u2014 install sharp to enable auto-resize"
-                    };
-                  imageData = raw;
+                  const errMsg = normalizeErrorMessage(result.reason);
+                  descriptions.push(
+                    `## (error)`,
+                    `Gemini call failed: ${errMsg.slice(0, 120)}`,
+                    ``
+                  );
                 }
-                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"));
+              console.log(`   ${c.dim("descriptions.md")} (Gemini frame analysis)`);
             }
-            const descPath = join(snapshotDir, "descriptions.md");
-            writeFileSync(descPath, descriptions.join("\n"));
-            console.log(`   ${c.dim("descriptions.md")} (Gemini frame analysis)`);
+          } catch (descErr) {
+            const msg = normalizeErrorMessage(descErr);
+            console.log(`   ${c.dim(`--describe failed: ${msg}`)}`);
           }
-        } catch (descErr) {
-          const msg = normalizeErrorMessage(descErr);
-          console.log(`   ${c.dim(`--describe failed: ${msg}`)}`);
         }
-      }
+      });
     } catch (err) {
       const msg = normalizeErrorMessage(err);
       console.error(`