hyperframes 0.8.158 → 0.8.160

package/dist/{sherpa-IBKSF6GX.js → sherpa-GFRG3TMM.js}

@@ -16,24 +16,24 @@ import {
   sherpaRuntimeLoadError,
   sherpaUnsupportedReason,
   transcribeWithSherpa
-} from "./chunk-4YDQQQY6.js";
+} from "./chunk-MP676E4B.js";
 import "./chunk-BXCMXMJQ.js";
 import "./chunk-3DKN5WKL.js";
 import "./chunk-EOVYQ3IG.js";
-import "./chunk-ZZ3ZWTOI.js";
-import "./chunk-T243WV6D.js";
+import "./chunk-DJZEIVAP.js";
+import "./chunk-G642IIVK.js";
 import "./chunk-6BEFEWFB.js";
-import "./chunk-SQHWDFTV.js";
+import "./chunk-X3SCQP2A.js";
 import "./chunk-PO2SDVQA.js";
-import "./chunk-KEGTYA7V.js";
+import "./chunk-IK3SOMZ4.js";
 import "./chunk-XT6MXC7A.js";
-import "./chunk-IRRRH66M.js";
-import "./chunk-FJT35XBA.js";
+import "./chunk-PLEMSN3E.js";
+import "./chunk-LYIG2GZ5.js";
 import "./chunk-KCF6GHJP.js";
 import "./chunk-JYVGYKXG.js";
 import "./chunk-7KDQAD2W.js";
-import "./chunk-SGIZMTWO.js";
-import "./chunk-LPOTN5GW.js";
+import "./chunk-Q3TFX4OZ.js";
+import "./chunk-P47XYVEQ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-ALLKNYC3.js";
@@ -42,10 +42,10 @@ import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
-import "./chunk-YIJMVFEJ.js";
-import "./chunk-54DMWFQZ.js";
+import "./chunk-22QHO26F.js";
+import "./chunk-D3ZWBHZP.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-7F3B5YYT.js";
+import "./chunk-2742O5DO.js";
 import "./chunk-IWFLMU2N.js";
 import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";

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

@@ -22,11 +22,11 @@ Run commands as `npx hyperframes ...` unless project instructions provide a wrap
 3. **Author:** write the composition using `/hyperframes-core`. To know what is on a project's timeline (tracks, clips, starts, ends, what plays), run `npx hyperframes timeline --json` instead of reading `index.html` and every sub-composition file: nested rows carry absolute main-timeline `absStart`/`absEnd` and their owning `file`, not just their local, per-sub-composition time. Prefer `--json` over the text form; it costs fewer tokens for the same or better correctness. See `references/upgrade-info-misc.md` for one-liners that answer common questions without reading the whole output.
 4. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes.
 5. **Run the final gate:** run `npx hyperframes check`; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add `--snapshots` for annotated overview frames and finding crops.
-6. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene.
+6. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene. Inspect the opening 30 seconds and reported problem times at full resolution; zoom into fine geometry, text, and WebGL edges rather than judging a contact sheet alone.
 7. **Open the final Studio preview:** run `npx hyperframes preview --background`, verify the URL returns HTTP 200, hand the timeline project URL to the user, and ask whether to revise or render. Keep it alive until review ends.
 8. **Render only after approval:** use `--quality draft` while iterating, `--quality looks` for the first real encode (the CLI default), and `--quality delivery` for final delivery.
 9. **Hand the project to the desktop app (on offer):** when the render's Framey line ends in `hyperframes open …`, offer `npx hyperframes open [dir]`. It opens the project in the HyperFrames desktop app and adds it to Home; under Claude Code, Codex or Grok its chat picks up this conversation. Without the app it exits 1 and prints the download link. `--json` for agents. When `open` says to run `catch-up` once the person is back, or any command ends with a line naming it, run `npx hyperframes catch-up [dir]` before your next change: it lists what was asked and changed in the app since the hand-off. An older CLI has no `catch-up`.
-10. **Verify the output:** confirm the file exists and is non-empty. Read the render summary's second line (`beginframe` vs `screenshot`, GPU, stage timings). `screenshot` + `software gpu` on Linux is the slow path. `ffprobe -v error -show_format -show_streams` and compare duration (and fps if the brief set it) to the root `data-duration`.
+10. **Verify the output:** confirm the file exists and is non-empty. Read the render summary's second line (`beginframe` vs `screenshot`, GPU, stage timings). `screenshot` + `software gpu` on Linux is the slow path. `ffprobe -v error -show_format -show_streams` and compare duration (and fps if the brief set it) to the root `data-duration`. Visually inspect decoded output frames at the same times as the preview, including close-ups; a successful check or encode does not certify the pixels inside a canvas.
 
 <!-- history (trial): remove this block together with the command -->
 
@@ -104,8 +104,9 @@ Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timel
 
 - Non-TTY mode is automatic and scaffolds the centered blank. Pass `--example` only to start from a named example. Use `--non-interactive` to force flag-only mode on a TTY.
 - Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop.
-- When disk is tight, run `npx hyperframes clean` (`--dry-run` to list first); it removes what dead renders left and idle caches that rebuild themselves, never outputs, sources or anything a running render uses. Write QC frames to a temp dir, not the project.
+- When disk is tight, run `npx hyperframes clean` (`--dry-run` to list first); it removes what dead renders left and idle caches that rebuild themselves, never outputs, sources or anything a running render uses. Write disposable QC frames to a temp dir, then remove only that owned directory. Managed snapshot runs retain the newest 10 plus current/latest/rendered evidence; active captures and runs younger than 24 hours are protected. Copy intentional before/after evidence outside managed storage before it ages out. Never delete `.hyperframes` wholesale: it also holds project history.
 - Use `--strict`, `--strict-all`, and `--strict-variables` when the corresponding warnings, variables, or CI conditions must gate the render.
+- For `shader_unbounded_cosine_pow`, clamp the cosine to `[0, 1]` before `pow(1 - cosine, exponent)`; a lower-only `max` is insufficient. Follow `/hyperframes-animation` → `adapters/three.md` for the source fix and affected-GPU preview/export verification. Lint only recognizes static shader expressions, and software rendering can miss hardware-specific invalid pixels.
 - JSON paths redact the home directory as `$HOME`; do not try to reverse the redaction.
 - When a hosted cloud project approaches or exceeds the 200 MB upload limit, use `cloud render --dry-run --json` and follow the `.hyperframesignore` investigation in `references/cloud.md`. Never ignore an asset merely because it is large.
 - Never render merely because checks pass. Pause at the final preview and wait for approval.
@@ -194,6 +195,6 @@ Two entries in `hyperframes --help` are not part of the authoring loop, and reac
 
 Run `npx hyperframes usage --json` at the start of a video workflow and again at milestones such as after drafting and before rendering. A fresh read at handoff can serve as the start read. Use `--harness claude-code`, `--harness codex`, or `--harness grok` to select explicitly.
 
-Known results contain `status: "known"`, `harness`, `planTier`, `session`, and `weekly`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`.
+Known results contain `status: "known"`, `harness`, `planTier`, `session`, `weekly`, and `spend`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows; a spend-metered plan (such as Enterprise) has neither and reports `spend`, the share of its billing-period spend limit already used, with `resetsAt: null`. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`. Only Claude Code reports `spend`; it is `null` elsewhere. When no window is available the result is `status: "unknown"` with `reason: "no_usage_windows"`.
 
 Unknown results contain `status: "unknown"` and a token-free `reason`. Missing, expired, unsupported, ambiguous, or unreadable logins and unavailable provider responses return unknown. Report the unknown state without guessing allowance. The command reads existing credentials without refreshing or rewriting them and emits no tokens or telemetry. Usage is a snapshot; it does not reserve allowance or estimate the next video's cost. Keep scope and workflow choices with the user.

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

@@ -112,6 +112,14 @@ Still PNGs. Each run writes `.hyperframes/artifacts/snapshots/<id>/` unless `--o
 
 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`.
 
+### Keep verification clean and inspect the actual pixels
+
+Inspect full-resolution frames in the opening 30 seconds, each mounted scene, and every reported problem interval. Contact sheets locate moments; use close-ups to judge thin edges, glass, particles, and WebGL geometry. Check the live preview and decoded render at matching times. Canvas shader defects can survive a successful DOM/layout audit. Record the browser/GPU and capture path when results differ across machines; isolate the failing material or pass before changing rendering defaults.
+
+Managed snapshot storage keeps the newest 10 run folders, the newest evidence for the current revision and retained rendered revisions, and the latest snapshot. Live captures and folders younger than 24 hours are also preserved. Automatic cleanup removes whole eligible old UUID folders, including contact sheets and descriptions; arbitrary `--output` folders are untouched. Save intentional before/after evidence outside this managed storage.
+
+For disposable checks, allocate a temporary output folder and remove that folder after inspecting it. Use `hyperframes clean --dry-run` to inspect broader cleanup. `clean --snapshots` explicitly discards snapshot evidence; use it only when that evidence is no longer needed. Never recommend removing all of `.hyperframes`, which also contains project history and other state.
+
 ### Zooming into a reported finding
 
 `hyperframes check --snapshots` already writes a `finding-NN-<code>.png` crop for every error finding that carries a bbox, but the same zoom is available standalone once you know what to look at:

package/dist/skills/hyperframes-cli/references/upgrade-info-misc.md

@@ -129,6 +129,6 @@ For voice selection, Whisper model rules, output format choice, and the TTS →
 
 Run `npx hyperframes usage --json` at the start of a video workflow and again at milestones such as after drafting and before rendering. A fresh read at handoff can serve as the start read. Use `--harness claude-code`, `--harness codex`, or `--harness grok` to select explicitly.
 
-Known results contain `status: "known"`, `harness`, `planTier`, `session`, and `weekly`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`.
+Known results contain `status: "known"`, `harness`, `planTier`, `session`, `weekly`, and `spend`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows; a spend-metered plan (such as Enterprise) has neither and reports `spend`, the share of its billing-period spend limit already used, with `resetsAt: null`. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`. Only Claude Code reports `spend`; it is `null` elsewhere. When no window is available the result is `status: "unknown"` with `reason: "no_usage_windows"`.
 
 Unknown results contain `status: "unknown"` and a token-free `reason`. Missing, expired, unsupported, ambiguous, or unreadable logins and unavailable provider responses return unknown. Report the unknown state without guessing allowance. The command reads existing credentials without refreshing or rewriting them and emits no tokens or telemetry. Usage is a snapshot; it does not reserve allowance or estimate the next video's cost. Keep scope and workflow choices with the user.

package/dist/{skills-E75DFHGG.js → skills-LKJA27ZN.js}

@@ -6,8 +6,8 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   trackSkillsInstallSkipped
-} from "./chunk-2XUQPJ3W.js";
-import "./chunk-H6BWNY56.js";
+} from "./chunk-KRE55WLI.js";
+import "./chunk-ICZVCVD3.js";
 import {
   diag
 } from "./chunk-VWG7OQKU.js";
@@ -35,15 +35,15 @@ import {
   isCoreSkill,
   presentSkills,
   pruneOrphanedLockEntries
-} from "./chunk-W2SNLHKF.js";
+} from "./chunk-TTFDAWCS.js";
 import {
   withMeta
-} from "./chunk-QH2PL6J4.js";
+} from "./chunk-FRGYHRP6.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-RU6AIVON.js";
+import "./chunk-TU2CQJO3.js";
 import {
   buildNpxCommand
 } from "./chunk-6BEFEWFB.js";

package/dist/{skillsUpdateCheck-EPTKOBR6.js → skillsUpdateCheck-RFZJKZC4.js}

@@ -9,13 +9,13 @@ import {
   printSkillsUpdateNotice,
   refreshSkillsCache,
   skillsCheckDue
-} from "./chunk-W2SNLHKF.js";
-import "./chunk-QH2PL6J4.js";
+} from "./chunk-TTFDAWCS.js";
+import "./chunk-FRGYHRP6.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-RU6AIVON.js";
+import "./chunk-TU2CQJO3.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 export {

package/dist/{snapshot-Z6T4I5TE.js → snapshot-EOYA4MLG.js}

@@ -4,6 +4,9 @@ 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-MRF4AMKD.js";
 import {
   parseAngle
 } from "./chunk-KZI44OPA.js";
@@ -14,13 +17,8 @@ import {
 } from "./chunk-57GN6KWT.js";
 import {
   captureArtifactRevision
-} from "./chunk-Y6E2PW7Z.js";
-import "./chunk-Z347DFOL.js";
-import {
-  serveStaticProjectHtml
-} from "./chunk-4R6OZQGX.js";
-import "./chunk-XUHOIDKG.js";
-import "./chunk-J4SSEVRU.js";
+} from "./chunk-GOASXWDD.js";
+import "./chunk-V2FQQILJ.js";
 import "./chunk-X7MTZ4T2.js";
 import {
   DEFAULT_ZOOM_SCALE,
@@ -30,46 +28,55 @@ import {
   resolveCropRegion,
   runFfmpegOnce,
   seekCompositionTimeline
-} from "./chunk-7FGHFHWD.js";
+} from "./chunk-6MCASYIS.js";
 import "./chunk-FH7WODJH.js";
-import "./chunk-LAAGHMRC.js";
-import "./chunk-J7WFHOCW.js";
+import "./chunk-B5FZ2CQM.js";
+import "./chunk-ERTJPFCH.js";
 import "./chunk-WPNE5NEP.js";
-import "./chunk-DCQCGE2W.js";
-import "./chunk-56QTFOWH.js";
-import "./chunk-C6TPGUWD.js";
-import {
-  artifactDirectory,
-  forgetRecordedArtifacts,
-  recordArtifacts
-} from "./chunk-6PIGOKTE.js";
-import "./chunk-DISITOR6.js";
-import "./chunk-FFDC5OWV.js";
-import {
-  resolveProject
-} from "./chunk-L6AJC7UQ.js";
 import {
   formatLintFindings
 } from "./chunk-6CSYCFQV.js";
+import {
+  resolveProject
+} from "./chunk-37LNY2EC.js";
 import "./chunk-K2FLNJVB.js";
+import {
+  serveStaticProjectHtml
+} from "./chunk-GOTCGKX6.js";
+import "./chunk-X7MTZ4T2.js";
+import "./chunk-SHVDJON6.js";
 import "./chunk-DQBY7FRR.js";
 import {
   resolveLocalBrowserGpuMode
-} from "./chunk-YB26LWR2.js";
+} from "./chunk-SB5DX6AD.js";
 import "./chunk-442JNXRM.js";
-import "./chunk-GPUVPZRK.js";
+import "./chunk-XUHOIDKG.js";
+import "./chunk-VD7WQYTO.js";
+import "./chunk-PINFPWRV.js";
+import "./chunk-C6TPGUWD.js";
+import "./chunk-6JR2XUEE.js";
+import "./chunk-4ID635FL.js";
+import {
+  artifactDirectory,
+  finishSnapshotRun,
+  forgetRecordedArtifacts,
+  recordArtifacts,
+  retainSnapshotOutput
+} from "./chunk-JGYHWVXQ.js";
+import "./chunk-FFDC5OWV.js";
+import "./chunk-GG37I7B3.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import "./chunk-HVW7ABXD.js";
-import "./chunk-3FRK53UC.js";
-import "./chunk-LQXHRO6F.js";
-import "./chunk-QRPYTJBW.js";
+import "./chunk-D33YJZOH.js";
+import "./chunk-N2NDDTYW.js";
+import "./chunk-EVRUR7DW.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
 import "./chunk-5CS4T6C6.js";
-import "./chunk-2XUQPJ3W.js";
-import "./chunk-H6BWNY56.js";
+import "./chunk-KRE55WLI.js";
+import "./chunk-ICZVCVD3.js";
 import "./chunk-VWG7OQKU.js";
 import "./chunk-QWQ6GQTI.js";
 import {
@@ -93,7 +100,7 @@ import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-RU6AIVON.js";
+import "./chunk-TU2CQJO3.js";
 import {
   loadOptionalPackage
 } from "./chunk-3DKN5WKL.js";
@@ -103,10 +110,10 @@ import {
   findFFmpeg,
   findFFprobe,
   getFFmpegInstallHint
-} from "./chunk-KEGTYA7V.js";
+} from "./chunk-IK3SOMZ4.js";
 import "./chunk-XT6MXC7A.js";
-import "./chunk-IRRRH66M.js";
-import "./chunk-FJT35XBA.js";
+import "./chunk-PLEMSN3E.js";
+import "./chunk-LYIG2GZ5.js";
 import "./chunk-KCF6GHJP.js";
 import "./chunk-JYVGYKXG.js";
 import "./chunk-7KDQAD2W.js";
@@ -114,12 +121,12 @@ import {
   createRuntimeStartTimeResolver,
   isClipVisibleAt,
   isInClipWindow
-} from "./chunk-SGIZMTWO.js";
+} from "./chunk-Q3TFX4OZ.js";
 import {
   readElementRateSpec,
   sourceTimeAt,
   timeAtSourceTime
-} from "./chunk-LPOTN5GW.js";
+} from "./chunk-P47XYVEQ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-ALLKNYC3.js";
@@ -130,11 +137,11 @@ import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
 import {
   runCancellableProcess
-} from "./chunk-54DMWFQZ.js";
+} from "./chunk-D3ZWBHZP.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-7F3B5YYT.js";
+} from "./chunk-2742O5DO.js";
 import "./chunk-IWFLMU2N.js";
 import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";
@@ -231,6 +238,19 @@ var FFMPEG_EXTRACT_TIMEOUT_MS = 3e4;
 function formatSnapshotTimestamp(time) {
   return `${Number(time.toFixed(3))}s`;
 }
+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;
@@ -442,7 +462,7 @@ function computeSnapshotTimes(duration, opts) {
   return { times: times.map(round), appendedTail: false };
 }
 async function captureSnapshots(projectDir, opts) {
-  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-IVO43QBQ.js");
+  const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts-SLBVWQ7O.js");
   const capture = await captureArtifactRevision(projectDir).catch(warnSnapshotsNotRecorded);
   const invocation = randomUUID();
   const artifacts = [];
@@ -542,7 +562,7 @@ async function captureSnapshots(projectDir, opts) {
       mkdirSync(snapshotDir, { recursive: true });
       try {
         const { readdirSync } = await import("fs");
-        for (const file of readdirSync(snapshotDir)) {
+        for (const file of opts.keep ? [] : readdirSync(snapshotDir)) {
           if (/\.(png|jpg|jpeg)$/i.test(file)) {
             const path = resolve(snapshotDir, file);
             replaced.push(path);
@@ -555,7 +575,7 @@ async function captureSnapshots(projectDir, opts) {
       let syncVideoFrameVisibility = null;
       let extractMediaMetadata = null;
       try {
-        const engine = await import("./src-NDI4KNT3.js");
+        const engine = await import("./src-GPUDUKY6.js");
         injectVideoFramesBatch = engine.injectVideoFramesBatch;
         syncVideoFrameVisibility = engine.syncVideoFrameVisibility;
         extractMediaMetadata = engine.extractMediaMetadata;
@@ -685,8 +705,8 @@ async function captureSnapshots(projectDir, opts) {
         }
         await recaptureSnapshotComposite(page);
         const timeLabel = formatSnapshotTimestamp(time);
-        const index = String(i).padStart(2, "0");
-        const filename = `frame-${index}-at-${timeLabel}.png`;
+        const slot = opts.keep ? `at-${timeLabel}` : `${String(i).padStart(2, "0")}-at-${timeLabel}`;
+        const filename = opts.keep ? `${slot}.png` : `frame-${slot}.png`;
         const framePath = join(snapshotDir, filename);
         let crop;
         if (opts.zoom) {
@@ -708,9 +728,12 @@ async function captureSnapshots(projectDir, opts) {
             region,
             opts.zoomScale ?? DEFAULT_ZOOM_SCALE
           );
-          writeFileSync(framePath, buffer);
+          writeCaptureFileSync(framePath, buffer);
         } else {
-          await page.screenshot({ path: framePath, type: "png", omitBackground: true });
+          writeCaptureFileSync(
+            framePath,
+            await page.screenshot({ type: "png", omitBackground: true })
+          );
         }
         artifacts.push({
           id: `${invocation}-${i}`,
@@ -732,9 +755,9 @@ async function captureSnapshots(projectDir, opts) {
               `   ${c.warn("\u26A0")} --against has no frame at ${timeLabel} \u2014 reference pair skipped`
             );
           } else {
-            const refPath = join(snapshotDir, `ref-${index}-at-${timeLabel}.png`);
-            writeFileSync(refPath, refPng);
-            const pairPath = join(snapshotDir, `pair-${index}-at-${timeLabel}.jpg`);
+            const refPath = join(snapshotDir, `ref-${slot}.png`);
+            writeCaptureFileSync(refPath, refPng);
+            const pairPath = join(snapshotDir, `pair-${slot}.jpg`);
             const { createContactSheet } = await import("./contactSheet-27SRU7A4.js");
             await createContactSheet([framePath, refPath], pairPath, {
               cols: 2,
@@ -837,6 +860,11 @@ var snapshot_default = defineCommand({
       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."
@@ -902,6 +930,7 @@ var snapshot_default = defineCommand({
     }
     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;
+    if (args.keep === true && atTimestamps) assertDistinctKeepNames(atTimestamps);
     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;
@@ -914,8 +943,11 @@ var snapshot_default = defineCommand({
     const label = 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}`);
+    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, {
           frames,
@@ -930,7 +962,8 @@ var snapshot_default = defineCommand({
           zoomScale,
           autoProxy: args.proxy,
           browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"]),
-          against
+          against,
+          keep: args.keep === true
         });
         reportArtifacts(
           "snapshot",
@@ -956,7 +989,7 @@ ${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
         }
         try {
           const { createSnapshotContactSheet } = await import("./contactSheet-27SRU7A4.js");
-          const sheets = await createSnapshotContactSheet(
+          const sheets = args.keep === true ? [] : await createSnapshotContactSheet(
             snapshotDir,
             join(snapshotDir, "contact-sheet.jpg")
           );
@@ -1058,6 +1091,9 @@ ${c.success("\u25C7")}  ${paths.length} snapshots saved to ${snapshotDir}`);
       console.error(`
 ${c.error("\u2717")} Snapshot failed: ${msg}`);
       failCommand();
+    } finally {
+      if (managedSnapshotDir)
+        await finishSnapshotRun(project.dir, managedSnapshotDir).catch(warnSnapshotsNotRecorded);
     }
   }
 });

package/dist/{src-NDI4KNT3.js → src-GPUDUKY6.js}

@@ -53,6 +53,7 @@ import {
   assertPublicHttpsUrl,
   assertSwiftShader,
   assertWebGpuAdapterAvailable,
+  audioFailureDiagnostics,
   augmentPageNavigationTimeoutError,
   augmentProtocolTimeoutError,
   beginFrameCapture,
@@ -216,8 +217,8 @@ import {
   verifyGpuParity,
   writeCapturedFrame,
   writeUrlDownloadTelemetry
-} from "./chunk-IRRRH66M.js";
-import "./chunk-FJT35XBA.js";
+} from "./chunk-PLEMSN3E.js";
+import "./chunk-LYIG2GZ5.js";
 import "./chunk-KCF6GHJP.js";
 import {
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
@@ -229,8 +230,8 @@ import "./chunk-7KDQAD2W.js";
 import {
   MEDIA_VISUAL_STYLE_PROPERTIES,
   quantizeTimeToFrame
-} from "./chunk-SGIZMTWO.js";
-import "./chunk-LPOTN5GW.js";
+} from "./chunk-Q3TFX4OZ.js";
+import "./chunk-P47XYVEQ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-ALLKNYC3.js";
@@ -242,7 +243,7 @@ import "./chunk-RQVDTPGD.js";
 import {
   chromeMajorCeiling
 } from "./chunk-TWWSYAKJ.js";
-import "./chunk-7F3B5YYT.js";
+import "./chunk-2742O5DO.js";
 import {
   resolveProjectRelativeSrc
 } from "./chunk-IWFLMU2N.js";
@@ -319,6 +320,7 @@ export {
   assertPublicHttpsUrl,
   assertSwiftShader,
   assertWebGpuAdapterAvailable,
+  audioFailureDiagnostics,
   augmentPageNavigationTimeoutError,
   augmentProtocolTimeoutError,
   beginFrameCapture,

package/dist/{src-4GCHM2LX.js → src-IMCQRH4P.js}

@@ -69,7 +69,7 @@ import {
   serializeRenderRequest,
   startServer,
   validatePlanV2MaterializedTarget
-} from "./chunk-EEEUI3ON.js";
+} from "./chunk-2ZLYSXZC.js";
 import {
   FONT_FETCH_FAILED,
   FONT_FETCH_UNAVAILABLE,
@@ -78,11 +78,11 @@ import {
   injectDeterministicFontFaces
 } from "./chunk-3QATT3QF.js";
 import "./chunk-FI4I7CME.js";
-import "./chunk-T76NSAXO.js";
+import "./chunk-MMV6IY6U.js";
+import "./chunk-BZ56MTDX.js";
 import "./chunk-KLIKCX6Q.js";
 import "./chunk-EOOEC32M.js";
 import "./chunk-TJSTGSAW.js";
-import "./chunk-BZ56MTDX.js";
 import {
   DEFAULT_CONFIG,
   captureFrame,
@@ -96,15 +96,15 @@ import {
   isTransientBrowserError,
   prepareCaptureSessionForReuse,
   resolveConfig
-} from "./chunk-IRRRH66M.js";
-import "./chunk-FJT35XBA.js";
+} from "./chunk-PLEMSN3E.js";
+import "./chunk-LYIG2GZ5.js";
 import "./chunk-KCF6GHJP.js";
 import "./chunk-JYVGYKXG.js";
 import "./chunk-7KDQAD2W.js";
 import {
   quantizeTimeToFrame
-} from "./chunk-SGIZMTWO.js";
-import "./chunk-LPOTN5GW.js";
+} from "./chunk-Q3TFX4OZ.js";
+import "./chunk-P47XYVEQ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-ALLKNYC3.js";
@@ -114,7 +114,7 @@ import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-7F3B5YYT.js";
+import "./chunk-2742O5DO.js";
 import "./chunk-IWFLMU2N.js";
 import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";

package/dist/{staticProjectServer-ITNEQNQ7.js → staticProjectServer-S3NK3V4S.js}

@@ -5,24 +5,26 @@ var require = __hf_createRequire(import.meta.url);
 var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
+  inProcessAnswer,
   serveStaticProjectHtml
-} from "./chunk-4R6OZQGX.js";
-import "./chunk-XUHOIDKG.js";
-import "./chunk-J4SSEVRU.js";
+} from "./chunk-GOTCGKX6.js";
 import "./chunk-X7MTZ4T2.js";
-import "./chunk-DCQCGE2W.js";
-import "./chunk-56QTFOWH.js";
+import "./chunk-SHVDJON6.js";
+import "./chunk-XUHOIDKG.js";
+import "./chunk-VD7WQYTO.js";
+import "./chunk-PINFPWRV.js";
 import "./chunk-C6TPGUWD.js";
-import "./chunk-6PIGOKTE.js";
-import "./chunk-DISITOR6.js";
+import "./chunk-6JR2XUEE.js";
+import "./chunk-4ID635FL.js";
+import "./chunk-JGYHWVXQ.js";
 import "./chunk-FFDC5OWV.js";
-import "./chunk-GPUVPZRK.js";
+import "./chunk-GG37I7B3.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import "./chunk-HVW7ABXD.js";
-import "./chunk-3FRK53UC.js";
-import "./chunk-LQXHRO6F.js";
-import "./chunk-QRPYTJBW.js";
+import "./chunk-D33YJZOH.js";
+import "./chunk-N2NDDTYW.js";
+import "./chunk-EVRUR7DW.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
@@ -31,10 +33,10 @@ import "./chunk-KLIKCX6Q.js";
 import "./chunk-EOOEC32M.js";
 import "./chunk-TJSTGSAW.js";
 import "./chunk-EOVYQ3IG.js";
-import "./chunk-FJT35XBA.js";
+import "./chunk-LYIG2GZ5.js";
 import "./chunk-KCF6GHJP.js";
-import "./chunk-SGIZMTWO.js";
-import "./chunk-LPOTN5GW.js";
+import "./chunk-Q3TFX4OZ.js";
+import "./chunk-P47XYVEQ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import "./chunk-ALLKNYC3.js";
@@ -43,7 +45,7 @@ import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
-import "./chunk-7F3B5YYT.js";
+import "./chunk-2742O5DO.js";
 import "./chunk-IWFLMU2N.js";
 import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";
@@ -54,5 +56,6 @@ import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-M2WBOQ2Q.js";
 export {
+  inProcessAnswer,
   serveStaticProjectHtml
 };