Function captureSnapshots

packages/cli/src/commands/snapshot.ts:184–541

* Render key frames from a composition as PNG screenshots. * The agent can Read these to verify its output visually.

(
  projectDir: string,
  opts: {
    frames?: number;
    timeout?: number;
    at?: number[];
    outputDir?: string;
    angle?: Camera;
    includeEnd?: boolean;
  },
)

 * The agent can Read these to verify its output visually.
 */
async function captureSnapshots(
  projectDir: string,
  opts: {
    frames?: number;
    timeout?: number;
    at?: number[];
    outputDir?: string;
    angle?: Camera;
    includeEnd?: boolean;
  },
): Promise<string[]> {
  const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
  const { ensureBrowser } = await import("../browser/manager.js");

  const numFrames = opts.frames ?? 5;

  const html = await bundleToSingleHtml(projectDir);
  const server = await serveStaticProjectHtml(projectDir, html);

  const savedPaths: string[] = [];

  try {
    const browser = await ensureBrowser();
    const puppeteer = await import("puppeteer-core");
    const chromeBrowser = await puppeteer.default.launch({
      headless: true,
      executablePath: browser.executablePath,
      args: [
        "--no-sandbox",
        "--disable-gpu",
        "--disable-dev-shm-usage",
        "--enable-webgl",
        "--use-gl=angle",
        "--use-angle=swiftshader",
      ],
    });

    try {
      const page = await chromeBrowser.newPage();
      await page.setViewport(resolveCompositionViewportFromHtml(html));

      await page.goto(server.url, {
        waitUntil: "domcontentloaded",
        timeout: 10000,
      });

      // __renderReady is set after the player is constructed AND the root
      // timeline is bound — waiting for it guarantees renderSeek will work.
      const timeoutMs = opts.timeout ?? 5000;
      const runtimeReady = await page
        .waitForFunction(() => !!(window as any).__renderReady, { timeout: timeoutMs })
        .then(() => true)
        .catch(() => false);

      if (!runtimeReady) {
        console.warn(
          `\n   ${c.warn("⚠")} Runtime did not become render-ready within ${timeoutMs}ms — snapshots may be inaccurate`,
        );