hyperframes 0.8.151 → 0.8.152

package/dist/{render-WUSTRMUD.js → render-6GH5FSXU.js}

@@ -15,7 +15,7 @@ import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-4LE27ST4.js";
+} from "./chunk-7NPSXBIN.js";
 import "./chunk-FH7WODJH.js";
 import "./chunk-K2FLNJVB.js";
 import "./chunk-442JNXRM.js";
@@ -25,11 +25,11 @@ import {
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
-import "./chunk-XQKVEQNY.js";
-import "./chunk-QBYHNRHU.js";
+import "./chunk-5ERVRJMV.js";
+import "./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";
@@ -38,7 +38,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-M2WBOQ2Q.js";
 

package/dist/{render-batch-AQHU2JWZ.js → render-batch-UMBUQWWS.js}

@@ -14,7 +14,7 @@ import {
   loadProjectVariableSchema,
   reportVariableIssues,
   validateVariablesAgainstSchema
-} from "./chunk-4LE27ST4.js";
+} from "./chunk-7NPSXBIN.js";
 import "./chunk-FH7WODJH.js";
 import {
   errorBox
@@ -27,11 +27,11 @@ import {
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
-import "./chunk-XQKVEQNY.js";
-import "./chunk-QBYHNRHU.js";
+import "./chunk-5ERVRJMV.js";
+import "./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";
@@ -40,7 +40,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import {
   normalizeErrorMessage

package/dist/renderSetupWorker.js

@@ -20,14 +20,14 @@ import {
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-GNTVYF7E.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 "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-KGPLIH7B.js";

package/dist/{resolver-L5BDZJKU.js → resolver-KO6WWO5P.js}

@@ -11,16 +11,16 @@ import {
   resolveItemWithDependencies,
   resolveItemsByTag,
   unreachableRegistryMessage
-} from "./chunk-XGLNQDLN.js";
-import "./chunk-YZTVHRJ2.js";
+} from "./chunk-QESSGUKX.js";
+import "./chunk-3HPJM5IQ.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-XQKVEQNY.js";
-import "./chunk-QBYHNRHU.js";
+import "./chunk-5ERVRJMV.js";
+import "./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";
@@ -29,7 +29,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-M2WBOQ2Q.js";
 export {

package/dist/{sherpa-3S3ISG7G.js → sherpa-DADGYWNR.js}

@@ -16,26 +16,26 @@ import {
   sherpaRuntimeLoadError,
   sherpaUnsupportedReason,
   transcribeWithSherpa
-} from "./chunk-DIOBKUBV.js";
+} from "./chunk-E6EYZ33P.js";
 import "./chunk-BXCMXMJQ.js";
 import "./chunk-3DKN5WKL.js";
 import "./chunk-EOVYQ3IG.js";
-import "./chunk-QF7AE3DB.js";
-import "./chunk-KQGWP4KH.js";
+import "./chunk-QECEOV6W.js";
+import "./chunk-FNN5QINS.js";
 import "./chunk-6BEFEWFB.js";
 import "./chunk-YG2Y55KF.js";
 import "./chunk-PO2SDVQA.js";
 import "./chunk-4MLYMDQ4.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-IZPN423R.js";
-import "./chunk-3SVC7SW4.js";
+import "./chunk-EXH6L2XZ.js";
+import "./chunk-RN5I2DP5.js";
 import "./chunk-NE55C6S5.js";
 import "./chunk-JYVGYKXG.js";
-import "./chunk-XQKVEQNY.js";
-import "./chunk-QBYHNRHU.js";
+import "./chunk-5ERVRJMV.js";
+import "./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";
@@ -44,14 +44,14 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-YIJMVFEJ.js";
 import "./chunk-54DMWFQZ.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-GNTVYF7E.js";
+import "./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 "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-JZIEZCQM.js";

package/dist/skills/hyperframes-cli/SKILL.md

@@ -79,6 +79,9 @@ Static audits cannot catch every mount failure. When the project uses sub-compos
 
 ```bash
 npx hyperframes snapshot --at <t1>,<t2>,<t3>
+# For multiple samples within one scene or interval:
+npx hyperframes snapshot --composition <data-composition-id> --frames 8
+npx hyperframes snapshot --range 3:5 --frames 8
 ```
 
 Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timeline-registration timeouts as render-blocking mount defects. See `hyperframes-core/references/sub-compositions.md` for the corresponding fixes.

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -104,9 +104,13 @@ Drop a `*.motion.json` sidecar next to the composition (matching the html basena
 npx hyperframes snapshot                       # 5 key frames as PNG
 npx hyperframes snapshot ./my-project          # specific project
 npx hyperframes snapshot --frames 10           # evenly-spaced N frames
+npx hyperframes snapshot --range 3:5 --frames 8 # 8 frames within root-timeline seconds 3–5
+npx hyperframes snapshot --composition intro --frames 8 # 8 frames within this data-composition-id
 ```
 
-Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory. Not deprecated: it remains the standalone capture utility, while `check --snapshots` covers the gate's needs (overview frames annotated with labeled finding boxes, plus `finding-NN-<code>.png` crops for every error finding with a bbox).
+Still PNGs. Each run writes `.hyperframes/artifacts/snapshots/<id>/` unless `--output` is set. `snapshot` is the standalone capture; `check --snapshots` is the gate.
+
+One of `--at`, `--range START:END` (seconds), or `--composition <data-composition-id>` (not a CSS selector). `--frames` defaults to 5. Range and composition sample just before the end and add no extra end frame; `--at` adds one unless `--no-end`.
 
 ### Zooming into a reported finding
 

package/dist/{skills-X4WQEKNF.js → skills-QLKSNU4Y.js}

@@ -6,8 +6,8 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   trackSkillsInstallSkipped
-} from "./chunk-ZD3RDNZI.js";
-import "./chunk-IZ7L6V76.js";
+} from "./chunk-H2SGM2V2.js";
+import "./chunk-KZ3L3W4Q.js";
 import {
   diag
 } from "./chunk-VWG7OQKU.js";
@@ -35,15 +35,15 @@ import {
   isCoreSkill,
   presentSkills,
   pruneOrphanedLockEntries
-} from "./chunk-OSAH7S5M.js";
+} from "./chunk-H7FXBK3Q.js";
 import {
   withMeta
-} from "./chunk-35PWWBGZ.js";
+} from "./chunk-YYEYOFHW.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-TCWMDCBX.js";
+import "./chunk-IZIRIDJH.js";
 import {
   buildNpxCommand
 } from "./chunk-6BEFEWFB.js";

package/dist/{skillsUpdateCheck-UYCVHDZ6.js → skillsUpdateCheck-Z2QQGF2W.js}

@@ -9,13 +9,13 @@ import {
   printSkillsUpdateNotice,
   refreshSkillsCache,
   skillsCheckDue
-} from "./chunk-OSAH7S5M.js";
-import "./chunk-35PWWBGZ.js";
+} from "./chunk-H7FXBK3Q.js";
+import "./chunk-YYEYOFHW.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-TCWMDCBX.js";
+import "./chunk-IZIRIDJH.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 export {

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

@@ -8,14 +8,19 @@ import {
   parseAngle
 } from "./chunk-KZI44OPA.js";
 import {
+  pngDimensions,
   reportArtifacts,
   withProjectLock
-} from "./chunk-DHPFXAUF.js";
+} from "./chunk-57GN6KWT.js";
+import {
+  captureArtifactRevision
+} from "./chunk-KCFF4ENE.js";
+import "./chunk-7TASSBN2.js";
 import {
   serveStaticProjectHtml
-} from "./chunk-L3N7RJHS.js";
+} from "./chunk-GQETH4PE.js";
 import "./chunk-XUHOIDKG.js";
-import "./chunk-QLGBNGXC.js";
+import "./chunk-XEFFJRYX.js";
 import "./chunk-X7MTZ4T2.js";
 import {
   DEFAULT_ZOOM_SCALE,
@@ -25,41 +30,46 @@ import {
   resolveCropRegion,
   runFfmpegOnce,
   seekCompositionTimeline
-} from "./chunk-RYL6ZIJP.js";
+} from "./chunk-SWCSL6WS.js";
 import "./chunk-FH7WODJH.js";
-import "./chunk-RRBKEHST.js";
-import "./chunk-HVXRYMGQ.js";
+import "./chunk-4UMKAUZI.js";
+import "./chunk-PKO2EWO7.js";
 import "./chunk-WPNE5NEP.js";
-import "./chunk-BRF3O35X.js";
-import "./chunk-XNDXENJQ.js";
-import "./chunk-FJWEYVEM.js";
-import "./chunk-XXPYZBZ3.js";
-import "./chunk-3ZPFRDEJ.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-KXX6NLOT.js";
+} from "./chunk-IBYC3VUA.js";
 import {
   formatLintFindings
 } from "./chunk-6CSYCFQV.js";
 import "./chunk-K2FLNJVB.js";
+import "./chunk-DQBY7FRR.js";
 import {
   resolveLocalBrowserGpuMode
-} from "./chunk-ZGCRVM5M.js";
+} from "./chunk-EVTHG34H.js";
 import "./chunk-442JNXRM.js";
-import "./chunk-FAIYEIZ4.js";
+import "./chunk-D6RJXQLD.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import "./chunk-HVW7ABXD.js";
-import "./chunk-XGLNQDLN.js";
-import "./chunk-N4IXP3MY.js";
-import "./chunk-YZTVHRJ2.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-ZD3RDNZI.js";
-import "./chunk-IZ7L6V76.js";
+import "./chunk-5CS4T6C6.js";
+import "./chunk-H2SGM2V2.js";
+import "./chunk-KZ3L3W4Q.js";
 import "./chunk-VWG7OQKU.js";
 import "./chunk-XBSPQ52S.js";
 import {
@@ -82,7 +92,7 @@ import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-TCWMDCBX.js";
+import "./chunk-IZIRIDJH.js";
 import {
   loadOptionalPackage
 } from "./chunk-3DKN5WKL.js";
@@ -94,23 +104,23 @@ import {
   getFFmpegInstallHint
 } from "./chunk-4MLYMDQ4.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-IZPN423R.js";
-import "./chunk-3SVC7SW4.js";
+import "./chunk-EXH6L2XZ.js";
+import "./chunk-RN5I2DP5.js";
 import "./chunk-NE55C6S5.js";
 import "./chunk-JYVGYKXG.js";
 import {
   createRuntimeStartTimeResolver,
   isClipVisibleAt,
   isInClipWindow
-} from "./chunk-XQKVEQNY.js";
+} from "./chunk-5ERVRJMV.js";
 import {
   readElementRateSpec,
   sourceTimeAt,
   timeAtSourceTime
-} from "./chunk-QBYHNRHU.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";
@@ -122,16 +132,16 @@ import {
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-GNTVYF7E.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 {
   parseHTML
 } from "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import {
   normalizeErrorMessage
@@ -190,6 +200,7 @@ function resolveSnapshotCompositionRange(html, durations, id, duration) {
 }
 
 // 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";
@@ -429,18 +440,29 @@ function computeSnapshotTimes(duration, opts) {
   return { times: times.map(round), appendedTail: false };
 }
 async function captureSnapshots(projectDir, opts) {
-  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-26MXQOZG.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 = [];
@@ -463,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") {
@@ -512,13 +536,15 @@ async function captureSnapshots(projectDir, opts) {
         );
       }
       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 {
@@ -527,11 +553,12 @@ async function captureSnapshots(projectDir, opts) {
       let syncVideoFrameVisibility = null;
       let extractMediaMetadata = null;
       try {
-        const engine = await import("./src-2NN2WB6X.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.`
         );
@@ -634,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`
             );
@@ -647,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`
             );
@@ -657,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,
@@ -664,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,
@@ -678,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) {
@@ -701,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",
@@ -723,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",
@@ -834,7 +913,7 @@ 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 snapshotDir = args.output ? resolve(String(args.output)) : artifactDirectory(project.dir, "snapshots");
       await withProjectLock(project.dir, "snapshot", async () => {
         const paths = await captureSnapshots(project.dir, {
           frames,
@@ -863,10 +942,8 @@ ${c.error("\u2717")} Could not determine composition duration \u2014 no frames c
           );
           failCommand();
         }
-        console.log(
-          `
-${c.success("\u25C7")}  ${paths.length} snapshots saved to ${args.output ? snapshotDir : "snapshots/"}`
-        );
+        console.log(`
+${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
         for (const p of paths) {
           console.log(`   ${p}`);
         }

package/dist/{src-2NN2WB6X.js → src-AVQBAECC.js}

@@ -216,8 +216,8 @@ import {
   verifyGpuParity,
   writeCapturedFrame,
   writeUrlDownloadTelemetry
-} from "./chunk-IZPN423R.js";
-import "./chunk-3SVC7SW4.js";
+} from "./chunk-EXH6L2XZ.js";
+import "./chunk-RN5I2DP5.js";
 import "./chunk-NE55C6S5.js";
 import {
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
@@ -228,11 +228,11 @@ import {
 import {
   MEDIA_VISUAL_STYLE_PROPERTIES,
   quantizeTimeToFrame
-} from "./chunk-XQKVEQNY.js";
-import "./chunk-QBYHNRHU.js";
+} from "./chunk-5ERVRJMV.js";
+import "./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";
@@ -241,11 +241,11 @@ import "./chunk-RQVDTPGD.js";
 import {
   chromeMajorCeiling
 } from "./chunk-TWWSYAKJ.js";
-import "./chunk-GNTVYF7E.js";
+import "./chunk-YOEGUBBY.js";
 import {
   resolveProjectRelativeSrc
 } from "./chunk-IWFLMU2N.js";
-import "./chunk-APDLWWFG.js";
+import "./chunk-3VGU2SH7.js";
 import {
   FFMPEG_PATH_ENV,
   FFPROBE_PATH_ENV
@@ -253,7 +253,7 @@ import {
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import {
   TRANSITIONS,