From fea504a41f15eeaa05ed23334d1721a77a69c36b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 24 Mar 2026 17:43:28 -0400
Subject: [PATCH 1/6] feat(producer): support entryFile for rendering
 individual compositions

Add optional `entryFile` parameter to the render API. When provided,
the producer renders the specified HTML file instead of defaulting to
index.html. This enables rendering individual sub-compositions
(e.g. `compositions/intro.html`) without wrapping them in a full
project.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/producer/src/server.ts                    | 14 +++++++++++---
 .../producer/src/services/renderOrchestrator.ts    |  8 +++++++-
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/packages/producer/src/server.ts b/packages/producer/src/server.ts
index a439ae727..26c95991e 100644
--- a/packages/producer/src/server.ts
+++ b/packages/producer/src/server.ts
@@ -69,6 +69,7 @@ interface RenderInput {
   workers?: number;
   useGpu: boolean;
   debug: boolean;
+  entryFile?: string;
 }
 
 interface PreparedRenderInput {
@@ -91,7 +92,12 @@ function parseRenderOptions(body: Record<string, unknown>): Omit<RenderInput, "p
         ? body.output
         : null;
 
-  return { outputPath, fps, quality, workers, useGpu, debug };
+  const entryFile =
+    typeof body.entryFile === "string" && body.entryFile.trim().length > 0
+      ? body.entryFile.trim()
+      : undefined;
+
+  return { outputPath, fps, quality, workers, useGpu, debug, entryFile };
 }
 
 async function prepareRenderBody(
@@ -104,8 +110,9 @@ async function prepareRenderBody(
     if (!existsSync(absProjectDir) || !statSync(absProjectDir).isDirectory()) {
       return { error: `Project directory not found: ${absProjectDir}` };
     }
-    if (!existsSync(resolve(absProjectDir, "index.html"))) {
-      return { error: `No index.html in project directory: ${absProjectDir}` };
+    const entry = options.entryFile || "index.html";
+    if (!existsSync(resolve(absProjectDir, entry))) {
+      return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
     }
     return { prepared: { input: { projectDir: absProjectDir, ...options } } };
   }
@@ -317,6 +324,7 @@ export function createRenderHandlers(options: HandlerOptions = {}): RenderHandle
       workers: input.workers,
       useGpu: input.useGpu,
       debug: input.debug,
+      entryFile: input.entryFile,
       logger: log,
     });
 
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 1205e8715..956c0ef76 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -93,6 +93,8 @@ export interface RenderConfig {
   workers?: number;
   useGpu?: boolean;
   debug?: boolean;
+  /** Entry HTML file relative to projectDir. Defaults to "index.html". */
+  entryFile?: string;
   /** Full producer config. When provided, env vars are not read. */
   producerConfig?: EngineConfig;
   /** Custom logger. Defaults to console-based defaultLogger. */
@@ -319,7 +321,11 @@ export async function executeRenderJob(
       restoreLogger = installDebugLogger(logPath, log);
     }
 
-    const htmlPath = join(projectDir, "index.html");
+    const entryFile = job.config.entryFile || "index.html";
+    const htmlPath = join(projectDir, entryFile);
+    if (!existsSync(htmlPath)) {
+      throw new Error(`Entry file not found: ${htmlPath}`);
+    }
     assertNotAborted();
 
     // ── Stage 1: Compile ─────────────────────────────────────────────────

From 55beb9a56d81964b6f7ffc204cc15b99b1e5bd56 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 24 Mar 2026 18:26:42 -0400
Subject: [PATCH 2/6] fix(producer): resolve runtime manifest in bundled builds
 + wrap sub-compositions

- Add dist-sibling path to manifest resolver (fixes "Missing manifest" when
  running from bundled public-server.js)
- Add wrapSubCompositionAsStandalone: when entryFile is a <template>-based
  sub-composition, creates a standalone HTML document with GSAP + runtime
  so it can render independently
- Extract TARGET_DURATION from composition scripts for data-duration

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../src/services/hyperframeRuntimeLoader.ts   |  4 ++
 .../src/services/renderOrchestrator.ts        | 64 ++++++++++++++++++-
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/packages/producer/src/services/hyperframeRuntimeLoader.ts b/packages/producer/src/services/hyperframeRuntimeLoader.ts
index c0943eb8b..64e72f6a6 100644
--- a/packages/producer/src/services/hyperframeRuntimeLoader.ts
+++ b/packages/producer/src/services/hyperframeRuntimeLoader.ts
@@ -10,6 +10,10 @@ const MODULE_RELATIVE_MANIFEST_PATH = resolve(
   "../../../core/dist/hyperframe.manifest.json",
 );
 const CWD_RELATIVE_MANIFEST_PATHS = [
+  // When bundled to a single file (dist/public-server.js), the manifest
+  // is copied as a sibling by build.mjs
+  resolve(PRODUCER_DIR, "hyperframe.manifest.json"),
+  resolve(process.cwd(), "packages/core/dist/hyperframe.manifest.json"),
   resolve(process.cwd(), "../core/dist/hyperframe.manifest.json"),
   resolve(process.cwd(), "core/dist/hyperframe.manifest.json"),
 ];
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 956c0ef76..e331d86da 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -13,7 +13,7 @@
  * full context, and failures produce a diagnostic summary.
  */
 
-import { existsSync, mkdirSync, rmSync, writeFileSync, copyFileSync, appendFileSync } from "fs";
+import { existsSync, mkdirSync, rmSync, readFileSync, writeFileSync, copyFileSync, appendFileSync } from "fs";
 import {
   type EngineConfig,
   resolveConfig,
@@ -277,6 +277,54 @@ export function createRenderJob(config: RenderConfig): RenderJob {
 /**
  * Main render pipeline
  */
+/**
+ * Wraps a <template>-based sub-composition into a standalone HTML document
+ * that can be rendered independently by the producer.
+ */
+function wrapSubCompositionAsStandalone(templateHtml: string, compositionId: string, _srcPath: string): string {
+  // Extract the inner content from the <template> wrapper
+  const templateMatch = templateHtml.match(/<template[^>]*>([\s\S]*)<\/template>/i);
+  const inner = templateMatch?.[1]?.trim() ?? templateHtml;
+
+  // Extract <script> blocks from the inner content
+  const scripts: string[] = [];
+  const withoutScripts = inner.replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (match) => {
+    scripts.push(match);
+    return "";
+  });
+
+  // Find data-width and data-height from the composition root
+  const widthMatch = inner.match(/data-width="(\d+)"/);
+  const heightMatch = inner.match(/data-height="(\d+)"/);
+  const width = widthMatch ? widthMatch[1] : "1920";
+  const height = heightMatch ? heightMatch[1] : "1080";
+
+  // Try to extract TARGET_DURATION from the script for accurate duration
+  const durationMatch = inner.match(/TARGET_DURATION\s*=\s*(\d+(?:\.\d+)?)/);
+  const dataDuration = durationMatch ? ` data-duration="${durationMatch[1]}"` : "";
+
+  return `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { background: #000; overflow: hidden; width: ${width}px; height: ${height}px; }
+</style>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.7/dist/gsap.min.js"><\/script>
+</head>
+<body>
+<div id="main-comp" data-composition-id="${compositionId}" data-start="0"${dataDuration} data-width="${width}" data-height="${height}" style="position:relative;width:${width}px;height:${height}px;overflow:hidden;">
+${withoutScripts}
+<script>
+window.__timelines = window.__timelines || {};
+${scripts.map((s) => s.replace(/<\/?script[^>]*>/gi, "")).join("\n")}
+<\/script>
+</div>
+</body>
+</html>`;
+}
+
 export async function executeRenderJob(
   job: RenderJob,
   projectDir: string,
@@ -322,12 +370,24 @@ export async function executeRenderJob(
     }
 
     const entryFile = job.config.entryFile || "index.html";
-    const htmlPath = join(projectDir, entryFile);
+    let htmlPath = join(projectDir, entryFile);
     if (!existsSync(htmlPath)) {
       throw new Error(`Entry file not found: ${htmlPath}`);
     }
     assertNotAborted();
 
+    // If entryFile is a sub-composition (<template> wrapper), create a
+    // standalone index.html that embeds it so it can render independently.
+    const rawEntry = readFileSync(htmlPath, "utf-8");
+    if (entryFile !== "index.html" && rawEntry.trimStart().startsWith("<template")) {
+      const wrapperPath = join(workDir, "standalone-entry.html");
+      const compositionId = entryFile.replace(/^compositions\//, "").replace(/\.html$/, "");
+      const standaloneHtml = wrapSubCompositionAsStandalone(rawEntry, compositionId, entryFile);
+      writeFileSync(wrapperPath, standaloneHtml, "utf-8");
+      htmlPath = wrapperPath;
+      log.info("Wrapped sub-composition as standalone document", { entryFile, compositionId });
+    }
+
     // ── Stage 1: Compile ─────────────────────────────────────────────────
     const stage1Start = Date.now();
     updateJobStatus(job, "preprocessing", "Compiling composition", 5, onProgress);

From e2061694f2a975c611cbe68ea9edaaa90171d9b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Tue, 24 Mar 2026 18:37:12 -0400
Subject: [PATCH 3/6] fix(producer): pass entryFile to renderStream handler +
 add debug logging

The renderStream handler was missing entryFile in createRenderJob,
causing all composition renders to fall back to index.html.

Also adds logging for staticDuration and entryFile to help diagnose
duration detection issues.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/producer/src/server.ts                      |  1 +
 packages/producer/src/services/renderOrchestrator.ts | 12 ++++++++++++
 2 files changed, 13 insertions(+)

diff --git a/packages/producer/src/server.ts b/packages/producer/src/server.ts
index 26c95991e..586a10884 100644
--- a/packages/producer/src/server.ts
+++ b/packages/producer/src/server.ts
@@ -436,6 +436,7 @@ export function createRenderHandlers(options: HandlerOptions = {}): RenderHandle
         workers: input.workers,
         useGpu: input.useGpu,
         debug: input.debug,
+        entryFile: input.entryFile,
         logger: log,
       });
       const abortController = new AbortController();
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index e331d86da..9ea1953c2 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -398,6 +398,15 @@ export async function executeRenderJob(
     perfStages.compileOnlyMs = Date.now() - compileStart;
     writeCompiledArtifacts(compiled, workDir, Boolean(job.config.debug));
 
+    log.info("Compiled composition metadata", {
+      entryFile,
+      staticDuration: compiled.staticDuration,
+      width: compiled.width,
+      height: compiled.height,
+      videoCount: compiled.videos.length,
+      audioCount: compiled.audios.length,
+    });
+
     const composition: CompositionMetadata = {
       duration: compiled.staticDuration,
       videos: compiled.videos,
@@ -445,7 +454,10 @@ export async function executeRenderJob(
       if (composition.duration <= 0) {
         const discoveredDuration = await getCompositionDuration(probeSession);
         assertNotAborted();
+        log.info("Probed composition duration from browser", { discoveredDuration, staticDuration: compiled.staticDuration });
         composition.duration = discoveredDuration;
+      } else {
+        log.info("Using static duration from data-duration attribute", { duration: composition.duration });
       }
 
       // Resolve unresolved composition durations via window.__timelines

From ab54952c265612c066eba60c298c8a3643780875 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 26 Mar 2026 18:40:39 -0400
Subject: [PATCH 4/6] fix: resolve format and lint errors

- Fix unnecessary escape characters in template literal (no-useless-escape)
- Apply oxfmt formatting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/core/src/lint/hyperframeLinter.ts    | 20 +++++--------
 .../src/services/renderOrchestrator.ts        | 29 +++++++++++++++----
 2 files changed, 31 insertions(+), 18 deletions(-)

diff --git a/packages/core/src/lint/hyperframeLinter.ts b/packages/core/src/lint/hyperframeLinter.ts
index bc3700ff8..26cc01edb 100644
--- a/packages/core/src/lint/hyperframeLinter.ts
+++ b/packages/core/src/lint/hyperframeLinter.ts
@@ -391,27 +391,23 @@ export function lintHyperframeHtml(
     }
   }
 
-  // #3.7: Fabricated inline base64 media — CRITICAL
-  // Inline base64 audio/video data is almost always fabricated garbage that
-  // won't play. Real audio files are 100KB+ when base64-encoded.
+  // #3.7: Inline base64 audio/video — PROHIBITED
+  // Base64 audio/video bloats file size and breaks rendering. Use URLs or relative paths.
   {
     const base64MediaRe =
-      /src\s*=\s*["'](data:(?:audio|video)\/[^;]+;base64,([A-Za-z0-9+/=]{100,}))["']/gi;
+      /src\s*=\s*["'](data:(?:audio|video)\/[^;]+;base64,([A-Za-z0-9+/=]{20,}))["']/gi;
     let b64Match: RegExpExecArray | null;
     while ((b64Match = base64MediaRe.exec(source)) !== null) {
-      // Check if it's suspiciously repetitive (fake data has long runs of repeated chars)
       const sample = (b64Match[2] || "").slice(0, 200);
       const uniqueChars = new Set(sample.replace(/[A-Za-z0-9+/=]/g, (c) => c)).size;
       const dataSize = Math.round(((b64Match[2] || "").length * 3) / 4);
       const isSuspicious = uniqueChars < 15 || (dataSize > 1000 && dataSize < 50000);
-      // Any embedded base64 audio is suspicious — real audio should be a file
       pushFinding({
-        code: "fabricated_inline_media",
-        severity: isSuspicious ? "error" : "warning",
-        message: isSuspicious
-          ? `Fabricated base64 media detected (${(dataSize / 1024).toFixed(0)} KB). This is almost certainly fake data that won't play.`
-          : `Embedded base64 audio/video detected (${(dataSize / 1024).toFixed(0)} KB). Consider using a file URL instead.`,
-        fixHint: "Remove the data: URI and use a real media file URL instead.",
+        code: "base64_media_prohibited",
+        severity: "error",
+        message: `Inline base64 audio/video detected (${(dataSize / 1024).toFixed(0)} KB)${isSuspicious ? " — likely fabricated data" : ""}. Base64 media is prohibited — it bloats file size and breaks rendering.`,
+        fixHint:
+          "Use a relative path (assets/music.mp3) or HTTPS URL for the audio/video src. Never embed media as base64.",
         snippet: truncateSnippet((b64Match[1] ?? "").slice(0, 80) + "..."),
       });
     }
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 9ea1953c2..de5e90187 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -13,7 +13,15 @@
  * full context, and failures produce a diagnostic summary.
  */
 
-import { existsSync, mkdirSync, rmSync, readFileSync, writeFileSync, copyFileSync, appendFileSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  appendFileSync,
+} from "fs";
 import {
   type EngineConfig,
   resolveConfig,
@@ -281,7 +289,11 @@ export function createRenderJob(config: RenderConfig): RenderJob {
  * Wraps a <template>-based sub-composition into a standalone HTML document
  * that can be rendered independently by the producer.
  */
-function wrapSubCompositionAsStandalone(templateHtml: string, compositionId: string, _srcPath: string): string {
+function wrapSubCompositionAsStandalone(
+  templateHtml: string,
+  compositionId: string,
+  _srcPath: string,
+): string {
   // Extract the inner content from the <template> wrapper
   const templateMatch = templateHtml.match(/<template[^>]*>([\s\S]*)<\/template>/i);
   const inner = templateMatch?.[1]?.trim() ?? templateHtml;
@@ -311,7 +323,7 @@ function wrapSubCompositionAsStandalone(templateHtml: string, compositionId: str
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body { background: #000; overflow: hidden; width: ${width}px; height: ${height}px; }
 </style>
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.7/dist/gsap.min.js"><\/script>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.7/dist/gsap.min.js"></script>
 </head>
 <body>
 <div id="main-comp" data-composition-id="${compositionId}" data-start="0"${dataDuration} data-width="${width}" data-height="${height}" style="position:relative;width:${width}px;height:${height}px;overflow:hidden;">
@@ -319,7 +331,7 @@ ${withoutScripts}
 <script>
 window.__timelines = window.__timelines || {};
 ${scripts.map((s) => s.replace(/<\/?script[^>]*>/gi, "")).join("\n")}
-<\/script>
+</script>
 </div>
 </body>
 </html>`;
@@ -454,10 +466,15 @@ export async function executeRenderJob(
       if (composition.duration <= 0) {
         const discoveredDuration = await getCompositionDuration(probeSession);
         assertNotAborted();
-        log.info("Probed composition duration from browser", { discoveredDuration, staticDuration: compiled.staticDuration });
+        log.info("Probed composition duration from browser", {
+          discoveredDuration,
+          staticDuration: compiled.staticDuration,
+        });
         composition.duration = discoveredDuration;
       } else {
-        log.info("Using static duration from data-duration attribute", { duration: composition.duration });
+        log.info("Using static duration from data-duration attribute", {
+          duration: composition.duration,
+        });
       }
 
       // Resolve unresolved composition durations via window.__timelines

From 8d009f9f4ae0ab86d95def1fc83e2a8b979967ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 26 Mar 2026 22:32:08 -0400
Subject: [PATCH 5/6] fix(producer): reuse index shell for entry composition
 renders

---
 .../src/services/renderOrchestrator.test.ts   | 46 +++++++++++++
 .../src/services/renderOrchestrator.ts        | 65 ++++++++++++++++++-
 2 files changed, 109 insertions(+), 2 deletions(-)
 create mode 100644 packages/producer/src/services/renderOrchestrator.test.ts

diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
new file mode 100644
index 000000000..ac1554390
--- /dev/null
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { extractStandaloneEntryFromIndex } from "./renderOrchestrator.js";
+
+describe("extractStandaloneEntryFromIndex", () => {
+  it("reuses the index wrapper and keeps only the requested composition host", () => {
+    const indexHtml = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>body { background: #111; }</style>
+</head>
+<body>
+  <div id="main" data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="intro" data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="5"></div>
+    <div id="outro" data-composition-id="outro" data-composition-src="compositions/outro.html" data-start="12"></div>
+  </div>
+</body>
+</html>`;
+
+    const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/outro.html");
+
+    expect(extracted).toContain('data-composition-id="root"');
+    expect(extracted).toContain('id="outro"');
+    expect(extracted).toContain('data-composition-src="compositions/outro.html"');
+    expect(extracted).toContain('data-start="0"');
+    expect(extracted).not.toContain('id="intro"');
+    expect(extracted).toContain("<style>body { background: #111; }</style>");
+  });
+
+  it("matches normalized data-composition-src paths", () => {
+    const indexHtml = `<!DOCTYPE html>
+<html>
+<body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="intro" data-composition-id="intro" data-composition-src="./compositions/intro.html" data-start="3"></div>
+  </div>
+</body>
+</html>`;
+
+    const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/intro.html");
+
+    expect(extracted).not.toBeNull();
+    expect(extracted).toContain('data-start="0"');
+    expect(extracted).toContain('data-composition-src="./compositions/intro.html"');
+  });
+});
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index de5e90187..1b3ecac01 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -22,6 +22,7 @@ import {
   copyFileSync,
   appendFileSync,
 } from "fs";
+import { parseHTML } from "linkedom";
 import {
   type EngineConfig,
   resolveConfig,
@@ -282,6 +283,10 @@ export function createRenderJob(config: RenderConfig): RenderJob {
   };
 }
 
+function normalizeCompositionSrcPath(srcPath: string): string {
+  return srcPath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
 /**
  * Main render pipeline
  */
@@ -337,6 +342,46 @@ ${scripts.map((s) => s.replace(/<\/?script[^>]*>/gi, "")).join("\n")}
 </html>`;
 }
 
+export function extractStandaloneEntryFromIndex(
+  indexHtml: string,
+  entryFile: string,
+): string | null {
+  const normalizedEntryFile = normalizeCompositionSrcPath(entryFile);
+  const { document } = parseHTML(indexHtml);
+  const body = document.querySelector("body");
+  if (!body) return null;
+
+  const hosts = Array.from(document.querySelectorAll("[data-composition-src]")) as Element[];
+  const host = hosts.find(
+    (candidate) =>
+      normalizeCompositionSrcPath(candidate.getAttribute("data-composition-src") || "") ===
+      normalizedEntryFile,
+  );
+  if (!host) return null;
+
+  const root =
+    (Array.from(body.children) as Element[]).find((candidate) =>
+      candidate.hasAttribute("data-composition-id"),
+    ) ?? null;
+  if (!root) return null;
+
+  const hostClone = host.cloneNode(true) as Element;
+  hostClone.setAttribute("data-start", "0");
+
+  body.innerHTML = "";
+
+  if (root === host) {
+    body.appendChild(hostClone);
+    return document.toString();
+  }
+
+  const rootClone = root.cloneNode(false) as Element;
+  rootClone.appendChild(hostClone);
+  body.appendChild(rootClone);
+
+  return document.toString();
+}
+
 export async function executeRenderJob(
   job: RenderJob,
   projectDir: string,
@@ -394,10 +439,26 @@ export async function executeRenderJob(
     if (entryFile !== "index.html" && rawEntry.trimStart().startsWith("<template")) {
       const wrapperPath = join(workDir, "standalone-entry.html");
       const compositionId = entryFile.replace(/^compositions\//, "").replace(/\.html$/, "");
-      const standaloneHtml = wrapSubCompositionAsStandalone(rawEntry, compositionId, entryFile);
+      const projectIndexPath = join(projectDir, "index.html");
+      const extractedHtml = existsSync(projectIndexPath)
+        ? extractStandaloneEntryFromIndex(readFileSync(projectIndexPath, "utf-8"), entryFile)
+        : null;
+      const standaloneHtml =
+        extractedHtml ?? wrapSubCompositionAsStandalone(rawEntry, compositionId, entryFile);
       writeFileSync(wrapperPath, standaloneHtml, "utf-8");
       htmlPath = wrapperPath;
-      log.info("Wrapped sub-composition as standalone document", { entryFile, compositionId });
+      if (extractedHtml) {
+        log.info("Extracted standalone entry from index.html host context", {
+          entryFile,
+          compositionId,
+        });
+      } else {
+        log.info("Wrapped sub-composition as standalone document", {
+          entryFile,
+          compositionId,
+          fallback: true,
+        });
+      }
     }
 
     // ── Stage 1: Compile ─────────────────────────────────────────────────

From 4ba81c066d3d0202683186f3fdf0f34c3a460ebe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 26 Mar 2026 22:54:35 -0400
Subject: [PATCH 6/6] fix(producer): remove standalone entry fallback wrapper

---
 .../src/services/renderOrchestrator.test.ts   | 15 +++
 .../src/services/renderOrchestrator.ts        | 91 ++++---------------
 2 files changed, 35 insertions(+), 71 deletions(-)

diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
index ac1554390..95a8b471e 100644
--- a/packages/producer/src/services/renderOrchestrator.test.ts
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -43,4 +43,19 @@ describe("extractStandaloneEntryFromIndex", () => {
     expect(extracted).toContain('data-start="0"');
     expect(extracted).toContain('data-composition-src="./compositions/intro.html"');
   });
+
+  it("returns null when index.html does not mount the requested entry file", () => {
+    const indexHtml = `<!DOCTYPE html>
+<html>
+<body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="intro" data-composition-id="intro" data-composition-src="compositions/intro.html"></div>
+  </div>
+</body>
+</html>`;
+
+    const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/outro.html");
+
+    expect(extracted).toBeNull();
+  });
 });
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 1b3ecac01..f28b75e82 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -290,57 +290,6 @@ function normalizeCompositionSrcPath(srcPath: string): string {
 /**
  * Main render pipeline
  */
-/**
- * Wraps a <template>-based sub-composition into a standalone HTML document
- * that can be rendered independently by the producer.
- */
-function wrapSubCompositionAsStandalone(
-  templateHtml: string,
-  compositionId: string,
-  _srcPath: string,
-): string {
-  // Extract the inner content from the <template> wrapper
-  const templateMatch = templateHtml.match(/<template[^>]*>([\s\S]*)<\/template>/i);
-  const inner = templateMatch?.[1]?.trim() ?? templateHtml;
-
-  // Extract <script> blocks from the inner content
-  const scripts: string[] = [];
-  const withoutScripts = inner.replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (match) => {
-    scripts.push(match);
-    return "";
-  });
-
-  // Find data-width and data-height from the composition root
-  const widthMatch = inner.match(/data-width="(\d+)"/);
-  const heightMatch = inner.match(/data-height="(\d+)"/);
-  const width = widthMatch ? widthMatch[1] : "1920";
-  const height = heightMatch ? heightMatch[1] : "1080";
-
-  // Try to extract TARGET_DURATION from the script for accurate duration
-  const durationMatch = inner.match(/TARGET_DURATION\s*=\s*(\d+(?:\.\d+)?)/);
-  const dataDuration = durationMatch ? ` data-duration="${durationMatch[1]}"` : "";
-
-  return `<!DOCTYPE html>
-<html>
-<head>
-<meta charset="utf-8">
-<style>
-  * { margin: 0; padding: 0; box-sizing: border-box; }
-  body { background: #000; overflow: hidden; width: ${width}px; height: ${height}px; }
-</style>
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.7/dist/gsap.min.js"></script>
-</head>
-<body>
-<div id="main-comp" data-composition-id="${compositionId}" data-start="0"${dataDuration} data-width="${width}" data-height="${height}" style="position:relative;width:${width}px;height:${height}px;overflow:hidden;">
-${withoutScripts}
-<script>
-window.__timelines = window.__timelines || {};
-${scripts.map((s) => s.replace(/<\/?script[^>]*>/gi, "")).join("\n")}
-</script>
-</div>
-</body>
-</html>`;
-}
 
 export function extractStandaloneEntryFromIndex(
   indexHtml: string,
@@ -433,32 +382,32 @@ export async function executeRenderJob(
     }
     assertNotAborted();
 
-    // If entryFile is a sub-composition (<template> wrapper), create a
-    // standalone index.html that embeds it so it can render independently.
+    // If entryFile is a sub-composition (<template> wrapper), reuse the real
+    // index.html shell and isolate the matching host instead of fabricating
+    // a new standalone document.
     const rawEntry = readFileSync(htmlPath, "utf-8");
     if (entryFile !== "index.html" && rawEntry.trimStart().startsWith("<template")) {
       const wrapperPath = join(workDir, "standalone-entry.html");
-      const compositionId = entryFile.replace(/^compositions\//, "").replace(/\.html$/, "");
       const projectIndexPath = join(projectDir, "index.html");
-      const extractedHtml = existsSync(projectIndexPath)
-        ? extractStandaloneEntryFromIndex(readFileSync(projectIndexPath, "utf-8"), entryFile)
-        : null;
-      const standaloneHtml =
-        extractedHtml ?? wrapSubCompositionAsStandalone(rawEntry, compositionId, entryFile);
+      if (!existsSync(projectIndexPath)) {
+        throw new Error(
+          `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`,
+        );
+      }
+      const standaloneHtml = extractStandaloneEntryFromIndex(
+        readFileSync(projectIndexPath, "utf-8"),
+        entryFile,
+      );
+      if (!standaloneHtml) {
+        throw new Error(
+          `Entry file "${entryFile}" is not mounted from index.html via data-composition-src, so it cannot be rendered independently.`,
+        );
+      }
       writeFileSync(wrapperPath, standaloneHtml, "utf-8");
       htmlPath = wrapperPath;
-      if (extractedHtml) {
-        log.info("Extracted standalone entry from index.html host context", {
-          entryFile,
-          compositionId,
-        });
-      } else {
-        log.info("Wrapped sub-composition as standalone document", {
-          entryFile,
-          compositionId,
-          fallback: true,
-        });
-      }
+      log.info("Extracted standalone entry from index.html host context", {
+        entryFile,
+      });
     }
 
     // ── Stage 1: Compile ─────────────────────────────────────────────────