hyperframes 0.4.3 → 0.4.5

package/dist/cli.js

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.4.3" : "0.0.0-dev";
+    VERSION = true ? "0.4.5" : "0.0.0-dev";
   }
 });
 
@@ -6245,7 +6245,15 @@ function runSkillsAdd(repo) {
   return new Promise((resolve35, reject) => {
     const child = spawn("npx", ["skills", "add", repo, "--all"], {
       stdio: "inherit",
-      timeout: 12e4
+      timeout: 12e4,
+      // GH #316 — the upstream `skills` CLI shells out to `git clone`.
+      // When Git's clone-hook protection is active (shipped on by
+      // default in 2.45.1, reverted in 2.45.2, still present on many
+      // corporate and CI setups), any globally-registered
+      // `git lfs install` post-checkout hook aborts the clone. The
+      // `repo` reaching this function is hardcoded in SOURCES below
+      // — no user input reaches the spawn — so opting out here is safe.
+      env: { ...process.env, GIT_CLONE_PROTECTION_ACTIVE: "0" }
     });
     child.on("close", (code, signal) => {
       if (code === 0) resolve35();
@@ -6333,7 +6341,9 @@ function lintProject(project) {
   }
   const projectFindings = [
     ...lintProjectAudioFiles(project.dir, allHtmlSources),
-    ...lintAudioSrcNotFound(project.dir, allHtmlSources)
+    ...lintAudioSrcNotFound(project.dir, allHtmlSources),
+    ...lintMultipleRootCompositions(project.dir),
+    ...lintDuplicateAudioTracks(allHtmlSources)
   ];
   if (projectFindings.length > 0) {
     for (const finding of projectFindings) {
@@ -6370,7 +6380,7 @@ function lintProjectAudioFiles(projectDir, htmlSources) {
       code: "audio_file_without_element",
       severity: "warning",
       message: `Found audio file(s) in project (${audioFiles.join(", ")}) but no <audio> element in any composition. The rendered video will be silent.`,
-      fixHint: 'Add an <audio id="my-audio" src="' + audioFiles[0] + '" data-start="0" data-track-index="0" data-volume="1"></audio> element inside the composition root.'
+      fixHint: 'Add an <audio id="my-audio" src="' + audioFiles[0] + '" data-start="0" data-duration="__DURATION__" data-track-index="0" data-volume="1"></audio> element inside the composition root. Replace __DURATION__ with the audio length in seconds.'
     });
   }
   return findings;
@@ -6402,6 +6412,74 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
   }
   return findings;
 }
+function lintMultipleRootCompositions(projectDir) {
+  const findings = [];
+  try {
+    const rootHtmlFiles = readdirSync2(projectDir).filter((f3) => f3.endsWith(".html"));
+    const rootCompositions = [];
+    for (const file of rootHtmlFiles) {
+      const content = readFileSync7(join9(projectDir, file), "utf-8");
+      if (/data-composition-id/i.test(content)) {
+        rootCompositions.push(file);
+      }
+    }
+    if (rootCompositions.length > 1) {
+      findings.push({
+        code: "multiple_root_compositions",
+        severity: "error",
+        message: `Multiple root-level HTML files with data-composition-id: ${rootCompositions.join(", ")}. The runtime may discover both as entry points, causing duplicate audio playback.`,
+        fixHint: "A project should have exactly one root index.html with data-composition-id. Remove or rename extra files."
+      });
+    }
+  } catch {
+  }
+  return findings;
+}
+function lintDuplicateAudioTracks(htmlSources) {
+  const findings = [];
+  function extractAttr(tag, name) {
+    const re2 = new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, "i");
+    const m2 = tag.match(re2);
+    return m2?.[1] ?? null;
+  }
+  const tracks = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const html of htmlSources) {
+    const audioTagRe = /<audio\b[^>]*>/gi;
+    let match;
+    while ((match = audioTagRe.exec(html)) !== null) {
+      const tag = match[0];
+      const trackStr = extractAttr(tag, "data-track-index");
+      const startStr = extractAttr(tag, "data-start");
+      const durStr = extractAttr(tag, "data-duration");
+      const src = extractAttr(tag, "src") ?? "unknown";
+      if (!trackStr || !startStr) continue;
+      const trackIndex = parseInt(trackStr, 10);
+      const start = parseFloat(startStr);
+      const duration = durStr ? parseFloat(durStr) : Infinity;
+      const key2 = `${src}:${start}:${duration}:${trackIndex}`;
+      if (seen.has(key2)) continue;
+      seen.add(key2);
+      tracks.push({ trackIndex, start, end: start + duration, src });
+    }
+  }
+  for (let i2 = 0; i2 < tracks.length; i2++) {
+    for (let j2 = i2 + 1; j2 < tracks.length; j2++) {
+      const a = tracks[i2];
+      const b = tracks[j2];
+      if (a.trackIndex !== b.trackIndex) continue;
+      if (a.start < b.end && b.start < a.end) {
+        findings.push({
+          code: "duplicate_audio_track",
+          severity: "warning",
+          message: `Multiple <audio> elements on track ${a.trackIndex} overlap (${a.src} at ${a.start}-${Number.isFinite(a.end) ? a.end.toFixed(1) : "end"}s, ${b.src} at ${b.start}-${Number.isFinite(b.end) ? b.end.toFixed(1) : "end"}s). This causes layered audio playback.`,
+          fixHint: "Use non-overlapping time windows or different track indices."
+        });
+      }
+    }
+  }
+  return findings;
+}
 function shouldBlockRender(strictErrors, strictAll, totalErrors, totalWarnings) {
   return strictErrors && totalErrors > 0 || strictAll && (totalErrors > 0 || totalWarnings > 0);
 }
@@ -6480,10 +6558,12 @@ function isPortAvailableOnHost(port, host) {
     });
   });
 }
-async function testPortOnAllHosts(port) {
-  const hosts = ["127.0.0.1", "0.0.0.0", "::1", "::"];
-  const results = await Promise.all(hosts.map((h3) => isPortAvailableOnHost(port, h3)));
-  return results.every(Boolean);
+async function testPortOnAllHosts(port, probe = isPortAvailableOnHost) {
+  for (const host of PORT_PROBE_HOSTS) {
+    const available = await probe(port, host);
+    if (!available) return false;
+  }
+  return true;
 }
 function detectHyperframesServer(port, normalizedProjectDir) {
   return new Promise((resolveResult) => {
@@ -6680,7 +6760,7 @@ async function findPortAndServe(fetch4, startPort, projectDir, forceNew) {
     `Ports ${startPort}\u2013${endPort} are all in use. Use --port to specify a different starting port.`
   );
 }
-var execFileAsync, MAX_PORT_SCAN, PROBE_TIMEOUT_MS, PROBE_MAX_BYTES;
+var execFileAsync, MAX_PORT_SCAN, PROBE_TIMEOUT_MS, PROBE_MAX_BYTES, PORT_PROBE_HOSTS;
 var init_portUtils = __esm({
   "src/server/portUtils.ts"() {
     "use strict";
@@ -6689,6 +6769,7 @@ var init_portUtils = __esm({
     MAX_PORT_SCAN = 100;
     PROBE_TIMEOUT_MS = 300;
     PROBE_MAX_BYTES = 4096;
+    PORT_PROBE_HOSTS = ["127.0.0.1", "0.0.0.0", "::1", "::"];
   }
 });
 
@@ -10434,10 +10515,10 @@ function compareDocumentPosition(nodeA, nodeB) {
 function uniqueSort(nodes) {
   nodes = nodes.filter((node, i2, arr) => !arr.includes(node, i2 + 1));
   nodes.sort((a, b) => {
-    const relative4 = compareDocumentPosition(a, b);
-    if (relative4 & DocumentPosition.PRECEDING) {
+    const relative5 = compareDocumentPosition(a, b);
+    if (relative5 & DocumentPosition.PRECEDING) {
       return -1;
-    } else if (relative4 & DocumentPosition.FOLLOWING) {
+    } else if (relative5 & DocumentPosition.FOLLOWING) {
       return 1;
     }
     return 0;
@@ -20850,12 +20931,20 @@ async function createCaptureSession(serverUrl, outputDir, options, onBeforeCaptu
     config
   };
 }
+function isFontResourceError(type, text, locationUrl) {
+  if (type !== "error") return false;
+  if (!text.startsWith("Failed to load resource")) return false;
+  return /fonts\.googleapis|fonts\.gstatic|\.(woff2?|ttf|otf)(\b|$)/i.test(
+    `${locationUrl} ${text}`
+  );
+}
 async function initializeSession(session) {
   const { page, serverUrl } = session;
   page.on("console", (msg) => {
     const type = msg.type();
     const text = msg.text();
-    const isFontLoadError = type === "error" && text.startsWith("Failed to load resource") && /fonts\.googleapis|fonts\.gstatic|\.woff2?(\b|$)/i.test(text);
+    const locationUrl = msg.location()?.url ?? "";
+    const isFontLoadError = isFontResourceError(type, text, locationUrl);
     const isResourceLoadError = type === "error" && text.startsWith("Failed to load resource") && !isFontLoadError;
     const prefix = isResourceLoadError ? "[non-blocking]" : type === "error" ? "[Browser:ERROR]" : type === "warn" ? "[Browser:WARN]" : "[Browser]";
     if (!isFontLoadError) {
@@ -24221,6 +24310,40 @@ var init_ffprobe2 = __esm({
   }
 });
 
+// ../producer/src/utils/paths.ts
+import { resolve as resolve13, basename, join as join27, relative as relative2, isAbsolute as isAbsolute3 } from "path";
+function isPathInside(childPath, parentPath) {
+  const absChild = resolve13(childPath);
+  const absParent = resolve13(parentPath);
+  if (absChild === absParent) return true;
+  const rel = relative2(absParent, absChild);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute3(rel);
+}
+function toExternalAssetKey(absPath) {
+  if (absPath.startsWith("hf-ext/")) return absPath;
+  let normalised = absPath.replace(/\\/g, "/");
+  normalised = normalised.replace(/^\/\/\?\/UNC\//i, "//");
+  normalised = normalised.replace(/^\/\/\?\//, "");
+  normalised = normalised.replace(/^\/\/([^/]+)\//, "unc/$1/");
+  normalised = normalised.replace(/^\/+/, "");
+  normalised = normalised.replace(/^([A-Za-z]):\/?/, "$1/");
+  return "hf-ext/" + normalised;
+}
+function resolveRenderPaths(projectDir, outputPath, rendersDir = DEFAULT_RENDERS_DIR) {
+  const absoluteProjectDir = resolve13(projectDir);
+  const projectName = basename(absoluteProjectDir);
+  const resolvedOutputPath = outputPath ?? join27(rendersDir, `${projectName}.mp4`);
+  const absoluteOutputPath = resolve13(resolvedOutputPath);
+  return { absoluteProjectDir, absoluteOutputPath };
+}
+var DEFAULT_RENDERS_DIR;
+var init_paths = __esm({
+  "../producer/src/utils/paths.ts"() {
+    "use strict";
+    DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? resolve13(new URL(import.meta.url).pathname, "../../..", "renders");
+  }
+});
+
 // ../producer/src/utils/urlDownloader.ts
 var init_urlDownloader2 = __esm({
   "../producer/src/utils/urlDownloader.ts"() {
@@ -24284,7 +24407,7 @@ var init_fontData_generated = __esm({
 // ../producer/src/services/deterministicFonts.ts
 import { existsSync as existsSync25, mkdirSync as mkdirSync15, readFileSync as readFileSync18, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir6 } from "os";
-import { join as join27 } from "path";
+import { join as join28 } from "path";
 function normalizeFamilyName(family) {
   return family.trim().replace(/^['"]|['"]$/g, "").trim().toLowerCase();
 }
@@ -24395,14 +24518,14 @@ function fontSlug(familyName) {
   return familyName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
 function fontCacheDir(slug) {
-  const dir = join27(GOOGLE_FONTS_CACHE_DIR, slug);
+  const dir = join28(GOOGLE_FONTS_CACHE_DIR, slug);
   if (!existsSync25(dir)) {
     mkdirSync15(dir, { recursive: true });
   }
   return dir;
 }
 function cachedWoff2Path(slug, weight, style) {
-  return join27(fontCacheDir(slug), `${weight}-${style}.woff2`);
+  return join28(fontCacheDir(slug), `${weight}-${style}.woff2`);
 }
 async function fetchGoogleFont(familyName) {
   const slug = fontSlug(familyName);
@@ -24614,14 +24737,14 @@ var init_deterministicFonts = __esm({
       poppins: "poppins",
       "segoe ui": "roboto"
     };
-    GOOGLE_FONTS_CACHE_DIR = join27(homedir6(), ".cache", "hyperframes", "fonts");
+    GOOGLE_FONTS_CACHE_DIR = join28(homedir6(), ".cache", "hyperframes", "fonts");
     WOFF2_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
   }
 });
 
 // ../producer/src/services/htmlCompiler.ts
 import { readFileSync as readFileSync19, existsSync as existsSync26, mkdirSync as mkdirSync16 } from "fs";
-import { join as join28, dirname as dirname9, resolve as resolve13 } from "path";
+import { join as join29, dirname as dirname9, resolve as resolve14 } from "path";
 import postcss from "postcss";
 function dedupeElementsById(elements) {
   const deduped = /* @__PURE__ */ new Map();
@@ -24640,7 +24763,7 @@ async function resolveMediaDuration(src, mediaStart, baseDir, downloadDir, tagNa
       return { duration: 0, resolvedPath: src };
     }
   } else if (!filePath.startsWith("/")) {
-    filePath = join28(baseDir, filePath);
+    filePath = join29(baseDir, filePath);
   }
   if (!existsSync26(filePath)) {
     return { duration: 0, resolvedPath: filePath };
@@ -24706,7 +24829,7 @@ async function parseSubCompositions(html, projectDir, downloadDir, parentOffset
     const elEnd = elEndRaw ? parseFloat(elEndRaw) : Infinity;
     const absoluteStart = parentOffset + elStart;
     const absoluteEnd = Math.min(parentEnd, isFinite(elEnd) ? parentOffset + elEnd : Infinity);
-    const filePath = resolve13(projectDir, srcPath);
+    const filePath = resolve14(projectDir, srcPath);
     if (visited.has(filePath)) {
       continue;
     }
@@ -24906,7 +25029,7 @@ function inlineSubCompositions(html, subCompositions, projectDir) {
     if (!srcPath) continue;
     let compHtml = subCompositions.get(srcPath) || null;
     if (!compHtml) {
-      const filePath = resolve13(projectDir, srcPath);
+      const filePath = resolve14(projectDir, srcPath);
       if (existsSync26(filePath)) {
         compHtml = readFileSync19(filePath, "utf-8");
       }
@@ -25119,7 +25242,7 @@ ${safeText}
   return result;
 }
 function collectExternalAssets(html, projectDir) {
-  const absProjectDir = resolve13(projectDir);
+  const absProjectDir = resolve14(projectDir);
   const externalAssets = /* @__PURE__ */ new Map();
   const CSS_URL_RE2 = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
   function processPath(rawPath) {
@@ -25127,12 +25250,12 @@ function collectExternalAssets(html, projectDir) {
     if (!trimmed || trimmed.startsWith("/") || trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("//") || trimmed.startsWith("data:") || trimmed.startsWith("#")) {
       return null;
     }
-    const absPath = resolve13(absProjectDir, trimmed);
-    if (absPath.startsWith(absProjectDir + "/") || absPath === absProjectDir) {
+    const absPath = resolve14(absProjectDir, trimmed);
+    if (isPathInside(absPath, absProjectDir)) {
       return null;
     }
     if (!existsSync26(absPath)) return null;
-    const safeKey = "hf-ext/" + absPath.replace(/^\//, "");
+    const safeKey = toExternalAssetKey(absPath);
     externalAssets.set(safeKey, absPath);
     return safeKey;
   }
@@ -25204,7 +25327,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
   const audios = dedupeElementsById([...mainAudios, ...subAudios]);
   for (const video of videos) {
     if (isHttpUrl(video.src)) continue;
-    const videoPath = resolve13(projectDir, video.src);
+    const videoPath = resolve14(projectDir, video.src);
     const reencode = `ffmpeg -i "${video.src}" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4`;
     Promise.all([analyzeKeyframeIntervals(videoPath), extractVideoMetadata(videoPath)]).then(([analysis, metadata]) => {
       if (analysis.isProblematic) {
@@ -25339,6 +25462,7 @@ var init_htmlCompiler2 = __esm({
     init_esm10();
     init_src();
     init_ffprobe2();
+    init_paths();
     init_src2();
     init_urlDownloader2();
     init_deterministicFonts();
@@ -25397,7 +25521,7 @@ import {
   copyFileSync as copyFileSync2,
   appendFileSync
 } from "fs";
-import { join as join29, dirname as dirname10, resolve as resolve14 } from "path";
+import { join as join30, 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";
@@ -25453,17 +25577,17 @@ function installDebugLogger(logPath, log = defaultLogger) {
   };
 }
 function writeCompiledArtifacts(compiled, workDir, includeSummary) {
-  const compileDir = join29(workDir, "compiled");
+  const compileDir = join30(workDir, "compiled");
   mkdirSync17(compileDir, { recursive: true });
-  writeFileSync10(join29(compileDir, "index.html"), compiled.html, "utf-8");
+  writeFileSync10(join30(compileDir, "index.html"), compiled.html, "utf-8");
   for (const [srcPath, html] of compiled.subCompositions) {
-    const outPath = join29(compileDir, srcPath);
+    const outPath = join30(compileDir, srcPath);
     mkdirSync17(dirname10(outPath), { recursive: true });
     writeFileSync10(outPath, html, "utf-8");
   }
   for (const [relativePath, absolutePath] of compiled.externalAssets) {
-    const outPath = resolve14(join29(compileDir, relativePath));
-    if (!outPath.startsWith(compileDir + "/")) {
+    const outPath = resolve15(join30(compileDir, relativePath));
+    if (!isPathInside(outPath, compileDir)) {
       console.warn(`[Render] Skipping external asset with unsafe path: ${relativePath}`);
       continue;
     }
@@ -25491,7 +25615,7 @@ function writeCompiledArtifacts(compiled, workDir, includeSummary) {
       })),
       subCompositions: Array.from(compiled.subCompositions.keys())
     };
-    writeFileSync10(join29(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
+    writeFileSync10(join30(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
   }
 }
 function createRenderJob(config) {
@@ -25535,9 +25659,9 @@ function extractStandaloneEntryFromIndex(indexHtml, entryFile) {
 }
 async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSignal) {
   const moduleDir = dirname10(fileURLToPath3(import.meta.url));
-  const producerRoot = process.env.PRODUCER_RENDERS_DIR ? resolve14(process.env.PRODUCER_RENDERS_DIR, "..") : resolve14(moduleDir, "../..");
-  const debugDir = join29(producerRoot, ".debug");
-  const workDir = job.config.debug ? join29(debugDir, job.id) : join29(dirname10(outputPath), `work-${job.id}`);
+  const producerRoot = process.env.PRODUCER_RENDERS_DIR ? resolve15(process.env.PRODUCER_RENDERS_DIR, "..") : resolve15(moduleDir, "../..");
+  const debugDir = join30(producerRoot, ".debug");
+  const workDir = job.config.debug ? join30(debugDir, job.id) : join30(dirname10(outputPath), `work-${job.id}`);
   const pipelineStart = Date.now();
   const log = job.config.logger ?? defaultLogger;
   let fileServer = null;
@@ -25545,7 +25669,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
   let lastBrowserConsole = [];
   let restoreLogger = null;
   const perfStages = {};
-  const perfOutputPath = join29(workDir, "perf-summary.json");
+  const perfOutputPath = join30(workDir, "perf-summary.json");
   const cfg = { ...job.config.producerConfig ?? resolveConfig() };
   const outputFormat = job.config.format ?? "mp4";
   const isWebm = outputFormat === "webm";
@@ -25567,19 +25691,19 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     assertNotAborted();
     if (!existsSync27(workDir)) mkdirSync17(workDir, { recursive: true });
     if (job.config.debug) {
-      const logPath = join29(workDir, "render.log");
+      const logPath = join30(workDir, "render.log");
       restoreLogger = installDebugLogger(logPath, log);
     }
     const entryFile = job.config.entryFile || "index.html";
-    let htmlPath = join29(projectDir, entryFile);
+    let htmlPath = join30(projectDir, entryFile);
     if (!existsSync27(htmlPath)) {
       throw new Error(`Entry file not found: ${htmlPath}`);
     }
     assertNotAborted();
     const rawEntry = readFileSync20(htmlPath, "utf-8");
     if (entryFile !== "index.html" && rawEntry.trimStart().startsWith("<template")) {
-      const wrapperPath = join29(workDir, "standalone-entry.html");
-      const projectIndexPath = join29(projectDir, "index.html");
+      const wrapperPath = join30(workDir, "standalone-entry.html");
+      const projectIndexPath = join30(projectDir, "index.html");
       if (!existsSync27(projectIndexPath)) {
         throw new Error(
           `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`
@@ -25603,7 +25727,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const stage1Start = Date.now();
     updateJobStatus(job, "preprocessing", "Compiling composition", 5, onProgress);
     const compileStart = Date.now();
-    let compiled = await compileForRender(projectDir, htmlPath, join29(workDir, "downloads"));
+    let compiled = await compileForRender(projectDir, htmlPath, join30(workDir, "downloads"));
     assertNotAborted();
     perfStages.compileOnlyMs = Date.now() - compileStart;
     writeCompiledArtifacts(compiled, workDir, Boolean(job.config.debug));
@@ -25632,7 +25756,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         reasons.push(`${compiled.unresolvedCompositions.length} unresolved composition(s)`);
       fileServer = await createFileServer2({
         projectDir,
-        compiledDir: join29(workDir, "compiled"),
+        compiledDir: join30(workDir, "compiled"),
         port: 0
       });
       assertNotAborted();
@@ -25645,7 +25769,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       };
       probeSession = await createCaptureSession(
         fileServer.url,
-        join29(workDir, "probe"),
+        join30(workDir, "probe"),
         captureOpts,
         null,
         cfg
@@ -25677,7 +25801,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
             compiled,
             resolutions,
             projectDir,
-            join29(workDir, "downloads")
+            join30(workDir, "downloads")
           );
           assertNotAborted();
           composition.videos = compiled.videos;
@@ -25812,12 +25936,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const stage2Start = Date.now();
     updateJobStatus(job, "preprocessing", "Extracting video frames", 10, onProgress);
     let frameLookup = null;
-    const compiledDir = join29(workDir, "compiled");
+    const compiledDir = join30(workDir, "compiled");
     if (composition.videos.length > 0) {
       const extractionResult = await extractAllVideoFrames(
         composition.videos,
         projectDir,
-        { fps: job.config.fps, outputDir: join29(workDir, "video-frames") },
+        { fps: job.config.fps, outputDir: join30(workDir, "video-frames") },
         abortSignal,
         void 0,
         compiledDir
@@ -25851,13 +25975,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     }
     const stage3Start = Date.now();
     updateJobStatus(job, "preprocessing", "Processing audio tracks", 20, onProgress);
-    const audioOutputPath = join29(workDir, "audio.aac");
+    const audioOutputPath = join30(workDir, "audio.aac");
     let hasAudio = false;
     if (composition.audios.length > 0) {
       const audioResult = await processCompositionAudio(
         composition.audios,
         projectDir,
-        join29(workDir, "audio-work"),
+        join30(workDir, "audio-work"),
         audioOutputPath,
         job.duration,
         abortSignal,
@@ -25875,12 +25999,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     if (!fileServer) {
       fileServer = await createFileServer2({
         projectDir,
-        compiledDir: join29(workDir, "compiled"),
+        compiledDir: join30(workDir, "compiled"),
         port: 0
       });
       assertNotAborted();
     }
-    const framesDir = join29(workDir, "captured-frames");
+    const framesDir = join30(workDir, "captured-frames");
     if (!existsSync27(framesDir)) mkdirSync17(framesDir, { recursive: true });
     const captureOptions = {
       width,
@@ -25892,7 +26016,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const workerCount = calculateOptimalWorkers(job.totalFrames, job.config.workers, cfg);
     const FORMAT_EXT2 = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
     const videoExt = FORMAT_EXT2[outputFormat] ?? ".mp4";
-    const videoOnlyPath = join29(workDir, `video-only${videoExt}`);
+    const videoOnlyPath = join30(workDir, `video-only${videoExt}`);
     const preset = getEncoderPreset(job.config.quality, outputFormat);
     const effectiveQuality = job.config.crf ?? preset.quality;
     const effectiveBitrate = job.config.videoBitrate;
@@ -26168,7 +26292,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     }
     if (job.config.debug) {
       if (existsSync27(outputPath)) {
-        const debugOutput = join29(workDir, `output${videoExt}`);
+        const debugOutput = join30(workDir, `output${videoExt}`);
         copyFileSync2(outputPath, debugOutput);
       }
     } else {
@@ -26269,6 +26393,7 @@ var init_renderOrchestrator = __esm({
     init_fileServer2();
     init_htmlCompiler2();
     init_logger();
+    init_paths();
     RenderCancelledError = class extends Error {
       reason;
       constructor(message = "render_cancelled", reason = "aborted") {
@@ -26306,7 +26431,7 @@ var init_config3 = __esm({
 
 // ../producer/src/services/hyperframeLint.ts
 import { existsSync as existsSync28, readFileSync as readFileSync21, statSync as statSync8 } from "fs";
-import { resolve as resolve15, join as join30 } from "path";
+import { resolve as resolve16, join as join31 } from "path";
 function isStringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -26333,7 +26458,7 @@ function pickEntryFile(files, preferredEntryFile) {
   return null;
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
-  const absProjectDir = resolve15(projectDir);
+  const absProjectDir = resolve16(projectDir);
   if (!existsSync28(absProjectDir) || !statSync8(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
@@ -26341,7 +26466,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
     (value) => typeof value === "string" && value.trim().length > 0
   );
   for (const entryFile of entryCandidates) {
-    const absoluteEntryPath = resolve15(absProjectDir, entryFile);
+    const absoluteEntryPath = resolve16(absProjectDir, entryFile);
     if (!absoluteEntryPath.startsWith(absProjectDir)) {
       return { error: `Entry file must stay inside project directory: ${entryFile}` };
     }
@@ -26354,7 +26479,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
     }
   }
   return {
-    error: `No HTML entry file found in project directory: ${join30(absProjectDir, preferredEntryFile || "index.html")}`
+    error: `No HTML entry file found in project directory: ${join31(absProjectDir, preferredEntryFile || "index.html")}`
   };
 }
 function prepareHyperframeLintBody(body) {
@@ -26400,23 +26525,6 @@ var init_hyperframeLint = __esm({
   }
 });
 
-// ../producer/src/utils/paths.ts
-import { resolve as resolve16, basename, join as join31 } from "path";
-function resolveRenderPaths(projectDir, outputPath, rendersDir = DEFAULT_RENDERS_DIR) {
-  const absoluteProjectDir = resolve16(projectDir);
-  const projectName = basename(absoluteProjectDir);
-  const resolvedOutputPath = outputPath ?? join31(rendersDir, `${projectName}.mp4`);
-  const absoluteOutputPath = resolve16(resolvedOutputPath);
-  return { absoluteProjectDir, absoluteOutputPath };
-}
-var DEFAULT_RENDERS_DIR;
-var init_paths = __esm({
-  "../producer/src/utils/paths.ts"() {
-    "use strict";
-    DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? resolve16(new URL(import.meta.url).pathname, "../../..", "renders");
-  }
-});
-
 // ../producer/src/utils/semaphore.ts
 var Semaphore;
 var init_semaphore = __esm({
@@ -28219,7 +28327,7 @@ __export(add_exports, {
   runAdd: () => runAdd
 });
 import { existsSync as existsSync33 } from "fs";
-import { resolve as resolve21, relative as relative2 } from "path";
+import { resolve as resolve21, relative as relative3 } from "path";
 function remapTarget(item, originalTarget, paths) {
   if (item.type === "hyperframes:block") {
     const blocksDir = paths.blocks.replace(/\/+$/, "");
@@ -28358,7 +28466,7 @@ var init_add = __esm({
           console.log("");
           console.log(`${c.success("\u2713")} Added ${c.accent(result.name)} (${result.type})`);
           for (const file of result.written) {
-            console.log(`  ${c.dim(relative2(projectDir, file))}`);
+            console.log(`  ${c.dim(relative3(projectDir, file))}`);
           }
           if (result.snippet) {
             console.log("");
@@ -30787,18 +30895,18 @@ function checkFFmpeg() {
   return {
     ok: false,
     detail: "Not found",
-    hint: process.platform === "darwin" ? "brew install ffmpeg" : "sudo apt install ffmpeg"
+    hint: getFFmpegInstallHint()
   };
 }
 function checkFFprobe() {
   try {
-    const result = execSync3("which ffprobe", { encoding: "utf-8", timeout: 5e3 }).trim();
-    return { ok: true, detail: result };
+    const version = execSync3("ffprobe -version", { encoding: "utf-8", timeout: 5e3 }).split("\n")[0] ?? "";
+    return { ok: true, detail: version.trim() };
   } catch {
     return {
       ok: false,
       detail: "Not found",
-      hint: "Installed with ffmpeg"
+      hint: `Installed with ffmpeg \u2014 ${getFFmpegInstallHint()}`
     };
   }
 }
@@ -31450,7 +31558,7 @@ __export(snapshot_exports, {
   examples: () => examples18
 });
 import { existsSync as existsSync44, readFileSync as readFileSync31, mkdirSync as mkdirSync24 } from "fs";
-import { resolve as resolve32, join as join44, dirname as dirname20, relative as relative3, isAbsolute as isAbsolute3 } from "path";
+import { resolve as resolve32, join as join44, dirname as dirname20, relative as relative4, isAbsolute as isAbsolute4 } from "path";
 import { fileURLToPath as fileURLToPath8 } from "url";
 async function captureSnapshots(projectDir, opts) {
   const { bundleToSingleHtml: bundleToSingleHtml2 } = await Promise.resolve().then(() => (init_compiler(), compiler_exports));
@@ -31483,8 +31591,8 @@ async function captureSnapshots(projectDir, opts) {
       return;
     }
     const filePath = resolve32(projectDir, decodeURIComponent(url).replace(/^\//, ""));
-    const rel = relative3(projectDir, filePath);
-    if (rel.startsWith("..") || isAbsolute3(rel)) {
+    const rel = relative4(projectDir, filePath);
+    if (rel.startsWith("..") || isAbsolute4(rel)) {
       res.writeHead(403);
       res.end();
       return;
@@ -73405,7 +73513,7 @@ async function captionImagesWithGemini(outputDir, progress, warnings) {
     const imageFiles = readdirSync13(join47(outputDir, "assets")).filter(
       (f3) => /\.(png|jpg|jpeg|webp|gif)$/i.test(f3)
     );
-    const model = "gemini-2.5-flash";
+    const model = process.env.HYPERFRAMES_GEMINI_MODEL || "gemini-3.1-flash-lite-preview";
     const BATCH_SIZE = 20;
     for (let i2 = 0; i2 < imageFiles.length; i2 += BATCH_SIZE) {
       const batch = imageFiles.slice(i2, i2 + BATCH_SIZE);
@@ -73667,50 +73775,7 @@ function loadEnvFile(startDir) {
   }
 }
 async function generateProjectScaffold(outputDir, url, tokens, animationCatalog, hasScreenshots, hasLotties, hasShaders, catalogedAssets, progress, warnings) {
-  const indexPath = join49(outputDir, "index.html");
   const metaPath = join49(outputDir, "meta.json");
-  if (!existsSync45(indexPath)) {
-    writeFileSync20(
-      indexPath,
-      `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=1920, height=1080" />
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-    <style>
-      * { margin: 0; padding: 0; box-sizing: border-box; }
-      html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: #000; }
-    </style>
-  </head>
-  <body>
-    <!-- Root composition wrapper \u2014 AGENT: update data-duration to match total video length -->
-    <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="28">
-
-      <!-- SCENE SLOTS \u2014 AGENT: adjust count, durations, and IDs to match your scene plan -->
-      <div id="scene-1" data-composition-src="compositions/scene-1.html" data-start="0" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
-      <div id="scene-2" data-composition-src="compositions/scene-2.html" data-start="7" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
-      <div id="scene-3" data-composition-src="compositions/scene-3.html" data-start="14" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
-      <div id="scene-4" data-composition-src="compositions/scene-4.html" data-start="21" data-duration="7" data-track-index="1" data-width="1920" data-height="1080"></div>
-
-      <!-- NARRATION \u2014 AGENT: update src after generating TTS -->
-      <audio id="narration" data-start="0" data-duration="28" data-track-index="0" data-volume="1" src="narration.wav"></audio>
-
-      <!-- CAPTIONS (optional \u2014 only add if user requests captions/subtitles) -->
-
-    </div>
-
-    <script>
-      window.__timelines = window.__timelines || {};
-      var tl = gsap.timeline({ paused: true });
-      window.__timelines["main"] = tl;
-    </script>
-  </body>
-</html>
-`,
-      "utf-8"
-    );
-  }
   if (!existsSync45(metaPath)) {
     const hostname = new URL(url).hostname.replace(/^www\./, "");
     writeFileSync20(