From 43128ae5d9d0d63ece6ed4874fee5244bdd02ae4 Mon Sep 17 00:00:00 2001
From: Mu-Tsun Tsai <don.m.t.tsai@gmail.com>
Date: Fri, 24 Apr 2026 23:22:54 +0800
Subject: [PATCH 1/2] fix(engine,producer): parse sub-composition media inside
 <template> wrappers

Sub-compositions wrapped in <template> had their media silently skipped
because linkedom's querySelectorAll (like the browser) doesn't descend
into template content. Unwrap one level of <template> in parseAudio /
Video / ImageElements via a shared helper, and guard
recompileWithResolutions from clobbering first-pass offsets when the
inlined HTML yields no sub-composition media.
---
 packages/engine/src/services/audioMixer.ts    |  3 +-
 .../src/services/videoFrameExtractor.ts       |  6 +-
 .../engine/src/utils/htmlTemplate.test.ts     | 63 +++++++++++++++++++
 packages/engine/src/utils/htmlTemplate.ts     | 24 +++++++
 .../producer/src/services/htmlCompiler.ts     | 15 ++++-
 5 files changed, 105 insertions(+), 6 deletions(-)
 create mode 100644 packages/engine/src/utils/htmlTemplate.test.ts
 create mode 100644 packages/engine/src/utils/htmlTemplate.ts

diff --git a/packages/engine/src/services/audioMixer.ts b/packages/engine/src/services/audioMixer.ts
index 726726425..a3ccb804c 100644
--- a/packages/engine/src/services/audioMixer.ts
+++ b/packages/engine/src/services/audioMixer.ts
@@ -11,6 +11,7 @@ import { extractAudioMetadata } from "../utils/ffprobe.js";
 import { downloadToTemp, isHttpUrl } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
+import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import type { AudioElement, AudioTrack, MixResult } from "./audioMixer.types.js";
 
 export type { AudioElement, AudioTrack, MixResult } from "./audioMixer.types.js";
@@ -24,7 +25,7 @@ interface ExtractResult {
 
 export function parseAudioElements(html: string): AudioElement[] {
   const elements: AudioElement[] = [];
-  const { document } = parseHTML(html);
+  const { document } = parseHTML(unwrapTemplate(html));
 
   // Parse <audio> elements
   const audioEls = document.querySelectorAll("audio[id][src]");
diff --git a/packages/engine/src/services/videoFrameExtractor.ts b/packages/engine/src/services/videoFrameExtractor.ts
index 8f81c6dee..097fe9ef9 100644
--- a/packages/engine/src/services/videoFrameExtractor.ts
+++ b/packages/engine/src/services/videoFrameExtractor.ts
@@ -17,6 +17,7 @@ import {
 } from "../utils/hdr.js";
 import { downloadToTemp, isHttpUrl } from "../utils/urlDownloader.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
+import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 import {
   FRAME_FILENAME_PREFIX,
@@ -102,7 +103,7 @@ export interface ExtractionResult {
 
 export function parseVideoElements(html: string): VideoElement[] {
   const videos: VideoElement[] = [];
-  const { document } = parseHTML(html);
+  const { document } = parseHTML(unwrapTemplate(html));
 
   const videoEls = document.querySelectorAll("video[src]");
   let autoIdCounter = 0;
@@ -156,7 +157,8 @@ export interface ImageElement {
 
 export function parseImageElements(html: string): ImageElement[] {
   const images: ImageElement[] = [];
-  const { document } = parseHTML(html);
+  // See parseVideoElements above for why we unwrap <template>.
+  const { document } = parseHTML(unwrapTemplate(html));
 
   const imgEls = document.querySelectorAll("img[src]");
   let autoIdCounter = 0;
diff --git a/packages/engine/src/utils/htmlTemplate.test.ts b/packages/engine/src/utils/htmlTemplate.test.ts
new file mode 100644
index 000000000..69689578d
--- /dev/null
+++ b/packages/engine/src/utils/htmlTemplate.test.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { unwrapTemplate } from "./htmlTemplate.js";
+
+describe("unwrapTemplate", () => {
+  it("returns input unchanged when there is no <template>", () => {
+    const html = `<div>hello</div>`;
+    expect(unwrapTemplate(html)).toBe(html);
+  });
+
+  it("unwraps the contents of a top-level <template>", () => {
+    const inner = `<div id="root"><audio id="a" src="a.mp3"></audio></div>`;
+    const html = `<!doctype html><html><body><template>${inner}</template></body></html>`;
+    expect(unwrapTemplate(html)).toBe(inner);
+  });
+
+  it("handles attributes on the <template> tag", () => {
+    const inner = `<span>hi</span>`;
+    const html = `<template id="t" data-x="1">${inner}</template>`;
+    expect(unwrapTemplate(html)).toBe(inner);
+  });
+
+  it("returns input unchanged when <template> has no closing tag", () => {
+    const html = `<template><div>broken`;
+    expect(unwrapTemplate(html)).toBe(html);
+  });
+
+  it("returns empty string for an empty template", () => {
+    const html = `<body><template></template></body>`;
+    expect(unwrapTemplate(html)).toBe("");
+  });
+
+  // Nested templates: the greedy match intentionally captures everything
+  // from the first <template> to the last </template>. A sub-composition
+  // that embeds its own <template> (e.g. for cloning) keeps that inner
+  // template intact after one unwrap — we only peel the outermost wrapper.
+  it("only unwraps the outermost <template> when nested", () => {
+    const inner = `outer-before<template>inner-content</template>outer-after`;
+    const html = `<body><template>${inner}</template></body>`;
+    expect(unwrapTemplate(html)).toBe(inner);
+  });
+
+  // Invariant: after one unwrap, any remaining <template> in the output is
+  // user content (e.g. a cloning template inside the composition DOM), not
+  // a second sub-composition wrapper. Running unwrapTemplate a second time
+  // would incorrectly strip user content, so callers should unwrap once.
+  it("is intended to be called once per sub-composition level", () => {
+    const userTemplate = `<template id="row"><tr><td></td></tr></template>`;
+    const composition = `<div>${userTemplate}</div>`;
+    const wrapped = `<template>${composition}</template>`;
+    expect(unwrapTemplate(wrapped)).toBe(composition);
+  });
+
+  // Known limitation: the greedy regex anchors on the LAST </template>, so
+  // two sibling top-level <template>s get treated as one and the text
+  // between them leaks into the captured content. Sub-composition HTML
+  // authored via the documented convention always has exactly one top-level
+  // wrapper, so this never happens in the render pipeline — but if a future
+  // caller passes multi-template input, they need a different parser.
+  it("collapses two sibling top-level <template>s (known limitation)", () => {
+    const html = `<template>a</template>middle<template>b</template>`;
+    expect(unwrapTemplate(html)).toBe(`a</template>middle<template>b`);
+  });
+});
diff --git a/packages/engine/src/utils/htmlTemplate.ts b/packages/engine/src/utils/htmlTemplate.ts
new file mode 100644
index 000000000..f559515e5
--- /dev/null
+++ b/packages/engine/src/utils/htmlTemplate.ts
@@ -0,0 +1,24 @@
+/**
+ * Sub-compositions wrap their content in a <template> tag. linkedom follows the
+ * browser contract where querySelectorAll does not descend into template content
+ * (it's a separate DocumentFragment), so media elements inside the wrapper are
+ * invisible to a plain DOM scrape. Unwrap one level of <template> if present so
+ * sub-composition media get parsed alongside main-composition media.
+ *
+ * Assumes at most one top-level <template> per input. The greedy match runs
+ * from the first `<template>` to the last `</template>`, which correctly peels
+ * a single wrapper (even when its content contains a nested <template>, e.g. a
+ * cloning template inside the composition DOM). It does NOT handle inputs with
+ * multiple sibling top-level <template>s — `<template>a</template>b<template>c</template>`
+ * collapses to `a</template>b<template>c`, which is wrong. Sub-composition
+ * HTML authored via the documented convention has exactly one wrapper, so
+ * this caveat doesn't surface in the render pipeline; callers producing
+ * different shapes need their own parser.
+ */
+export function unwrapTemplate(html: string): string {
+  const match = html.match(/<template[^>]*>([\s\S]*)<\/template>/i);
+  // Check match[1] against undefined specifically — an empty template
+  // produces `match[1] === ""`, which a truthiness check would treat as
+  // "no match found" and fall through to the original html.
+  return match && match[1] !== undefined ? match[1] : html;
+}
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 5e1418135..11f2f1d1e 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -1233,9 +1233,18 @@ export async function recompileWithResolutions(
   const mainImages = parseImageElements(html);
 
   // Keep inlined sub-composition media authoritative on ID collisions.
-  const videos = dedupeElementsById([...mainVideos, ...subVideos]);
-  const audios = dedupeElementsById([...mainAudios, ...subAudios]);
-  const images = dedupeElementsById([...mainImages, ...subImages]);
+  //
+  // `compiled.html` has already been inlined — the original host elements with
+  // `[data-composition-src]` no longer exist, so `parseSubCompositions` above
+  // returns empty arrays. If we blindly dedupe at this point we replace the
+  // already-offset media from the first compile pass (in compileForRender)
+  // with the scene-local versions parsed from the inlined HTML, losing the
+  // parent offset. Only overwrite when we actually have sub-composition data
+  // to merge in.
+  const hasSubMedia = subVideos.length > 0 || subAudios.length > 0 || subImages.length > 0;
+  const videos = hasSubMedia ? dedupeElementsById([...mainVideos, ...subVideos]) : compiled.videos;
+  const audios = hasSubMedia ? dedupeElementsById([...mainAudios, ...subAudios]) : compiled.audios;
+  const images = hasSubMedia ? dedupeElementsById([...mainImages, ...subImages]) : compiled.images;
 
   const remaining = compiled.unresolvedCompositions.filter(
     (c) => !resolutions.some((r) => r.id === c.id),

From 0af63950c497526d570c552e7ade03cf1dddff24 Mon Sep 17 00:00:00 2001
From: Mu-Tsun Tsai <don.m.t.tsai@gmail.com>
Date: Sat, 25 Apr 2026 00:05:41 +0800
Subject: [PATCH 2/2] fix(producer): don't overwrite compiled end time from
 browser DOM
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The browser reconciliation step copies `data-end` from the browser DOM onto
already-compiled media records when they disagree by more than a tick. For
sub-composition clips that is wrong: the compiled end was produced by
`parseSubCompositions` after adding the host's `data-start` offset, while
the browser reads the inlined DOM where the clip's `data-end` is still
scene-local. The reconciler sees the gap and replaces the offset-adjusted
end with the scene-local value, clipping the tail of every sub-composition
video/audio at render time.

Only fill `end` (and, for video, mediaStart / hasAudio) when the static
pipeline had no value — keep the compiled `end` authoritative otherwise.
Preview was already correct because it never runs this reconciliation.
---
 packages/producer/src/services/renderOrchestrator.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 33afa3200..7ff835794 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -1191,7 +1191,12 @@ export async function executeRenderJob(
                 if (existing.src !== src) {
                   existing.src = src;
                 }
-                if (el.end > 0 && (existing.end <= 0 || Math.abs(existing.end - el.end) > 0.0001)) {
+                // Only fill `end` when the static pipeline had nothing — otherwise the
+                // compiled value (which includes sub-composition host offsets) is
+                // authoritative. The browser's `data-end` is read from the inlined DOM
+                // where sub-composition clips still have scene-local end values, and
+                // overwriting would undo the offset applied in parseSubCompositions.
+                if (el.end > 0 && existing.end <= 0) {
                   existing.end = el.end;
                 }
                 if (
@@ -1224,7 +1229,8 @@ export async function executeRenderJob(
                 if (existing.src !== src) {
                   existing.src = src;
                 }
-                if (el.end > 0 && (existing.end <= 0 || Math.abs(existing.end - el.end) > 0.0001)) {
+                // See the video branch above for why we only fill `end` when missing.
+                if (el.end > 0 && existing.end <= 0) {
                   existing.end = el.end;
                 }
                 if (