fix(producer): give inlined media a document-unique render id (#3342)

* fix(producer): give inlined media a document-unique render id

Element ids are unique per composition file, but the render document is
the inlined union of every file. The producer merged the per-file media
lists and deduplicated by id, so clips that shared an id collapsed into a
single entry, and every id-keyed stage (extract, inject, visibility,
bounds) resolved to whichever element came first in the document. The
surviving clip's frames landed on the wrong element and the visible scene
rendered without footage.

Two shapes hit this, and neither is author error:

  - Two scenes that each declare `<video id="clip">`. Legal per file, and
    unavoidable when a scene is duplicated into a copy with inner ids
    kept, or when one file is mounted twice.
  - Two scenes that each declare a bare `<video>`. The timing compiler
    numbers auto-ids per file, so both arrive as `hf-video-0` with no
    authored id involved at all.

Stamp a document-unique `data-hf-render-id` while inlining, and read the
media list off the inlined document instead of merging per-file lists.
The render id equals the element id whenever that id is already unique,
so documents without a collision keep identical pipeline keys.

Author `id` attributes are left alone: 158 of the 161 registry blocks
reference their own ids from `#id` CSS or getElementById, so renaming
would trade broken footage for broken styling. The engine resolves media
elements through the render id instead, falling back to getElementById
for documents the producer never compiled.

Collecting from the inlined document also retires the per-file media
extraction in parseSubCompositions along with its offset bookkeeping;
host offsets are recovered from the composition hosts the clip sits in.

* fix(core): resolve render-frame siblings by render id in the runtime

The injector creates each `__render_frame_<id>__` sibling from the media
element's render id, but four runtime readers still built that id from the
plain `el.id`. On a document where two compositions share a media id, all
of them resolved the first collider's frame.

colorGrading is the one that changes pixels: findRenderFrameImage returns
the image the grading pass samples, with no class check to catch the
mismatch, so the second video was graded from the first one's frame.
media, mediaProxy and video-texture-compat use it as a render-mode or
substitute-source signal, where both colliders happen to agree during
render, but none of them should rest on that.

Add renderFrameSibling as the single owner of "which frame belongs to
this element" and route all four through it. It reads the stamped render
id and falls back to the author id, so a collision-free document resolves
exactly as before and an uncompiled one (preview, snapshot, check) is
unchanged.

The engine's in-page bridge keeps its own copy of the rule because code
serialized into page.evaluate cannot import; it now names core as the
definition, and a test pins the sibling-id format both sides build so
they cannot drift apart silently.

* refactor(engine): build render-frame sibling ids from core's definition

The drift guard named both sides but pinned one. renderFrameSibling.test
asserts core's format, while the engine rebuilt the same id from a literal
template at six independent sites. Changing the format on either side left
the test green and every runtime reader silently unable to find its frame —
this PR's own failure mode, one level up.

Export the affixes and renderFrameIdForRenderId from core, and take the id
from there at all six. Four sites resolve it on the Node side, where the
engine can import; the two that iterate the DOM in-page receive the affixes
as evaluate arguments, which avoids depending on bridge install order.

Also switch two `__hfMediaId?.(el) ?? el.id` reads to `||`. The bridge
returns "" for an element with neither id, so `??` kept the empty string
and built `__render_frame___`, which no reader looks for. Inert today
because the compiler assigns positional ids to id-less timed media, but it
made the two sides disagree in the one case they could.

Author: miguel-heygen

packages/core/src/compiler/index.ts

@@ -89,3 +89,5 @@ export {
 
 // Asset-path primitives (shared across core, producer, CLI)
 export { CSS_URL_RE, PATH_ATTRS, isNonRelativeUrl, isPathInside } from "./assetPaths";
+
+export { MEDIA_RENDER_ID_ATTR, assignMediaRenderIds } from "./mediaRenderIds";

packages/core/src/compiler/mediaRenderIds.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from "vitest";
+import { parseHTML } from "linkedom";
+import { MEDIA_RENDER_ID_ATTR, assignMediaRenderIds } from "./mediaRenderIds";
+
+function stamp(html: string): string[] {
+  const { document } = parseHTML(html);
+  assignMediaRenderIds(document as unknown as Parameters<typeof assignMediaRenderIds>[0]);
+  return Array.from(document.querySelectorAll("video, audio, img")).map(
+    (el) => el.getAttribute(MEDIA_RENDER_ID_ATTR) ?? "",
+  );
+}
+
+describe("assignMediaRenderIds", () => {
+  it("keeps the element id when it is already unique", () => {
+    expect(stamp('<video id="hero" src="a.mp4">')).toEqual(["hero"]);
+  });
+
+  it("disambiguates a media id shared by two inlined compositions", () => {
+    // Two scenes each authored `<video id="clip">`: legal per file, duplicated
+    // once both are inlined into one render document.
+    expect(stamp('<video id="clip" src="a.mp4"><video id="clip" src="a.mp4">')).toEqual([
+      "clip",
+      "clip__hf2",
+    ]);
+  });
+
+  it("disambiguates per-file auto-ids, which collide without any authored id", () => {
+    // The timing compiler numbers unnamed media per file, so two bare <video>s
+    // in two scenes both arrive as `hf-video-0`.
+    expect(stamp('<video id="hf-video-0" src="a.mp4"><video id="hf-video-0" src="b.mp4">')).toEqual(
+      ["hf-video-0", "hf-video-0__hf2"],
+    );
+  });
+
+  it("keeps disambiguating past the first collision", () => {
+    const html = '<video id="c" src="a.mp4"><video id="c" src="a.mp4"><video id="c" src="a.mp4">';
+    expect(stamp(html)).toEqual(["c", "c__hf2", "c__hf3"]);
+  });
+
+  it("separates ids across tag types", () => {
+    expect(
+      stamp('<video id="m" src="a.mp4"><audio id="m" src="a.mp3"><img id="m" src="a.png">'),
+    ).toEqual(["m", "m__hf2", "m__hf3"]);
+  });
+
+  it("does not renumber elements that already carry a render id", () => {
+    const { document } = parseHTML(
+      `<video id="clip" ${MEDIA_RENDER_ID_ATTR}="clip" src="a.mp4">` +
+        `<video id="clip" ${MEDIA_RENDER_ID_ATTR}="clip__hf2" src="a.mp4">`,
+    );
+    assignMediaRenderIds(document as unknown as Parameters<typeof assignMediaRenderIds>[0]);
+    expect(
+      Array.from(document.querySelectorAll("video")).map((el) =>
+        el.getAttribute(MEDIA_RENDER_ID_ATTR),
+      ),
+    ).toEqual(["clip", "clip__hf2"]);
+  });
+
+  it("does not claim an id that a later element already holds as its render id", () => {
+    // Re-running over a partially stamped document must not hand `clip__hf2`
+    // to the first element and collide with the element already holding it.
+    const { document } = parseHTML(
+      `<video id="clip__hf2" src="a.mp4">` +
+        `<video id="clip" ${MEDIA_RENDER_ID_ATTR}="clip__hf2" src="a.mp4">`,
+    );
+    assignMediaRenderIds(document as unknown as Parameters<typeof assignMediaRenderIds>[0]);
+    const ids = Array.from(document.querySelectorAll("video")).map((el) =>
+      el.getAttribute(MEDIA_RENDER_ID_ATTR),
+    );
+    expect(new Set(ids).size).toBe(2);
+    expect(ids[1]).toBe("clip__hf2");
+  });
+
+  it("leaves media without a src alone", () => {
+    const { document } = parseHTML('<video id="no-src"></video>');
+    assignMediaRenderIds(document as unknown as Parameters<typeof assignMediaRenderIds>[0]);
+    expect(document.querySelector("video")?.hasAttribute(MEDIA_RENDER_ID_ATTR)).toBe(false);
+  });
+});

packages/core/src/compiler/mediaRenderIds.ts

@@ -0,0 +1,87 @@
+/**
+ * Document-unique identity for media elements in a compiled render document.
+ *
+ * Element `id`s are only unique within one composition FILE. The render
+ * document is the inlined union of every file, so ids collide there in two
+ * ways an author cannot avoid:
+ *
+ * 1. Two scenes each declare `<video id="clip">` — legal per file, duplicated
+ *    once inlined.
+ * 2. Two scenes each declare a bare `<video>` — the timing compiler numbers
+ *    auto-ids per file, so both become `hf-video-0`.
+ *
+ * The render pipeline keys media on that id (extract, inject, visibility,
+ * bounds), so a collision collapses N elements into one entry and every
+ * lookup resolves to whichever element happens to come first in the document.
+ * The surviving clip's frames land on the wrong element and the visible scene
+ * paints without footage.
+ *
+ * This module is the single owner of the fix: after inlining, every media
+ * element gets a document-unique `data-hf-render-id`. It equals the element's
+ * own id whenever that id is already unique, so uncolliding documents keep
+ * byte-identical pipeline keys and log output. Author-visible `id` attributes
+ * are never rewritten — 158 of the 161 registry blocks reference their own ids
+ * from `#id` CSS or `getElementById`, so renaming would break scene styling to
+ * fix scene footage.
+ */
+
+export const MEDIA_RENDER_ID_ATTR = "data-hf-render-id";
+
+/** Elements the render pipeline addresses by id. */
+const MEDIA_SELECTOR = "video[src], audio[src], img[src]";
+
+interface MediaElementLike {
+  getAttribute(name: string): string | null;
+  setAttribute(name: string, value: string): void;
+}
+
+interface DocumentLike {
+  querySelectorAll(selector: string): Iterable<MediaElementLike>;
+}
+
+/**
+ * Derive a document-unique render id from an element's own id.
+ *
+ * `taken` accumulates every id handed out so far, including the plain ids of
+ * elements that have not been visited yet is NOT required: a later element
+ * whose plain id was already claimed simply gets a suffix. Document order
+ * therefore decides who keeps the plain id, which keeps the first (and, in the
+ * overwhelmingly common single-occurrence case, only) element stable.
+ */
+function uniqueRenderId(baseId: string, taken: Set<string>): string {
+  if (!taken.has(baseId)) return baseId;
+  let suffix = 2;
+  while (taken.has(`${baseId}__hf${suffix}`)) suffix += 1;
+  return `${baseId}__hf${suffix}`;
+}
+
+/**
+ * Stamp `data-hf-render-id` on every media element in a compiled document.
+ *
+ * Idempotent: an element that already carries the attribute keeps it, so
+ * re-compiling a document (the resolved-durations recompile path) does not
+ * renumber ids out from under an in-flight extraction.
+ */
+export function assignMediaRenderIds(document: DocumentLike): void {
+  const taken = new Set<string>();
+  const pending: MediaElementLike[] = [];
+
+  for (const el of document.querySelectorAll(MEDIA_SELECTOR)) {
+    const existing = el.getAttribute(MEDIA_RENDER_ID_ATTR);
+    if (existing) {
+      taken.add(existing);
+      continue;
+    }
+    pending.push(el);
+  }
+
+  for (const el of pending) {
+    const baseId = el.getAttribute("id");
+    // An element with no id yet is numbered by the timing compiler before this
+    // runs. If one slips through, fall back to a positional id rather than
+    // stamping an empty string that every other id-less element would share.
+    const renderId = uniqueRenderId(baseId || `hf-media-${taken.size}`, taken);
+    taken.add(renderId);
+    el.setAttribute(MEDIA_RENDER_ID_ATTR, renderId);
+  }
+}

packages/core/src/index.ts

@@ -144,6 +144,14 @@ export {
   MEDIA_DURATION_CLAMP_EPSILON_SECONDS,
 } from "./compiler/timingCompiler";
 
+export { MEDIA_RENDER_ID_ATTR, assignMediaRenderIds } from "./compiler/mediaRenderIds";
+
+export {
+  RENDER_FRAME_ID_PREFIX,
+  RENDER_FRAME_ID_SUFFIX,
+  renderFrameIdForRenderId,
+} from "./runtime/renderFrameSibling";
+
 // Lint moved to @hyperframes/lint. Import lint APIs from @hyperframes/lint
 // directly, or via the back-compat stub at @hyperframes/core/lint. Not
 // re-exported here — doing so would cycle core's main entry through the lint

packages/core/src/runtime/adapters/video-texture-compat.ts

@@ -13,13 +13,15 @@
  * sibling), the original `<video>` path is used unchanged.
  */
 
+import { findInjectedRenderFrame } from "../renderFrameSibling.js";
+
 /**
  * Resolve the decoded render-frame `<img>` for a source `<video>`, if the
  * engine has injected one and it has decoded pixels. Returns null in preview
  * mode or before the frame is decoded, so callers fall back to the video.
  *
  * The injector inserts the `<img>` as the video's immediate next sibling and
- * also gives it the id `__render_frame_<videoId>__`; we check the sibling
+ * also gives it the id `__render_frame_<renderId>__`; we check the sibling
  * first (cheap) and fall back to an id lookup in case a node was inserted
  * between them.
  */
@@ -33,11 +35,9 @@ function resolveRenderFrameImage(video: HTMLVideoElement): HTMLImageElement | nu
   ) {
     return sibling;
   }
-  if (video.id) {
-    const byId = document.getElementById(`__render_frame_${video.id}__`);
-    if (byId instanceof HTMLImageElement && byId.complete && byId.naturalWidth > 0) {
-      return byId;
-    }
+  const byId = findInjectedRenderFrame(video);
+  if (byId && byId.complete && byId.naturalWidth > 0) {
+    return byId;
   }
   return null;
 }

packages/core/src/runtime/colorGrading.ts

@@ -41,6 +41,7 @@ import {
 import { copyMediaVisualStyles } from "../inline-scripts/parityContract";
 import { readVariablesForElement } from "./variableScope";
 import { swallow } from "./diagnostics";
+import { findInjectedRenderFrame } from "./renderFrameSibling";
 
 type ColorGradingMediaElement = HTMLVideoElement | HTMLImageElement;
 
@@ -2470,9 +2471,8 @@ function isDrawableSource(source: TexImageSource): boolean {
 }
 
 function findRenderFrameImage(video: HTMLVideoElement): HTMLImageElement | null {
-  if (!video.id) return null;
-  const frame = document.getElementById(`__render_frame_${video.id}__`);
-  return frame instanceof HTMLImageElement && isDrawableSource(frame) ? frame : null;
+  const frame = findInjectedRenderFrame(video);
+  return frame && isDrawableSource(frame) ? frame : null;
 }
 
 function hasInjectedRenderFrame(element: ColorGradingMediaElement): boolean {

packages/core/src/runtime/media.ts

@@ -3,6 +3,7 @@ import { interpolateVolumeGain, type VolumeKeyframe } from "./mediaVolumeEnvelop
 import { elementVolumeLaneGain } from "./audioAutomationVolume.js";
 import { readElementPlaybackRate, readMediaStart } from "./playbackRate.js";
 import { clampAudioGain } from "../audioGain.js";
+import { findInjectedRenderFrame } from "./renderFrameSibling.js";
 export { readElementPlaybackRate, resolveNaturalMediaTimelineDuration } from "./playbackRate.js";
 
 export function readElementPlaybackStart(el: Element): number {
@@ -410,8 +411,7 @@ export function syncRuntimeMedia(params: {
         // effect during render, and the per-tick set just kicks Chrome's
         // media pipeline for nothing. Preview is unaffected (the sibling
         // only exists during render).
-        const skipForInjectedVideo =
-          el.tagName === "VIDEO" && el.id && !!document.getElementById(`__render_frame_${el.id}__`);
+        const skipForInjectedVideo = el.tagName === "VIDEO" && !!findInjectedRenderFrame(el);
         if (!skipForInjectedVideo) {
           try {
             el.currentTime = relTime;

packages/core/src/runtime/mediaProxy.ts

@@ -1,6 +1,7 @@
 import { postRuntimeMessage } from "./bridge";
 import { swallow } from "./diagnostics";
 import { evictMediaSyncState } from "./media";
+import { findInjectedRenderFrame } from "./renderFrameSibling";
 import type { RuntimeJson } from "./types";
 
 /**
@@ -62,11 +63,7 @@ function currentSrcValue(el: HTMLMediaElement): string {
  */
 function isRenderMode(el: HTMLMediaElement): boolean {
   if (window.__HF_EXPORT_RENDER_SEEK_CONFIG) return true;
-  return (
-    el instanceof HTMLVideoElement &&
-    !!el.id &&
-    !!document.getElementById(`__render_frame_${el.id}__`)
-  );
+  return el instanceof HTMLVideoElement && !!findInjectedRenderFrame(el);
 }
 
 /**

packages/core/src/runtime/renderFrameSibling.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { MEDIA_RENDER_ID_ATTR } from "../compiler/mediaRenderIds";
+import {
+  readMediaRenderId,
+  renderFrameElementId,
+  findInjectedRenderFrame,
+} from "./renderFrameSibling";
+
+function videoWith(attrs: Record<string, string>): HTMLVideoElement {
+  const el = document.createElement("video");
+  for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+  return el;
+}
+
+describe("readMediaRenderId", () => {
+  it("prefers the stamped render id over the author id", () => {
+    expect(readMediaRenderId(videoWith({ id: "clip", [MEDIA_RENDER_ID_ATTR]: "clip__hf2" }))).toBe(
+      "clip__hf2",
+    );
+  });
+
+  it("falls back to the author id in an uncompiled document", () => {
+    expect(readMediaRenderId(videoWith({ id: "clip" }))).toBe("clip");
+  });
+
+  it("returns null when the element has neither", () => {
+    expect(readMediaRenderId(videoWith({}))).toBeNull();
+  });
+});
+
+describe("renderFrameElementId", () => {
+  // Pins the id format the engine's in-page bridge mirrors when it CREATES the
+  // sibling (screenshotService.ensureRenderFrameSiblings). If this format
+  // changes on one side only, the readers stop finding the frame.
+  it("wraps the render id in the injector's sibling id format", () => {
+    expect(renderFrameElementId(videoWith({ id: "hero" }))).toBe("__render_frame_hero__");
+    expect(renderFrameElementId(videoWith({ id: "c", [MEDIA_RENDER_ID_ATTR]: "c__hf2" }))).toBe(
+      "__render_frame_c__hf2__",
+    );
+  });
+});
+
+describe("findInjectedRenderFrame", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("resolves each colliding video to its own frame, not the first one's", () => {
+    // Two scenes sharing `<video id="clip">`. Resolving by author id returned
+    // scene-a's frame for both, so scene-b read another clip's pixels.
+    document.body.innerHTML =
+      `<video id="clip" ${MEDIA_RENDER_ID_ATTR}="clip"></video>` +
+      `<img id="__render_frame_clip__" class="__render_frame__">` +
+      `<video id="clip" ${MEDIA_RENDER_ID_ATTR}="clip__hf2"></video>` +
+      `<img id="__render_frame_clip__hf2__" class="__render_frame__">`;
+
+    const [first, second] = Array.from(document.querySelectorAll("video"));
+    expect(findInjectedRenderFrame(first!)?.id).toBe("__render_frame_clip__");
+    expect(findInjectedRenderFrame(second!)?.id).toBe("__render_frame_clip__hf2__");
+  });
+
+  it("still resolves by author id when the document was never compiled", () => {
+    document.body.innerHTML =
+      '<video id="solo"></video><img id="__render_frame_solo__" class="__render_frame__">';
+    expect(findInjectedRenderFrame(document.querySelector("video")!)?.id).toBe(
+      "__render_frame_solo__",
+    );
+  });
+
+  it("returns null in preview, where no sibling exists", () => {
+    document.body.innerHTML = '<video id="solo"></video>';
+    expect(findInjectedRenderFrame(document.querySelector("video")!)).toBeNull();
+  });
+});