hyperframes 0.4.11-alpha.1 → 0.4.12

package/dist/cli.js

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.4.11-alpha.1" : "0.0.0-dev";
+    VERSION = true ? "0.4.12" : "0.0.0-dev";
   }
 });
 
@@ -5199,7 +5199,9 @@ function readConfig() {
       telemetryNoticeShown: parsed.telemetryNoticeShown ?? DEFAULT_CONFIG.telemetryNoticeShown,
       commandCount: parsed.commandCount ?? DEFAULT_CONFIG.commandCount,
       lastUpdateCheck: parsed.lastUpdateCheck,
-      latestVersion: parsed.latestVersion
+      latestVersion: parsed.latestVersion,
+      pendingUpdate: parsed.pendingUpdate,
+      completedUpdate: parsed.completedUpdate
     };
     cachedConfig = config;
     return { ...config };
@@ -5429,8 +5431,8 @@ function flushSync() {
   eventQueue = [];
   const payload = JSON.stringify({ api_key: POSTHOG_API_KEY, batch });
   try {
-    const { spawn: spawn12 } = __require("child_process");
-    const child = spawn12(
+    const { spawn: spawn13 } = __require("child_process");
+    const child = spawn13(
       process.execPath,
       [
         "-e",
@@ -20492,7 +20494,7 @@ var init_config2 = __esm({
       ffmpegStreamingTimeout: 6e5,
       hdr: false,
       hdrAutoDetect: true,
-      audioGain: 1.35,
+      audioGain: 1,
       frameDataUriCacheLimit: 256,
       playerReadyTimeout: 45e3,
       renderReadyTimeout: 15e3,
@@ -22729,6 +22731,37 @@ async function convertSdrToHdr(inputPath, outputPath, signal, config) {
     );
   }
 }
+async function convertVfrToCfr(inputPath, outputPath, targetFps, startTime, duration, signal, config) {
+  const timeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG2.ffmpegProcessTimeout;
+  const args = [
+    "-ss",
+    String(startTime),
+    "-i",
+    inputPath,
+    "-t",
+    String(duration),
+    "-fps_mode",
+    "cfr",
+    "-r",
+    String(targetFps),
+    "-c:v",
+    "libx264",
+    "-preset",
+    "fast",
+    "-crf",
+    "18",
+    "-c:a",
+    "copy",
+    "-y",
+    outputPath
+  ];
+  const result = await runFfmpeg(args, { signal, timeout });
+  if (!result.success) {
+    throw new Error(
+      `VFR\u2192CFR conversion failed (exit ${result.exitCode}): ${result.stderr.slice(-300)}`
+    );
+  }
+}
 async function extractAllVideoFrames(videos, baseDir, options, signal, config, compiledDir) {
   const startTime = Date.now();
   const extracted = [];
@@ -22786,6 +22819,39 @@ async function extractAllVideoFrames(videos, baseDir, options, signal, config, c
       }
     }
   }
+  const vfrNormDir = join21(options.outputDir, "_vfr_normalized");
+  for (let i2 = 0; i2 < resolvedVideos.length; i2++) {
+    if (signal?.aborted) break;
+    const entry = resolvedVideos[i2];
+    if (!entry) continue;
+    const metadata = await extractVideoMetadata(entry.videoPath);
+    if (!metadata.isVFR) continue;
+    let segDuration = entry.video.end - entry.video.start;
+    if (!Number.isFinite(segDuration) || segDuration <= 0) {
+      const sourceRemaining = metadata.durationSeconds - entry.video.mediaStart;
+      segDuration = sourceRemaining > 0 ? sourceRemaining : metadata.durationSeconds;
+    }
+    mkdirSync12(vfrNormDir, { recursive: true });
+    const normalizedPath = join21(vfrNormDir, `${entry.video.id}_cfr.mp4`);
+    try {
+      await convertVfrToCfr(
+        entry.videoPath,
+        normalizedPath,
+        options.fps,
+        entry.video.mediaStart,
+        segDuration,
+        signal,
+        config
+      );
+      entry.videoPath = normalizedPath;
+      entry.video = { ...entry.video, mediaStart: 0 };
+    } catch (err) {
+      errors.push({
+        videoId: entry.video.id,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   const results = await Promise.all(
     resolvedVideos.map(async ({ video, videoPath }) => {
       if (signal?.aborted) {
@@ -23546,7 +23612,7 @@ async function processCompositionAudio(elements, baseDir, workDir, outputPath, t
           end: element.end,
           mediaStart: element.mediaStart,
           duration: element.end - element.start,
-          volume: element.volume || 1
+          volume: element.volume ?? 1
         });
       } catch (err) {
         errors.push(`Error: ${element.id} \u2014 ${err instanceof Error ? err.message : String(err)}`);
@@ -27658,8 +27724,8 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
         );
       }
       if (metadata.isVFR) {
-        console.warn(
-          `[Compiler] WARNING: Video "${video.id}" is variable frame rate (VFR). Screen recordings and phone videos are often VFR, which causes stuttering and frame skipping in renders. Re-encode with: ${reencode}`
+        console.info(
+          `[Compiler] Video "${video.id}" is variable frame rate (VFR); the engine will normalize it to CFR before frame extraction. If rendering feels slow on this video, pre-encode once with: ${reencode}`
         );
       }
     }).catch(() => {
@@ -27857,11 +27923,11 @@ import { join as join31, dirname as dirname10, resolve as resolve15 } from "path
 import { randomUUID as randomUUID2 } from "crypto";
 import { freemem as freemem2 } from "os";
 import { fileURLToPath as fileURLToPath3 } from "url";
-async function safeCleanup(label2, fn, log = defaultLogger) {
+async function safeCleanup(label2, fn, log2 = defaultLogger) {
   try {
     await fn();
   } catch (err) {
-    log.debug(`Cleanup failed (${label2})`, {
+    log2.debug(`Cleanup failed (${label2})`, {
       error: err instanceof Error ? err.message : String(err)
     });
   }
@@ -27889,7 +27955,7 @@ function updateJobStatus(job, status, stage, progress, onProgress) {
   if (status === "failed" || status === "complete") job.completedAt = /* @__PURE__ */ new Date();
   if (onProgress) onProgress(job, stage);
 }
-function installDebugLogger(logPath, log = defaultLogger) {
+function installDebugLogger(logPath, log2 = defaultLogger) {
   const origLog = console.log;
   const origError = console.error;
   const origWarn = console.warn;
@@ -27900,7 +27966,7 @@ function installDebugLogger(logPath, log = defaultLogger) {
     try {
       appendFileSync(logPath, line);
     } catch (err) {
-      log.debug("Debug log write failed", {
+      log2.debug("Debug log write failed", {
         logPath,
         error: err instanceof Error ? err.message : String(err)
       });
@@ -27967,15 +28033,15 @@ function writeCompiledArtifacts(compiled, workDir, includeSummary) {
     writeFileSync10(join31(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
   }
 }
-function applyRenderModeHints(cfg, compiled, log = defaultLogger) {
+function applyRenderModeHints(cfg, compiled, log2 = defaultLogger) {
   if (cfg.forceScreenshot || !compiled.renderModeHints.recommendScreenshot) return;
   cfg.forceScreenshot = true;
-  log.warn("Auto-selected screenshot capture mode for render compatibility", {
+  log2.warn("Auto-selected screenshot capture mode for render compatibility", {
     reasonCodes: compiled.renderModeHints.reasons.map((reason) => reason.code),
     reasons: compiled.renderModeHints.reasons.map((reason) => reason.message)
   });
 }
-function blitHdrVideoLayer(canvas, el, time, fps, hdrFrameDirs, hdrStartTimes, width, height, log, sourceTransfer, targetTransfer) {
+function blitHdrVideoLayer(canvas, el, time, fps, hdrFrameDirs, hdrStartTimes, width, height, log2, sourceTransfer, targetTransfer) {
   const frameDir = hdrFrameDirs.get(el.id);
   const startTime = hdrStartTimes.get(el.id);
   if (!frameDir || startTime === void 0) {
@@ -28025,14 +28091,14 @@ function blitHdrVideoLayer(canvas, el, time, fps, hdrFrameDirs, hdrStartTimes, w
       );
     }
   } catch (err) {
-    if (log) {
-      log.debug(`HDR blit failed for ${el.id}`, {
+    if (log2) {
+      log2.debug(`HDR blit failed for ${el.id}`, {
         error: err instanceof Error ? err.message : String(err)
       });
     }
   }
 }
-function blitHdrImageLayer(canvas, el, hdrImageBuffers, width, height, log, sourceTransfer, targetTransfer) {
+function blitHdrImageLayer(canvas, el, hdrImageBuffers, width, height, log2, sourceTransfer, targetTransfer) {
   const buf = hdrImageBuffers.get(el.id);
   if (!buf) {
     return;
@@ -28074,8 +28140,8 @@ function blitHdrImageLayer(canvas, el, hdrImageBuffers, width, height, log, sour
       );
     }
   } catch (err) {
-    if (log) {
-      log.debug(`HDR image blit failed for ${el.id}`, {
+    if (log2) {
+      log2.debug(`HDR image blit failed for ${el.id}`, {
         error: err instanceof Error ? err.message : String(err)
       });
     }
@@ -28126,7 +28192,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
   const debugDir = join31(producerRoot, ".debug");
   const workDir = job.config.debug ? join31(debugDir, job.id) : join31(dirname10(outputPath), `work-${job.id}`);
   const pipelineStart = Date.now();
-  const log = job.config.logger ?? defaultLogger;
+  const log2 = job.config.logger ?? defaultLogger;
   let fileServer = null;
   let probeSession = null;
   let lastBrowserConsole = [];
@@ -28159,7 +28225,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     if (!existsSync28(workDir)) mkdirSync17(workDir, { recursive: true });
     if (job.config.debug) {
       const logPath = join31(workDir, "render.log");
-      restoreLogger = installDebugLogger(logPath, log);
+      restoreLogger = installDebugLogger(logPath, log2);
     }
     const entryFile = job.config.entryFile || "index.html";
     let htmlPath = join31(projectDir, entryFile);
@@ -28187,7 +28253,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       }
       writeFileSync10(wrapperPath, standaloneHtml, "utf-8");
       htmlPath = wrapperPath;
-      log.info("Extracted standalone entry from index.html host context", {
+      log2.info("Extracted standalone entry from index.html host context", {
         entryFile
       });
     }
@@ -28197,9 +28263,9 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     let compiled = await compileForRender(projectDir, htmlPath, join31(workDir, "downloads"));
     assertNotAborted();
     perfStages.compileOnlyMs = Date.now() - compileStart;
-    applyRenderModeHints(cfg, compiled, log);
+    applyRenderModeHints(cfg, compiled, log2);
     writeCompiledArtifacts(compiled, workDir, Boolean(job.config.debug));
-    log.info("Compiled composition metadata", {
+    log2.info("Compiled composition metadata", {
       entryFile,
       staticDuration: compiled.staticDuration,
       width: compiled.width,
@@ -28251,13 +28317,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       if (composition.duration <= 0) {
         const discoveredDuration = await getCompositionDuration(probeSession);
         assertNotAborted();
-        log.info("Probed composition duration from browser", {
+        log2.info("Probed composition duration from browser", {
           discoveredDuration,
           staticDuration: compiled.staticDuration
         });
         composition.duration = discoveredDuration;
       } else {
-        log.info("Using static duration from data-duration attribute", {
+        log2.info("Using static duration from data-duration attribute", {
           duration: composition.duration
         });
       }
@@ -28387,7 +28453,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           }
         }
       } catch (err) {
-        log.warn("Failed to gather browser diagnostics for zero-duration composition", {
+        log2.warn("Failed to gather browser diagnostics for zero-duration composition", {
           error: err instanceof Error ? err.message : String(err)
         });
         diagnostics.push("(Could not gather browser diagnostics \u2014 page may have crashed)");
@@ -28400,7 +28466,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         (line) => /404|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_REFUSED|net::ERR_/i.test(line)
       );
       if (failedRequests.length > 0) {
-        log.warn("Browser encountered network failures during page load:", {
+        log2.warn("Browser encountered network failures during page load:", {
           failures: failedRequests.slice(0, 10)
         });
         for (const line of failedRequests.slice(0, 5)) {
@@ -28507,13 +28573,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       }
     }
     if (effectiveHdr && outputFormat !== "mp4") {
-      log.warn(
+      log2.warn(
         `[Render] HDR source detected but format is ${outputFormat} \u2014 falling back to SDR. Use --format mp4 for HDR10 output.`
       );
       effectiveHdr = void 0;
     }
     if (effectiveHdr) {
-      log.info(
+      log2.info(
         `[Render] HDR source detected \u2014 output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
       );
     }
@@ -28568,7 +28634,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const preset = getEncoderPreset(job.config.quality, outputFormat, encoderHdr);
     job.framesRendered = 0;
     if (hasHdrContent) {
-      log.info("[Render] HDR layered composite: z-ordered DOM + native HLG video layers");
+      log2.info("[Render] HDR layered composite: z-ordered DOM + native HLG video layers");
       cfg.forceScreenshot = true;
       const hdrVideoIds = composition.videos.filter((v) => nativeHdrVideoIds.has(v.id)).map((v) => v.id);
       const hdrVideoSrcPaths = /* @__PURE__ */ new Map();
@@ -28611,7 +28677,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         endFrame: Math.ceil((t3.time + t3.duration) * job.config.fps)
       }));
       if (transitionRanges.length > 0) {
-        log.info("[Render] Detected shader transitions for HDR compositing", {
+        log2.info("[Render] Detected shader transitions for HDR compositing", {
           count: transitionRanges.length,
           transitions: transitionRanges.map((t3) => ({
             shader: t3.shader,
@@ -28704,7 +28770,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         const result = await runFfmpeg(ffmpegArgs, { signal: abortSignal });
         if (!result.success) {
           hdrDiagnostics.videoExtractionFailures += 1;
-          log.error("HDR frame pre-extraction failed; aborting render", {
+          log2.error("HDR frame pre-extraction failed; aborting render", {
             videoId,
             srcPath,
             stderr: result.stderr.slice(-400)
@@ -28746,7 +28812,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           }
         } catch (err) {
           hdrDiagnostics.imageDecodeFailures += 1;
-          log.error("HDR image decode failed; aborting render", {
+          log2.error("HDR image decode failed; aborting render", {
             imageId,
             srcPath,
             error: err instanceof Error ? err.message : String(err)
@@ -28790,7 +28856,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           const layers = groupIntoLayers(filteredStacking);
           const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
           if (shouldLog) {
-            log.info("[diag] compositeToBuffer plan", {
+            log2.info("[diag] compositeToBuffer plan", {
               frame: debugFrameIndex,
               time: time.toFixed(3),
               filterSize: elementFilter?.size,
@@ -28821,7 +28887,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   hdrImageBuffers,
                   width,
                   height,
-                  log,
+                  log2,
                   imageTransfers.get(layer.element.id),
                   effectiveHdr?.transfer
                 );
@@ -28835,7 +28901,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   hdrVideoStartTimes,
                   width,
                   height,
-                  log,
+                  log2,
                   videoTransfers.get(layer.element.id),
                   effectiveHdr?.transfer
                 );
@@ -28844,7 +28910,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                 const after2 = countNonZeroRgb482(canvas);
                 if (isHdrImage) {
                   const buf = hdrImageBuffers.get(layer.element.id);
-                  log.info("[diag] hdr layer blit", {
+                  log2.info("[diag] hdr layer blit", {
                     frame: debugFrameIndex,
                     layerIdx,
                     id: layer.element.id,
@@ -28860,7 +28926,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   const localTime = time - startTime;
                   const frameNum = Math.floor(localTime * job.config.fps) + 1;
                   const expectedFrame = frameDir ? join31(frameDir, `frame_${String(frameNum).padStart(4, "0")}.png`) : null;
-                  log.info("[diag] hdr layer blit", {
+                  log2.info("[diag] hdr layer blit", {
                     frame: debugFrameIndex,
                     layerIdx,
                     id: layer.element.id,
@@ -28903,7 +28969,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
                   const dumpPath = join31(debugDumpDir, dumpName);
                   writeFileSync10(dumpPath, domPng);
-                  log.info("[diag] dom layer blit", {
+                  log2.info("[diag] dom layer blit", {
                     frame: debugFrameIndex,
                     layerIdx,
                     layerIds: layer.elementIds,
@@ -28916,7 +28982,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   });
                 }
               } catch (err) {
-                log.warn("DOM layer decode/blit failed; skipping overlay", {
+                log2.warn("DOM layer decode/blit failed; skipping overlay", {
                   layerIds: layer.elementIds,
                   error: err instanceof Error ? err.message : String(err)
                 });
@@ -28925,7 +28991,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           }
           if (shouldLog && debugDumpDir) {
             const finalNonZero = countNonZeroRgb482(canvas);
-            log.info("[diag] compositeToBuffer end", {
+            log2.info("[diag] compositeToBuffer end", {
               frame: debugFrameIndex,
               finalNonZeroPixels: finalNonZero,
               totalPixels: width * height,
@@ -28954,7 +29020,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           );
           if (i2 % 30 === 0) {
             const hdrEl = stackingInfo.find((e2) => e2.isHdr);
-            log.debug("[Render] HDR layer composite frame", {
+            log2.debug("[Render] HDR layer composite frame", {
               frame: i2,
               time: time.toFixed(2),
               hdrElement: hdrEl ? { z: hdrEl.zIndex, visible: hdrEl.visible, width: hdrEl.width } : null,
@@ -28987,7 +29053,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                     hdrImageBuffers,
                     width,
                     height,
-                    log,
+                    log2,
                     imageTransfers.get(el.id),
                     effectiveHdr?.transfer
                   );
@@ -29001,7 +29067,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                     hdrVideoStartTimes,
                     width,
                     height,
-                    log,
+                    log2,
                     videoTransfers.get(el.id),
                     effectiveHdr?.transfer
                   );
@@ -29027,7 +29093,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   effectiveHdr.transfer
                 );
               } catch (err) {
-                log.warn("DOM layer decode/blit failed; skipping overlay for transition scene", {
+                log2.warn("DOM layer decode/blit failed; skipping overlay for transition scene", {
                   frameIndex: i2,
                   sceneIds: Array.from(sceneIds),
                   error: err instanceof Error ? err.message : String(err)
@@ -29059,7 +29125,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                     try {
                       rmSync6(frameDir, { recursive: true, force: true });
                     } catch (err) {
-                      log.warn("Failed to clean up HDR frame directory", {
+                      log2.warn("Failed to clean up HDR frame directory", {
                         videoId,
                         frameDir,
                         error: err instanceof Error ? err.message : String(err)
@@ -29367,7 +29433,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       try {
         writeFileSync10(perfOutputPath, JSON.stringify(perfSummary, null, 2), "utf-8");
       } catch (err) {
-        log.debug("Failed to write perf summary", {
+        log2.debug("Failed to write perf summary", {
           perfOutputPath,
           error: err instanceof Error ? err.message : String(err)
         });
@@ -29379,14 +29445,14 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         copyFileSync2(outputPath, debugOutput);
       }
     } else if (process.env.KEEP_TEMP === "1") {
-      log.info("KEEP_TEMP=1 \u2014 leaving workDir on disk for inspection", { workDir });
+      log2.info("KEEP_TEMP=1 \u2014 leaving workDir on disk for inspection", { workDir });
     } else {
       await safeCleanup(
         "remove workDir",
         () => {
           rmSync6(workDir, { recursive: true, force: true });
         },
-        log
+        log2
       );
     }
     if (restoreLogger) restoreLogger();
@@ -29401,12 +29467,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           () => {
             fs4.close();
           },
-          log
+          log2
         );
       }
       if (probeSession) {
         const session = probeSession;
-        await safeCleanup("close probe session (cancel)", () => closeCaptureSession(session), log);
+        await safeCleanup("close probe session (cancel)", () => closeCaptureSession(session), log2);
       }
       if (!job.config.debug) {
         await safeCleanup(
@@ -29414,7 +29480,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           () => {
             rmSync6(workDir, { recursive: true, force: true });
           },
-          log
+          log2
         );
       }
       if (restoreLogger) restoreLogger();
@@ -29425,7 +29491,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const isTimeoutError = errorMessage.includes("Waiting failed") || errorMessage.includes("timeout exceeded") || errorMessage.includes("Navigation timeout");
     const wasParallel = job.config.workers !== 1;
     if (isTimeoutError && wasParallel) {
-      log.warn(
+      log2.warn(
         `Parallel capture timed out with ${job.config.workers ?? "auto"} workers. Video-heavy compositions often need sequential capture. Retry with --workers 1`
       );
     }
@@ -29450,12 +29516,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         () => {
           fs4.close();
         },
-        log
+        log2
       );
     }
     if (probeSession) {
       const session = probeSession;
-      await safeCleanup("close probe session (error)", () => closeCaptureSession(session), log);
+      await safeCleanup("close probe session (error)", () => closeCaptureSession(session), log2);
     }
     if (!job.config.debug) {
       await safeCleanup(
@@ -29463,7 +29529,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         () => {
           if (existsSync28(workDir)) rmSync6(workDir, { recursive: true, force: true });
         },
-        log
+        log2
       );
     }
     if (restoreLogger) restoreLogger();
@@ -29727,12 +29793,12 @@ async function prepareRenderBody(body) {
     }
   };
 }
-function resolveOutputPath(projectDir, outputCandidate, rendersDir, log) {
+function resolveOutputPath(projectDir, outputCandidate, rendersDir, log2) {
   try {
     return resolveRenderPaths(projectDir, outputCandidate, rendersDir).absoluteOutputPath;
   } catch (error) {
     const fallbackPath = resolve17(rendersDir, `producer-fallback-${Date.now()}.mp4`);
-    log.warn("Failed to resolve output path, using fallback", {
+    log2.warn("Failed to resolve output path, using fallback", {
       fallback: fallbackPath,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -29764,19 +29830,19 @@ function createArtifactStore(ttlMs) {
     }
   };
 }
-function cleanupTempDir(dir, log) {
+function cleanupTempDir(dir, log2) {
   if (!dir) return;
   try {
     rmSync7(dir, { recursive: true, force: true });
   } catch (error) {
-    log.warn("Failed to cleanup temp project dir", {
+    log2.warn("Failed to cleanup temp project dir", {
       cleanupProjectDir: dir,
       error: error instanceof Error ? error.message : String(error)
     });
   }
 }
 function createRenderHandlers(options = {}) {
-  const log = options.logger ?? defaultLogger;
+  const log2 = options.logger ?? defaultLogger;
   const getRequestId = options.getRequestId ?? ((c2) => c2.req.header("x-request-id") || crypto2.randomUUID());
   const outputUrlPrefix = options.outputUrlPrefix ?? "/outputs";
   const rendersDir = options.rendersDir ?? process.env.PRODUCER_RENDERS_DIR ?? "/tmp";
@@ -29803,7 +29869,7 @@ function createRenderHandlers(options = {}) {
       return c2.json({ success: false, requestId, error: preparedResult.error }, 400);
     }
     const result = runHyperframeLint(preparedResult.prepared);
-    log.info("lint completed", {
+    log2.info("lint completed", {
       requestId,
       entryFile: preparedResult.prepared.entryFile,
       source: preparedResult.prepared.source,
@@ -29836,12 +29902,12 @@ function createRenderHandlers(options = {}) {
       input.projectDir,
       input.outputPath,
       rendersDir,
-      log
+      log2
     );
     const outputDir = dirname11(absoluteOutputPath);
     if (!existsSync30(outputDir)) mkdirSync18(outputDir, { recursive: true });
     const release2 = await renderSemaphore.acquire();
-    log.info("render started", {
+    log2.info("render started", {
       requestId,
       projectDir: input.projectDir,
       fps: input.fps,
@@ -29855,7 +29921,7 @@ function createRenderHandlers(options = {}) {
       useGpu: input.useGpu,
       debug: input.debug,
       entryFile: input.entryFile,
-      logger: log
+      logger: log2
     });
     let lastLoggedPct = -10;
     try {
@@ -29863,14 +29929,14 @@ function createRenderHandlers(options = {}) {
         const pct = Math.floor(j2.progress * 100);
         if (pct >= lastLoggedPct + 10) {
           lastLoggedPct = pct;
-          log.info(`render progress ${pct}%`, { requestId, stage: j2.currentStage, message });
+          log2.info(`render progress ${pct}%`, { requestId, stage: j2.currentStage, message });
         }
       });
       const fileSize = existsSync30(absoluteOutputPath) ? statSync9(absoluteOutputPath).size : 0;
       const durationMs = Date.now() - t0;
       const outputToken = store.register(absoluteOutputPath);
       const outputUrl = `${outputUrlPrefix}/${outputToken}`;
-      log.info("render completed", {
+      log2.info("render completed", {
         requestId,
         durationMs,
         fileSize,
@@ -29890,7 +29956,7 @@ function createRenderHandlers(options = {}) {
     } catch (error) {
       const durationMs = Date.now() - t0;
       const errorMsg = error instanceof Error ? error.message : String(error);
-      log.error("render failed", {
+      log2.error("render failed", {
         requestId,
         durationMs,
         error: errorMsg,
@@ -29909,7 +29975,7 @@ function createRenderHandlers(options = {}) {
       );
     } finally {
       release2();
-      cleanupTempDir(cleanupProjectDir, log);
+      cleanupTempDir(cleanupProjectDir, log2);
     }
   };
   const renderStream = (c2) => {
@@ -29947,11 +30013,11 @@ function createRenderHandlers(options = {}) {
         input.projectDir,
         input.outputPath,
         rendersDir,
-        log
+        log2
       );
       const outputDir = dirname11(absoluteOutputPath);
       if (!existsSync30(outputDir)) mkdirSync18(outputDir, { recursive: true });
-      log.info("render-stream started", { requestId, projectDir: input.projectDir });
+      log2.info("render-stream started", { requestId, projectDir: input.projectDir });
       const job = createRenderJob({
         fps: input.fps,
         quality: input.quality,
@@ -29960,7 +30026,7 @@ function createRenderHandlers(options = {}) {
         useGpu: input.useGpu,
         debug: input.debug,
         entryFile: input.entryFile,
-        logger: log
+        logger: log2
       });
       const abortController = new AbortController();
       const onRequestAbort = () => abortController.abort(new RenderCancelledError("request_aborted"));
@@ -29998,7 +30064,7 @@ function createRenderHandlers(options = {}) {
         const fileSize = existsSync30(absoluteOutputPath) ? statSync9(absoluteOutputPath).size : 0;
         const outputToken = store.register(absoluteOutputPath);
         const outputUrl = `${outputUrlPrefix}/${outputToken}`;
-        log.info("render-stream completed", { requestId, fileSize, perf: job.perfSummary ?? null });
+        log2.info("render-stream completed", { requestId, fileSize, perf: job.perfSummary ?? null });
         await stream.writeSSE({
           data: JSON.stringify({
             type: "complete",
@@ -30025,7 +30091,7 @@ function createRenderHandlers(options = {}) {
         }
         const errorMsg = error instanceof Error ? error.message : String(error);
         const elapsedMs = Date.now() - t0;
-        log.error("render-stream failed", {
+        log2.error("render-stream failed", {
           requestId,
           elapsedMs,
           error: errorMsg,
@@ -30044,7 +30110,7 @@ function createRenderHandlers(options = {}) {
       } finally {
         release2();
         c2.req.raw.signal.removeEventListener("abort", onRequestAbort);
-        cleanupTempDir(cleanupProjectDir, log);
+        cleanupTempDir(cleanupProjectDir, log2);
       }
     });
   };
@@ -30087,22 +30153,22 @@ function createProducerApp(options = {}) {
 }
 function startServer(options = {}) {
   const port = options.port ?? parseInt(process.env.PRODUCER_PORT ?? "9847", 10);
-  const log = options.logger ?? defaultLogger;
+  const log2 = options.logger ?? defaultLogger;
   const app = createProducerApp(options);
   const server = serve3({ fetch: app.fetch, port }, () => {
-    log.info(`Listening on http://localhost:${port}`);
+    log2.info(`Listening on http://localhost:${port}`);
   });
   server.setTimeout(0);
   server.requestTimeout = 0;
   server.keepAliveTimeout = 0;
   function shutdown(signal) {
-    log.info(`Received ${signal}, shutting down`);
+    log2.info(`Received ${signal}, shutting down`);
     server.close(() => {
-      log.info("Server closed");
+      log2.info("Server closed");
       process.exit(0);
     });
     setTimeout(() => {
-      log.warn("Forced exit after 30s timeout");
+      log2.warn("Forced exit after 30s timeout");
       process.exit(1);
     }, 3e4).unref();
   }
@@ -37824,7 +37890,7 @@ var require_node = __commonJS({
     var tty = __require("tty");
     var util = __require("util");
     exports.init = init;
-    exports.log = log;
+    exports.log = log2;
     exports.formatArgs = formatArgs;
     exports.save = save;
     exports.load = load;
@@ -37959,7 +38025,7 @@ var require_node = __commonJS({
       }
       return (/* @__PURE__ */ new Date()).toISOString() + " ";
     }
-    function log(...args) {
+    function log2(...args) {
       return process.stderr.write(util.formatWithOptions(exports.inspectOpts, ...args) + "\n");
     }
     function save(namespaces) {
@@ -47424,7 +47490,7 @@ var require_logging_utils = __commonJS({
     exports.getDebugBackend = getDebugBackend;
     exports.getStructuredBackend = getStructuredBackend;
     exports.setBackend = setBackend;
-    exports.log = log;
+    exports.log = log2;
     var events_1 = __require("events");
     var process2 = __importStar(__require("process"));
     var util = __importStar(__require("util"));
@@ -47456,7 +47522,7 @@ var require_logging_utils = __commonJS({
         this.func.info = (...args) => this.invokeSeverity(LogSeverity.INFO, ...args);
         this.func.warn = (...args) => this.invokeSeverity(LogSeverity.WARNING, ...args);
         this.func.error = (...args) => this.invokeSeverity(LogSeverity.ERROR, ...args);
-        this.func.sublog = (namespace2) => log(namespace2, this.func);
+        this.func.sublog = (namespace2) => log2(namespace2, this.func);
       }
       invoke(fields, ...args) {
         if (this.upstream) {
@@ -47623,7 +47689,7 @@ var require_logging_utils = __commonJS({
       cachedBackend = backend;
       loggerCache.clear();
     }
-    function log(namespace, parent) {
+    function log2(namespace, parent) {
       if (!cachedBackend) {
         const enablesFlag = process2.env[exports.env.nodeEnables];
         if (!enablesFlag) {
@@ -47756,7 +47822,7 @@ var require_src5 = __commonJS({
     exports.HEADER_NAME = "Metadata-Flavor";
     exports.HEADER_VALUE = "Google";
     exports.HEADERS = Object.freeze({ [exports.HEADER_NAME]: exports.HEADER_VALUE });
-    var log = logger.log("gcp-metadata");
+    var log2 = logger.log("gcp-metadata");
     exports.METADATA_SERVER_DETECTION = Object.freeze({
       "assume-present": "don't try to ping the metadata server, but assume it's present",
       none: "don't try to ping the metadata server, but don't try to use it either",
@@ -47819,9 +47885,9 @@ var require_src5 = __commonJS({
         responseType: "text",
         timeout: requestTimeout()
       };
-      log.info("instance request %j", req);
+      log2.info("instance request %j", req);
       const res = await requestMethod(req);
-      log.info("instance metadata is %s", res.data);
+      log2.info("instance metadata is %s", res.data);
       const metadataFlavor = res.headers.get(exports.HEADER_NAME);
       if (metadataFlavor !== exports.HEADER_VALUE) {
         throw new RangeError(`Invalid response from metadata service: incorrect ${exports.HEADER_NAME} header. Expected '${exports.HEADER_VALUE}', got ${metadataFlavor ? `'${metadataFlavor}'` : "no header"}`);
@@ -78025,8 +78091,8 @@ var init_capture2 = __esm({
         } catch (err) {
           const errMsg = err instanceof Error ? err.message : String(err);
           try {
-            const { mkdirSync: mkdirSync29, writeFileSync: writeFileSync23 } = await import("fs");
-            mkdirSync29(outputDir, { recursive: true });
+            const { mkdirSync: mkdirSync30, writeFileSync: writeFileSync23 } = await import("fs");
+            mkdirSync30(outputDir, { recursive: true });
             const isTimeout = /timeout|timed out/i.test(errMsg);
             const reason = isTimeout ? "Page navigation timed out \u2014 the site may be blocking headless browsers or requires authentication." : `Capture failed: ${errMsg}`;
             writeFileSync23(
@@ -78093,6 +78159,256 @@ var init_telemetry2 = __esm({
   }
 });
 
+// src/utils/installerDetection.ts
+import { realpathSync } from "fs";
+import { posix as posix2 } from "path";
+function resolveEntry() {
+  const entry = process.argv[1];
+  if (!entry) return null;
+  try {
+    return realpathSync(entry);
+  } catch {
+    return entry;
+  }
+}
+function normalizePath(path2) {
+  return path2.replaceAll("\\", "/");
+}
+function isWorkspaceLink(realEntry) {
+  const normalized = normalizePath(realEntry);
+  return normalized.includes("/packages/cli/");
+}
+function isEphemeralExec(realEntry) {
+  const normalized = normalizePath(realEntry);
+  return normalized.includes("/_npx/") || normalized.includes("/.npm/_npx/") || posix2.basename(posix2.dirname(normalized)).startsWith("bunx-");
+}
+function isHomebrewInstall(realEntry) {
+  return normalizePath(realEntry).includes("/Cellar/hyperframes/");
+}
+function detectInstaller() {
+  const realEntry = resolveEntry();
+  if (!realEntry) {
+    return {
+      kind: "skip",
+      installCommand: () => null,
+      reason: "Could not resolve process entry path"
+    };
+  }
+  const normalizedEntry = normalizePath(realEntry);
+  if (isWorkspaceLink(realEntry)) {
+    return {
+      kind: "skip",
+      installCommand: () => null,
+      reason: "Running from a workspace link (monorepo dev)"
+    };
+  }
+  if (isEphemeralExec(realEntry)) {
+    return {
+      kind: "skip",
+      installCommand: () => null,
+      reason: "Running via ephemeral exec (npx / bunx)"
+    };
+  }
+  if (isHomebrewInstall(realEntry)) {
+    return {
+      kind: "brew",
+      // Updating a brew formula isn't a straight `install`; the formula needs
+      // to have been published. Defer to `brew upgrade` which is a no-op if
+      // the tap hasn't caught up.
+      installCommand: () => "brew upgrade hyperframes",
+      reason: `Homebrew install detected at ${realEntry}`
+    };
+  }
+  if (normalizedEntry.includes("/.bun/")) {
+    return {
+      kind: "bun",
+      installCommand: (version) => `bun add -g hyperframes@${version}`,
+      reason: `bun global install detected at ${realEntry}`
+    };
+  }
+  if (normalizedEntry.includes("/pnpm/global/")) {
+    return {
+      kind: "pnpm",
+      installCommand: (version) => `pnpm add -g hyperframes@${version}`,
+      reason: `pnpm global install detected at ${realEntry}`
+    };
+  }
+  if (normalizedEntry.includes("/lib/node_modules/hyperframes/") || normalizedEntry.includes("/npm/node_modules/hyperframes/")) {
+    return {
+      kind: "npm",
+      installCommand: (version) => `npm install -g hyperframes@${version}`,
+      reason: `npm global install detected at ${realEntry}`
+    };
+  }
+  return {
+    kind: "skip",
+    installCommand: () => null,
+    reason: `Unknown install layout at ${realEntry}`
+  };
+}
+var init_installerDetection = __esm({
+  "src/utils/installerDetection.ts"() {
+    "use strict";
+  }
+});
+
+// src/utils/autoUpdate.ts
+var autoUpdate_exports = {};
+__export(autoUpdate_exports, {
+  reportCompletedUpdate: () => reportCompletedUpdate,
+  scheduleBackgroundInstall: () => scheduleBackgroundInstall
+});
+import { spawn as spawn12 } from "child_process";
+import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync29, openSync } from "fs";
+import { homedir as homedir10 } from "os";
+import { join as join53 } from "path";
+import { compareVersions as compareVersions2 } from "compare-versions";
+function isAutoInstallDisabled() {
+  if (isDevMode()) return true;
+  if (process.env["CI"] === "true" || process.env["CI"] === "1") return true;
+  if (process.env["HYPERFRAMES_NO_UPDATE_CHECK"] === "1") return true;
+  if (process.env["HYPERFRAMES_NO_AUTO_INSTALL"] === "1") return true;
+  return false;
+}
+function majorOf(version) {
+  const match = /^(\d+)\./.exec(version);
+  return match?.[1] ? Number.parseInt(match[1], 10) : Number.NaN;
+}
+function log(line) {
+  try {
+    mkdirSync29(CONFIG_DIR2, { recursive: true, mode: 448 });
+    appendFileSync2(LOG_FILE, `${(/* @__PURE__ */ new Date()).toISOString()} ${line}
+`, { mode: 384 });
+  } catch {
+  }
+}
+function launchDetachedInstall(installCommand, version) {
+  mkdirSync29(CONFIG_DIR2, { recursive: true, mode: 448 });
+  const configFile = join53(CONFIG_DIR2, "config.json");
+  const nodeScript = `
+    const { exec } = require("node:child_process");
+    const { readFileSync, renameSync, writeFileSync } = require("node:fs");
+    const CFG = ${JSON.stringify(configFile)};
+    const TMP = \`\${CFG}.tmp\`;
+    const VERSION = ${JSON.stringify(version)};
+    const CMD = ${JSON.stringify(installCommand)};
+    exec(CMD, { windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (err, _stdout, stderr) => {
+      let cfg = {};
+      try { cfg = JSON.parse(readFileSync(CFG, "utf-8")); } catch (e) {}
+      cfg.completedUpdate = {
+        version: VERSION,
+        ok: !err,
+        finishedAt: new Date().toISOString(),
+        ...(err ? { error: String(stderr || err.message || "install failed").slice(-400) } : {}),
+      };
+      delete cfg.pendingUpdate;
+      try {
+        writeFileSync(TMP, JSON.stringify(cfg, null, 2) + "\\n", { mode: 0o600 });
+        renameSync(TMP, CFG);
+      } catch (e) {}
+    });
+  `;
+  const out = openSync(LOG_FILE, "a", 384);
+  const child = spawn12(process.execPath, ["-e", nodeScript], {
+    detached: true,
+    stdio: ["ignore", out, out],
+    windowsHide: true,
+    env: { ...process.env, HYPERFRAMES_NO_UPDATE_CHECK: "1", HYPERFRAMES_NO_AUTO_INSTALL: "1" }
+  });
+  child.unref();
+  log(`[launch] pid=${child.pid ?? "?"} cmd=${installCommand} version=${version}`);
+}
+function scheduleBackgroundInstall(latestVersion, currentVersion) {
+  if (isAutoInstallDisabled()) return false;
+  if (!latestVersion || !currentVersion) return false;
+  let cmp;
+  try {
+    cmp = compareVersions2(latestVersion, currentVersion);
+  } catch {
+    return false;
+  }
+  if (cmp <= 0) return false;
+  const latestMajor = majorOf(latestVersion);
+  const currentMajor = majorOf(currentVersion);
+  if (Number.isFinite(latestMajor) && Number.isFinite(currentMajor) && latestMajor > currentMajor) {
+    log(`[skip] major-bump ${currentVersion} -> ${latestVersion}`);
+    return false;
+  }
+  const installer = detectInstaller();
+  if (installer.kind === "skip") {
+    log(`[skip] ${installer.reason}`);
+    return false;
+  }
+  const installCommand = installer.installCommand(latestVersion);
+  if (!installCommand) return false;
+  const config = readConfig();
+  if (config.pendingUpdate) {
+    const startedAt = Date.parse(config.pendingUpdate.startedAt);
+    const age = Number.isFinite(startedAt) ? Date.now() - startedAt : Number.POSITIVE_INFINITY;
+    if (age < PENDING_TIMEOUT_MS && config.pendingUpdate.version === latestVersion) {
+      return false;
+    }
+  }
+  if (config.completedUpdate && config.completedUpdate.version === latestVersion) {
+    return false;
+  }
+  config.pendingUpdate = {
+    version: latestVersion,
+    command: installCommand,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeConfig(config);
+  try {
+    launchDetachedInstall(installCommand, latestVersion);
+    return true;
+  } catch (err) {
+    log(`[error] spawn failed: ${String(err)}`);
+    const rollback = readConfig();
+    delete rollback.pendingUpdate;
+    writeConfig(rollback);
+    return false;
+  }
+}
+function reportCompletedUpdate() {
+  if (process.env["HYPERFRAMES_NO_UPDATE_CHECK"] === "1") return;
+  const config = readConfig();
+  const done = config.completedUpdate;
+  if (!done) return;
+  if (done.ok) {
+    delete config.completedUpdate;
+    writeConfig(config);
+  } else if (!done.reported) {
+    config.completedUpdate = { ...done, reported: true };
+    writeConfig(config);
+  } else {
+    return;
+  }
+  if (!process.stderr.isTTY) return;
+  if (done.ok) {
+    process.stderr.write(`  hyperframes auto-updated to v${done.version}
+
+`);
+  } else if (!done.reported) {
+    process.stderr.write(
+      `  hyperframes auto-update to v${done.version} failed. Run \`hyperframes upgrade\` to retry.
+
+`
+    );
+  }
+}
+var CONFIG_DIR2, LOG_FILE, PENDING_TIMEOUT_MS;
+var init_autoUpdate = __esm({
+  "src/utils/autoUpdate.ts"() {
+    "use strict";
+    init_config();
+    init_env();
+    init_installerDetection();
+    CONFIG_DIR2 = join53(homedir10(), ".hyperframes");
+    LOG_FILE = join53(CONFIG_DIR2, "auto-update.log");
+    PENDING_TIMEOUT_MS = 10 * 60 * 1e3;
+  }
+});
+
 // import("./commands/**/*.js") in src/help.ts
 var globImport_commands_js;
 var init_ = __esm({
@@ -78294,10 +78610,15 @@ if (!isHelp && command !== "telemetry" && command !== "unknown") {
   });
 }
 if (!isHelp && !hasJsonFlag && command !== "upgrade") {
-  Promise.resolve().then(() => (init_updateCheck(), updateCheck_exports)).then((mod) => {
+  Promise.resolve().then(() => (init_autoUpdate(), autoUpdate_exports)).then((mod) => mod.reportCompletedUpdate()).catch(() => {
+  });
+  Promise.resolve().then(() => (init_updateCheck(), updateCheck_exports)).then(async (mod) => {
     _printUpdateNotice = mod.printUpdateNotice;
-    mod.checkForUpdate().catch(() => {
-    });
+    const result = await mod.checkForUpdate().catch(() => null);
+    if (result?.updateAvailable) {
+      const auto = await Promise.resolve().then(() => (init_autoUpdate(), autoUpdate_exports)).catch(() => null);
+      auto?.scheduleBackgroundInstall(result.latest, result.current);
+    }
   });
 }
 process.on("beforeExit", () => {