Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli): snapshot a time range or one composition (#5519)
Xuanru Li1cd086f7e367
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex 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.tsindex 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 complexityimport { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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];+}