Skip to content

Write HTML. Render video. Built for agents.

feat(cli): snapshot --keep redoes one still and leaves the others (#5605)

Miguel Ángelc0636d017f68
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index b1d91149b2..c186b36622 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -869,6 +869,7 @@ npx hyperframes snapshot my-project --at 1.5,4.3 --against ref.mp4
| `--composition <id>` | Spread `--frames` across the visible interval of the element with this `data-composition-id`. Use one of `--at`, `--range` or `--composition`. |
| `--output, -o` | Where the PNGs go (default: a new `<project>/.hyperframes/artifacts/snapshots/<id>` per run) |
| `--end` / `--no-end` | Always add a readable end-of-timeline frame (default: on). `--no-end` captures only your `--at` times. |
+| `--keep` | Add to `--output` instead of clearing it, naming each still for its time: `at-0s.png`, `at-1.5s.png`, `at-12.25s.png` (no trailing zeros). Snapshotting one moment again replaces only that still. No contact sheet. |
| `--zoom` | Crop to a CSS selector or an exact `x,y,w,h` region, using a raised device scale factor. Layout is untouched — never CSS zoom or a resized viewport. A selector that matches nothing is an error. |
| `--against` | A reference video, such as footage you are rebuilding. For every captured time also saves its frame-exact frame (`ref-XX-…png`) and a labelled render / reference pair (`pair-XX-…jpg`). |
| `--zoom-scale` | Pixel density for `--zoom` crops (default 3) |
diff --git a/packages/cli/src/commands/snapshot-contactSheet.test.ts b/packages/cli/src/commands/snapshot-contactSheet.test.ts
index f943c9804c..cf43763c45 100644
--- a/packages/cli/src/commands/snapshot-contactSheet.test.ts
+++ b/packages/cli/src/commands/snapshot-contactSheet.test.ts
@@ -1,16 +1,23 @@
import { runCommand } from "citty";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+ existsSync,
+ linkSync,
+ lstatSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ readdirSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const capture = vi.hoisted(() => ({
evaluate: vi.fn(),
- screenshot: vi.fn(async ({ path }: { path: string }) => {
- const bytes = Buffer.from("captured PNG");
- writeFileSync(path, bytes);
- return bytes;
- }),
+ screenshot: vi.fn(async () => Buffer.from("captured PNG")),
closeBrowser: vi.fn(async () => undefined),
closeServer: vi.fn(async () => undefined),
seek: vi.fn(async () => undefined),
@@ -43,6 +50,21 @@ import snapshotCommand from "./snapshot.js";
import { historyDeps } from "../utils/historyOwner.js";
import { openProjectHistory } from "@hyperframes/studio-server/history";
+/** The page's answers for one run: asset check, duration, ready, then two per frame. */
+function primePage(frames: number) {
+ capture.evaluate
+ .mockReset()
+ .mockResolvedValueOnce({ loaded: [], errored: [], unused: [] })
+ .mockResolvedValueOnce(2)
+ .mockResolvedValueOnce(true);
+ for (let i = 0; i < frames; i++) {
+ capture.evaluate.mockResolvedValueOnce([]).mockResolvedValueOnce(undefined);
+ }
+}
+
+const PROJECT_HTML =
+ '<html><body><div id="root" data-composition-id="main" data-width="640" data-height="360" data-start="0" data-duration="2">Visible</div><script>window.__timelines = { main: { duration() { return 2; }, seek() {} } };</script></body></html>';
+
describe("snapshot contact sheet failures", () => {
let project: string;
@@ -50,19 +72,8 @@ describe("snapshot contact sheet failures", () => {
vi.resetModules();
vi.clearAllMocks();
project = mkdtempSync(join(tmpdir(), "hf-snapshot-contact-sheet-"));
- writeFileSync(
- join(project, "index.html"),
- '<html><body><div id="root" data-composition-id="main" data-width="640" data-height="360" data-start="0" data-duration="2">Visible</div><script>window.__timelines = { main: { duration() { return 2; }, seek() {} } };</script></body></html>',
- );
- capture.evaluate
- .mockReset()
- .mockResolvedValueOnce({ loaded: [], errored: [], unused: [] })
- .mockResolvedValueOnce(2)
- .mockResolvedValueOnce(true)
- .mockResolvedValueOnce([])
- .mockResolvedValueOnce(undefined)
- .mockResolvedValueOnce([])
- .mockResolvedValueOnce(undefined);
+ writeFileSync(join(project, "index.html"), PROJECT_HTML);
+ primePage(2);
vi.spyOn(console, "log").mockImplementation(() => undefined);
vi.spyOn(console, "warn").mockImplementation(() => undefined);
vi.spyOn(console, "error").mockImplementation(() => undefined);
@@ -161,20 +172,8 @@ describe("snapshot contact sheet failures", () => {
historyRoot: historyDeps.historyRoot,
ownerWaitMs: 0,
});
- capture.screenshot.mockImplementation(async ({ path }: { path: string }) => {
- const bytes = Buffer.from("replaced PNG");
- writeFileSync(path, bytes);
- return bytes;
- });
- capture.evaluate
- .mockReset()
- .mockResolvedValueOnce({ loaded: [], errored: [], unused: [] })
- .mockResolvedValueOnce(2)
- .mockResolvedValueOnce(true)
- .mockResolvedValueOnce([])
- .mockResolvedValueOnce(undefined)
- .mockResolvedValueOnce([])
- .mockResolvedValueOnce(undefined);
+ capture.screenshot.mockImplementation(async () => Buffer.from("replaced PNG"));
+ primePage(2);
try {
await runCommand(snapshotCommand, args);
for (const [index, time] of ["0.5", "1"].entries()) {
@@ -194,3 +193,70 @@ describe("snapshot contact sheet failures", () => {
}
});
});
+
+describe("snapshot --keep", () => {
+ let project: string;
+ let stills: string;
+
+ beforeEach(() => {
+ project = mkdtempSync(join(tmpdir(), "hf-snapshot-keep-"));
+ stills = join(project, "boards", "stills");
+ writeFileSync(join(project, "index.html"), PROJECT_HTML);
+ vi.spyOn(console, "log").mockImplementation(() => undefined);
+ vi.spyOn(console, "warn").mockImplementation(() => undefined);
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ rmSync(project, { recursive: true, force: true });
+ });
+
+ async function snapshot(at: string, bytes: string) {
+ capture.screenshot.mockImplementation(async () => Buffer.from(bytes));
+ primePage(at.split(",").length);
+ await runCommand(snapshotCommand, {
+ rawArgs: [project, "--keep", "--at", at, "--no-end", "--describe", "false", "-o", stills],
+ });
+ }
+
+ it("redoes one moment and keeps every other still", async () => {
+ await snapshot("0,0.5,1.5", "first PNG");
+ await snapshot("0.5", "redo PNG");
+
+ expect(readdirSync(stills).sort()).toEqual(["at-0.5s.png", "at-0s.png", "at-1.5s.png"]);
+ expect(readFileSync(join(stills, "at-0s.png"), "utf8")).toBe("first PNG");
+ expect(readFileSync(join(stills, "at-0.5s.png"), "utf8")).toBe("redo PNG");
+ expect(readFileSync(join(stills, "at-1.5s.png"), "utf8")).toBe("first PNG");
+ expect(existsSync(join(stills, "contact-sheet.jpg"))).toBe(false);
+ });
+
+ it("refuses two times that would share a still, before touching the folder", async () => {
+ await snapshot("1.5", "first PNG");
+ capture.screenshot.mockClear();
+
+ await expect(snapshot("1.5,1.5004", "second PNG")).rejects.toThrow(
+ "--keep would name both 1.5 and 1.5004 at-1.5s.png",
+ );
+ expect(capture.screenshot).not.toHaveBeenCalled();
+ expect(readFileSync(join(stills, "at-1.5s.png"), "utf8")).toBe("first PNG");
+ });
+
+ it("replaces a linked still without writing through the link", async () => {
+ mkdirSync(stills, { recursive: true });
+ const hardVictim = join(project, "hard-victim.png");
+ writeFileSync(hardVictim, "hard victim");
+ linkSync(hardVictim, join(stills, "at-0.5s.png"));
+ const softVictim = join(project, "soft-victim.png");
+ writeFileSync(softVictim, "soft victim");
+ if (process.platform !== "win32") symlinkSync(softVictim, join(stills, "at-1.5s.png"));
+
+ await snapshot("0.5,1.5", "new PNG");
+
+ expect(readFileSync(hardVictim, "utf8")).toBe("hard victim");
+ expect(readFileSync(softVictim, "utf8")).toBe("soft victim");
+ for (const still of ["at-0.5s.png", "at-1.5s.png"]) {
+ expect(lstatSync(join(stills, still)).isFile()).toBe(true);
+ expect(readFileSync(join(stills, still), "utf8")).toBe("new PNG");
+ }
+ });
+});
diff --git a/packages/cli/src/commands/snapshot.test.ts b/packages/cli/src/commands/snapshot.test.ts
index 4b6789648f..593fd106c0 100644
--- a/packages/cli/src/commands/snapshot.test.ts
+++ b/packages/cli/src/commands/snapshot.test.ts
@@ -48,6 +48,10 @@ describe("formatSnapshotTimestamp", () => {
it.each([
[1.12, "1.12s"],
[0.30000000000000004, "0.3s"],
+ [0, "0s"],
+ [1.5, "1.5s"],
+ [12.25, "12.25s"],
+ [1.5000001, "1.5s"],
])("formats %s without discarding useful precision", (time, expected) => {
expect(formatSnapshotTimestamp(time)).toBe(expected);
});
@@ -76,9 +80,7 @@ describe("tailFrameTime", () => {
describe("transparent snapshot capture", () => {
it("asks Chrome to retain the alpha channel in review PNGs", () => {
const source = readFileSync(new URL("./snapshot.ts", import.meta.url), "utf8");
- expect(source).toContain(
- 'page.screenshot({ path: framePath, type: "png", omitBackground: true })',
- );
+ expect(source).toContain('page.screenshot({ type: "png", omitBackground: true })');
});
it("exposes --proxy/--no-proxy and forwards the override to the static server", () => {
@@ -931,10 +933,7 @@ describe("snapshot composite recapture", () => {
const injection = source.indexOf("await injectVideoFramesBatch(page, updates)");
const visibility = source.indexOf("await syncVideoFrameVisibility(", injection);
const recapture = source.indexOf("await recaptureSnapshotComposite(page)", visibility);
- const finalCapture = source.indexOf(
- 'page.screenshot({ path: framePath, type: "png"',
- recapture,
- );
+ const finalCapture = source.indexOf('page.screenshot({ type: "png"', recapture);
expect(injection).toBeGreaterThan(-1);
expect(visibility).toBeGreaterThan(injection);
expect(recapture).toBeGreaterThan(visibility);
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index 58d25def41..81ae52b0b7 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -49,6 +49,7 @@ import { formatLintFindings } from "../utils/lintFormat.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { serveStaticProjectHtml } from "../utils/staticProjectServer.js";
import { c } from "../ui/colors.js";
+import { writeCaptureFileSync } from "../capture/captureFile.js";
import { runCancellableProcess } from "../utils/cancellableProcess.js";
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
import { parseAngle, type Camera } from "./motionShotLayout.js";
@@ -100,6 +101,21 @@ export function formatSnapshotTimestamp(time: number): string {
return `${Number(time.toFixed(3))}s`;
}
+/** --keep names a still by its millisecond label, so two distinct times may not share one. */
+function assertDistinctKeepNames(times: number[]): void {
+ const timeByLabel = new Map<string, number>();
+ for (const time of times) {
+ const label = formatSnapshotTimestamp(time);
+ const other = timeByLabel.get(label);
+ if (other !== undefined && 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);
+ }
+}
+
/** Shows media by the runtime's visibility rule. A clip held at the composition end, or past the end of a source
* shorter than its slot, samples one nominal 30fps frame inside the source; FFmpeg has no frame at or past its end. */
export function resolveSnapshotVideoFrameTime(input: {
@@ -466,6 +482,8 @@ async function captureSnapshots(
browserGpuMode?: BrowserGpuMode;
/** Reference video: save its frame at each captured time plus a render|reference pair. */
against?: string;
+ /** Add to outputDir without clearing it; name each still by its time, not its place in the run. */
+ keep?: boolean;
},
): Promise<string[]> {
const { bundleWithLocalizedFonts } = await import("../utils/bundleWithLocalizedFonts.js");
@@ -604,7 +622,7 @@ async function captureSnapshots(
mkdirSync(snapshotDir, { recursive: true });
try {
const { readdirSync } = await import("node: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);
@@ -819,8 +837,10 @@ async function captureSnapshots(
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: { x: number; y: number; width: number; height: number } | undefined;
@@ -845,9 +865,12 @@ async function captureSnapshots(
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}`,
@@ -871,9 +894,9 @@ async function captureSnapshots(
` ${c.warn("⚠")} --against has no frame at ${timeLabel} — 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("../capture/contactSheet.js");
await createContactSheet([framePath, refPath], pairPath, {
cols: 2,
@@ -998,6 +1021,12 @@ export default defineCommand({
"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:
@@ -1074,6 +1103,7 @@ export default defineCommand({
.map((s) => parseFloat(s.trim()))
.filter((n) => !isNaN(n))
: undefined;
+ if (args.keep === true && atTimestamps) assertDistinctKeepNames(atTimestamps);
// Gemini frame analysis runs by default (silently skipped if
// GEMINI_API_KEY is not set). `--describe "custom question"` overrides
// the default prompt with a targeted question. `--describe false` opts
@@ -1122,6 +1152,7 @@ export default defineCommand({
autoProxy: args.proxy as boolean | undefined,
browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"] as boolean | undefined),
against,
+ keep: args.keep === true,
});
reportArtifacts(
"snapshot",
@@ -1146,13 +1177,16 @@ export default defineCommand({
);
}
- // Generate contact sheet for quick AI review
+ // Generate contact sheet for quick AI review; a --keep folder mixes runs, so it gets none.
try {
const { createSnapshotContactSheet } = await import("../capture/contactSheet.js");
- const sheets = await createSnapshotContactSheet(
- snapshotDir,
- join(snapshotDir, "contact-sheet.jpg"),
- );
+ 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)`);