From 17c99b788fdffaff895cc20679a5b867f2f39b95 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Thu, 5 Nov 2026 14:41:19 +0000
Subject: [PATCH 01/10] fix(core): detect template entries structurally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

isTemplateEntry only matched a raw file that starts with <template>, so the
full-document sub-composition shape (<!doctype html><html><body><template>
<div data-composition-id>...</template></body></html>) was not recognised and
resolveEntryHtmlPath compiled the raw file, whose root sits in an inert
template: no timeline, no duration, "Composition has zero duration".

A template entry is now a document whose <template> holds the composition
root with no live composition root outside it. Detection and extraction share
one lookup (locateSceneRoot), the same one readSceneRoot uses.

— Jerrai
---
 packages/core/src/compiler/htmlDocument.ts    | 23 ++++++-
 .../core/src/compiler/standaloneEntry.test.ts | 53 +++++++++++++---
 packages/core/src/compiler/standaloneEntry.ts |  8 +--
 .../render/stages/compileStage.test.ts        | 60 +++++++++++++++++++
 4 files changed, 129 insertions(+), 15 deletions(-)

diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index 09d4a6c1820..2be2c23bba0 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -16,8 +16,29 @@ const SIMPLE_RUNTIME_FLAG_ASSIGNMENTS = [
 
 const LEADING_COMMENTS = /^(?:\s|<!--(?:>|->|[\s\S]*?-->))*/;
 
+export interface SceneRootLookup {
+  root: Element | null;
+  hasTemplate: boolean;
+  hasLiveRoot: boolean;
+}
+
+// linkedom has no inert <template> content, so the template's innerHTML is re-parsed.
+// Elements outside the template are the document's live DOM.
+export function locateSceneRoot(html: string): SceneRootLookup {
+  const { document } = parseHTML(html);
+  const template = document.querySelector("template");
+  const liveRoot = document.querySelector("[data-composition-id]") as Element | null;
+  if (!template) return { root: liveRoot, hasTemplate: false, hasLiveRoot: liveRoot !== null };
+  const root = parseHTML(template.innerHTML).document.querySelector(
+    "[data-composition-id]",
+  ) as Element | null;
+  return { root, hasTemplate: true, hasLiveRoot: liveRoot !== null };
+}
+
+/** A scene file whose composition root exists only inside a <template>, with no live root beside it. */
 export function isTemplateEntry(html: string): boolean {
-  return /^<template[\s>/]/i.test(html.replace(LEADING_COMMENTS, ""));
+  const { root, hasTemplate, hasLiveRoot } = locateSceneRoot(html);
+  return hasTemplate && root !== null && !hasLiveRoot;
 }
 
 export function isFullHtmlDocument(html: string): boolean {
diff --git a/packages/core/src/compiler/standaloneEntry.test.ts b/packages/core/src/compiler/standaloneEntry.test.ts
index bb8e7e10f52..c4d1b7ee6be 100644
--- a/packages/core/src/compiler/standaloneEntry.test.ts
+++ b/packages/core/src/compiler/standaloneEntry.test.ts
@@ -2,24 +2,61 @@ import { parseHTML } from "linkedom";
 import { describe, expect, it } from "vitest";
 import { extractStandaloneEntryFromIndex, isTemplateEntry } from "./standaloneEntry";
 
+const ROOT = `<div id="root" data-composition-id="scene" data-width="640" data-height="360" data-duration="3"><p id="label">Hello</p></div>`;
+const SCENE_SCRIPT = `<script>window.__timelines = window.__timelines || {}; const tl = gsap.timeline({ paused: true }); tl.to("#label", { opacity: 1, duration: 3 }, 0); window.__timelines["scene"] = tl;</script>`;
+const SCENE_STYLE = `<style>#root { position: absolute; inset: 0; background: #123456; }</style>`;
+
 describe("isTemplateEntry", () => {
   it.each([
-    "<template></template>",
-    " \n<!-- Scene author notes -->\n<template id='scene'></template>",
-    "<!-- a --><!-- <template> is inert --><TEMPLATE></TEMPLATE>",
-    "<!--><template></template>",
-  ])("recognizes a template entry past leading comments: %s", (html) => {
+    `<template>${ROOT}</template>`,
+    ` \n<!-- Scene author notes -->\n<template id='scene'>${ROOT}</template>`,
+    `<!-- a --><!-- <template> is inert --><TEMPLATE>${ROOT}</TEMPLATE>`,
+    `<!--><template>${ROOT}</template>`,
+  ])("recognizes a template-first fragment entry: %s", (html) => {
+    expect(isTemplateEntry(html)).toBe(true);
+  });
+
+  it("recognizes the full-document shape whose composition root lives in the body template", () => {
+    const html = `<!doctype html>
+<html>
+  <head><meta charset="UTF-8" /></head>
+  <body>
+    <template>
+      ${SCENE_STYLE}
+      ${ROOT}
+      ${SCENE_SCRIPT}
+    </template>
+  </body>
+</html>`;
     expect(isTemplateEntry(html)).toBe(true);
   });
 
   it.each([
     "<template-card></template-card>",
-    "<!doctype html><html><body><template></template></body></html>",
-    "<div></div><template></template>",
-    "<!-- <template></template> -->",
+    `<template-card>${ROOT}</template-card>`,
+    `<!doctype html><html><body><template></template></body></html>`,
+    `<div></div><template></template>`,
+    `<!-- <template>${ROOT}</template> -->`,
+    `<!doctype html><html><body>${ROOT}</body></html>`,
   ])("does not mistake other entries for a template scene: %s", (html) => {
     expect(isTemplateEntry(html)).toBe(false);
   });
+
+  it("keeps a full document with a live composition root outside the template a plain entry", () => {
+    const html = `<!doctype html>
+<html>
+  <body>
+    <div id="live" data-composition-id="live" data-width="640" data-height="360" data-duration="3"></div>
+    <template>${ROOT}</template>
+  </body>
+</html>`;
+    expect(isTemplateEntry(html)).toBe(false);
+  });
+
+  it("keeps a template-first fragment with a live composition root beside it a plain entry", () => {
+    const html = `<template>${ROOT}</template><div data-composition-id="live"></div>`;
+    expect(isTemplateEntry(html)).toBe(false);
+  });
 });
 
 describe("extractStandaloneEntryFromIndex", () => {
diff --git a/packages/core/src/compiler/standaloneEntry.ts b/packages/core/src/compiler/standaloneEntry.ts
index 984979c4f1b..3bd46c8e04b 100644
--- a/packages/core/src/compiler/standaloneEntry.ts
+++ b/packages/core/src/compiler/standaloneEntry.ts
@@ -1,5 +1,6 @@
 import { parseHTML } from "linkedom";
 import { HF_AUDIO_FX_ATTR } from "../audioFx";
+import { locateSceneRoot } from "./htmlDocument";
 
 export { isTemplateEntry } from "./htmlDocument";
 
@@ -7,13 +8,8 @@ function normalizeCompositionSrcPath(srcPath: string): string {
   return srcPath.replace(/\\/g, "/").replace(/^\.\//, "");
 }
 
-// linkedom has no inert <template> content, so the template's innerHTML is re-parsed.
 function readSceneRoot(entryHtml: string | undefined): Element | null {
-  if (!entryHtml) return null;
-  const { document } = parseHTML(entryHtml);
-  const template = document.querySelector("template");
-  const scope = template ? parseHTML(template.innerHTML).document : document;
-  return scope.querySelector("[data-composition-id]") as Element | null;
+  return entryHtml ? locateSceneRoot(entryHtml).root : null;
 }
 
 // The scene's own chain replaces the index's, which belongs to the whole project.
diff --git a/packages/producer/src/services/render/stages/compileStage.test.ts b/packages/producer/src/services/render/stages/compileStage.test.ts
index 4aa158509b7..4ab9a75e9bf 100644
--- a/packages/producer/src/services/render/stages/compileStage.test.ts
+++ b/packages/producer/src/services/render/stages/compileStage.test.ts
@@ -521,6 +521,66 @@ describe("resolveEntryHtmlPath", () => {
     expect(html).not.toContain('id="other"');
   });
 
+  describe("canonical sub-composition document", () => {
+    const SCENE_ROOT = `<div id="root" data-composition-id="scene" data-width="640" data-height="360" data-duration="3"><p id="label">Hello</p></div>`;
+    const SCENE_SCRIPT = `<script>window.__timelines = window.__timelines || {}; const tl = gsap.timeline({ paused: true }); tl.to("#label", { opacity: 1, duration: 3 }, 0); window.__timelines["scene"] = tl;</script>`;
+    const SCENE_STYLE = `<style>#root { position: absolute; inset: 0; background: #123456; }</style>`;
+    const INDEX = `<!doctype html><html><body>
+        <div data-composition-id="root" data-width="640" data-height="360" data-duration="9">
+          <div id="scene" data-composition-id="scene" data-composition-src="compositions/scene.html"></div>
+        </div>
+      </body></html>`;
+
+    function writeScene(html: string): void {
+      if (!fixture) throw new Error("fixture not set up");
+      mkdirSync(join(fixture.workDir, "project", "compositions"));
+      writeFileSync(join(fixture.workDir, "project", "compositions", "scene.html"), html);
+    }
+
+    it("isolates a full-document scene whose root lives in the body template", () => {
+      fixture = setupFixture(INDEX);
+      writeScene(`<!doctype html>
+<html>
+  <head><meta charset="UTF-8" /></head>
+  <body>
+    <template>
+      ${SCENE_STYLE}
+      ${SCENE_ROOT}
+      ${SCENE_SCRIPT}
+    </template>
+  </body>
+</html>`);
+      const wrapper = resolve("compositions/scene.html");
+      expect(wrapper).toBe(join(fixture.workDir, "standalone-entry.html"));
+      const html = readFileSync(wrapper, "utf-8");
+      expect(html).toContain('id="scene"');
+      expect(html).toContain('data-duration="3"');
+      expect(html).not.toContain('data-duration="9"');
+    });
+
+    it("still isolates the template-first fragment form of the same scene", () => {
+      fixture = setupFixture(INDEX);
+      writeScene(`<template>${SCENE_STYLE}${SCENE_ROOT}${SCENE_SCRIPT}</template>`);
+      const wrapper = resolve("compositions/scene.html");
+      expect(wrapper).toBe(join(fixture.workDir, "standalone-entry.html"));
+      expect(readFileSync(wrapper, "utf-8")).toContain('data-duration="3"');
+    });
+
+    it("leaves a full document with a live root outside its template untouched", () => {
+      fixture = setupFixture(INDEX);
+      writeScene(`<!doctype html>
+<html>
+  <body>
+    <div id="live" data-composition-id="live" data-width="640" data-height="360" data-duration="3"></div>
+    <template>${SCENE_ROOT}</template>
+  </body>
+</html>`);
+      expect(resolve("compositions/scene.html")).toBe(
+        join(fixture.workDir, "project", "compositions", "scene.html"),
+      );
+    });
+  });
+
   it("refuses a template entry that index.html does not mount", () => {
     fixture = setupFixture(PLAIN_HTML);
     mkdirSync(join(fixture.workDir, "project", "compositions"));

From b25bc35ab5d40a023341be38e7f65a542506989b Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Thu, 5 Nov 2026 14:50:10 +0000
Subject: [PATCH 02/10] fix(core): drop comments from the template lookup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The comment ratchet allows no net rise in a file's comment share; the PR
description carries the explanation.

— Jerrai
---
 packages/core/src/compiler/htmlDocument.ts | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index 2be2c23bba0..881292faaef 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -22,8 +22,6 @@ export interface SceneRootLookup {
   hasLiveRoot: boolean;
 }
 
-// linkedom has no inert <template> content, so the template's innerHTML is re-parsed.
-// Elements outside the template are the document's live DOM.
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
   const template = document.querySelector("template");
@@ -35,7 +33,6 @@ export function locateSceneRoot(html: string): SceneRootLookup {
   return { root, hasTemplate: true, hasLiveRoot: liveRoot !== null };
 }
 
-/** A scene file whose composition root exists only inside a <template>, with no live root beside it. */
 export function isTemplateEntry(html: string): boolean {
   const { root, hasTemplate, hasLiveRoot } = locateSceneRoot(html);
   return hasTemplate && root !== null && !hasLiveRoot;

From ab08e0a3f5bb5749fafd49f55edba51ec259f466 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Fri, 6 Nov 2026 10:47:07 +0000
Subject: [PATCH 03/10] fix(core): find the scene template among several
 templates

locateSceneRoot read only the first <template>, so a scene template that
follows another template was treated as not a template entry. Scan every
template and take the first whose content holds a composition root.
---
 packages/core/src/compiler/htmlDocument.ts    | 16 ++++++----
 .../core/src/compiler/standaloneEntry.test.ts | 29 +++++++++++++++++++
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index 881292faaef..2c84344586e 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -22,15 +22,19 @@ export interface SceneRootLookup {
   hasLiveRoot: boolean;
 }
 
+/** The scene root is the first `<template>` whose content holds a composition root. */
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
-  const template = document.querySelector("template");
+  const templates = Array.from(document.querySelectorAll("template")) as Element[];
   const liveRoot = document.querySelector("[data-composition-id]") as Element | null;
-  if (!template) return { root: liveRoot, hasTemplate: false, hasLiveRoot: liveRoot !== null };
-  const root = parseHTML(template.innerHTML).document.querySelector(
-    "[data-composition-id]",
-  ) as Element | null;
-  return { root, hasTemplate: true, hasLiveRoot: liveRoot !== null };
+  let root: Element | null = null;
+  for (const template of templates) {
+    root = parseHTML(template.innerHTML).document.querySelector(
+      "[data-composition-id]",
+    ) as Element | null;
+    if (root) break;
+  }
+  return { root, hasTemplate: templates.length > 0, hasLiveRoot: liveRoot !== null };
 }
 
 export function isTemplateEntry(html: string): boolean {
diff --git a/packages/core/src/compiler/standaloneEntry.test.ts b/packages/core/src/compiler/standaloneEntry.test.ts
index c4d1b7ee6be..ba2e7646b0f 100644
--- a/packages/core/src/compiler/standaloneEntry.test.ts
+++ b/packages/core/src/compiler/standaloneEntry.test.ts
@@ -1,5 +1,6 @@
 import { parseHTML } from "linkedom";
 import { describe, expect, it } from "vitest";
+import { locateSceneRoot } from "./htmlDocument";
 import { extractStandaloneEntryFromIndex, isTemplateEntry } from "./standaloneEntry";
 
 const ROOT = `<div id="root" data-composition-id="scene" data-width="640" data-height="360" data-duration="3"><p id="label">Hello</p></div>`;
@@ -57,6 +58,34 @@ describe("isTemplateEntry", () => {
     const html = `<template>${ROOT}</template><div data-composition-id="live"></div>`;
     expect(isTemplateEntry(html)).toBe(false);
   });
+
+  it.each([
+    `<template id="card"><div class="card">Card</div></template><template id="scene">${ROOT}</template>`,
+    `<!doctype html><html><body><template><svg><symbol id="i"></symbol></svg></template><template>${ROOT}</template></body></html>`,
+    `<template></template><template><p>x</p></template><template>${ROOT}</template>`,
+  ])("finds the scene template when an earlier template holds no composition root: %s", (html) => {
+    expect(isTemplateEntry(html)).toBe(true);
+    expect(locateSceneRoot(html).root?.getAttribute("data-composition-id")).toBe("scene");
+  });
+
+  it("takes the first template that holds a composition root when several do", () => {
+    const second = `<div data-composition-id="later"></div>`;
+    const html = `<template>${ROOT}</template><template>${second}</template>`;
+    expect(locateSceneRoot(html).root?.getAttribute("data-composition-id")).toBe("scene");
+  });
+
+  it("reports no root when no template holds a composition root", () => {
+    const lookup = locateSceneRoot(`<template><p>a</p></template><template><p>b</p></template>`);
+    expect(lookup).toMatchObject({ root: null, hasTemplate: true, hasLiveRoot: false });
+  });
+
+  it("reads a single template and a template-free document as before", () => {
+    expect(locateSceneRoot(`<template>${ROOT}</template>`).root?.id).toBe("root");
+    expect(locateSceneRoot(`<!doctype html><html><body>${ROOT}</body></html>`)).toMatchObject({
+      hasTemplate: false,
+      hasLiveRoot: true,
+    });
+  });
 });
 
 describe("extractStandaloneEntryFromIndex", () => {

From acf753f6f55a5d5c8ebc1d6c1cd0328df0090575 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Fri, 6 Nov 2026 10:49:55 +0000
Subject: [PATCH 04/10] fix(core): drop the added comment (comment ratchet)

---
 packages/core/src/compiler/htmlDocument.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index 2c84344586e..27c884e20fb 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -22,7 +22,6 @@ export interface SceneRootLookup {
   hasLiveRoot: boolean;
 }
 
-/** The scene root is the first `<template>` whose content holds a composition root. */
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
   const templates = Array.from(document.querySelectorAll("template")) as Element[];

From 1dbcf8ff93257a9a7faf3fe6268d61cd9874a0f8 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Fri, 6 Nov 2026 11:52:54 +0000
Subject: [PATCH 05/10] chore: raise the inspector unpacked size budget by 0.5%

The inspector bundles core; the multi-template scene lookup added a few
hundred bytes and put it 10 bytes over the 1% tolerance.
---
 scripts/package-size-budgets.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json
index e6dfac2ae7a..b7f80ff60f9 100644
--- a/scripts/package-size-budgets.json
+++ b/scripts/package-size-budgets.json
@@ -21,7 +21,7 @@
   },
   "@hyperframes/inspector": {
     "packed": 858046,
-    "unpacked": 3645432
+    "unpacked": 3665000
   },
   "@hyperframes/lint": {
     "packed": 191022,

From 30a2fdd793b8f003e88d238b818decb341480746 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Fri, 6 Nov 2026 12:14:42 +0000
Subject: [PATCH 06/10] fix(core): refuse a file with several scene templates,
 naming them

---
 packages/core/src/compiler/htmlDocument.ts    | 31 +++++++++++++++----
 .../core/src/compiler/standaloneEntry.test.ts | 15 ++++++---
 2 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index 27c884e20fb..a0917a61aa0 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -16,24 +16,43 @@ const SIMPLE_RUNTIME_FLAG_ASSIGNMENTS = [
 
 const LEADING_COMMENTS = /^(?:\s|<!--(?:>|->|[\s\S]*?-->))*/;
 
+interface SceneTemplate {
+  position: number;
+  id: string | null;
+  root: Element;
+}
+
 export interface SceneRootLookup {
   root: Element | null;
   hasTemplate: boolean;
   hasLiveRoot: boolean;
 }
 
+function describeSceneTemplate({ position, id, root }: SceneTemplate): string {
+  const label = id ? `template #${position} (id="${id}")` : `template #${position}`;
+  return `${label} holding composition "${root.getAttribute("data-composition-id")}"`;
+}
+
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
-  const templates = Array.from(document.querySelectorAll("template")) as Element[];
   const liveRoot = document.querySelector("[data-composition-id]") as Element | null;
-  let root: Element | null = null;
-  for (const template of templates) {
-    root = parseHTML(template.innerHTML).document.querySelector(
+  const templates = Array.from(document.querySelectorAll("template")) as Element[];
+  const sceneTemplates = templates.flatMap((template, index) => {
+    const root = parseHTML(template.innerHTML).document.querySelector(
       "[data-composition-id]",
     ) as Element | null;
-    if (root) break;
+    return root ? [{ position: index + 1, id: template.getAttribute("id"), root }] : [];
+  });
+  if (!liveRoot && sceneTemplates.length > 1) {
+    throw new Error(
+      `This file has more than one scene template, so it is unclear which one to render: ${sceneTemplates.map(describeSceneTemplate).join("; ")}. Keep one composition root per file.`,
+    );
   }
-  return { root, hasTemplate: templates.length > 0, hasLiveRoot: liveRoot !== null };
+  return {
+    root: sceneTemplates[0]?.root ?? null,
+    hasTemplate: templates.length > 0,
+    hasLiveRoot: liveRoot !== null,
+  };
 }
 
 export function isTemplateEntry(html: string): boolean {
diff --git a/packages/core/src/compiler/standaloneEntry.test.ts b/packages/core/src/compiler/standaloneEntry.test.ts
index ba2e7646b0f..ba6fde62e82 100644
--- a/packages/core/src/compiler/standaloneEntry.test.ts
+++ b/packages/core/src/compiler/standaloneEntry.test.ts
@@ -68,10 +68,17 @@ describe("isTemplateEntry", () => {
     expect(locateSceneRoot(html).root?.getAttribute("data-composition-id")).toBe("scene");
   });
 
-  it("takes the first template that holds a composition root when several do", () => {
-    const second = `<div data-composition-id="later"></div>`;
-    const html = `<template>${ROOT}</template><template>${second}</template>`;
-    expect(locateSceneRoot(html).root?.getAttribute("data-composition-id")).toBe("scene");
+  it("refuses a file whose several templates each hold a composition root, naming them", () => {
+    const html = `<template id="intro">${ROOT}</template><template><div data-composition-id="later"></div></template>`;
+    expect(() => locateSceneRoot(html)).toThrow(
+      'This file has more than one scene template, so it is unclear which one to render: template #1 (id="intro") holding composition "scene"; template #2 holding composition "later". Keep one composition root per file.',
+    );
+    expect(() => isTemplateEntry(html)).toThrow(/more than one scene template/);
+  });
+
+  it("does not refuse when a live root makes the file a plain entry", () => {
+    const html = `<template>${ROOT}</template><template>${ROOT}</template><div data-composition-id="live"></div>`;
+    expect(isTemplateEntry(html)).toBe(false);
   });
 
   it("reports no root when no template holds a composition root", () => {

From 4dc886748172c5ccd1e378df7ae977a575356617 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Fri, 6 Nov 2026 12:20:38 +0000
Subject: [PATCH 07/10] chore: trim the inspector size budget bump to what is
 needed

---
 scripts/package-size-budgets.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json
index b7f80ff60f9..ed7b3782310 100644
--- a/scripts/package-size-budgets.json
+++ b/scripts/package-size-budgets.json
@@ -21,7 +21,7 @@
   },
   "@hyperframes/inspector": {
     "packed": 858046,
-    "unpacked": 3665000
+    "unpacked": 3650000
   },
   "@hyperframes/lint": {
     "packed": 191022,

From aec3cff74579b346491bbdde3e591fcfe213a23e Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Sat, 7 Nov 2026 02:30:59 +0000
Subject: [PATCH 08/10] fix(core): render the first scene template and lint the
 ambiguity instead of failing

A file with several scene templates and no live root rendered its first one
before; locateSceneRoot threw and stopped such projects rendering. It returns
the first again, and the multiple_scene_templates lint warning names each.

Co-authored-by: Jerrai <jerrai@heygen.com>
---
 docs/reference/lint-rules.mdx                 |  6 ++++
 .../core/src/compiler/htmlBundler.test.ts     | 17 ++++++++++
 packages/core/src/compiler/htmlDocument.ts    | 34 ++++++-------------
 .../core/src/compiler/standaloneEntry.test.ts |  8 ++---
 packages/lint/src/rules/composition.test.ts   | 26 ++++++++++++++
 packages/lint/src/rules/composition.ts        | 27 +++++++++++++++
 .../render/stages/compileStage.test.ts        | 12 +++++++
 7 files changed, 102 insertions(+), 28 deletions(-)

diff --git a/docs/reference/lint-rules.mdx b/docs/reference/lint-rules.mdx
index e1ab7d70439..b8aad8358d4 100644
--- a/docs/reference/lint-rules.mdx
+++ b/docs/reference/lint-rules.mdx
@@ -47,6 +47,12 @@ lints the file it is editing.
 
 **Fix:** Give every caption element the same `data-track-index`.
 
+### `multiple_scene_templates`
+
+**Warning.** A file has more than one `<template>` holding a composition root and no composition root outside them. Only the first one renders; the message names each template.
+
+**Fix:** Keep one composition root per file, or move the other scenes into their own files.
+
 ### `clip_ends_past_root_duration`
 
 **Warning.** A clip runs past the root composition's `data-duration`, so it is cut off in previews, posters and renders.
diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts
index 7011c39482a..bab1399bd71 100644
--- a/packages/core/src/compiler/htmlBundler.test.ts
+++ b/packages/core/src/compiler/htmlBundler.test.ts
@@ -285,6 +285,23 @@ describe("bundleToSingleHtml", () => {
     },
   );
 
+  it("bundles the first scene template of a file with two scene templates and no live root", async () => {
+    const dir = makeTempProject({
+      "index.html": `<!doctype html><html><body>
+        <div data-composition-id="root" data-width="320" data-height="180" data-duration="6">
+          <div data-composition-id="scene" data-composition-src="compositions/scene.html" data-start="0" data-duration="6"></div>
+        </div>
+      </body></html>`,
+      "compositions/scene.html": `<template><div data-composition-id="scene" data-duration="6"><h1>first scene</h1></div></template>
+        <template><div data-composition-id="other"><h1>second scene</h1></div></template>`,
+    });
+
+    const bundled = await bundleToSingleHtml(dir, { entryFile: "compositions/scene.html" });
+
+    expect(bundled).toContain("first scene");
+    expect(bundled).not.toContain("second scene");
+  });
+
   it("rebases direct-entry authored asset paths before inlining", async () => {
     const spriteSvg = '<svg xmlns="http://www.w3.org/2000/svg"><circle r="4"/></svg>';
     const bgSvg = '<svg xmlns="http://www.w3.org/2000/svg"><rect width="8" height="8"/></svg>';
diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index a0917a61aa0..78e93f4d614 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -16,40 +16,28 @@ const SIMPLE_RUNTIME_FLAG_ASSIGNMENTS = [
 
 const LEADING_COMMENTS = /^(?:\s|<!--(?:>|->|[\s\S]*?-->))*/;
 
-interface SceneTemplate {
-  position: number;
-  id: string | null;
-  root: Element;
-}
-
 export interface SceneRootLookup {
   root: Element | null;
   hasTemplate: boolean;
   hasLiveRoot: boolean;
 }
 
-function describeSceneTemplate({ position, id, root }: SceneTemplate): string {
-  const label = id ? `template #${position} (id="${id}")` : `template #${position}`;
-  return `${label} holding composition "${root.getAttribute("data-composition-id")}"`;
-}
-
+/** The first scene template wins; the `multiple_scene_templates` lint rule reports the rest. */
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
   const liveRoot = document.querySelector("[data-composition-id]") as Element | null;
   const templates = Array.from(document.querySelectorAll("template")) as Element[];
-  const sceneTemplates = templates.flatMap((template, index) => {
-    const root = parseHTML(template.innerHTML).document.querySelector(
-      "[data-composition-id]",
-    ) as Element | null;
-    return root ? [{ position: index + 1, id: template.getAttribute("id"), root }] : [];
-  });
-  if (!liveRoot && sceneTemplates.length > 1) {
-    throw new Error(
-      `This file has more than one scene template, so it is unclear which one to render: ${sceneTemplates.map(describeSceneTemplate).join("; ")}. Keep one composition root per file.`,
-    );
-  }
+  const sceneRoot =
+    templates
+      .map(
+        (template) =>
+          parseHTML(template.innerHTML).document.querySelector(
+            "[data-composition-id]",
+          ) as Element | null,
+      )
+      .find((root) => root !== null) ?? null;
   return {
-    root: sceneTemplates[0]?.root ?? null,
+    root: sceneRoot,
     hasTemplate: templates.length > 0,
     hasLiveRoot: liveRoot !== null,
   };
diff --git a/packages/core/src/compiler/standaloneEntry.test.ts b/packages/core/src/compiler/standaloneEntry.test.ts
index ba6fde62e82..62a406f153d 100644
--- a/packages/core/src/compiler/standaloneEntry.test.ts
+++ b/packages/core/src/compiler/standaloneEntry.test.ts
@@ -68,12 +68,10 @@ describe("isTemplateEntry", () => {
     expect(locateSceneRoot(html).root?.getAttribute("data-composition-id")).toBe("scene");
   });
 
-  it("refuses a file whose several templates each hold a composition root, naming them", () => {
+  it("renders the first scene template when several hold a composition root and none is live", () => {
     const html = `<template id="intro">${ROOT}</template><template><div data-composition-id="later"></div></template>`;
-    expect(() => locateSceneRoot(html)).toThrow(
-      'This file has more than one scene template, so it is unclear which one to render: template #1 (id="intro") holding composition "scene"; template #2 holding composition "later". Keep one composition root per file.',
-    );
-    expect(() => isTemplateEntry(html)).toThrow(/more than one scene template/);
+    expect(locateSceneRoot(html).root?.getAttribute("data-composition-id")).toBe("scene");
+    expect(isTemplateEntry(html)).toBe(true);
   });
 
   it("does not refuse when a live root makes the file a plain entry", () => {
diff --git a/packages/lint/src/rules/composition.test.ts b/packages/lint/src/rules/composition.test.ts
index dbf984409c3..97a1ca6ea28 100644
--- a/packages/lint/src/rules/composition.test.ts
+++ b/packages/lint/src/rules/composition.test.ts
@@ -4,6 +4,32 @@ import { lintHyperframeHtml } from "../hyperframeLinter.js";
 import { parseCompositionVariables } from "@hyperframes/parsers/composition";
 
 describe("composition rules", () => {
+  describe("multiple_scene_templates", () => {
+    const scene = (id: string) =>
+      `<div data-composition-id="${id}" data-width="320" data-height="180"></div>`;
+    const find = async (html: string) =>
+      (await lintHyperframeHtml(html, { isSubComposition: true })).findings.find(
+        (f) => f.code === "multiple_scene_templates",
+      );
+
+    it("warns, naming each scene template", async () => {
+      const finding = await find(
+        `<template id="intro">${scene("a")}</template><template>${scene("b")}</template>`,
+      );
+      expect(finding?.severity).toBe("warning");
+      expect(finding?.message).toContain('template #1 (id="intro") holding composition "a"');
+      expect(finding?.message).toContain('template #2 holding composition "b"');
+    });
+
+    it.each([
+      `<template>${scene("a")}</template>`,
+      `<template><svg></svg></template><template>${scene("a")}</template>`,
+      `<template>${scene("a")}</template><template>${scene("b")}</template>${scene("live")}`,
+    ])("is quiet for %s", async (html) => {
+      expect(await find(html)).toBeUndefined();
+    });
+  });
+
   describe("canonical timing contract", () => {
     it("rejects deprecated attributes even when canonical attributes are also present", async () => {
       const result = await lintHyperframeHtml(`<!doctype html><html><body>
diff --git a/packages/lint/src/rules/composition.ts b/packages/lint/src/rules/composition.ts
index b9f2be48002..dae349bb929 100644
--- a/packages/lint/src/rules/composition.ts
+++ b/packages/lint/src/rules/composition.ts
@@ -1,5 +1,6 @@
 import type { LintContext, HyperframeLintFinding, ExtractedBlock, OpenTag } from "../context";
 import selectorParser from "postcss-selector-parser";
+import { parseHTML } from "linkedom";
 import {
   findHtmlTag,
   extractTimelineRegistryKeys,
@@ -1946,6 +1947,32 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
         snippet: truncateSnippet(style.content.slice(0, 120)),
       }));
   },
+
+  // multiple_scene_templates: the renderer takes the first scene template of a file with no live root.
+  ({ rawSource }) => {
+    const { document } = parseHTML(rawSource);
+    if (document.querySelector("[data-composition-id]")) return [];
+    const scenes = Array.from(document.querySelectorAll("template")).flatMap((template, index) => {
+      const compositionId = parseHTML(template.innerHTML)
+        .document.querySelector("[data-composition-id]")
+        ?.getAttribute("data-composition-id");
+      if (compositionId === undefined) return [];
+      const id = template.getAttribute("id");
+      return [
+        `template #${index + 1}${id ? ` (id="${id}")` : ""} holding composition "${compositionId}"`,
+      ];
+    });
+    if (scenes.length < 2) return [];
+    return [
+      {
+        code: "multiple_scene_templates",
+        severity: "warning",
+        message: `This file has more than one scene template and no live composition root, so only the first renders: ${scenes.join("; ")}.`,
+        fixHint:
+          "Keep one composition root per file, or move the other scenes into their own files.",
+      },
+    ];
+  },
 ];
 
 const CLIP_MEDIA_TAGS = new Set<string>(["img", "video", "audio"]);
diff --git a/packages/producer/src/services/render/stages/compileStage.test.ts b/packages/producer/src/services/render/stages/compileStage.test.ts
index 4ab9a75e9bf..74ed8487db4 100644
--- a/packages/producer/src/services/render/stages/compileStage.test.ts
+++ b/packages/producer/src/services/render/stages/compileStage.test.ts
@@ -566,6 +566,18 @@ describe("resolveEntryHtmlPath", () => {
       expect(readFileSync(wrapper, "utf-8")).toContain('data-duration="3"');
     });
 
+    it("isolates the first scene template when a file holds two and no live root", () => {
+      fixture = setupFixture(INDEX);
+      writeScene(
+        `<template>${SCENE_ROOT}</template><template><div data-composition-id="other" data-duration="5"></div></template>`,
+      );
+      const wrapper = resolve("compositions/scene.html");
+      expect(wrapper).toBe(join(fixture.workDir, "standalone-entry.html"));
+      const html = readFileSync(wrapper, "utf-8");
+      expect(html).toContain('data-duration="3"');
+      expect(html).not.toContain('id="other"');
+    });
+
     it("leaves a full document with a live root outside its template untouched", () => {
       fixture = setupFixture(INDEX);
       writeScene(`<!doctype html>

From 1f007a2c07381bfcf3937e25d4f427f0d1db2221 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Sat, 7 Nov 2026 02:57:45 +0000
Subject: [PATCH 09/10] chore(core): drop the locateSceneRoot comment line the
 comment ratchet counts

Co-authored-by: Jerrai <jerrai@heygen.com>
---
 packages/core/src/compiler/htmlDocument.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index 78e93f4d614..fd414c9daf1 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -22,7 +22,6 @@ export interface SceneRootLookup {
   hasLiveRoot: boolean;
 }
 
-/** The first scene template wins; the `multiple_scene_templates` lint rule reports the rest. */
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
   const liveRoot = document.querySelector("[data-composition-id]") as Element | null;

From 4c89caa8834e629221751c789e77ae90d87656f5 Mon Sep 17 00:00:00 2001
From: Jerrai <jerrai@heygen.com>
Date: Sat, 7 Nov 2026 03:42:21 +0000
Subject: [PATCH 10/10] fix(core): one shared scene-template pick for the
 compiler, the inliner and the loader

A scene template after a card template was detected by locateSceneRoot but
mounted from the first template of any kind, so it rendered blank.
findSceneTemplate picks the first template holding a composition root and
locateSceneRoot, resolveSubCompositionContent and the loader all use it.

Co-authored-by: Jerrai <jerrai@heygen.com>
---
 .../core/src/compiler/htmlBundler.test.ts     | 30 +++++++++++++++++++
 packages/core/src/compiler/htmlDocument.ts    | 14 ++++-----
 .../src/runtime/compositionLoader.test.ts     | 21 +++++++++++++
 .../core/src/runtime/compositionLoader.ts     |  8 ++++-
 .../parsers/src/subCompositionValidity.ts     | 16 +++++++++-
 5 files changed, 78 insertions(+), 11 deletions(-)

diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts
index bab1399bd71..00e1570ab19 100644
--- a/packages/core/src/compiler/htmlBundler.test.ts
+++ b/packages/core/src/compiler/htmlBundler.test.ts
@@ -302,6 +302,36 @@ describe("bundleToSingleHtml", () => {
     expect(bundled).not.toContain("second scene");
   });
 
+  it.each([
+    [
+      "a card template before the scene",
+      `<template id="card"><div class="card">card</div></template>`,
+      "mounted scene",
+      "",
+    ],
+    [
+      "two scene templates",
+      "",
+      "mounted scene",
+      `<template><div data-composition-id="other"><h1>second scene</h1></div></template>`,
+    ],
+  ])("mounts the scene template of a file with %s", async (_label, before, expected, after) => {
+    const dir = makeTempProject({
+      "index.html": `<!doctype html><html><body>
+        <div data-composition-id="root" data-width="320" data-height="180" data-duration="6">
+          <div data-composition-id="scene" data-composition-src="compositions/scene.html" data-start="0" data-duration="6"></div>
+        </div>
+      </body></html>`,
+      "compositions/scene.html": `${before}<template><div data-composition-id="scene" data-duration="6"><h1>mounted scene</h1></div></template>${after}`,
+    });
+
+    const bundled = await bundleToSingleHtml(dir);
+
+    expect(bundled).toContain(expected);
+    expect(bundled).not.toContain("second scene");
+    expect(bundled).not.toContain(">card<");
+  });
+
   it("rebases direct-entry authored asset paths before inlining", async () => {
     const spriteSvg = '<svg xmlns="http://www.w3.org/2000/svg"><circle r="4"/></svg>';
     const bgSvg = '<svg xmlns="http://www.w3.org/2000/svg"><rect width="8" height="8"/></svg>';
diff --git a/packages/core/src/compiler/htmlDocument.ts b/packages/core/src/compiler/htmlDocument.ts
index fd414c9daf1..e4ad6189c8f 100644
--- a/packages/core/src/compiler/htmlDocument.ts
+++ b/packages/core/src/compiler/htmlDocument.ts
@@ -1,4 +1,5 @@
 import { acceleratedCanvasTrackerSource } from "../pageMotionBlur.js";
+import { findSceneTemplate } from "@hyperframes/parsers/sub-composition-validity";
 import { parseHTML } from "linkedom";
 
 export const RUNTIME_BOOTSTRAP_ATTR = "data-hyperframes-preview-runtime";
@@ -25,16 +26,11 @@ export interface SceneRootLookup {
 export function locateSceneRoot(html: string): SceneRootLookup {
   const { document } = parseHTML(html);
   const liveRoot = document.querySelector("[data-composition-id]") as Element | null;
-  const templates = Array.from(document.querySelectorAll("template")) as Element[];
+  const templates = Array.from(document.querySelectorAll("template"));
   const sceneRoot =
-    templates
-      .map(
-        (template) =>
-          parseHTML(template.innerHTML).document.querySelector(
-            "[data-composition-id]",
-          ) as Element | null,
-      )
-      .find((root) => root !== null) ?? null;
+    (findSceneTemplate(templates)?.content.querySelector(
+      "[data-composition-id]",
+    ) as Element | null) ?? null;
   return {
     root: sceneRoot,
     hasTemplate: templates.length > 0,
diff --git a/packages/core/src/runtime/compositionLoader.test.ts b/packages/core/src/runtime/compositionLoader.test.ts
index 261aa6507c4..00977798b2a 100644
--- a/packages/core/src/runtime/compositionLoader.test.ts
+++ b/packages/core/src/runtime/compositionLoader.test.ts
@@ -149,6 +149,27 @@ describe("loadCompositions external hosts", () => {
     ).toBe(false);
   });
 
+  it.each([
+    ["a card template before the scene", `<template><div class="card">card</div></template>`, ""],
+    [
+      "two scene templates",
+      "",
+      `<template><div data-composition-id="other"><p>second scene</p></div></template>`,
+    ],
+  ])("mounts the scene template of a fetched file with %s", async (_label, before, after) => {
+    const host = appendExternalHost("https://example.com/comp.html", "scene-1");
+    const scene = `<template><div data-composition-id="scene-1"><p>Hello World</p></div></template>`;
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(`${before}${scene}${after}`, { status: 200 }),
+    );
+
+    await loadFixture();
+
+    expect(host.textContent).toContain("Hello World");
+    expect(host.textContent).not.toContain("card");
+    expect(host.textContent).not.toContain("second scene");
+  });
+
   it("sizes a flattened inner root from a px-suffixed or fractional size", async () => {
     const host = appendExternalHost("https://example.com/comp.html", "scene-1");
     const compositionHtml = `
diff --git a/packages/core/src/runtime/compositionLoader.ts b/packages/core/src/runtime/compositionLoader.ts
index e843a3dd9a6..f6d66d9683b 100644
--- a/packages/core/src/runtime/compositionLoader.ts
+++ b/packages/core/src/runtime/compositionLoader.ts
@@ -1,3 +1,4 @@
+import { findSceneTemplate } from "@hyperframes/parsers/sub-composition-validity";
 import {
   SVG_REFERENCE_ALIASES_ATTR,
   readSvgReferenceAliases,
@@ -185,6 +186,11 @@ function rewriteSubCompositionAssetPaths(root: ParentNode, compositionUrl: URL |
   }
 }
 
+function sceneOrFirstTemplate(doc: Document): HTMLTemplateElement | null {
+  const templates = Array.from(doc.querySelectorAll<HTMLTemplateElement>("template"));
+  return findSceneTemplate(templates) ?? templates[0] ?? null;
+}
+
 function uniqueCompositionId(baseId: string, index: number): string {
   return `${baseId}__hf${index}`;
 }
@@ -800,7 +806,7 @@ async function mountExternalCompositions(
             ? doc.querySelector<HTMLTemplateElement>(
                 `template#${CSS.escape(authoredCompositionId)}-template`,
               )
-            : null) ?? doc.querySelector<HTMLTemplateElement>("template");
+            : null) ?? sceneOrFirstTemplate(doc);
         const sourceNode = template ? template.content : doc.body;
         return await mount({
           host,
diff --git a/packages/parsers/src/subCompositionValidity.ts b/packages/parsers/src/subCompositionValidity.ts
index 9f64eb17871..c4232237675 100644
--- a/packages/parsers/src/subCompositionValidity.ts
+++ b/packages/parsers/src/subCompositionValidity.ts
@@ -55,11 +55,25 @@ export interface ParsableDocumentLike {
   documentElement: { outerHTML?: string } | null;
   body?: { innerHTML?: string | null } | null;
   querySelector(selector: string): { innerHTML?: string | null } | null;
+  querySelectorAll(selector: string): ArrayLike<{ innerHTML?: string | null } & SceneTemplateLike>;
+}
+
+export interface SceneTemplateLike {
+  content: { querySelector(selector: string): unknown };
+}
+
+export function findSceneTemplate<T extends SceneTemplateLike>(
+  templates: ArrayLike<T>,
+): T | undefined {
+  return Array.from(templates).find(
+    (template) => template.content.querySelector("[data-composition-id]") != null,
+  );
 }
 
 /** Resolve authored content without invoking linkedom's synthetic body getter. */
 export function resolveSubCompositionContent(html: string, document: ParsableDocumentLike) {
-  const template = document.querySelector("template");
+  const templates = Array.from(document.querySelectorAll("template"));
+  const template = findSceneTemplate(templates) ?? templates[0];
   if (template) return { contentHtml: template.innerHTML ?? "", hasTemplate: true };
 
   const body = document.querySelector("body");