npm - hyperframes - Versions diffs - 0.2.3 → 0.2.4 - Mend

hyperframes 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/dist/cli.js +674 -249
package/dist/hyperframe-runtime.js +5 -5
package/dist/hyperframe.manifest.json +1 -1
package/dist/hyperframe.runtime.iife.js +5 -5
package/dist/skills/hyperframes/SKILL.md +76 -5
package/dist/skills/hyperframes/house-style.md +1 -1
package/dist/skills/hyperframes/references/captions.md +1 -1
package/dist/skills/hyperframes/references/examples.md +1 -1
package/dist/skills/hyperframes/references/fonts.md +134 -0
package/dist/skills/hyperframes/references/motion-principles.md +69 -0
package/dist/skills/hyperframes/references/transitions/catalog.md +2 -2
package/package.json +1 -1

package/dist/cli.js CHANGED Viewed

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.2.3" : "0.0.0-dev";
+    VERSION = true ? "0.2.4" : "0.0.0-dev";
   }
 });
@@ -2731,7 +2731,7 @@ import { get as httpsGet } from "https";
 import { pipeline } from "stream/promises";
 function downloadFile(url, dest) {
   const tmp = `${dest}.tmp`;
-  return new Promise((resolve27, reject) => {
+  return new Promise((resolve28, reject) => {
     const follow = (u) => {
       httpsGet(u, (res) => {
         if (res.statusCode === 301 || res.statusCode === 302) {
@@ -2748,7 +2748,7 @@ function downloadFile(url, dest) {
         const file = createWriteStream(tmp);
         pipeline(res, file).then(() => {
           renameSync(tmp, dest);
-          resolve27();
+          resolve28();
         }).catch((err) => {
           try {
             unlinkSync(tmp);
@@ -3401,13 +3401,13 @@ function hasNpx() {
   }
 }
 function runSkillsAdd(repo) {
-  return new Promise((resolve27, reject) => {
+  return new Promise((resolve28, reject) => {
     const child = spawn("npx", ["skills", "add", repo, "--all"], {
       stdio: "inherit",
       timeout: 12e4
     });
     child.on("close", (code, signal) => {
-      if (code === 0) resolve27();
+      if (code === 0) resolve28();
       else if (signal === "SIGINT" || code === 130) process.exit(0);
       else reject(new Error(`npx skills add exited with code ${code}`));
     });
@@ -3554,7 +3554,8 @@ var init_utils = __esm({
 // ../core/src/lint/context.ts
 function buildLintContext(html, options = {}) {
-  let source = html || "";
+  const rawSource = html || "";
+  let source = rawSource;
   const templateMatch = source.match(/<template[^>]*>([\s\S]*)<\/template>/i);
   if (templateMatch?.[1]) source = templateMatch[1];
   const tags = extractOpenTags(source);
@@ -3565,6 +3566,7 @@ function buildLintContext(html, options = {}) {
   const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
   return {
     source,
+    rawSource,
     tags,
     styles,
     scripts,
@@ -4971,6 +4973,56 @@ var init_composition = __esm({
         }
         return findings;
       },
+      // root_composition_missing_data_start
+      ({ rootTag }) => {
+        const findings = [];
+        if (!rootTag) return findings;
+        const compId = readAttr(rootTag.raw, "data-composition-id");
+        if (!compId) return findings;
+        const hasStart = readAttr(rootTag.raw, "data-start") !== null;
+        if (!hasStart) {
+          findings.push({
+            code: "root_composition_missing_data_start",
+            severity: "warning",
+            message: `Root composition "${compId}" is missing data-start. The runtime needs data-start="0" on the root element to begin playback.`,
+            fixHint: 'Add data-start="0" to the root composition element.',
+            snippet: truncateSnippet(rootTag.raw)
+          });
+        }
+        return findings;
+      },
+      // standalone_composition_wrapped_in_template
+      ({ rawSource, options }) => {
+        const findings = [];
+        if (options.isSubComposition) return findings;
+        const trimmed = rawSource.trimStart().toLowerCase();
+        if (trimmed.startsWith("<template")) {
+          findings.push({
+            code: "standalone_composition_wrapped_in_template",
+            severity: "warning",
+            message: "Root index.html is wrapped in a <template> tag. Only sub-compositions loaded via data-composition-src should use <template> wrappers. The runtime cannot play a standalone composition inside a template.",
+            fixHint: "Remove the <template> wrapper. Use <!DOCTYPE html><html>...<div data-composition-id>...</div>...</html> instead."
+          });
+        }
+        return findings;
+      },
+      // root_composition_missing_html_wrapper
+      ({ rawSource, options }) => {
+        const findings = [];
+        if (options.isSubComposition) return findings;
+        const trimmed = rawSource.trimStart().toLowerCase();
+        const hasDoctype = trimmed.startsWith("<!doctype") || trimmed.startsWith("<html");
+        const hasComposition = rawSource.includes("data-composition-id");
+        if (hasComposition && !hasDoctype) {
+          findings.push({
+            code: "root_composition_missing_html_wrapper",
+            severity: "warning",
+            message: "Composition is missing <!DOCTYPE html> and <html> wrapper. The bundler and preview expect a complete HTML document for index.html files.",
+            fixHint: 'Wrap the composition in <!DOCTYPE html><html><head><meta charset="UTF-8"></head><body>...</body></html>.'
+          });
+        }
+        return findings;
+      },
       // requestanimationframe_in_composition
       ({ scripts }) => {
         const findings = [];
@@ -5192,7 +5244,7 @@ function lintProject(project) {
       const filePath = join6(compositionsDir, file);
       const html = readFileSync6(filePath, "utf-8");
       allHtmlSources.push(html);
-      const result = lintHyperframeHtml(html, { filePath });
+      const result = lintHyperframeHtml(html, { filePath, isSubComposition: true });
       results.push({ file: `compositions/${file}`, result });
       totalErrors += result.errorCount;
       totalWarnings += result.warningCount;
@@ -5328,6 +5380,238 @@ var init_lintFormat = __esm({
   }
 });
+// src/server/portUtils.ts
+import net from "net";
+import http from "http";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { resolve as resolve2 } from "path";
+function isPortAvailableOnHost(port, host) {
+  return new Promise((resolve28) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", (err) => {
+      resolve28(err.code !== "EADDRINUSE");
+    });
+    server.listen({ port, host }, () => {
+      server.close(() => {
+        resolve28(true);
+      });
+    });
+  });
+}
+async function testPortOnAllHosts(port) {
+  const hosts = ["127.0.0.1", "0.0.0.0", "::1", "::"];
+  const results = await Promise.all(hosts.map((h2) => isPortAvailableOnHost(port, h2)));
+  return results.every(Boolean);
+}
+function detectHyperframesServer(port, normalizedProjectDir) {
+  return new Promise((resolveResult) => {
+    const req = http.get(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/__hyperframes_config",
+        timeout: PROBE_TIMEOUT_MS
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return resolveResult({ type: "not-hyperframes" });
+        }
+        let data = "";
+        let bytes = 0;
+        res.on("data", (chunk) => {
+          bytes += typeof chunk === "string" ? chunk.length : chunk.byteLength;
+          if (bytes > PROBE_MAX_BYTES) {
+            req.destroy();
+            return resolveResult({ type: "not-hyperframes" });
+          }
+          data += chunk;
+        });
+        res.on("error", () => {
+          resolveResult({ type: "not-hyperframes" });
+        });
+        res.on("end", () => {
+          try {
+            const json = JSON.parse(data);
+            if (json.isHyperframes !== true) {
+              return resolveResult({ type: "not-hyperframes" });
+            }
+            const normalize = (p) => resolve2(p).replace(/\\/g, "/").toLowerCase();
+            if (normalize(json.projectDir) === normalizedProjectDir) {
+              return resolveResult({ type: "match" });
+            }
+            return resolveResult({ type: "mismatch", projectName: json.projectName });
+          } catch {
+            resolveResult({ type: "not-hyperframes" });
+          }
+        });
+      }
+    );
+    req.on("error", () => {
+      resolveResult({ type: "not-hyperframes" });
+    });
+    req.on("timeout", () => {
+      req.destroy();
+      resolveResult({ type: "not-hyperframes" });
+    });
+  });
+}
+async function getProcessOnPort(port) {
+  if (process.platform === "win32") return null;
+  try {
+    const { stdout: stdout2 } = await execFileAsync("lsof", [`-ti:${port}`, "-sTCP:LISTEN"], {
+      timeout: 2e3
+    });
+    const pid = stdout2.trim().split("\n")[0]?.trim();
+    return pid || null;
+  } catch {
+    return null;
+  }
+}
+function probePort(port) {
+  return new Promise((resolveResult) => {
+    const req = http.get(
+      { hostname: "127.0.0.1", port, path: "/__hyperframes_config", timeout: PROBE_TIMEOUT_MS },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return resolveResult(null);
+        }
+        let data = "";
+        let bytes = 0;
+        res.on("data", (chunk) => {
+          bytes += typeof chunk === "string" ? chunk.length : chunk.byteLength;
+          if (bytes > PROBE_MAX_BYTES) {
+            req.destroy();
+            return resolveResult(null);
+          }
+          data += chunk;
+        });
+        res.on("error", () => resolveResult(null));
+        res.on("end", () => {
+          try {
+            const json = JSON.parse(data);
+            resolveResult(json.isHyperframes === true ? json : null);
+          } catch {
+            resolveResult(null);
+          }
+        });
+      }
+    );
+    req.on("error", () => resolveResult(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolveResult(null);
+    });
+  });
+}
+async function scanActiveServers(startPort = 3002) {
+  const endPort = startPort + MAX_PORT_SCAN - 1;
+  const servers = [];
+  const batchSize = 20;
+  for (let batchStart = startPort; batchStart <= endPort; batchStart += batchSize) {
+    const batchEnd = Math.min(batchStart + batchSize - 1, endPort);
+    const ports = Array.from({ length: batchEnd - batchStart + 1 }, (_2, i) => batchStart + i);
+    const results = await Promise.all(
+      ports.map(async (port) => {
+        const config = await probePort(port);
+        if (!config) return null;
+        const pid = await getProcessOnPort(port);
+        return {
+          port,
+          projectName: config.projectName,
+          projectDir: config.projectDir,
+          version: config.version,
+          pid
+        };
+      })
+    );
+    for (const r of results) {
+      if (r) servers.push(r);
+    }
+  }
+  return servers;
+}
+async function killActiveServers(startPort = 3002) {
+  const servers = await scanActiveServers(startPort);
+  let killed = 0;
+  for (const server of servers) {
+    if (server.pid) {
+      try {
+        process.kill(parseInt(server.pid, 10), "SIGTERM");
+        killed++;
+      } catch {
+      }
+    }
+  }
+  return killed;
+}
+async function findPortAndServe(fetch3, startPort, projectDir, forceNew) {
+  const { createAdaptorServer } = await import("@hono/node-server");
+  const normalizedDir = resolve2(projectDir).replace(/\\/g, "/").toLowerCase();
+  const endPort = startPort + MAX_PORT_SCAN - 1;
+  let server = null;
+  for (let port = startPort; port <= endPort; port++) {
+    const available = await testPortOnAllHosts(port);
+    if (available) {
+      if (!server) server = createAdaptorServer({ fetch: fetch3 });
+      try {
+        await new Promise((resolveListener, rejectListener) => {
+          const onError = (err) => {
+            server.removeListener("listening", onListening);
+            rejectListener(err);
+          };
+          const onListening = () => {
+            server.removeListener("error", onError);
+            resolveListener();
+          };
+          server.once("error", onError);
+          server.once("listening", onListening);
+          server.listen(port);
+        });
+        return { type: "started", server, port };
+      } catch (err) {
+        if (err.code === "EADDRINUSE") {
+          continue;
+        }
+        throw err;
+      }
+    }
+    if (!forceNew) {
+      const detection = await detectHyperframesServer(port, normalizedDir);
+      if (detection.type === "match") {
+        return { type: "already-running", port };
+      }
+      if (detection.type === "mismatch") {
+        console.log(
+          `  ${c.dim(`Port ${port} in use by HyperFrames project "${detection.projectName}" \u2014 skipping`)}`
+        );
+        continue;
+      }
+    }
+    const pid = await getProcessOnPort(port);
+    if (pid) {
+      console.log(`  ${c.dim(`Port ${port} in use by PID ${pid} \u2014 skipping`)}`);
+    }
+  }
+  throw new Error(
+    `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 init_portUtils = __esm({
+  "src/server/portUtils.ts"() {
+    "use strict";
+    init_colors();
+    execFileAsync = promisify(execFile);
+    MAX_PORT_SCAN = 100;
+    PROBE_TIMEOUT_MS = 300;
+    PROBE_MAX_BYTES = 4096;
+  }
+});
 // src/server/fileWatcher.ts
 import { watch } from "fs";
 function createProjectWatcher(projectDir) {
@@ -5372,11 +5656,11 @@ var init_fileWatcher = __esm({
 });
 // ../core/src/studio-api/helpers/safePath.ts
-import { resolve as resolve2, sep, join as join7 } from "path";
+import { resolve as resolve3, sep, join as join7 } from "path";
 import { readdirSync as readdirSync3 } from "fs";
 function isSafePath(base, resolved) {
-  const norm = resolve2(base) + sep;
-  return resolved.startsWith(norm) || resolved === resolve2(base);
+  const norm = resolve3(base) + sep;
+  return resolved.startsWith(norm) || resolved === resolve3(base);
 }
 function walkDir(dir, prefix = "") {
   const files = [];
@@ -5441,7 +5725,7 @@ import {
   renameSync as renameSync2,
   readdirSync as readdirSync4
 } from "fs";
-import { resolve as resolve3, dirname, join as join8 } from "path";
+import { resolve as resolve4, dirname, join as join8 } from "path";
 async function resolveProjectFile(c2, adapter2, opts) {
   const id = c2.req.param("id");
   const project = await adapter2.resolveProject(id);
@@ -5452,7 +5736,7 @@ async function resolveProjectFile(c2, adapter2, opts) {
   if (filePath.includes("\0")) {
     return { error: c2.json({ error: "forbidden" }, 403) };
   }
-  const absPath = resolve3(project.dir, filePath);
+  const absPath = resolve4(project.dir, filePath);
   if (!isSafePath(project.dir, absPath)) {
     return { error: c2.json({ error: "forbidden" }, 403) };
   }
@@ -5472,7 +5756,7 @@ function generateCopyPath(projectDir, originalPath) {
   const cleanBase = copyMatch ? base.slice(0, -copyMatch[0].length) : base;
   let num = copyMatch ? copyMatch[1] ? parseInt(copyMatch[1]) + 1 : 2 : 1;
   let candidate = num === 1 ? `${cleanBase} (copy)${ext}` : `${cleanBase} (copy ${num})${ext}`;
-  while (existsSync7(resolve3(projectDir, candidate))) {
+  while (existsSync7(resolve4(projectDir, candidate))) {
     num++;
     candidate = `${cleanBase} (copy ${num})${ext}`;
   }
@@ -5553,7 +5837,7 @@ function registerFileRoutes(api, adapter2) {
     if (!body.newPath || body.newPath.includes("\0")) {
       return c2.json({ error: "newPath required" }, 400);
     }
-    const newAbs = resolve3(res.project.dir, body.newPath);
+    const newAbs = resolve4(res.project.dir, body.newPath);
     if (!isSafePath(res.project.dir, newAbs)) {
       return c2.json({ error: "forbidden" }, 403);
     }
@@ -5572,12 +5856,12 @@ function registerFileRoutes(api, adapter2) {
     if (!body.path || body.path.includes("\0")) {
       return c2.json({ error: "path required" }, 400);
     }
-    const srcAbs = resolve3(project.dir, body.path);
+    const srcAbs = resolve4(project.dir, body.path);
     if (!isSafePath(project.dir, srcAbs) || !existsSync7(srcAbs)) {
       return c2.json({ error: "not found" }, 404);
     }
     const copyPath = generateCopyPath(project.dir, body.path);
-    const destAbs = resolve3(project.dir, copyPath);
+    const destAbs = resolve4(project.dir, copyPath);
     if (!isSafePath(project.dir, destAbs)) {
       return c2.json({ error: "forbidden" }, 403);
     }
@@ -5596,7 +5880,7 @@ function registerFileRoutes(api, adapter2) {
       const project = await adapter2.resolveProject(c2.req.param("id"));
       if (!project) return c2.json({ error: "not found" }, 404);
       const subDir = c2.req.query("dir") ?? "";
-      const targetDir = subDir ? resolve3(project.dir, subDir) : project.dir;
+      const targetDir = subDir ? resolve4(project.dir, subDir) : project.dir;
       if (!isSafePath(project.dir, targetDir)) return c2.json({ error: "forbidden" }, 403);
       if (subDir && !existsSync7(targetDir)) mkdirSync5(targetDir, { recursive: true });
       const formData = await c2.req.formData();
@@ -5610,7 +5894,7 @@ function registerFileRoutes(api, adapter2) {
           skipped.push(name);
           continue;
         }
-        const destPath = resolve3(targetDir, name);
+        const destPath = resolve4(targetDir, name);
         if (!isSafePath(project.dir, destPath)) continue;
         let finalPath = destPath;
         let finalName = name;
@@ -5619,13 +5903,13 @@ function registerFileRoutes(api, adapter2) {
           const ext = dotIdx > 0 ? name.slice(dotIdx) : "";
           const base = dotIdx > 0 ? name.slice(0, dotIdx) : name;
           let n = 2;
-          while (n < 1e4 && existsSync7(resolve3(targetDir, `${base} (${n})${ext}`))) n++;
+          while (n < 1e4 && existsSync7(resolve4(targetDir, `${base} (${n})${ext}`))) n++;
           if (n >= 1e4) {
             skipped.push(name);
             continue;
           }
           finalName = `${base} (${n})${ext}`;
-          finalPath = resolve3(targetDir, finalName);
+          finalPath = resolve4(targetDir, finalName);
         }
         const buffer = Buffer.from(await value.arrayBuffer());
         writeFileSync4(finalPath, buffer);
@@ -9535,8 +9819,8 @@ var init_custom_element_registry = __esm({
         } : (element) => element.localName === localName;
         registry.set(localName, { Class, check });
         if (waiting.has(localName)) {
-          for (const resolve27 of waiting.get(localName))
-            resolve27(Class);
+          for (const resolve28 of waiting.get(localName))
+            resolve28(Class);
           waiting.delete(localName);
         }
         ownerDocument.querySelectorAll(
@@ -9576,13 +9860,13 @@ var init_custom_element_registry = __esm({
        */
       whenDefined(localName) {
         const { registry, waiting } = this;
-        return new Promise((resolve27) => {
+        return new Promise((resolve28) => {
           if (registry.has(localName))
-            resolve27(registry.get(localName).Class);
+            resolve28(registry.get(localName).Class);
           else {
             if (!waiting.has(localName))
               waiting.set(localName, []);
-            waiting.get(localName).push(resolve27);
+            waiting.get(localName).push(resolve28);
           }
         });
       }
@@ -18283,7 +18567,7 @@ var init_esm10 = __esm({
 });
 // ../core/src/compiler/rewriteSubCompPaths.ts
-import { join as join9, resolve as resolve4, dirname as dirname2 } from "path";
+import { join as join9, resolve as resolve5, dirname as dirname2 } from "path";
 function isAbsoluteOrSpecial(val) {
   return !val || val.startsWith("http://") || val.startsWith("https://") || val.startsWith("//") || val.startsWith("data:") || val.startsWith("#");
 }
@@ -18296,7 +18580,7 @@ function rewriteAssetPath(compSrcPath, relativePath) {
   const compDir = dirname2(compSrcPath);
   if (!compDir || compDir === ".") return relativePath;
   const resolved = join9(compDir, relativePath);
-  const normalized = resolve4("/", resolved).slice(1);
+  const normalized = resolve5("/", resolved).slice(1);
   return normalized;
 }
 function rewriteAssetPaths(elements, compSrcPath, getAttr2, setAttr) {
@@ -18308,7 +18592,7 @@ function rewriteAssetPaths(elements, compSrcPath, getAttr2, setAttr) {
       if (isAbsoluteOrSpecial(val)) continue;
       if (!needsRewrite(val)) continue;
       const rewritten = join9(compDir, val);
-      const normalized = resolve4("/", rewritten).slice(1);
+      const normalized = resolve5("/", rewritten).slice(1);
       if (normalized !== val) {
         setAttr(el, attr, normalized);
       }
@@ -18397,7 +18681,7 @@ var init_subComposition = __esm({
 // ../core/src/studio-api/routes/preview.ts
 import { existsSync as existsSync9, readFileSync as readFileSync9, statSync as statSync2 } from "fs";
-import { resolve as resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 function registerPreviewRoutes(api, adapter2) {
   api.get("/projects/:id/preview", async (c2) => {
     const project = await adapter2.resolveProject(c2.req.param("id"));
@@ -18405,7 +18689,7 @@ function registerPreviewRoutes(api, adapter2) {
     try {
       let bundled = await adapter2.bundle(project.dir);
       if (!bundled) {
-        const indexPath = resolve5(project.dir, "index.html");
+        const indexPath = resolve6(project.dir, "index.html");
         if (!existsSync9(indexPath)) return c2.text("not found", 404);
         bundled = readFileSync9(indexPath, "utf-8");
       }
@@ -18421,7 +18705,7 @@ ${runtimeTag}`;
       }
       return c2.html(bundled);
     } catch {
-      const file = resolve5(project.dir, "index.html");
+      const file = resolve6(project.dir, "index.html");
       if (existsSync9(file)) return c2.html(readFileSync9(file, "utf-8"));
       return c2.text("not found", 404);
     }
@@ -18432,7 +18716,7 @@ ${runtimeTag}`;
     const compPath = decodeURIComponent(
       c2.req.path.replace(`/projects/${project.id}/preview/comp/`, "").split("?")[0] ?? ""
     );
-    const compFile = resolve5(project.dir, compPath);
+    const compFile = resolve6(project.dir, compPath);
     if (!isSafePath(project.dir, compFile) || !existsSync9(compFile) || !statSync2(compFile).isFile()) {
       return c2.text("not found", 404);
     }
@@ -18447,7 +18731,7 @@ ${runtimeTag}`;
     const subPath = decodeURIComponent(
       c2.req.path.replace(`/projects/${project.id}/preview/`, "").split("?")[0] ?? ""
     );
-    const file = resolve5(project.dir, subPath);
+    const file = resolve6(project.dir, subPath);
     if (!isSafePath(project.dir, file) || !existsSync9(file) || !statSync2(file).isFile()) {
       return c2.text("not found", 404);
     }
@@ -19823,7 +20107,7 @@ var init_timingCompiler = __esm({
 // ../core/src/inline-scripts/hyperframesRuntime.engine.ts
 import { buildSync } from "esbuild";
-import { dirname as dirname3, resolve as resolve6 } from "path";
+import { dirname as dirname3, resolve as resolve7 } from "path";
 import { fileURLToPath } from "url";
 var init_hyperframesRuntime_engine = __esm({
   "../core/src/inline-scripts/hyperframesRuntime.engine.ts"() {
@@ -19990,18 +20274,35 @@ async function getCdpSession(page) {
   }
   return client;
 }
+async function sendBeginFrame(client, params) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await client.send("HeadlessExperimental.beginFrame", params);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const isPending = msg.includes("Another frame is pending");
+      if (isPending && attempt < PENDING_FRAME_RETRIES) {
+        await new Promise((r) => setTimeout(r, 50 * 2 ** attempt));
+        continue;
+      }
+      if (isPending) {
+        throw new Error(
+          `[BeginFrame] Frame still pending after ${PENDING_FRAME_RETRIES} retries \u2014 CPU overloaded by parallel renders. Reduce concurrent renders or use --docker for isolation.`
+        );
+      }
+      throw err;
+    }
+  }
+}
 async function beginFrameCapture(page, options, frameTimeTicks, interval) {
   const client = await getCdpSession(page);
-  const format = options.format === "png" ? "png" : "jpeg";
-  const result = await client.send("HeadlessExperimental.beginFrame", {
-    frameTimeTicks,
-    interval,
-    screenshot: {
-      format,
-      quality: format === "jpeg" ? options.quality ?? 80 : void 0,
-      optimizeForSpeed: true
-    }
-  });
+  const isPng = options.format === "png";
+  const screenshot = {
+    format: isPng ? "png" : "jpeg",
+    quality: isPng ? void 0 : options.quality ?? 80,
+    optimizeForSpeed: true
+  };
+  const result = await sendBeginFrame(client, { frameTimeTicks, interval, screenshot });
   let buffer;
   if (result.screenshotData) {
     buffer = Buffer.from(result.screenshotData, "base64");
@@ -20011,16 +20312,12 @@ async function beginFrameCapture(page, options, frameTimeTicks, interval) {
     if (cached2) {
       buffer = cached2;
     } else {
-      const retry = await client.send("HeadlessExperimental.beginFrame", {
+      const fallback = await sendBeginFrame(client, {
         frameTimeTicks: frameTimeTicks + 1e-3,
         interval,
-        screenshot: {
-          format,
-          quality: format === "jpeg" ? options.quality ?? 80 : void 0,
-          optimizeForSpeed: true
-        }
+        screenshot
       });
-      buffer = retry.screenshotData ? Buffer.from(retry.screenshotData, "base64") : Buffer.alloc(0);
+      buffer = fallback.screenshotData ? Buffer.from(fallback.screenshotData, "base64") : Buffer.alloc(0);
       if (buffer.length > 0) lastFrameCache.set(page, buffer);
     }
   }
@@ -20134,13 +20431,14 @@ async function syncVideoFrameVisibility(page, activeVideoIds) {
     }
   }, activeVideoIds);
 }
-var cdpSessionCache, lastFrameCache;
+var cdpSessionCache, lastFrameCache, PENDING_FRAME_RETRIES;
 var init_screenshotService = __esm({
   "../engine/src/services/screenshotService.ts"() {
     "use strict";
     init_src();
     cdpSessionCache = /* @__PURE__ */ new WeakMap();
     lastFrameCache = /* @__PURE__ */ new WeakMap();
+    PENDING_FRAME_RETRIES = 5;
   }
 });
@@ -20472,7 +20770,7 @@ var init_frameCapture = __esm({
 // ../engine/src/utils/gpuEncoder.ts
 import { spawn as spawn2 } from "child_process";
 async function detectGpuEncoder() {
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const ffmpeg = spawn2("ffmpeg", ["-encoders"], {
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -20481,13 +20779,13 @@ async function detectGpuEncoder() {
       stdout2 += data.toString();
     });
     ffmpeg.on("close", () => {
-      if (stdout2.includes("h264_nvenc")) resolve27("nvenc");
-      else if (stdout2.includes("h264_videotoolbox")) resolve27("videotoolbox");
-      else if (stdout2.includes("h264_vaapi")) resolve27("vaapi");
-      else if (stdout2.includes("h264_qsv")) resolve27("qsv");
-      else resolve27(null);
+      if (stdout2.includes("h264_nvenc")) resolve28("nvenc");
+      else if (stdout2.includes("h264_videotoolbox")) resolve28("videotoolbox");
+      else if (stdout2.includes("h264_vaapi")) resolve28("vaapi");
+      else if (stdout2.includes("h264_qsv")) resolve28("qsv");
+      else resolve28(null);
     });
-    ffmpeg.on("error", () => resolve27(null));
+    ffmpeg.on("error", () => resolve28(null));
   });
 }
 async function getCachedGpuEncoder() {
@@ -20526,7 +20824,7 @@ async function runFfmpeg(args, opts) {
   const signal = opts?.signal;
   const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
   const onStderr = opts?.onStderr;
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const ffmpeg = spawn3("ffmpeg", args);
     let stderr = "";
     const onAbort = () => {
@@ -20552,7 +20850,7 @@ async function runFfmpeg(args, opts) {
     ffmpeg.on("close", (code) => {
       clearTimeout(timer);
       if (signal) signal.removeEventListener("abort", onAbort);
-      resolve27({
+      resolve28({
         success: !signal?.aborted && code === 0,
         exitCode: code,
         stderr,
@@ -20562,7 +20860,7 @@ async function runFfmpeg(args, opts) {
     ffmpeg.on("error", (err) => {
       clearTimeout(timer);
       if (signal) signal.removeEventListener("abort", onAbort);
-      resolve27({
+      resolve28({
         success: false,
         exitCode: null,
         stderr: err.message,
@@ -20721,7 +21019,7 @@ async function encodeFramesFromDir(framesDir, framePattern, outputPath, options,
   const inputPath = join17(framesDir, framePattern);
   const inputArgs = ["-framerate", String(options.fps), "-i", inputPath];
   const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const ffmpeg = spawn4("ffmpeg", args);
     let stderr = "";
     const onAbort = () => {
@@ -20746,7 +21044,7 @@ async function encodeFramesFromDir(framesDir, framePattern, outputPath, options,
       if (signal) signal.removeEventListener("abort", onAbort);
       const durationMs = Date.now() - startTime;
       if (signal?.aborted) {
-        resolve27({
+        resolve28({
           success: false,
           outputPath,
           durationMs,
@@ -20757,7 +21055,7 @@ async function encodeFramesFromDir(framesDir, framePattern, outputPath, options,
         return;
       }
       if (code !== 0) {
-        resolve27({
+        resolve28({
           success: false,
           outputPath,
           durationMs,
@@ -20768,12 +21066,12 @@ async function encodeFramesFromDir(framesDir, framePattern, outputPath, options,
         return;
       }
       const fileSize = existsSync15(outputPath) ? statSync4(outputPath).size : 0;
-      resolve27({ success: true, outputPath, durationMs, framesEncoded: frameCount, fileSize });
+      resolve28({ success: true, outputPath, durationMs, framesEncoded: frameCount, fileSize });
     });
     ffmpeg.on("error", (err) => {
       clearTimeout(timer);
       if (signal) signal.removeEventListener("abort", onAbort);
-      resolve27({
+      resolve28({
         success: false,
         outputPath,
         durationMs: Date.now() - startTime,
@@ -20831,18 +21129,18 @@ async function encodeFramesChunkedConcat(framesDir, framePattern, outputPath, op
     let gpuEncoder = null;
     if (options.useGpu) gpuEncoder = await getCachedGpuEncoder();
     const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder);
-    const chunkResult = await new Promise((resolve27) => {
+    const chunkResult = await new Promise((resolve28) => {
       const ffmpeg = spawn4("ffmpeg", args);
       let stderr = "";
       ffmpeg.stderr.on("data", (d) => {
         stderr += d.toString();
       });
       ffmpeg.on("close", (code) => {
-        if (code === 0) resolve27({ success: true });
-        else resolve27({ success: false, error: `Chunk ${i} encode failed: ${stderr.slice(-400)}` });
+        if (code === 0) resolve28({ success: true });
+        else resolve28({ success: false, error: `Chunk ${i} encode failed: ${stderr.slice(-400)}` });
       });
       ffmpeg.on("error", (err) => {
-        resolve27({ success: false, error: `Chunk ${i} encode error: ${err.message}` });
+        resolve28({ success: false, error: `Chunk ${i} encode error: ${err.message}` });
       });
     });
     if (!chunkResult.success) {
@@ -20872,18 +21170,18 @@ async function encodeFramesChunkedConcat(framesDir, framePattern, outputPath, op
     "-y",
     outputPath
   ];
-  const concatResult = await new Promise((resolve27) => {
+  const concatResult = await new Promise((resolve28) => {
     const ffmpeg = spawn4("ffmpeg", concatArgs);
     let stderr = "";
     ffmpeg.stderr.on("data", (d) => {
       stderr += d.toString();
     });
     ffmpeg.on("close", (code) => {
-      if (code === 0) resolve27({ success: true });
-      else resolve27({ success: false, error: `Chunk concat failed: ${stderr.slice(-400)}` });
+      if (code === 0) resolve28({ success: true });
+      else resolve28({ success: false, error: `Chunk concat failed: ${stderr.slice(-400)}` });
     });
     ffmpeg.on("error", (err) => {
-      resolve27({ success: false, error: `Chunk concat error: ${err.message}` });
+      resolve28({ success: false, error: `Chunk concat error: ${err.message}` });
     });
   });
   if (!concatResult.success) {
@@ -20991,16 +21289,16 @@ function createFrameReorderBuffer(startFrame, endFrame) {
     }
   };
   return {
-    waitForFrame: (frame) => new Promise((resolve27) => {
-      waiters.push({ frame, resolve: resolve27 });
+    waitForFrame: (frame) => new Promise((resolve28) => {
+      waiters.push({ frame, resolve: resolve28 });
       resolveWaiters();
     }),
     advanceTo: (frame) => {
       nextFrame = frame;
       resolveWaiters();
     },
-    waitForAllDone: () => new Promise((resolve27) => {
-      waiters.push({ frame: endFrame, resolve: resolve27 });
+    waitForAllDone: () => new Promise((resolve28) => {
+      waiters.push({ frame: endFrame, resolve: resolve28 });
       resolveWaiters();
     })
   };
@@ -21129,7 +21427,7 @@ async function spawnStreamingEncoder(outputPath, options, signal, config) {
   let stderr = "";
   let exitCode = null;
   let exitPromiseResolve = null;
-  const exitPromise = new Promise((resolve27) => exitPromiseResolve = resolve27);
+  const exitPromise = new Promise((resolve28) => exitPromiseResolve = resolve28);
   ffmpeg.stderr?.on("data", (data) => {
     stderr += data.toString();
   });
@@ -21173,8 +21471,8 @@ Process error: ${err.message}`;
       clearTimeout(timer);
       if (signal) signal.removeEventListener("abort", onAbort);
       if (ffmpeg.stdin && !ffmpeg.stdin.destroyed) {
-        await new Promise((resolve27) => {
-          ffmpeg.stdin.end(() => resolve27());
+        await new Promise((resolve28) => {
+          ffmpeg.stdin.end(() => resolve28());
         });
       }
       await exitPromise;
@@ -21213,7 +21511,7 @@ var init_streamingEncoder = __esm({
 // ../engine/src/utils/ffprobe.ts
 import { spawn as spawn6 } from "child_process";
 function runFfprobe(args) {
-  return new Promise((resolve27, reject) => {
+  return new Promise((resolve28, reject) => {
     const proc = spawn6("ffprobe", args);
     let stdout2 = "";
     let stderr = "";
@@ -21227,7 +21525,7 @@ function runFfprobe(args) {
       if (code !== 0) {
         reject(new Error(`[FFmpeg] ffprobe exited with code ${code}: ${stderr}`));
       } else {
-        resolve27(stdout2);
+        resolve28(stdout2);
       }
     });
     proc.on("error", (err) => {
@@ -21524,7 +21822,7 @@ async function extractVideoFramesRange(videoPath, videoId, startTime, duration,
   ];
   if (format === "png") args.push("-compression_level", "6");
   args.push("-y", outputPattern);
-  return new Promise((resolve27, reject) => {
+  return new Promise((resolve28, reject) => {
     const ffmpeg = spawn7("ffmpeg", args);
     let stderr = "";
     const onAbort = () => {
@@ -21559,7 +21857,7 @@ async function extractVideoFramesRange(videoPath, videoId, startTime, duration,
       files.forEach((file, index) => {
         framePaths.set(index, join19(videoOutputDir, file));
       });
-      resolve27({
+      resolve28({
         videoId,
         srcPath: videoPath,
         outputDir: videoOutputDir,
@@ -21581,7 +21879,7 @@ async function extractVideoFramesRange(videoPath, videoId, startTime, duration,
     });
   });
 }
-async function extractAllVideoFrames(videos, baseDir, options, signal, config) {
+async function extractAllVideoFrames(videos, baseDir, options, signal, config, compiledDir) {
   const startTime = Date.now();
   const extracted = [];
   const errors = [];
@@ -21594,7 +21892,8 @@ async function extractAllVideoFrames(videos, baseDir, options, signal, config) {
       try {
         let videoPath = video.src;
         if (!videoPath.startsWith("/") && !isHttpUrl(videoPath)) {
-          videoPath = join19(baseDir, videoPath);
+          const fromCompiled = compiledDir ? join19(compiledDir, videoPath) : null;
+          videoPath = fromCompiled && existsSync18(fromCompiled) ? fromCompiled : join19(baseDir, videoPath);
         }
         if (isHttpUrl(videoPath)) {
           const downloadDir = join19(options.outputDir, "_downloads");
@@ -22072,7 +22371,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
     tracksProcessed: tracks.length
   };
 }
-async function processCompositionAudio(elements, baseDir, workDir, outputPath, totalDuration, signal, config) {
+async function processCompositionAudio(elements, baseDir, workDir, outputPath, totalDuration, signal, config, compiledDir) {
   const startMs = Date.now();
   const tracks = [];
   const errors = [];
@@ -22086,7 +22385,8 @@ async function processCompositionAudio(elements, baseDir, workDir, outputPath, t
       try {
         let srcPath = element.src;
         if (!srcPath.startsWith("/") && !isHttpUrl(srcPath)) {
-          srcPath = join20(baseDir, srcPath);
+          const fromCompiled = compiledDir ? join20(compiledDir, srcPath) : null;
+          srcPath = fromCompiled && existsSync19(fromCompiled) ? fromCompiled : join20(baseDir, srcPath);
         }
         if (isHttpUrl(srcPath)) {
           try {
@@ -22099,7 +22399,7 @@ async function processCompositionAudio(elements, baseDir, workDir, outputPath, t
           }
         }
         if (!existsSync19(srcPath)) {
-          errors.push(`Source not found: ${element.id}`);
+          errors.push(`Source not found: ${element.id} (${element.src})`);
           return;
         }
         if (element.end - element.start <= 0) {
@@ -22460,11 +22760,11 @@ function createFileServer(options) {
       headers: { "Content-Type": contentType }
     });
   });
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const server = serve({ fetch: app.fetch, port }, (info) => {
       const actualPort = info.port;
       const url = `http://localhost:${actualPort}`;
-      resolve27({
+      resolve28({
         url,
         port: actualPort,
         close: () => server.close()
@@ -22578,9 +22878,9 @@ var init_src2 = __esm({
 });
 // ../core/src/compiler/htmlCompiler.ts
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 function resolveMediaSrc(src, projectDir) {
-  return src.startsWith("http://") || src.startsWith("https://") ? src : resolve7(projectDir, src);
+  return src.startsWith("http://") || src.startsWith("https://") ? src : resolve8(projectDir, src);
 }
 async function compileHtml(rawHtml, projectDir, probeMediaDuration) {
   const { html: staticCompiled, unresolved } = compileTimingAttrs(rawHtml);
@@ -22659,7 +22959,7 @@ var init_staticGuard = __esm({
 // ../core/src/compiler/htmlBundler.ts
 import { readFileSync as readFileSync14, existsSync as existsSync22 } from "fs";
-import { join as join23, resolve as resolve8, isAbsolute, sep as sep2 } from "path";
+import { join as join23, resolve as resolve9, isAbsolute, sep as sep2 } from "path";
 import { transformSync } from "esbuild";
 function parseHTMLContent(html) {
   const trimmed = html.trimStart().toLowerCase();
@@ -22669,9 +22969,9 @@ function parseHTMLContent(html) {
   return parseHTML(`<!DOCTYPE html><html><head></head><body>${html}</body></html>`).document;
 }
 function safePath(projectDir, relativePath) {
-  const resolved = resolve8(projectDir, relativePath);
-  const normalizedBase = resolve8(projectDir) + sep2;
-  if (!resolved.startsWith(normalizedBase) && resolved !== resolve8(projectDir)) return null;
+  const resolved = resolve9(projectDir, relativePath);
+  const normalizedBase = resolve9(projectDir) + sep2;
+  if (!resolved.startsWith(normalizedBase) && resolved !== resolve9(projectDir)) return null;
   return resolved;
 }
 function stripEmbeddedRuntimeScripts2(html) {
@@ -23206,7 +23506,7 @@ var init_compiler = __esm({
 // ../producer/src/services/hyperframeRuntimeLoader.ts
 import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync23, readFileSync as readFileSync15 } from "fs";
-import { dirname as dirname7, resolve as resolve9 } from "path";
+import { dirname as dirname7, resolve as resolve10 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function resolveHyperframeManifestPath() {
   if (process.env.PRODUCER_HYPERFRAME_MANIFEST_PATH) {
@@ -23242,7 +23542,7 @@ function resolveVerifiedHyperframeRuntime() {
       `[HyperframeRuntimeLoader] Invalid manifest at ${manifestPath}; missing iife artifact or sha256.`
     );
   }
-  const runtimePath = resolve9(dirname7(manifestPath), runtimeFileName);
+  const runtimePath = resolve10(dirname7(manifestPath), runtimeFileName);
   if (!existsSync23(runtimePath)) {
     throw new Error(`[HyperframeRuntimeLoader] Missing runtime artifact at ${runtimePath}.`);
   }
@@ -23266,18 +23566,18 @@ var init_hyperframeRuntimeLoader = __esm({
   "../producer/src/services/hyperframeRuntimeLoader.ts"() {
     "use strict";
     PRODUCER_DIR = dirname7(fileURLToPath2(import.meta.url));
-    SIBLING_MANIFEST_PATH = resolve9(PRODUCER_DIR, "hyperframe.manifest.json");
-    MODULE_RELATIVE_MANIFEST_PATH = resolve9(
+    SIBLING_MANIFEST_PATH = resolve10(PRODUCER_DIR, "hyperframe.manifest.json");
+    MODULE_RELATIVE_MANIFEST_PATH = resolve10(
       PRODUCER_DIR,
       "../../../core/dist/hyperframe.manifest.json"
     );
     CWD_RELATIVE_MANIFEST_PATHS = [
       // When bundled to a single file (dist/public-server.js), the manifest
       // is copied as a sibling by build.mjs
-      resolve9(PRODUCER_DIR, "hyperframe.manifest.json"),
-      resolve9(process.cwd(), "packages/core/dist/hyperframe.manifest.json"),
-      resolve9(process.cwd(), "../core/dist/hyperframe.manifest.json"),
-      resolve9(process.cwd(), "core/dist/hyperframe.manifest.json")
+      resolve10(PRODUCER_DIR, "hyperframe.manifest.json"),
+      resolve10(process.cwd(), "packages/core/dist/hyperframe.manifest.json"),
+      resolve10(process.cwd(), "../core/dist/hyperframe.manifest.json"),
+      resolve10(process.cwd(), "core/dist/hyperframe.manifest.json")
     ];
   }
 });
@@ -23380,10 +23680,10 @@ function createFileServer2(options) {
       headers: { "Content-Type": contentType }
     });
   });
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const connections = /* @__PURE__ */ new Set();
     const server = serve2({ fetch: app.fetch, port }, (info) => {
-      resolve27({
+      resolve28({
         url: `http://localhost:${info.port}`,
         port: info.port,
         close: () => {
@@ -23906,7 +24206,7 @@ var init_deterministicFonts = __esm({
 // ../producer/src/services/htmlCompiler.ts
 import { readFileSync as readFileSync17, existsSync as existsSync25, mkdirSync as mkdirSync15 } from "fs";
-import { join as join25, dirname as dirname8, resolve as resolve10 } from "path";
+import { join as join25, dirname as dirname8, resolve as resolve11 } from "path";
 import postcss from "postcss";
 function dedupeElementsById(elements) {
   const deduped = /* @__PURE__ */ new Map();
@@ -23991,7 +24291,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 = resolve10(projectDir, srcPath);
+    const filePath = resolve11(projectDir, srcPath);
     if (visited.has(filePath)) {
       continue;
     }
@@ -24191,7 +24491,7 @@ function inlineSubCompositions(html, subCompositions, projectDir) {
     if (!srcPath) continue;
     let compHtml = subCompositions.get(srcPath) || null;
     if (!compHtml) {
-      const filePath = resolve10(projectDir, srcPath);
+      const filePath = resolve11(projectDir, srcPath);
       if (existsSync25(filePath)) {
         compHtml = readFileSync17(filePath, "utf-8");
       }
@@ -24404,7 +24704,7 @@ ${safeText}
   return result;
 }
 function collectExternalAssets(html, projectDir) {
-  const absProjectDir = resolve10(projectDir);
+  const absProjectDir = resolve11(projectDir);
   const externalAssets = /* @__PURE__ */ new Map();
   const CSS_URL_RE2 = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
   function processPath(rawPath) {
@@ -24412,7 +24712,7 @@ 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 = resolve10(absProjectDir, trimmed);
+    const absPath = resolve11(absProjectDir, trimmed);
     if (absPath.startsWith(absProjectDir + "/") || absPath === absProjectDir) {
       return null;
     }
@@ -24489,7 +24789,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
   const audios = dedupeElementsById([...mainAudios, ...subAudios]);
   for (const video of videos) {
     if (isHttpUrl(video.src)) continue;
-    const videoPath = resolve10(projectDir, video.src);
+    const videoPath = resolve11(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) {
@@ -24682,7 +24982,7 @@ import {
   copyFileSync as copyFileSync2,
   appendFileSync
 } from "fs";
-import { join as join26, dirname as dirname9, resolve as resolve11 } from "path";
+import { join as join26, dirname as dirname9, resolve as resolve12 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 import { freemem as freemem2 } from "os";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -24747,7 +25047,7 @@ function writeCompiledArtifacts(compiled, workDir, includeSummary) {
     writeFileSync8(outPath, html, "utf-8");
   }
   for (const [relativePath, absolutePath] of compiled.externalAssets) {
-    const outPath = resolve11(join26(compileDir, relativePath));
+    const outPath = resolve12(join26(compileDir, relativePath));
     if (!outPath.startsWith(compileDir + "/")) {
       console.warn(`[Render] Skipping external asset with unsafe path: ${relativePath}`);
       continue;
@@ -24820,7 +25120,7 @@ function extractStandaloneEntryFromIndex(indexHtml, entryFile) {
 }
 async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSignal) {
   const moduleDir = dirname9(fileURLToPath3(import.meta.url));
-  const producerRoot = process.env.PRODUCER_RENDERS_DIR ? resolve11(process.env.PRODUCER_RENDERS_DIR, "..") : resolve11(moduleDir, "../..");
+  const producerRoot = process.env.PRODUCER_RENDERS_DIR ? resolve12(process.env.PRODUCER_RENDERS_DIR, "..") : resolve12(moduleDir, "../..");
   const debugDir = join26(producerRoot, ".debug");
   const workDir = job.config.debug ? join26(debugDir, job.id) : join26(dirname9(outputPath), `work-${job.id}`);
   const pipelineStart = Date.now();
@@ -25097,12 +25397,15 @@ 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 = join26(workDir, "compiled");
     if (composition.videos.length > 0) {
       const extractionResult = await extractAllVideoFrames(
         composition.videos,
         projectDir,
         { fps: job.config.fps, outputDir: join26(workDir, "video-frames") },
-        abortSignal
+        abortSignal,
+        void 0,
+        compiledDir
       );
       assertNotAborted();
       if (extractionResult.extracted.length > 0) {
@@ -25142,7 +25445,9 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         join26(workDir, "audio-work"),
         audioOutputPath,
         job.duration,
-        abortSignal
+        abortSignal,
+        void 0,
+        compiledDir
       );
       assertNotAborted();
       hasAudio = audioResult.success;
@@ -25589,7 +25894,7 @@ var init_config3 = __esm({
 // ../producer/src/services/hyperframeLint.ts
 import { existsSync as existsSync27, readFileSync as readFileSync19, statSync as statSync8 } from "fs";
-import { resolve as resolve12, join as join27 } from "path";
+import { resolve as resolve13, join as join27 } from "path";
 function isStringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -25616,7 +25921,7 @@ function pickEntryFile(files, preferredEntryFile) {
   return null;
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
-  const absProjectDir = resolve12(projectDir);
+  const absProjectDir = resolve13(projectDir);
   if (!existsSync27(absProjectDir) || !statSync8(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
@@ -25624,7 +25929,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
     (value) => typeof value === "string" && value.trim().length > 0
   );
   for (const entryFile of entryCandidates) {
-    const absoluteEntryPath = resolve12(absProjectDir, entryFile);
+    const absoluteEntryPath = resolve13(absProjectDir, entryFile);
     if (!absoluteEntryPath.startsWith(absProjectDir)) {
       return { error: `Entry file must stay inside project directory: ${entryFile}` };
     }
@@ -25684,19 +25989,59 @@ var init_hyperframeLint = __esm({
 });
 // ../producer/src/utils/paths.ts
-import { resolve as resolve13, basename, join as join28 } from "path";
+import { resolve as resolve14, basename, join as join28 } from "path";
 function resolveRenderPaths(projectDir, outputPath, rendersDir = DEFAULT_RENDERS_DIR) {
-  const absoluteProjectDir = resolve13(projectDir);
+  const absoluteProjectDir = resolve14(projectDir);
   const projectName = basename(absoluteProjectDir);
   const resolvedOutputPath = outputPath ?? join28(rendersDir, `${projectName}.mp4`);
-  const absoluteOutputPath = resolve13(resolvedOutputPath);
+  const absoluteOutputPath = resolve14(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");
+    DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? resolve14(new URL(import.meta.url).pathname, "../../..", "renders");
+  }
+});
+// ../producer/src/utils/semaphore.ts
+var Semaphore;
+var init_semaphore = __esm({
+  "../producer/src/utils/semaphore.ts"() {
+    "use strict";
+    Semaphore = class {
+      constructor(maxConcurrent) {
+        this.maxConcurrent = maxConcurrent;
+      }
+      queue = [];
+      active = 0;
+      async acquire() {
+        if (this.active < this.maxConcurrent) {
+          this.active++;
+          return () => this.release();
+        }
+        return new Promise((resolve28) => {
+          this.queue.push(() => {
+            this.active++;
+            resolve28(() => this.release());
+          });
+        });
+      }
+      release() {
+        this.active--;
+        const next = this.queue.shift();
+        if (next) next();
+      }
+      /** Current number of active slots. */
+      get activeCount() {
+        return this.active;
+      }
+      /** Number of waiters in the queue. */
+      get waitingCount() {
+        return this.queue.length;
+      }
+    };
   }
 });
@@ -25710,7 +26055,7 @@ import {
   rmSync as rmSync7,
   createReadStream
 } from "fs";
-import { resolve as resolve14, dirname as dirname10, join as join29 } from "path";
+import { resolve as resolve15, dirname as dirname10, join as join29 } from "path";
 import { tmpdir as tmpdir2 } from "os";
 import { parseArgs as parseArgs2 } from "util";
 import crypto from "crypto";
@@ -25732,12 +26077,12 @@ async function prepareRenderBody(body) {
   const options = parseRenderOptions(body);
   const projectDir = typeof body.projectDir === "string" ? body.projectDir : void 0;
   if (projectDir) {
-    const absProjectDir = resolve14(projectDir);
+    const absProjectDir = resolve15(projectDir);
     if (!existsSync28(absProjectDir) || !statSync9(absProjectDir).isDirectory()) {
       return { error: `Project directory not found: ${absProjectDir}` };
     }
     const entry = options.entryFile || "index.html";
-    if (!existsSync28(resolve14(absProjectDir, entry))) {
+    if (!existsSync28(resolve15(absProjectDir, entry))) {
       return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
     }
     return { prepared: { input: { projectDir: absProjectDir, ...options } } };
@@ -25778,7 +26123,7 @@ function resolveOutputPath(projectDir, outputCandidate, rendersDir, log) {
   try {
     return resolveRenderPaths(projectDir, outputCandidate, rendersDir).absoluteOutputPath;
   } catch (error) {
-    const fallbackPath = resolve14(rendersDir, `producer-fallback-${Date.now()}.mp4`);
+    const fallbackPath = resolve15(rendersDir, `producer-fallback-${Date.now()}.mp4`);
     log.warn("Failed to resolve output path, using fallback", {
       fallback: fallbackPath,
       error: error instanceof Error ? error.message : String(error)
@@ -25829,6 +26174,8 @@ function createRenderHandlers(options = {}) {
   const rendersDir = options.rendersDir ?? process.env.PRODUCER_RENDERS_DIR ?? "/tmp";
   const artifactTtlMs = options.artifactTtlMs ?? Number(process.env.PRODUCER_OUTPUT_ARTIFACT_TTL_MS || 15 * 60 * 1e3);
   const store = createArtifactStore(artifactTtlMs);
+  const maxConcurrentRenders = options.maxConcurrentRenders ?? Number(process.env.PRODUCER_MAX_CONCURRENT_RENDERS || 2);
+  const renderSemaphore = new Semaphore(maxConcurrentRenders);
   const startTime = Date.now();
   const health = (c2) => c2.json({
     status: "ok",
@@ -25885,6 +26232,7 @@ function createRenderHandlers(options = {}) {
     );
     const outputDir = dirname10(absoluteOutputPath);
     if (!existsSync28(outputDir)) mkdirSync17(outputDir, { recursive: true });
+    const release2 = await renderSemaphore.acquire();
     log.info("render started", {
       requestId,
       projectDir: input.projectDir,
@@ -25952,6 +26300,7 @@ function createRenderHandlers(options = {}) {
         500
       );
     } finally {
+      release2();
       cleanupTempDir(cleanupProjectDir, log);
     }
   };
@@ -26008,6 +26357,16 @@ function createRenderHandlers(options = {}) {
       const abortController = new AbortController();
       const onRequestAbort = () => abortController.abort(new RenderCancelledError("request_aborted"));
       c2.req.raw.signal.addEventListener("abort", onRequestAbort, { once: true });
+      if (renderSemaphore.activeCount >= maxConcurrentRenders) {
+        await stream.writeSSE({
+          data: JSON.stringify({
+            type: "queued",
+            requestId,
+            position: renderSemaphore.waitingCount
+          })
+        });
+      }
+      const release2 = await renderSemaphore.acquire();
       try {
         await executeRenderJob(
           job,
@@ -26075,6 +26434,7 @@ function createRenderHandlers(options = {}) {
           })
         });
       } finally {
+        release2();
         c2.req.raw.signal.removeEventListener("abort", onRequestAbort);
         cleanupTempDir(cleanupProjectDir, log);
       }
@@ -26099,7 +26459,12 @@ function createRenderHandlers(options = {}) {
       }
     });
   };
-  return { render: render2, renderStream, lint, health, outputs };
+  const queue = (c2) => c2.json({
+    maxConcurrentRenders,
+    activeRenders: renderSemaphore.activeCount,
+    queuedRenders: renderSemaphore.waitingCount
+  });
+  return { render: render2, renderStream, lint, health, outputs, queue };
 }
 function createProducerApp(options = {}) {
   const app = new Hono4();
@@ -26107,6 +26472,7 @@ function createProducerApp(options = {}) {
   app.get("/health", handlers.health);
   app.post("/render", handlers.render);
   app.post("/render/stream", handlers.renderStream);
+  app.get("/render/queue", handlers.queue);
   app.post("/lint", handlers.lint);
   app.get("/outputs/:token", handlers.outputs);
   return app;
@@ -26144,7 +26510,8 @@ var init_server = __esm({
     init_hyperframeLint();
     init_paths();
     init_logger();
-    entryScript = process.argv[1] ? resolve14(process.argv[1]) : "";
+    init_semaphore();
+    entryScript = process.argv[1] ? resolve15(process.argv[1]) : "";
     isPublicServerEntry = entryScript.endsWith("/public-server.js") || entryScript.endsWith("/src/server.ts");
     if (isPublicServerEntry) {
       const { values } = parseArgs2({
@@ -26217,18 +26584,18 @@ __export(studioServer_exports, {
 import { Hono as Hono5 } from "hono";
 import { streamSSE as streamSSE3 } from "hono/streaming";
 import { existsSync as existsSync29, readFileSync as readFileSync20, writeFileSync as writeFileSync10, statSync as statSync10 } from "fs";
-import { resolve as resolve15, join as join30, basename as basename2 } from "path";
+import { resolve as resolve16, join as join30, basename as basename2 } from "path";
 function resolveDistDir() {
-  const builtPath = resolve15(__dirname, "studio");
-  if (existsSync29(resolve15(builtPath, "index.html"))) return builtPath;
-  const devPath = resolve15(__dirname, "..", "..", "..", "studio", "dist");
-  if (existsSync29(resolve15(devPath, "index.html"))) return devPath;
+  const builtPath = resolve16(__dirname, "studio");
+  if (existsSync29(resolve16(builtPath, "index.html"))) return builtPath;
+  const devPath = resolve16(__dirname, "..", "..", "..", "studio", "dist");
+  if (existsSync29(resolve16(devPath, "index.html"))) return devPath;
   return builtPath;
 }
 function resolveRuntimePath() {
-  const builtPath = resolve15(__dirname, "hyperframe-runtime.js");
+  const builtPath = resolve16(__dirname, "hyperframe-runtime.js");
   if (existsSync29(builtPath)) return builtPath;
-  const devPath = resolve15(
+  const devPath = resolve16(
     __dirname,
     "..",
     "..",
@@ -26379,6 +26746,14 @@ function createStudioServer(options) {
     }
   };
   const app = new Hono5();
+  app.get("/__hyperframes_config", (c2) => {
+    return c2.json({
+      isHyperframes: true,
+      projectName: projectId,
+      projectDir,
+      version: VERSION
+    });
+  });
   app.get("/api/runtime.js", (c2) => {
     if (!existsSync29(runtimePath)) return c2.text("runtime not built", 404);
     return c2.body(readFileSync20(runtimePath, "utf-8"), 200, {
@@ -26412,7 +26787,7 @@ function createStudioServer(options) {
     return api.fetch(forwardReq);
   });
   app.get("/assets/*", (c2) => {
-    const filePath = resolve15(studioDir, c2.req.path.slice(1));
+    const filePath = resolve16(studioDir, c2.req.path.slice(1));
     if (!existsSync29(filePath) || !statSync10(filePath).isFile()) return c2.text("not found", 404);
     const content = readFileSync20(filePath);
     return new Response(content, {
@@ -26420,7 +26795,7 @@ function createStudioServer(options) {
     });
   });
   app.get("/icons/*", (c2) => {
-    const filePath = resolve15(studioDir, c2.req.path.slice(1));
+    const filePath = resolve16(studioDir, c2.req.path.slice(1));
     if (!existsSync29(filePath) || !statSync10(filePath).isFile()) return c2.text("not found", 404);
     const content = readFileSync20(filePath);
     return new Response(content, {
@@ -26428,7 +26803,7 @@ function createStudioServer(options) {
     });
   });
   app.get("*", (c2) => {
-    const indexPath = resolve15(studioDir, "index.html");
+    const indexPath = resolve16(studioDir, "index.html");
     if (!existsSync29(indexPath)) {
       return c2.text("Studio not found. Rebuild with: pnpm run build", 500);
     }
@@ -26441,6 +26816,7 @@ var init_studioServer = __esm({
   "src/server/studioServer.ts"() {
     "use strict";
     init_fileWatcher();
+    init_version();
     init_studio_api();
     _thumbnailBrowser = null;
     _thumbnailBrowserInitializing = null;
@@ -26455,45 +26831,12 @@ __export(preview_exports, {
 });
 import { spawn as spawn8 } from "child_process";
 import { existsSync as existsSync30, lstatSync, symlinkSync, unlinkSync as unlinkSync5, readlinkSync, mkdirSync as mkdirSync18 } from "fs";
-import { resolve as resolve16, dirname as dirname11, basename as basename3, join as join31 } from "path";
+import { resolve as resolve17, dirname as dirname11, basename as basename3, join as join31 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { createRequire } from "module";
-async function serveWithPortFallback(fetch3, startPort, maxAttempts = 10) {
-  const { createAdaptorServer } = await import("@hono/node-server");
-  const server = createAdaptorServer({ fetch: fetch3 });
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const port = startPort + attempt;
-    try {
-      await new Promise((resolveListener, rejectListener) => {
-        const onError = (err) => {
-          server.removeListener("listening", onListening);
-          rejectListener(err);
-        };
-        const onListening = () => {
-          server.removeListener("error", onError);
-          resolveListener();
-        };
-        server.once("error", onError);
-        server.once("listening", onListening);
-        server.listen(port);
-      });
-      return { server, port };
-    } catch (err) {
-      const code = err.code;
-      if (code === "EADDRINUSE") {
-        continue;
-      }
-      throw err;
-    }
-  }
-  const lastPort = startPort + maxAttempts - 1;
-  throw new Error(
-    `Ports ${startPort}\u2013${lastPort} are all in use. Use --port to specify a different port.`
-  );
-}
 async function runDevMode(dir, projectName) {
   const thisFile = fileURLToPath4(import.meta.url);
-  const repoRoot = resolve16(dirname11(thisFile), "..", "..", "..", "..");
+  const repoRoot = resolve17(dirname11(thisFile), "..", "..", "..", "..");
   const projectsDir = join31(repoRoot, "packages", "studio", "data", "projects");
   const pName = projectName ?? basename3(dir);
   const symlinkPath = join31(projectsDir, pName);
@@ -26505,7 +26848,7 @@ async function runDevMode(dir, projectName) {
         const stat = lstatSync(symlinkPath);
         if (stat.isSymbolicLink()) {
           const target = readlinkSync(symlinkPath);
-          if (resolve16(target) !== resolve16(dir)) {
+          if (resolve17(target) !== resolve17(dir)) {
             unlinkSync5(symlinkPath);
           }
         }
@@ -26559,8 +26902,8 @@ async function runDevMode(dir, projectName) {
       }
     });
   }
-  return new Promise((resolve27) => {
-    child.on("close", () => resolve27());
+  return new Promise((resolve28) => {
+    child.on("close", () => resolve28());
   });
 }
 function hasLocalStudio(dir) {
@@ -26582,7 +26925,7 @@ async function runLocalStudioMode(dir, projectName) {
   let createdSymlink = false;
   if (dir !== symlinkPath) {
     if (existsSync30(symlinkPath) && lstatSync(symlinkPath).isSymbolicLink()) {
-      if (resolve16(readlinkSync(symlinkPath)) !== resolve16(dir)) {
+      if (resolve17(readlinkSync(symlinkPath)) !== resolve17(dir)) {
         unlinkSync5(symlinkPath);
       }
     }
@@ -26630,20 +26973,20 @@ async function runLocalStudioMode(dir, projectName) {
       }
     });
   }
-  return new Promise((resolve27) => {
-    child.on("close", () => resolve27());
+  return new Promise((resolve28) => {
+    child.on("close", () => resolve28());
   });
 }
-async function runEmbeddedMode(dir, startPort, projectName) {
+async function runEmbeddedMode(dir, startPort, projectName, forceNew = false) {
   const { createStudioServer: createStudioServer2 } = await Promise.resolve().then(() => (init_studioServer(), studioServer_exports));
   const pName = projectName ?? basename3(dir);
   const { app } = createStudioServer2({ projectDir: dir, projectName: pName });
   Wt2(c.bold("hyperframes preview"));
   const s = be();
   s.start("Starting studio...");
-  let actualPort;
+  let result;
   try {
-    ({ port: actualPort } = await serveWithPortFallback(app.fetch, startPort));
+    result = await findPortAndServe(app.fetch, startPort, dir, forceNew);
   } catch (err) {
     s.stop(c.error("Failed to start studio"));
     console.error();
@@ -26652,11 +26995,26 @@ async function runEmbeddedMode(dir, startPort, projectName) {
     process.exitCode = 1;
     return;
   }
-  const url = `http://localhost:${actualPort}`;
+  if (result.type === "already-running") {
+    const url2 = `http://localhost:${result.port}`;
+    s.stop(c.success("Already running"));
+    console.log();
+    console.log(`  ${c.dim("Project")}   ${c.accent(pName)}`);
+    console.log(`  ${c.dim("Studio")}    ${c.accent(url2)}`);
+    console.log();
+    console.log(
+      `  ${c.dim("Reusing existing server. Use --force-new to start a fresh instance.")}`
+    );
+    console.log();
+    import("open").then((mod) => mod.default(`${url2}#project/${pName}`)).catch(() => {
+    });
+    return;
+  }
+  const url = `http://localhost:${result.port}`;
   s.stop(c.success("Studio running"));
   console.log();
-  if (actualPort !== startPort) {
-    console.log(`  ${c.warn(`Port ${startPort} is in use, using ${actualPort} instead`)}`);
+  if (result.port !== startPort) {
+    console.log(`  ${c.warn(`Port ${startPort} is in use, using ${result.port} instead`)}`);
     console.log();
   }
   console.log(`  ${c.dim("Project")}   ${c.accent(pName)}`);
@@ -26682,21 +27040,72 @@ var init_preview2 = __esm({
     init_env();
     init_lintProject();
     init_lintFormat();
+    init_portUtils();
     examples = [
       ["Preview the current project", "hyperframes preview"],
       ["Preview a specific project directory", "hyperframes preview ./my-video"],
-      ["Use a custom port", "hyperframes preview --port 8080"]
+      ["Use a custom port", "hyperframes preview --port 8080"],
+      ["Force a new server even if one is already running", "hyperframes preview --force-new"],
+      ["List all active preview servers", "hyperframes preview --list"],
+      ["Kill all active preview servers", "hyperframes preview --kill-all"]
     ];
     preview_default = defineCommand({
       meta: { name: "preview", description: "Start the studio for previewing compositions" },
       args: {
         dir: { type: "positional", description: "Project directory", required: false },
-        port: { type: "string", description: "Port to run the preview server on", default: "3002" }
+        port: { type: "string", description: "Port to run the preview server on", default: "3002" },
+        "force-new": {
+          type: "boolean",
+          description: "Start a new server even if one is already running for this project",
+          default: false
+        },
+        list: {
+          type: "boolean",
+          description: "List all active preview servers and exit",
+          default: false
+        },
+        "kill-all": {
+          type: "boolean",
+          description: "Kill all active preview servers and exit",
+          default: false
+        }
       },
       async run({ args }) {
-        const rawArg = args.dir;
-        const dir = resolve16(rawArg ?? ".");
         const startPort = parseInt(args.port ?? "3002", 10);
+        if (args.list) {
+          const servers = await scanActiveServers(startPort);
+          if (servers.length === 0) {
+            console.log("\n  No active preview servers found.\n");
+            return;
+          }
+          console.log(`
+  ${c.bold("Active preview servers:")}
+`);
+          for (const s of servers) {
+            const pidStr = s.pid ? c.dim(` (PID ${s.pid})`) : "";
+            console.log(
+              `  ${c.accent(`Port ${s.port}`)}  ${s.projectName}  ${c.dim(s.projectDir)}${pidStr}`
+            );
+          }
+          console.log(`
+  ${servers.length} server${servers.length === 1 ? "" : "s"} running.
+`);
+          return;
+        }
+        if (args["kill-all"]) {
+          const servers = await scanActiveServers(startPort);
+          if (servers.length === 0) {
+            console.log("\n  No active preview servers to kill.\n");
+            return;
+          }
+          const killed = await killActiveServers(startPort);
+          console.log(`
+  Killed ${killed} preview server${killed === 1 ? "" : "s"}.
+`);
+          return;
+        }
+        const rawArg = args.dir;
+        const dir = resolve17(rawArg ?? ".");
         const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
         const projectName = isImplicitCwd ? basename3(process.env.PWD ?? dir) : basename3(dir);
         const indexPath = join31(dir, "index.html");
@@ -26715,7 +27124,8 @@ var init_preview2 = __esm({
         if (hasLocalStudio(dir)) {
           return runLocalStudioMode(dir, projectName);
         }
-        return runEmbeddedMode(dir, startPort, projectName);
+        const forceNew = !!args["force-new"];
+        return runEmbeddedMode(dir, startPort, projectName, forceNew);
       }
     });
   }
@@ -26736,7 +27146,7 @@ import {
   readFileSync as readFileSync21,
   readdirSync as readdirSync10
 } from "fs";
-import { resolve as resolve17, basename as basename4, join as join32, dirname as dirname12 } from "path";
+import { resolve as resolve18, basename as basename4, join as join32, dirname as dirname12 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { execFileSync as execFileSync4, spawn as spawn9 } from "child_process";
 function probeVideo(filePath) {
@@ -26806,8 +27216,8 @@ function transcodeToMp4(inputPath, outputPath) {
 }
 function resolveAssetDir(devSegments, builtSegments) {
   const base = dirname12(fileURLToPath5(import.meta.url));
-  const devPath = resolve17(base, ...devSegments);
-  const builtPath = resolve17(base, ...builtSegments);
+  const devPath = resolve18(base, ...devSegments);
+  const builtPath = resolve18(base, ...builtSegments);
   return existsSync31(devPath) ? devPath : builtPath;
 }
 function getStaticTemplateDir(templateId) {
@@ -26892,7 +27302,7 @@ async function handleVideoFile(videoPath, destDir, interactive) {
       }
       if (shouldTranscode) {
         const mp4Name = localVideoName.replace(/\.[^.]+$/, ".mp4");
-        const mp4Path = resolve17(destDir, mp4Name);
+        const mp4Path = resolve18(destDir, mp4Name);
         const spin = be();
         spin.start("Transcoding to H.264 MP4...");
         const ok = await transcodeToMp4(videoPath, mp4Path);
@@ -26901,10 +27311,10 @@ async function handleVideoFile(videoPath, destDir, interactive) {
           localVideoName = mp4Name;
         } else {
           spin.stop(c.warn("Transcode failed \u2014 copying original file"));
-          copyFileSync3(videoPath, resolve17(destDir, localVideoName));
+          copyFileSync3(videoPath, resolve18(destDir, localVideoName));
         }
       } else {
-        copyFileSync3(videoPath, resolve17(destDir, localVideoName));
+        copyFileSync3(videoPath, resolve18(destDir, localVideoName));
       }
     } else {
       if (interactive) {
@@ -26914,10 +27324,10 @@ async function handleVideoFile(videoPath, destDir, interactive) {
         console.log(c.warn("ffmpeg not installed \u2014 cannot transcode. Copying original."));
         console.log(c.dim("Install: ") + c.accent("brew install ffmpeg"));
       }
-      copyFileSync3(videoPath, resolve17(destDir, localVideoName));
+      copyFileSync3(videoPath, resolve18(destDir, localVideoName));
     }
   } else {
-    copyFileSync3(videoPath, resolve17(destDir, localVideoName));
+    copyFileSync3(videoPath, resolve18(destDir, localVideoName));
   }
   return { meta, localVideoName };
 }
@@ -26931,7 +27341,7 @@ async function scaffoldProject(destDir, name, templateId, localVideoName, durati
   }
   patchVideoSrc(destDir, localVideoName, durationSeconds);
   writeFileSync11(
-    resolve17(destDir, "meta.json"),
+    resolve18(destDir, "meta.json"),
     JSON.stringify(
       {
         id: name,
@@ -26947,7 +27357,7 @@ async function scaffoldProject(destDir, name, templateId, localVideoName, durati
   if (existsSync31(sharedDir)) {
     for (const entry of readdirSync10(sharedDir, { withFileTypes: true })) {
       const src = join32(sharedDir, entry.name);
-      const dest = resolve17(destDir, entry.name);
+      const dest = resolve18(destDir, entry.name);
       if (entry.isFile() || entry.isSymbolicLink()) {
         copyFileSync3(src, dest);
       }
@@ -27039,7 +27449,7 @@ var init_init = __esm({
         if (!interactive) {
           const templateId2 = templateFlag ?? "blank";
           const name2 = args.name ?? "my-video";
-          const destDir2 = resolve17(name2);
+          const destDir2 = resolve18(name2);
           if (existsSync31(destDir2) && readdirSync10(destDir2).length > 0) {
             console.error(c.error(`Directory already exists and is not empty: ${name2}`));
             process.exit(1);
@@ -27053,7 +27463,7 @@ var init_init = __esm({
             process.exit(1);
           }
           if (videoFlag) {
-            const videoPath = resolve17(videoFlag);
+            const videoPath = resolve18(videoFlag);
             if (!existsSync31(videoPath)) {
               console.error(c.error(`Video file not found: ${videoFlag}`));
               process.exit(1);
@@ -27067,13 +27477,13 @@ var init_init = __esm({
             );
           }
           if (audioFlag) {
-            const audioPath = resolve17(audioFlag);
+            const audioPath = resolve18(audioFlag);
             if (!existsSync31(audioPath)) {
               console.error(c.error(`Audio file not found: ${audioFlag}`));
               process.exit(1);
             }
             sourceFilePath2 = audioPath;
-            copyFileSync3(audioPath, resolve17(destDir2, basename4(audioPath)));
+            copyFileSync3(audioPath, resolve18(destDir2, basename4(audioPath)));
             console.log(`Audio: ${basename4(audioPath)}`);
           }
           if (sourceFilePath2 && !skipTranscribe) {
@@ -27113,7 +27523,7 @@ var init_init = __esm({
             process.exit(1);
           }
           trackInitTemplate(templateId2);
-          const transcriptFile2 = resolve17(destDir2, "transcript.json");
+          const transcriptFile2 = resolve18(destDir2, "transcript.json");
           if (existsSync31(transcriptFile2)) {
             await patchTranscript(destDir2, transcriptFile2);
           }
@@ -27159,7 +27569,7 @@ var init_init = __esm({
           }
           name = nameResult;
         }
-        const destDir = resolve17(name);
+        const destDir = resolve18(name);
         if (existsSync31(destDir) && readdirSync10(destDir).length > 0) {
           const overwrite = await Rt({
             message: `Directory ${c.accent(name)} already exists and is not empty. Overwrite?`,
@@ -27174,7 +27584,7 @@ var init_init = __esm({
         let sourceFilePath;
         let videoDuration;
         if (videoFlag) {
-          const videoPath = resolve17(videoFlag);
+          const videoPath = resolve18(videoFlag);
           if (!existsSync31(videoPath)) {
             R2.error(`File not found: ${videoFlag}`);
             Nt("Setup cancelled.");
@@ -27186,7 +27596,7 @@ var init_init = __esm({
           localVideoName = result.localVideoName;
           videoDuration = result.meta.durationSeconds;
         } else if (audioFlag) {
-          const audioPath = resolve17(audioFlag);
+          const audioPath = resolve18(audioFlag);
           if (!existsSync31(audioPath)) {
             R2.error(`File not found: ${audioFlag}`);
             Nt("Setup cancelled.");
@@ -27194,7 +27604,7 @@ var init_init = __esm({
           }
           mkdirSync19(destDir, { recursive: true });
           sourceFilePath = audioPath;
-          copyFileSync3(audioPath, resolve17(destDir, basename4(audioPath)));
+          copyFileSync3(audioPath, resolve18(destDir, basename4(audioPath)));
           R2.info(`Audio copied to ${c.accent(basename4(audioPath))}`);
         }
         if (sourceFilePath) {
@@ -27279,7 +27689,7 @@ ${c.dim("Use --template blank for offline use.")}`
           process.exit(1);
         }
         trackInitTemplate(templateId);
-        const transcriptFile = resolve17(destDir, "transcript.json");
+        const transcriptFile = resolve18(destDir, "transcript.json");
         if (existsSync31(transcriptFile)) {
           await patchTranscript(destDir, transcriptFile);
         }
@@ -27344,11 +27754,11 @@ var init_format = __esm({
 // src/utils/project.ts
 import { existsSync as existsSync32, statSync as statSync11 } from "fs";
-import { resolve as resolve18, basename as basename5 } from "path";
+import { resolve as resolve19, basename as basename5 } from "path";
 function resolveProject(dirArg) {
-  const dir = resolve18(dirArg ?? ".");
+  const dir = resolve19(dirArg ?? ".");
   const name = basename5(dir);
-  const indexPath = resolve18(dir, "index.html");
+  const indexPath = resolve19(dir, "index.html");
   if (!existsSync32(dir) || !statSync11(dir).isDirectory()) {
     errorBox("Not a directory: " + dir);
     process.exit(1);
@@ -27377,7 +27787,7 @@ __export(play_exports, {
   examples: () => examples3
 });
 import { existsSync as existsSync33, readFileSync as readFileSync22 } from "fs";
-import { resolve as resolve19, dirname as dirname13 } from "path";
+import { resolve as resolve20, dirname as dirname13 } from "path";
 function commandDir() {
   return dirname13(new URL(import.meta.url).pathname);
 }
@@ -27385,10 +27795,10 @@ function resolveRuntimePath2() {
   const d = commandDir();
   const candidates = [
     // Bundled with CLI dist
-    resolve19(d, "hyperframe-runtime.js"),
-    resolve19(d, "..", "hyperframe-runtime.js"),
+    resolve20(d, "hyperframe-runtime.js"),
+    resolve20(d, "..", "hyperframe-runtime.js"),
     // Monorepo dev: commands/ → src/ → cli/ → packages/ then into core/dist/
-    resolve19(d, "..", "..", "..", "core", "dist", "hyperframe.runtime.iife.js")
+    resolve20(d, "..", "..", "..", "core", "dist", "hyperframe.runtime.iife.js")
   ];
   for (const p of candidates) {
     if (existsSync33(p)) return p;
@@ -27399,10 +27809,10 @@ function resolvePlayerPath() {
   const d = commandDir();
   const candidates = [
     // Monorepo dev: commands/ → src/ → cli/ → packages/ then into player/dist/
-    resolve19(d, "..", "..", "..", "player", "dist", "hyperframes-player.global.js"),
+    resolve20(d, "..", "..", "..", "player", "dist", "hyperframes-player.global.js"),
     // Bundled with CLI dist
-    resolve19(d, "hyperframes-player.global.js"),
-    resolve19(d, "..", "hyperframes-player.global.js")
+    resolve20(d, "hyperframes-player.global.js"),
+    resolve20(d, "..", "hyperframes-player.global.js")
   ];
   for (const p of candidates) {
     if (existsSync33(p)) return p;
@@ -27505,7 +27915,7 @@ var init_play = __esm({
         });
         app.get("/composition/*", async (ctx) => {
           const reqPath = ctx.req.path.replace("/composition/", "");
-          const filePath = resolve19(project.dir, reqPath);
+          const filePath = resolve20(project.dir, reqPath);
           if (!filePath.startsWith(project.dir)) return ctx.text("Forbidden", 403);
           if (!existsSync33(filePath)) return ctx.text("Not found", 404);
           const content = readFileSync22(filePath, "utf-8");
@@ -27657,7 +28067,7 @@ __export(render_exports, {
 });
 import { mkdirSync as mkdirSync20, readFileSync as readFileSync23, statSync as statSync12, writeFileSync as writeFileSync12, rmSync as rmSync8 } from "fs";
 import { cpus as cpus3, freemem as freemem3, tmpdir as tmpdir3 } from "os";
-import { resolve as resolve20, dirname as dirname14, join as join33, basename as basename6 } from "path";
+import { resolve as resolve21, dirname as dirname14, join as join33, basename as basename6 } from "path";
 import { execFileSync as execFileSync5, spawn as spawn10 } from "child_process";
 function defaultWorkerCount() {
   return Math.max(1, Math.min(Math.floor(CPU_CORE_COUNT * 3 / 4), 8));
@@ -27666,8 +28076,8 @@ function dockerImageTag(version) {
   return `${DOCKER_IMAGE_PREFIX}:${version}`;
 }
 function resolveDockerfilePath() {
-  const builtPath = resolve20(__dirname, "docker", "Dockerfile.render");
-  const devPath = resolve20(__dirname, "..", "src", "docker", "Dockerfile.render");
+  const builtPath = resolve21(__dirname, "docker", "Dockerfile.render");
+  const devPath = resolve21(__dirname, "..", "src", "docker", "Dockerfile.render");
   for (const p of [builtPath, devPath]) {
     try {
       statSync12(p);
@@ -27751,9 +28161,9 @@ async function renderDocker(projectDir, outputPath, options) {
     // GPU encoding requires host GPU passthrough
     ...options.gpu ? ["--gpus", "all"] : [],
     "-v",
-    `${resolve20(projectDir)}:/project:ro`,
+    `${resolve21(projectDir)}:/project:ro`,
     "-v",
-    `${resolve20(outputDir)}:/output`,
+    `${resolve21(outputDir)}:/output`,
     imageTag,
     "/project",
     "--output",
@@ -27962,6 +28372,10 @@ var init_render2 = __esm({
           type: "boolean",
           description: "Fail render on lint errors AND warnings",
           default: false
+        },
+        "max-concurrent-renders": {
+          type: "string",
+          description: "Max concurrent renders when using the producer server (1-10). Default: 2."
         }
       },
       async run({ args }) {
@@ -27993,12 +28407,23 @@ var init_render2 = __esm({
           }
           workers = parsed;
         }
-        const rendersDir = resolve20("renders");
+        if (args["max-concurrent-renders"] != null) {
+          const parsed = parseInt(args["max-concurrent-renders"], 10);
+          if (isNaN(parsed) || parsed < 1 || parsed > 10) {
+            errorBox(
+              "Invalid max-concurrent-renders",
+              `Got "${args["max-concurrent-renders"]}". Must be a number between 1 and 10.`
+            );
+            process.exit(1);
+          }
+          process.env.PRODUCER_MAX_CONCURRENT_RENDERS = String(parsed);
+        }
+        const rendersDir = resolve21("renders");
         const ext = FORMAT_EXT[format] ?? ".mp4";
         const now = /* @__PURE__ */ new Date();
         const datePart = now.toISOString().slice(0, 10);
         const timePart = now.toTimeString().slice(0, 8).replace(/:/g, "-");
-        const outputPath = args.output ? resolve20(args.output) : join33(rendersDir, `${project.name}_${datePart}_${timePart}${ext}`);
+        const outputPath = args.output ? resolve21(args.output) : join33(rendersDir, `${project.name}_${datePart}_${timePart}${ext}`);
         mkdirSync20(dirname14(outputPath), { recursive: true });
         const useDocker = args.docker ?? false;
         const useGpu = args.gpu ?? false;
@@ -28412,7 +28837,7 @@ __export(compositions_exports, {
   examples: () => examples7
 });
 import { existsSync as existsSync34, readFileSync as readFileSync25 } from "fs";
-import { resolve as resolve21, dirname as dirname15 } from "path";
+import { resolve as resolve22, dirname as dirname15 } from "path";
 function parseCompositions(html, baseDir) {
   const parser = new DOMParser();
   const doc = parser.parseFromString(html, "text/html");
@@ -28424,7 +28849,7 @@ function parseCompositions(html, baseDir) {
     const height = parseInt(div.getAttribute("data-height") ?? "1080", 10);
     const compositionSrc = div.getAttribute("data-composition-src");
     if (compositionSrc) {
-      const subPath = resolve21(baseDir, compositionSrc);
+      const subPath = resolve22(baseDir, compositionSrc);
       if (existsSync34(subPath)) {
         const subHtml = readFileSync25(subPath, "utf-8");
         const subInfo = parseSubComposition(subHtml, id, width, height);
@@ -28559,7 +28984,7 @@ __export(benchmark_exports, {
   examples: () => examples8
 });
 import { existsSync as existsSync35, statSync as statSync14 } from "fs";
-import { resolve as resolve22, join as join35 } from "path";
+import { resolve as resolve23, join as join35 } from "path";
 var examples8, DEFAULT_CONFIGS, benchmark_default;
 var init_benchmark = __esm({
   "src/commands/benchmark.ts"() {
@@ -28601,7 +29026,7 @@ var init_benchmark = __esm({
           process.exit(1);
         }
         const jsonOutput = args.json ?? false;
-        const benchDir = resolve22("renders", ".benchmark");
+        const benchDir = resolve23("renders", ".benchmark");
         let producer = null;
         try {
           producer = await loadProducer();
@@ -28865,7 +29290,7 @@ __export(transcribe_exports2, {
   examples: () => examples10
 });
 import { existsSync as existsSync36, writeFileSync as writeFileSync13 } from "fs";
-import { resolve as resolve23, join as join36, extname as extname7 } from "path";
+import { resolve as resolve24, join as join36, extname as extname7 } from "path";
 async function importTranscript(inputPath, dir, json) {
   const { loadTranscript: loadTranscript2, patchCaptionHtml: patchCaptionHtml2 } = await Promise.resolve().then(() => (init_normalize(), normalize_exports));
   const { words, format } = loadTranscript2(inputPath);
@@ -28989,12 +29414,12 @@ var init_transcribe2 = __esm({
         }
       },
       async run({ args }) {
-        const inputPath = resolve23(args.input);
+        const inputPath = resolve24(args.input);
         if (!existsSync36(inputPath)) {
           console.error(c.error(`File not found: ${args.input}`));
           process.exit(1);
         }
-        const dir = resolve23(args.dir ?? ".");
+        const dir = resolve24(args.dir ?? ".");
         const ext = extname7(inputPath).toLowerCase();
         const isImport = ext === ".json" || ext === ".srt" || ext === ".vtt";
         if (isImport) {
@@ -29217,7 +29642,7 @@ __export(tts_exports, {
   examples: () => examples11
 });
 import { existsSync as existsSync39, readFileSync as readFileSync26 } from "fs";
-import { resolve as resolve24, extname as extname8 } from "path";
+import { resolve as resolve25, extname as extname8 } from "path";
 function listVoices(json) {
   if (json) {
     console.log(JSON.stringify(BUNDLED_VOICES));
@@ -29305,7 +29730,7 @@ var init_tts = __esm({
           process.exit(1);
         }
         let text;
-        const maybeFile = resolve24(args.input);
+        const maybeFile = resolve25(args.input);
         if (existsSync39(maybeFile) && extname8(maybeFile).toLowerCase() === ".txt") {
           text = readFileSync26(maybeFile, "utf-8").trim();
           if (!text) {
@@ -29319,7 +29744,7 @@ var init_tts = __esm({
           console.error(c.error("No text provided."));
           process.exit(1);
         }
-        const output = resolve24(args.output ?? "speech.wav");
+        const output = resolve25(args.output ?? "speech.wav");
         const voice = args.voice ?? DEFAULT_VOICE;
         const speed = args.speed ? parseFloat(args.speed) : 1;
         if (isNaN(speed) || speed <= 0 || speed > 3) {
@@ -29373,13 +29798,13 @@ __export(docs_exports, {
   examples: () => examples12
 });
 import { readFileSync as readFileSync27, existsSync as existsSync40 } from "fs";
-import { resolve as resolve25, dirname as dirname17, join as join39 } from "path";
+import { resolve as resolve26, dirname as dirname17, join as join39 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 function docsDir() {
   const thisFile = fileURLToPath6(import.meta.url);
   const dir = dirname17(thisFile);
-  const devPath = resolve25(dir, "..", "docs");
-  const builtPath = resolve25(dir, "docs");
+  const devPath = resolve26(dir, "..", "docs");
+  const builtPath = resolve26(dir, "docs");
   return existsSync40(devPath) ? devPath : builtPath;
 }
 function formatInlineCode(line) {
@@ -29897,13 +30322,13 @@ __export(validate_exports, {
   default: () => validate_default
 });
 import { existsSync as existsSync41, readFileSync as readFileSync28 } from "fs";
-import { resolve as resolve26, join as join40, dirname as dirname18 } from "path";
+import { resolve as resolve27, join as join40, dirname as dirname18 } from "path";
 import { fileURLToPath as fileURLToPath7 } from "url";
 async function validateInBrowser(projectDir, opts) {
   const { bundleToSingleHtml: bundleToSingleHtml2 } = await Promise.resolve().then(() => (init_compiler(), compiler_exports));
   const { ensureBrowser: ensureBrowser2 } = await Promise.resolve().then(() => (init_manager2(), manager_exports2));
   let html = await bundleToSingleHtml2(projectDir);
-  const runtimePath = resolve26(
+  const runtimePath = resolve27(
     __dirname2,
     "..",
     "..",
@@ -29916,7 +30341,7 @@ async function validateInBrowser(projectDir, opts) {
     const runtimeSource = readFileSync28(runtimePath, "utf-8");
     html = html.replace(
       /<script[^>]*data-hyperframes-preview-runtime[^>]*src="[^"]*"[^>]*><\/script>/,
-      `<script data-hyperframes-preview-runtime="1">${runtimeSource}</script>`
+      () => `<script data-hyperframes-preview-runtime="1">${runtimeSource}</script>`
     );
   }
   const { createServer } = await import("http");