Skip to content

Write HTML. Render video. Built for agents.

feat(cli): snapshot a time range or one composition (#5519)

Xuanru Li1cd086f7e367
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index b75dbd32bc..5642a6d222 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -853,6 +853,8 @@ npx hyperframes snapshot my-project --at 1.5,4.3 --against ref.mp4
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--at` | Timestamps in seconds, comma-separated (`3.0,10.5,18.0`) |
| `--frames` | Evenly spaced frames instead (default 5) |
+| `--range <start,end>` | Spread `--frames` across this interval only, in root-timeline seconds, with no end-of-timeline frame added |
+| `--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 `<project>/snapshots`) |
| `--end` / `--no-end` | Always add a readable end-of-timeline frame (default: on). `--no-end` captures only your `--at` times. |
| `--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. |
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index ec328370f5..9d50c8ae0a 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -1,3 +1,9 @@
+import {
+ parseSnapshotRange,
+ sampleSnapshotRange,
+ resolveSnapshotCompositionRange,
+ type SnapshotRange,
+} from "./snapshotSampling.js";
import { failCommand } from "../utils/commandResult.js";
// fallow-ignore-file complexity
import { defineCommand } from "citty";
@@ -436,6 +442,8 @@ async function captureSnapshots(
projectDir: string,
opts: {
frames?: number;
+ range?: SnapshotRange;
+ composition?: string;
timeout?: number;
at?: number[];
outputDir?: string;
@@ -517,13 +525,38 @@ async function captureSnapshots(
return [];
}
- // Calculate seek positions — explicit timestamps or evenly spaced, always
- // including a readable end-of-timeline frame (FINDING [7]).
- const { times: positions, appendedTail } = computeSnapshotTimes(duration, {
- frames: numFrames,
- at: opts.at,
- includeEnd: opts.includeEnd,
- });
+ let range = opts.range;
+ if (opts.composition) {
+ const timing = await page.evaluate(() => ({
+ html: document.documentElement.outerHTML,
+ durations: Object.fromEntries(
+ Object.entries((window as any).__timelines ?? {}).map(([id, timeline]) => [
+ id,
+ Number((timeline as any).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]}–${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 — pass them explicitly.`)}`,
@@ -842,6 +875,16 @@ export default defineCommand({
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)",
@@ -892,6 +935,13 @@ export default defineCommand({
},
},
async run({ args }) {
+ if ([args.at, args.range, args.composition].filter((value) => value !== undefined).length > 1)
+ throw new Error("Use only one of --at, --range, or --composition");
+ const frames = parseInt(args.frames as string, 10) || 5;
+ const range = args.range === undefined ? undefined : parseSnapshotRange(String(args.range));
+ const composition =
+ args.composition === undefined ? undefined : 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)) {
@@ -920,7 +970,6 @@ export default defineCommand({
console.log("");
failCommand();
}
- const frames = parseInt(args.frames as string, 10) || 5;
const timeout = parseInt(args.timeout as string, 10) || 5000;
const atTimestamps = args.at
? String(args.at)
@@ -963,6 +1012,8 @@ export default defineCommand({
: join(project.dir, "snapshots");
const paths = await captureSnapshots(project.dir, {
frames,
+ range,
+ composition,
timeout,
at: atTimestamps,
outputDir: snapshotDir,
@@ -1001,10 +1052,8 @@ export default defineCommand({
snapshotDir,
join(snapshotDir, "contact-sheet.jpg"),
);
- if (sheets.length > 0) {
- const label =
- sheets.length === 1 ? "contact-sheet.jpg" : `contact-sheet-1..${sheets.length}.jpg`;
- console.log(` ${c.dim(label)} (grid view for AI review)`);
+ for (const sheet of sheets) {
+ console.log(` ${resolve(sheet)} (grid view for AI review)`);
}
} catch (err) {
console.warn(
@@ -1019,7 +1068,8 @@ export default defineCommand({
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")}`);
+ if (args.describe !== undefined)
+ 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");
diff --git a/packages/cli/src/commands/snapshotSampling.test.ts b/packages/cli/src/commands/snapshotSampling.test.ts
new file mode 100644
index 0000000000..7cb6bbeb9a
--- /dev/null
+++ b/packages/cli/src/commands/snapshotSampling.test.ts
@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import {
+ parseSnapshotRange,
+ sampleSnapshotRange,
+ resolveSnapshotCompositionRange,
+} from "./snapshotSampling.js";
+describe("snapshot scoped sampling", () => {
+ it("samples only the requested range with exact count", () => {
+ expect(sampleSnapshotRange([2, 4], 5, 10)).toEqual([2, 2.5, 3, 3.5, 4]);
+ expect(sampleSnapshotRange([2, 4], 1, 10)).toEqual([3]);
+ const samples = sampleSnapshotRange([2, 4], 8, 10, true);
+ expect(samples).toHaveLength(8);
+ expect(samples[0]).toBe(2);
+ expect(samples[7]).toBeLessThan(4);
+ });
+ it("rejects malformed ranges and counts", () => {
+ for (const v of ["1", "1:", ":2", "a:3", "3:2", "1:1", "-1:2", "0:Infinity"])
+ expect(() => parseSnapshotRange(v)).toThrow();
+ expect(parseSnapshotRange("1.8:2.5")).toEqual([1.8, 2.5]);
+ expect(parseSnapshotRange("1.8,2.5")).toEqual([1.8, 2.5]);
+ for (const n of [0, -1, 1.5, NaN]) expect(() => sampleSnapshotRange([1, 2], n, 5)).toThrow();
+ expect(() => sampleSnapshotRange([1, 6], 5, 5)).toThrow();
+ });
+ const html = `<html><body><div data-composition-id="main" data-duration="12"><div id="parent" data-composition-id="parent" data-start="3" data-duration="4"><div data-composition-id="child" data-start="2" data-duration="5"></div></div><div data-composition-id="later" data-start="parent + 1" data-duration="2"></div></div></body></html>`;
+ it("resolves nested offsets and clamps to ancestor visibility", () => {
+ expect(resolveSnapshotCompositionRange(html, {}, "child", 12)).toEqual([5, 7]);
+ expect(resolveSnapshotCompositionRange(html, {}, "later", 12)).toEqual([8, 10]);
+ expect(resolveSnapshotCompositionRange(html, {}, "main", 12)).toEqual([0, 12]);
+ });
+ it("uses registered duration and rejects missing or ambiguous IDs", () => {
+ const h =
+ '<div data-composition-id="main" data-duration="10"><div data-composition-id="intro" data-start="2"></div></div>';
+ expect(resolveSnapshotCompositionRange(h, { intro: 3 }, "intro", 10)).toEqual([2, 5]);
+ expect(resolveSnapshotCompositionRange(h, {}, "intro", 10)).toEqual([2, 10]);
+ expect(() => resolveSnapshotCompositionRange(h, {}, "absent", 10)).toThrow();
+ expect(() => resolveSnapshotCompositionRange(h + h, {}, "intro", 10)).toThrow();
+ });
+});
diff --git a/packages/cli/src/commands/snapshotSampling.ts b/packages/cli/src/commands/snapshotSampling.ts
new file mode 100644
index 0000000000..2e6472191d
--- /dev/null
+++ b/packages/cli/src/commands/snapshotSampling.ts
@@ -0,0 +1,76 @@
+import { parseHTML } from "linkedom";
+import { createRuntimeStartTimeResolver } from "@hyperframes/core";
+export type SnapshotRange = [number, number];
+export function parseSnapshotRange(value: string): SnapshotRange {
+ 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]!];
+}
+export function sampleSnapshotRange(
+ [start, end]: SnapshotRange,
+ frames: number,
+ duration: number,
+ exclusiveEnd = false,
+): number[] {
+ 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];
+ // Clip ends are exclusive; keep the last sample inside the visible interval.
+ const last =
+ exclusiveEnd || end === duration ? end - Math.min(0.001, (end - start) / (frames * 2)) : end;
+ return Array.from({ length: frames }, (_, i) => start + ((last - start) * i) / (frames - 1));
+}
+export function resolveSnapshotCompositionRange(
+ html: string,
+ durations: Record<string, number>,
+ id: string,
+ duration: number,
+): SnapshotRange {
+ const { document } = parseHTML(html);
+ const matches = Array.from(document.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: document as unknown as Document,
+ timelineRegistry: registry,
+ includeAuthoredTimingAttrs: true,
+ });
+ let start = 0,
+ end = duration;
+ for (let el: Element | null = matches[0] as unknown as Element; 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];
+}