hyperframes 0.6.13 → 0.6.15

package/dist/cli.js

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.6.13" : "0.0.0-dev";
+    VERSION = true ? "0.6.15" : "0.0.0-dev";
   }
 });
 
@@ -11321,8 +11321,8 @@ function flushSync() {
   eventQueue = [];
   const payload = JSON.stringify({ api_key: POSTHOG_API_KEY, batch });
   try {
-    const { spawn: spawn16 } = __require("child_process");
-    const child = spawn16(
+    const { spawn: spawn17 } = __require("child_process");
+    const child = spawn17(
       process.execPath,
       [
         "-e",
@@ -12235,6 +12235,37 @@ var init_skills = __esm({
   }
 });
 
+// src/utils/openBrowser.ts
+import { spawn as spawn2 } from "child_process";
+function buildBrowserArgs(url, options) {
+  const args = [];
+  if (options.userDataDir) {
+    args.push(`--user-data-dir=${options.userDataDir}`);
+  }
+  args.push(url);
+  return args;
+}
+function openBrowser(url, options = {}) {
+  if (options.browserPath) {
+    const args = buildBrowserArgs(url, options);
+    const child = spawn2(options.browserPath, args, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+    return;
+  }
+  import("open").then((mod) => mod.default(url)).catch(() => {
+  });
+}
+var init_openBrowser = __esm({
+  "src/utils/openBrowser.ts"() {
+    "use strict";
+  }
+});
+
 // ../core/src/lint/index.ts
 var lint_exports = {};
 __export(lint_exports, {
@@ -13055,7 +13086,7 @@ var init_mime = __esm({
 });
 
 // ../core/src/studio-api/helpers/waveform.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { existsSync as existsSync9, writeFileSync as writeFileSync6, mkdirSync as mkdirSync5 } from "fs";
 import { join as join11 } from "path";
 function buildWaveformCacheKey(assetPath) {
@@ -13079,7 +13110,7 @@ function computePeaks(floats, count) {
 }
 function decodeAudioPeaks(audioPath) {
   return new Promise((resolve43, reject) => {
-    const proc = spawn2(
+    const proc = spawn3(
       "ffmpeg",
       [
         "-i",
@@ -27898,7 +27929,10 @@ function registerThumbnailRoutes(api, adapter2) {
         selectorIndex
       });
       if (!buffer) {
-        return c3.json({ error: "Thumbnail generation returned null" }, 500);
+        return c3.json(
+          { error: "Thumbnail generation failed \u2014 Chrome browser may not be available" },
+          500
+        );
       }
       if (!existsSync14(cacheDir)) mkdirSync8(cacheDir, { recursive: true });
       writeFileSync9(cachePath2, buffer);
@@ -29854,10 +29888,10 @@ var init_frameCapture = __esm({
 });
 
 // ../engine/src/utils/gpuEncoder.ts
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn4 } from "child_process";
 async function detectGpuEncoder() {
   return new Promise((resolve43) => {
-    const ffmpeg = spawn3("ffmpeg", ["-encoders"], {
+    const ffmpeg = spawn4("ffmpeg", ["-encoders"], {
       stdio: ["pipe", "pipe", "pipe"]
     });
     let stdout2 = "";
@@ -29977,7 +30011,7 @@ var init_hdr = __esm({
 });
 
 // ../engine/src/utils/runFfmpeg.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn5 } from "child_process";
 function formatFfmpegError(exitCode, stderr, tailLines = DEFAULT_STDERR_TAIL_LINES) {
   const tail = (stderr ?? "").split(/\r?\n/).filter((line) => line.length > 0).slice(-tailLines).join("\n");
   if (exitCode === null) {
@@ -29993,7 +30027,7 @@ async function runFfmpeg(args, opts) {
   const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
   const onStderr = opts?.onStderr;
   return new Promise((resolve43) => {
-    const ffmpeg = spawn4("ffmpeg", args);
+    const ffmpeg = spawn5("ffmpeg", args);
     let stderr = "";
     const onAbort = () => {
       ffmpeg.kill("SIGTERM");
@@ -30047,7 +30081,7 @@ var init_runFfmpeg = __esm({
 });
 
 // ../engine/src/services/chunkEncoder.ts
-import { spawn as spawn5 } from "child_process";
+import { spawn as spawn6 } from "child_process";
 import { copyFileSync, existsSync as existsSync20, mkdirSync as mkdirSync11, readdirSync as readdirSync10, statSync as statSync6, writeFileSync as writeFileSync12 } from "fs";
 import { join as join24, dirname as dirname7 } from "path";
 function getEncoderPreset(quality, format = "mp4", hdr) {
@@ -30260,7 +30294,7 @@ async function encodeFramesFromDir(framesDir, framePattern, outputPath, options,
   const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
   const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
   return new Promise((resolve43) => {
-    const ffmpeg = spawn5("ffmpeg", args);
+    const ffmpeg = spawn6("ffmpeg", args);
     let stderr = "";
     const onAbort = () => {
       ffmpeg.kill("SIGTERM");
@@ -30370,7 +30404,7 @@ async function encodeFramesChunkedConcat(framesDir, framePattern, outputPath, op
     if (options.useGpu) gpuEncoder = await getCachedGpuEncoder();
     const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder);
     const chunkResult = await new Promise((resolve43) => {
-      const ffmpeg = spawn5("ffmpeg", args);
+      const ffmpeg = spawn6("ffmpeg", args);
       let stderr = "";
       ffmpeg.stderr.on("data", (d2) => {
         stderr += d2.toString();
@@ -30411,7 +30445,7 @@ async function encodeFramesChunkedConcat(framesDir, framePattern, outputPath, op
     outputPath
   ];
   const concatResult = await new Promise((resolve43) => {
-    const ffmpeg = spawn5("ffmpeg", concatArgs);
+    const ffmpeg = spawn6("ffmpeg", concatArgs);
     let stderr = "";
     ffmpeg.stderr.on("data", (d2) => {
       stderr += d2.toString();
@@ -30517,7 +30551,7 @@ var init_chunkEncoder = __esm({
 });
 
 // ../engine/src/services/streamingEncoder.ts
-import { spawn as spawn6 } from "child_process";
+import { spawn as spawn7 } from "child_process";
 import { existsSync as existsSync21, mkdirSync as mkdirSync12, statSync as statSync7 } from "fs";
 import { dirname as dirname8 } from "path";
 function createFrameReorderBuffer(startFrame, endFrame) {
@@ -30727,7 +30761,7 @@ async function spawnStreamingEncoder(outputPath, options, signal, config) {
   }
   const args = buildStreamingArgs(options, outputPath, gpuEncoder);
   const startTime = Date.now();
-  const ffmpeg = spawn6("ffmpeg", args, {
+  const ffmpeg = spawn7("ffmpeg", args, {
     stdio: ["pipe", "pipe", "pipe"]
   });
   let exitStatus = "running";
@@ -30766,21 +30800,31 @@ Process error: ${err.message}`;
     }
   }
   const streamingTimeout = config?.ffmpegStreamingTimeout ?? DEFAULT_CONFIG2.ffmpegStreamingTimeout;
-  const timer = setTimeout(() => {
-    if (exitStatus === "running") {
-      ffmpeg.kill("SIGTERM");
-    }
-  }, streamingTimeout);
+  let timer = null;
+  const resetTimer = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      if (exitStatus === "running") {
+        ffmpeg.kill("SIGTERM");
+      }
+    }, streamingTimeout);
+  };
+  resetTimer();
   const encoder = {
     writeFrame: (buffer) => {
       if (exitStatus !== "running" || !ffmpeg.stdin || ffmpeg.stdin.destroyed) {
         return false;
       }
       const copy = Buffer.from(buffer);
-      return ffmpeg.stdin.write(copy);
+      const accepted = ffmpeg.stdin.write(copy);
+      if (accepted) resetTimer();
+      return accepted;
     },
     close: async () => {
-      clearTimeout(timer);
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
       if (signal) signal.removeEventListener("abort", onAbort);
       const stdin = ffmpeg.stdin;
       if (stdin && !stdin.destroyed) {
@@ -30825,12 +30869,12 @@ var init_streamingEncoder = __esm({
 });
 
 // ../engine/src/utils/ffprobe.ts
-import { spawn as spawn7 } from "child_process";
+import { spawn as spawn8 } from "child_process";
 import { readFileSync as readFileSync18 } from "fs";
 import { extname as extname5 } from "path";
 function runFfprobe(args) {
   return new Promise((resolve43, reject) => {
-    const proc = spawn7("ffprobe", args);
+    const proc = spawn8("ffprobe", args);
     let stdout2 = "";
     let stderr = "";
     proc.stdout.on("data", (data) => {
@@ -32534,7 +32578,7 @@ var init_extractionCache = __esm({
 });
 
 // ../engine/src/services/videoFrameExtractor.ts
-import { spawn as spawn8 } from "child_process";
+import { spawn as spawn9 } from "child_process";
 import { existsSync as existsSync25, mkdirSync as mkdirSync15, readdirSync as readdirSync12, rmSync as rmSync5 } from "fs";
 import { isAbsolute as isAbsolute4, join as join28, posix as posix2, resolve as resolve15, sep as sep4 } from "path";
 function parseVideoElements(html) {
@@ -32632,7 +32676,7 @@ async function extractVideoFramesRange(videoPath, videoId, startTime, duration,
   if (format === "png") args.push("-compression_level", "6");
   args.push("-y", outputPattern);
   return new Promise((resolve43, reject) => {
-    const ffmpeg = spawn8("ffmpeg", args);
+    const ffmpeg = spawn9("ffmpeg", args);
     let stderr = "";
     const onAbort = () => {
       ffmpeg.kill("SIGTERM");
@@ -33968,18 +34012,19 @@ function calculateOptimalWorkers(totalFrames, requested, config) {
   }
   return finalWorkers;
 }
-function distributeFrames(totalFrames, workerCount, workDir) {
+function distributeFrames(totalFrames, workerCount, workDir, rangeStart = 0) {
   const tasks = [];
   const framesPerWorker = Math.ceil(totalFrames / workerCount);
   for (let i2 = 0; i2 < workerCount; i2++) {
-    const startFrame = i2 * framesPerWorker;
-    const endFrame = Math.min((i2 + 1) * framesPerWorker, totalFrames);
-    if (startFrame >= totalFrames) break;
+    const startFrame = rangeStart + i2 * framesPerWorker;
+    const endFrame = Math.min(rangeStart + (i2 + 1) * framesPerWorker, rangeStart + totalFrames);
+    if (startFrame >= rangeStart + totalFrames) break;
     tasks.push({
       workerId: i2,
       startFrame,
       endFrame,
-      outputDir: join30(workDir, `worker-${i2}`)
+      outputDir: join30(workDir, `worker-${i2}`),
+      outputFrameOffset: rangeStart
     });
   }
   return tasks;
@@ -33999,16 +34044,18 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
       config
     );
     await initializeSession(session);
+    const outputOffset = task.outputFrameOffset ?? 0;
     for (let i2 = task.startFrame; i2 < task.endFrame; i2++) {
       if (signal?.aborted) {
         throw new Error("Parallel worker cancelled");
       }
       const time = i2 * captureOptions.fps.den / captureOptions.fps.num;
+      const fileFrameIdx = i2 - outputOffset;
       if (onFrameBuffer) {
-        const { buffer } = await captureFrameToBuffer(session, i2, time);
+        const { buffer } = await captureFrameToBuffer(session, fileFrameIdx, time);
         await onFrameBuffer(i2, buffer);
       } else {
-        await captureFrame(session, i2, time);
+        await captureFrame(session, fileFrameIdx, time);
       }
       framesCaptured++;
       if (onFrameCaptured) onFrameCaptured(task.workerId, i2);
@@ -39029,17 +39076,18 @@ async function runCaptureStage(input) {
   let { workerCount, probeSession } = input;
   let lastBrowserConsole = [];
   const captureCfg = cfg.forceScreenshot === forceScreenshot ? cfg : { ...cfg, forceScreenshot };
-  if (frameRange !== void 0 && workerCount > 1) {
-    throw new Error(
-      `[captureStage] frameRange capture requires workerCount === 1 (received workerCount=${workerCount}). Distributed chunk workers fan out at the activity layer; reduce workerCount to 1 when passing frameRange.`
-    );
-  }
   if (frameRange !== void 0) {
     if (!Number.isFinite(frameRange.startFrame) || !Number.isFinite(frameRange.endFrame) || frameRange.startFrame < 0 || frameRange.endFrame <= frameRange.startFrame) {
       throw new Error(
         `[captureStage] invalid frameRange: ${JSON.stringify(frameRange)}. Expected non-negative startFrame strictly less than endFrame.`
       );
     }
+    const rangeFrames = frameRange.endFrame - frameRange.startFrame;
+    if (rangeFrames !== totalFrames) {
+      throw new Error(
+        `[captureStage] frameRange size (${rangeFrames}) must equal totalFrames (${totalFrames}). Received frameRange=${JSON.stringify(frameRange)}.`
+      );
+    }
   }
   if (workerCount > 1) {
     const attempts = await executeDiskCaptureWithAdaptiveRetry({
@@ -39053,6 +39101,7 @@ async function runCaptureStage(input) {
       captureOptions: buildCaptureOptions(),
       createBeforeCaptureHook: createRenderVideoFrameInjector,
       abortSignal,
+      frameRangeStart: frameRange?.startFrame,
       onProgress: (progress) => {
         job.framesRendered = progress.capturedFrames;
         const frameProgress = progress.capturedFrames / progress.totalFrames;
@@ -40942,16 +40991,17 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   }
   return ranges;
 }
-function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt) {
+function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0) {
   const workersPerBatch = Math.max(1, Math.floor(maxWorkers));
   const batches = [];
   for (let i2 = 0; i2 < ranges.length; i2 += workersPerBatch) {
     const batchIndex = batches.length;
     const batch = ranges.slice(i2, i2 + workersPerBatch).map((range, workerId) => ({
       workerId,
-      startFrame: range.startFrame,
-      endFrame: range.endFrame,
-      outputDir: join49(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`)
+      startFrame: rangeStart + range.startFrame,
+      endFrame: rangeStart + range.endFrame,
+      outputDir: join49(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`),
+      outputFrameOffset: rangeStart
     }));
     batches.push(batch);
   }
@@ -40982,6 +41032,7 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
   let currentWorkers = options.initialWorkerCount;
   let missingRanges = null;
   let attempt = 0;
+  const rangeStart = options.frameRangeStart ?? 0;
   while (true) {
     const frameCount = missingRanges ? countFrameRanges(missingRanges) : options.totalFrames;
     attempts.push({
@@ -40991,7 +41042,13 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
       reason: attempt === 0 ? "initial" : "retry"
     });
     const attemptWorkDir = join49(options.workDir, `capture-attempt-${attempt}`);
-    const batches = missingRanges ? buildMissingFrameRetryBatches(missingRanges, currentWorkers, attemptWorkDir, attempt) : [distributeFrames(options.totalFrames, currentWorkers, attemptWorkDir)];
+    const batches = missingRanges ? buildMissingFrameRetryBatches(
+      missingRanges,
+      currentWorkers,
+      attemptWorkDir,
+      attempt,
+      rangeStart
+    ) : [distributeFrames(options.totalFrames, currentWorkers, attemptWorkDir, rangeStart)];
     try {
       for (const tasks of batches) {
         const capturedBeforeBatch = countCapturedFrames(
@@ -43423,6 +43480,14 @@ async function plan(projectDir, config, planDir) {
     height,
     format: config.format
   };
+  try {
+    rmSync11(workDir, { recursive: true, force: true });
+  } catch (err) {
+    log2.warn("[plan] failed to remove temp work dir", {
+      workDir,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
   const freezeResult = await freezePlan({
     planDir,
     composition: compositionJson,
@@ -43436,14 +43501,6 @@ async function plan(projectDir, config, planDir) {
     hasAudio: audioResult.hasAudio
   });
   const planHash = freezeResult.planHash;
-  try {
-    rmSync11(workDir, { recursive: true, force: true });
-  } catch (err) {
-    log2.warn("[plan] failed to remove temp work dir", {
-      workDir,
-      error: err instanceof Error ? err.message : String(err)
-    });
-  }
   const sizeLimitBytes = config.planDirSizeLimitBytes ?? PLAN_DIR_SIZE_LIMIT_BYTES;
   const planDirBytes = measurePlanDirBytes(planDir);
   if (planDirBytes > sizeLimitBytes) {
@@ -43731,6 +43788,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       session = await createCaptureSession(fileServer.url, framesDir, captureOptions, null, cfg);
       await assertSwiftShader(session.page, readWebGlVendorInfoFromCanvas);
       await initializeSession(session);
+      const chunkWorkerCount = calculateOptimalWorkers(framesInChunk, void 0, cfg);
       await runCaptureStage({
         fileServer,
         workDir,
@@ -43740,11 +43798,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
         cfg,
         forceScreenshot: encoder.forceScreenshot,
         log: log2,
-        workerCount: 1,
-        // Pass the pre-warmed session through as `probeSession` so captureStage
-        // reuses it via `prepareCaptureSessionForReuse` instead of spinning up
-        // a fresh browser. The stage closes the session in its `finally`,
-        // so we MUST clear our own reference here to avoid a double-close.
+        workerCount: chunkWorkerCount,
+        // The parallel branch closes this session and spins up its own
+        // worker sessions, wasting the ~3-5s of pre-warmed setup. Worth a
+        // follow-up to skip pre-warmup when the resolved workerCount > 1.
         probeSession: session,
         needsAlpha: plan2.dimensions.format !== "mp4",
         captureAttempts: [],
@@ -43882,7 +43939,7 @@ var init_renderChunk = __esm({
 });
 
 // ../producer/src/services/render/audioPadTrim.ts
-import { spawn as spawn9 } from "child_process";
+import { spawn as spawn10 } from "child_process";
 function buildPadTrimAudioArgs(audioPath, outputPath, sourceDurationSeconds, targetDurationSeconds) {
   const delta = targetDurationSeconds - sourceDurationSeconds;
   const targetSec = formatSeconds(targetDurationSeconds);
@@ -44048,7 +44105,7 @@ async function defaultRunFfmpeg(args) {
 }
 function runFfprobeJson(args) {
   return new Promise((resolve43, reject) => {
-    const proc = spawn9("ffprobe", args);
+    const proc = spawn10("ffprobe", args);
     let stdout2 = "";
     let stderr = "";
     proc.stdout.on("data", (data) => {
@@ -44406,7 +44463,10 @@ async function getThumbnailBrowser() {
         }
       } catch {
       }
-      const acquired = await acquireBrowser2(buildChromeArgs2({ width: 1920, height: 1080 }));
+      const acquired = await acquireBrowser2(
+        buildChromeArgs2({ width: 1920, height: 1080, captureMode: "screenshot" }),
+        { forceScreenshot: true }
+      );
       _thumbnailBrowser = acquired.browser;
       _thumbnailBrowser.on("disconnected", () => {
         _thumbnailBrowser = null;
@@ -44423,7 +44483,11 @@ async function getThumbnailBrowser() {
       process.once("SIGTERM", () => void onExit());
       process.once("SIGINT", () => void onExit());
       return _thumbnailBrowser;
-    } catch {
+    } catch (err) {
+      console.warn(
+        "[Studio] Failed to launch thumbnail browser:",
+        err instanceof Error ? err.message : err
+      );
       _thumbnailBrowserInitializing = null;
       return null;
     }
@@ -44530,26 +44594,37 @@ function createStudioServer(options) {
     },
     async generateThumbnail(opts) {
       const browser = await getThumbnailBrowser();
-      if (!browser) return null;
+      if (!browser) {
+        console.warn("[Studio] Thumbnail: no browser available \u2014 Chrome may not be installed");
+        return null;
+      }
       let page = null;
       try {
         page = await browser.newPage();
         await page.setViewport({ width: opts.width || 1920, height: opts.height || 1080 });
         await page.goto(opts.previewUrl, { waitUntil: "domcontentloaded", timeout: 1e4 });
-        await page.waitForFunction(() => !!window.__timelines || !!window.__playerReady, {
-          timeout: 5e3
-        }).catch(() => {
+        await page.waitForFunction(
+          () => {
+            const w3 = window;
+            return !!(w3.__timelines && Object.keys(w3.__timelines).length > 0);
+          },
+          { timeout: 5e3 }
+        ).catch(() => {
         });
         await page.evaluate((t2) => {
-          const win = window;
-          if (win.__player?.seek) win.__player.seek(t2);
-          else if (win.__timeline?.seek) {
-            win.__timeline.pause();
-            win.__timeline.seek(t2);
+          const w3 = window;
+          if (typeof w3.__player?.seek === "function") {
+            w3.__player.seek(t2);
+          } else if (w3.__timelines) {
+            for (const tl of Object.values(w3.__timelines)) {
+              tl?.pause?.(t2);
+            }
+            w3.gsap?.ticker?.tick?.();
           }
         }, opts.seekTime);
         const manifestContent = readStudioManualEditManifestContent(opts.project.dir);
         await applyStudioManualEditsToThumbnailPage(page, manifestContent, opts.compPath);
+        await page.evaluate(() => document.fonts?.ready);
         await new Promise((r2) => setTimeout(r2, 200));
         await reapplyStudioManualEditsToThumbnailPage(page);
         let clip;
@@ -44567,7 +44642,11 @@ function createStudioServer(options) {
           }
         );
         return screenshot;
-      } catch {
+      } catch (err) {
+        console.warn(
+          "[Studio] Thumbnail generation failed:",
+          err instanceof Error ? err.message : err
+        );
         return null;
       } finally {
         await page?.close().catch(() => {
@@ -44714,7 +44793,7 @@ __export(preview_exports, {
   default: () => preview_default,
   examples: () => examples
 });
-import { spawn as spawn10 } from "child_process";
+import { spawn as spawn11 } from "child_process";
 import { existsSync as existsSync48, lstatSync as lstatSync2, symlinkSync as symlinkSync2, unlinkSync as unlinkSync5, readlinkSync, mkdirSync as mkdirSync30 } from "fs";
 import { resolve as resolve25, dirname as dirname18, basename as basename6, join as join58 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
@@ -44749,7 +44828,7 @@ async function runDevMode(dir, options) {
   const s2 = ft();
   s2.start("Starting studio...");
   const studioPkgDir = join58(repoRoot, "packages", "studio");
-  const child = spawn10("bun", ["run", "dev"], {
+  const child = spawn11("bun", ["run", "dev"], {
     cwd: studioPkgDir,
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -44768,7 +44847,9 @@ async function runDevMode(dir, options) {
       console.log();
       if (!options?.noOpen) {
         const urlToOpen = `${frontendUrl}#project/${pName}`;
-        import("open").then((mod) => mod.default(urlToOpen)).catch(() => {
+        openBrowser(urlToOpen, {
+          browserPath: options?.browserPath,
+          userDataDir: options?.userDataDir
         });
       }
       child.stdout?.removeListener("data", handleOutput);
@@ -44824,7 +44905,7 @@ async function runLocalStudioMode(dir, options) {
   ge(c2.bold("hyperframes preview") + c2.dim(" (local studio)"));
   const s2 = ft();
   s2.start("Starting studio...");
-  const child = spawn10("npx", ["vite"], {
+  const child = spawn11("npx", ["vite"], {
     cwd: studioPkgPath,
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -44843,7 +44924,9 @@ async function runLocalStudioMode(dir, options) {
       console.log(`  ${c2.dim("Press Ctrl+C to stop")}`);
       console.log();
       if (!options?.noOpen) {
-        import("open").then((mod) => mod.default(`${url}#project/${pName}`)).catch(() => {
+        openBrowser(`${url}#project/${pName}`, {
+          browserPath: options?.browserPath,
+          userDataDir: options?.userDataDir
         });
       }
     }
@@ -44910,7 +44993,9 @@ async function runEmbeddedMode(dir, startPort, options) {
     );
     console.log();
     if (!options?.noOpen) {
-      import("open").then((mod) => mod.default(`${url2}#project/${pName}`)).catch(() => {
+      openBrowser(`${url2}#project/${pName}`, {
+        browserPath: options?.browserPath,
+        userDataDir: options?.userDataDir
       });
     }
     return;
@@ -44931,7 +45016,9 @@ async function runEmbeddedMode(dir, startPort, options) {
   console.log(`  ${c2.dim("Press Ctrl+C to stop")}`);
   console.log();
   if (!options?.noOpen) {
-    import("open").then((mod) => mod.default(`${url}#project/${pName}`)).catch(() => {
+    openBrowser(`${url}#project/${pName}`, {
+      browserPath: options?.browserPath,
+      userDataDir: options?.userDataDir
     });
   }
   let rl;
@@ -44967,6 +45054,7 @@ var init_preview2 = __esm({
     init_dist5();
     init_colors();
     init_env();
+    init_openBrowser();
     init_lintProject();
     init_lintFormat();
     init_portUtils();
@@ -44976,6 +45064,7 @@ var init_preview2 = __esm({
       ["Use a custom port", "hyperframes preview --port 8080"],
       ["Force a new server even if one is already running", "hyperframes preview --force-new"],
       ["Start without opening the browser", "hyperframes preview --no-open"],
+      ["Open with a specific browser", "hyperframes preview --browser-path /usr/bin/chromium"],
       ["List all active preview servers", "hyperframes preview --list"],
       ["Kill all active preview servers", "hyperframes preview --kill-all"]
     ];
@@ -45003,6 +45092,14 @@ var init_preview2 = __esm({
           type: "boolean",
           default: true,
           description: "Open browser automatically"
+        },
+        "browser-path": {
+          type: "string",
+          description: "Path to the browser executable to open"
+        },
+        "user-data-dir": {
+          type: "string",
+          description: "Chromium-compatible user data directory (requires --browser-path)"
         }
       },
       async run({ args }) {
@@ -45053,15 +45150,28 @@ var init_preview2 = __esm({
             console.log();
           }
         }
+        if (args["user-data-dir"] && !args["browser-path"]) {
+          R2.error("--user-data-dir requires --browser-path");
+          process.exitCode = 1;
+          return;
+        }
         const noOpen = !args.open;
+        const browserPath = args["browser-path"];
+        const userDataDir = args["user-data-dir"];
         if (isDevMode()) {
-          return runDevMode(dir, { projectName, noOpen });
+          return runDevMode(dir, { projectName, noOpen, browserPath, userDataDir });
         }
         if (hasLocalStudio(dir)) {
-          return runLocalStudioMode(dir, { projectName, noOpen });
+          return runLocalStudioMode(dir, { projectName, noOpen, browserPath, userDataDir });
         }
         const forceNew = !!args["force-new"];
-        return runEmbeddedMode(dir, startPort, { projectName, forceNew, noOpen });
+        return runEmbeddedMode(dir, startPort, {
+          projectName,
+          forceNew,
+          noOpen,
+          browserPath,
+          userDataDir
+        });
       }
     });
   }
@@ -45086,7 +45196,7 @@ import {
 } from "fs";
 import { resolve as resolve26, basename as basename7, join as join59, dirname as dirname19 } from "path";
 import { fileURLToPath as fileURLToPath7 } from "url";
-import { execFileSync as execFileSync5, spawn as spawn11 } from "child_process";
+import { execFileSync as execFileSync5, spawn as spawn12 } from "child_process";
 function probeVideo(filePath) {
   try {
     const raw = execFileSync5(
@@ -45128,7 +45238,7 @@ function isWebCompatible(codec) {
 }
 function transcodeToMp4(inputPath, outputPath) {
   return new Promise((resolvePromise) => {
-    const child = spawn11(
+    const child = spawn12(
       "ffmpeg",
       [
         "-i",
@@ -46439,11 +46549,13 @@ var init_play = __esm({
     init_dist5();
     init_colors();
     init_project();
+    init_openBrowser();
     examples5 = [
       ["Play the current project", "hyperframes play"],
       ["Play a specific project directory", "hyperframes play ./my-video"],
       ["Use a custom port", "hyperframes play --port 8080"],
-      ["Start without opening the browser", "hyperframes play --no-open"]
+      ["Start without opening the browser", "hyperframes play --no-open"],
+      ["Open with a specific browser", "hyperframes play --browser-path /usr/bin/chromium"]
     ];
     play_default = defineCommand({
       meta: { name: "play", description: "Play a composition in a lightweight browser player" },
@@ -46454,11 +46566,24 @@ var init_play = __esm({
           type: "boolean",
           default: true,
           description: "Open browser automatically"
+        },
+        "browser-path": {
+          type: "string",
+          description: "Path to the browser executable to open"
+        },
+        "user-data-dir": {
+          type: "string",
+          description: "Chromium-compatible user data directory (requires --browser-path)"
         }
       },
       async run({ args }) {
         const project = resolveProject(args.dir);
         const startPort = parseInt(args.port ?? "3003", 10);
+        if (args["user-data-dir"] && !args["browser-path"]) {
+          R2.error("--user-data-dir requires --browser-path");
+          process.exitCode = 1;
+          return;
+        }
         const runtimePath = resolveRuntimePath2();
         if (!runtimePath) {
           R2.error("HyperFrames runtime not found. Run `bun run build` first.");
@@ -46559,7 +46684,9 @@ var init_play = __esm({
         console.log(`  ${c2.dim("Press Ctrl+C to stop")}`);
         console.log();
         if (args.open) {
-          import("open").then((mod) => mod.default(url)).catch(() => {
+          void openBrowser(url, {
+            browserPath: args["browser-path"],
+            userDataDir: args["user-data-dir"]
           });
         }
         return new Promise(() => {
@@ -47046,7 +47173,7 @@ __export(render_exports, {
 import { mkdirSync as mkdirSync32, readdirSync as readdirSync23, readFileSync as readFileSync36, statSync as statSync20, writeFileSync as writeFileSync26, rmSync as rmSync14 } from "fs";
 import { cpus as cpus4, freemem as freemem3, tmpdir as tmpdir4 } from "os";
 import { resolve as resolve32, dirname as dirname21, join as join62, basename as basename11 } from "path";
-import { execFileSync as execFileSync6, spawn as spawn12 } from "child_process";
+import { execFileSync as execFileSync6, spawn as spawn13 } from "child_process";
 function formatFpsParseError(input, reason) {
   switch (reason) {
     case "empty":
@@ -47266,7 +47393,7 @@ async function renderDocker(projectDir, outputPath, options) {
   }
   try {
     await new Promise((resolvePromise, reject) => {
-      const child = spawn12("docker", dockerArgs, {
+      const child = spawn13("docker", dockerArgs, {
         // When quiet, still show stderr so container errors surface
         stdio: options.quiet ? ["pipe", "pipe", "inherit"] : "inherit"
       });
@@ -49471,7 +49598,7 @@ __export(pipeline_exports, {
   resolveRenderTargets: () => resolveRenderTargets,
   waitForExit: () => waitForExit
 });
-import { spawn as spawn13 } from "child_process";
+import { spawn as spawn14 } from "child_process";
 import { extname as extname10 } from "path";
 function inferOutputFormat(outputPath) {
   const ext = extname10(outputPath).toLowerCase();
@@ -49648,7 +49775,7 @@ async function render2(options) {
   }
 }
 function spawnFfmpeg(args, label2, stdio) {
-  const proc = spawn13("ffmpeg", args, { stdio });
+  const proc = spawn14("ffmpeg", args, { stdio });
   let stderrBuf = "";
   proc.stderr?.on("data", (d2) => {
     stderrBuf += d2.toString();
@@ -51486,7 +51613,7 @@ __export(snapshot_exports, {
   default: () => snapshot_default,
   examples: () => examples22
 });
-import { spawn as spawn14 } from "child_process";
+import { spawn as spawn15 } from "child_process";
 import { existsSync as existsSync66, mkdtempSync as mkdtempSync3, readFileSync as readFileSync44, mkdirSync as mkdirSync36, rmSync as rmSync15 } from "fs";
 import { tmpdir as tmpdir5 } from "os";
 import { resolve as resolve40, join as join72, relative as relative9, isAbsolute as isAbsolute9 } from "path";
@@ -51512,7 +51639,7 @@ async function extractVideoFrameToBuffer(videoPath, timeSeconds, useVp9AlphaDeco
           "-y",
           outPath
         );
-        const ff = spawn14("ffmpeg", args);
+        const ff = spawn15("ffmpeg", args);
         let stderr = "";
         let timedOut = false;
         const timer = setTimeout(() => {
@@ -51629,19 +51756,14 @@ async function captureSnapshots(projectDir, opts) {
       for (let i2 = 0; i2 < positions.length; i2++) {
         const time = positions[i2];
         await page.evaluate((t2) => {
-          const win = window;
-          if (win.__player?.seek) {
-            win.__player.seek(t2);
-          } else {
-            const tls = win.__timelines;
-            if (tls) {
-              for (const key2 in tls) {
-                if (tls[key2]?.seek) {
-                  tls[key2].pause();
-                  tls[key2].seek(t2);
-                }
-              }
+          const w3 = window;
+          if (typeof w3.__player?.seek === "function") {
+            w3.__player.seek(t2);
+          } else if (w3.__timelines) {
+            for (const tl of Object.values(w3.__timelines)) {
+              tl?.pause?.(t2);
             }
+            w3.gsap?.ticker?.tick?.();
           }
         }, time);
         await page.evaluate(
@@ -94925,7 +95047,7 @@ __export(autoUpdate_exports, {
   reportCompletedUpdate: () => reportCompletedUpdate,
   scheduleBackgroundInstall: () => scheduleBackgroundInstall
 });
-import { spawn as spawn15 } from "child_process";
+import { spawn as spawn16 } from "child_process";
 import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync41, openSync as openSync2 } from "fs";
 import { homedir as homedir12 } from "os";
 import { join as join80 } from "path";
@@ -94976,7 +95098,7 @@ function launchDetachedInstall(installCommand, version) {
     });
   `;
   const out = openSync2(LOG_FILE, "a", 384);
-  const child = spawn15(process.execPath, ["-e", nodeScript], {
+  const child = spawn16(process.execPath, ["-e", nodeScript], {
     detached: true,
     stdio: ["ignore", out, out],
     windowsHide: true,