fix(core,producer): resolve relative data-start id-refs in render compile

Author: valeriangalliat

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

@@ -133,6 +133,17 @@ describe("compileTimingAttrs", () => {
     expect(compiled).not.toContain("data-hf-auto-start");
   });
 
+  it("leaves data-end off a relative data-start id-ref", () => {
+    const html =
+      '<video id="intro" src="a.mp4" data-start="0" data-duration="10">' +
+      '<video id="main" src="b.mp4" data-start="intro" data-duration="20">';
+    const { html: compiled } = compileTimingAttrs(html);
+
+    expect(compiled).toContain('data-start="intro"');
+    expect(compiled).not.toMatch(/id="main"[^>]*data-end=/);
+    expect(compiled).toMatch(/id="intro"[^>]*data-end="10"/);
+  });
+
   it("compiles audio tags the same as video (minus data-has-audio)", () => {
     const html = '<audio id="a1" src="music.mp3" data-start="0" data-duration="10">';
     const { html: compiled } = compileTimingAttrs(html);
@@ -229,6 +240,15 @@ describe("injectDurations", () => {
     // data-duration already present, should not be duplicated
     expect(result).toContain('data-duration="3"');
   });
+
+  it("injects data-duration but not data-end when data-start is a relative id-ref", () => {
+    const html = '<video id="main" src="b.mp4" data-start="intro">';
+    const result = injectDurations(html, [{ id: "main", duration: 5 }]);
+
+    expect(result).toContain('data-duration="5"');
+    expect(result).toContain('data-start="intro"');
+    expect(result).not.toMatch(/data-end=/);
+  });
 });
 
 describe("extractResolvedMedia", () => {

packages/core/src/compiler/timingCompiler.ts

@@ -2,7 +2,7 @@
  * Timing Compiler
  *
  * Shared, pure HTML compilation that normalizes timing attributes.
- * Works in both Node.js and browser (no dependencies, regex-based).
+ * Works in both Node.js and browser (regex-based, no DOM).
  *
  * Guarantees every timed element gets:
  * - id on media elements when missing
@@ -13,14 +13,17 @@
  * this compiler identifies them as "unresolved" so the caller can provide
  * durations via an environment-specific resolver (ffprobe, el.duration, etc.)
  * and call injectDurations() to complete the compilation.
+ *
+ * Relative `data-start` (`intro`, `intro + 0.5`) is not numeric — leave
+ * `data-end` off so extract can resolve the id-ref later.
  */
 
+import { parseNumeric } from "@hyperframes/parsers/composition-contract";
 import {
   parseStrictFiniteTimingNumber,
   readElementPlaybackRate,
   readMediaStart,
 } from "../runtime/playbackRate.js";
-
 // ── Types ────────────────────────────────────────────────────────────────
 
 export interface UnresolvedElement {
@@ -149,25 +152,26 @@ function compileTag(
     result = injectAttr(result, "data-hf-auto-start", "");
     startStr = "0";
   }
-  const start = parseFloat(startStr);
+  const start = parseNumeric(startStr);
   const attrReader = { getAttribute: (name: string) => getAttr(result, name) };
   const mediaStart = readMediaStart(attrReader);
   const playbackRate = readElementPlaybackRate(attrReader);
 
-  // 1. Compute data-end from data-start + data-duration
+  // 1. Compute data-end from data-start + data-duration. Skip relative id-refs.
   if (!hasAttr(result, "data-end")) {
     const durationStr = getAttr(result, "data-duration");
     const duration = parseStrictFiniteTimingNumber(durationStr);
     if (duration != null) {
-      const end = start + duration;
-      result = injectAttr(result, "data-end", String(end));
+      if (start != null) {
+        result = injectAttr(result, "data-end", String(start + duration));
+      }
     } else if (id) {
       // No data-duration: mark as unresolved so caller can provide it
       unresolved = {
         id,
         tagName: isVideo ? "video" : "audio",
         src: getAttr(result, "src") ?? undefined,
-        start,
+        start: start ?? 0,
         mediaStart,
         playbackRate,
       };
@@ -229,7 +233,7 @@ export function compileTimingAttrs(html: string): CompilationResult {
       unresolved.push({
         id,
         tagName: "div",
-        start: startStr ? parseFloat(startStr) : 0,
+        start: parseNumeric(startStr) ?? 0,
         mediaStart: 0,
         playbackRate: 1,
         compositionSrc: compositionSrc ?? undefined,
@@ -262,11 +266,12 @@ export function injectDurations(html: string, resolutions: ResolvedDuration[]):
         result = setAttr(result, "data-duration", String(duration));
       }
 
-      // Add data-end if missing
+      // Add data-end if missing. Skip relative id-refs.
       if (!hasAttr(result, "data-end")) {
-        const startStr = getAttr(result, "data-start");
-        const start = startStr ? parseFloat(startStr) : 0;
-        result = injectAttr(result, "data-end", String(start + duration));
+        const start = parseNumeric(getAttr(result, "data-start"));
+        if (start != null) {
+          result = injectAttr(result, "data-end", String(start + duration));
+        }
       }
 
       return result;
@@ -307,7 +312,7 @@ export function extractResolvedMedia(html: string): ResolvedMediaElement[] {
       id,
       tagName: isVideo ? "video" : "audio",
       src: getAttr(tag, "src") ?? undefined,
-      start: startStr !== null ? parseFloat(startStr) : 0,
+      start: parseNumeric(startStr) ?? 0,
       duration,
       mediaStart: readMediaStart(attrReader),
       playbackRate: readElementPlaybackRate(attrReader),
@@ -331,10 +336,10 @@ export function clampDurations(html: string, clamps: ResolvedDuration[]): string
       // Replace data-duration value
       tag = tag.replace(/data-duration=["'][^"']*["']/, `data-duration="${duration}"`);
 
-      // Recompute data-end from data-start + clamped duration
-      const startStr = getAttr(tag, "data-start");
-      const start = startStr ? parseFloat(startStr) : 0;
-      tag = tag.replace(/data-end=["'][^"']*["']/, `data-end="${start + duration}"`);
+      const start = parseNumeric(getAttr(tag, "data-start"));
+      if (start != null) {
+        tag = tag.replace(/data-end=["'][^"']*["']/, `data-end="${start + duration}"`);
+      }
 
       return tag;
     });

packages/engine/src/index.ts

@@ -211,6 +211,8 @@ export {
   isVideoFrameFormat,
 } from "./services/videoFrameExtractor.js";
 
+export { resolveReferencedStart, type RefResolverEl } from "./services/referenceResolver.js";
+
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
 
 export {

packages/engine/src/services/videoFrameExtractor.test.ts

@@ -57,6 +57,7 @@ import {
 import { runFfmpeg } from "../utils/runFfmpeg.js";
 import { COMPLETE_SENTINEL, GC_MARKER, SCHEMA_PREFIX } from "./extractionCache.js";
 import { resolveRuntimeMediaClipDuration } from "../../../core/src/runtime/media.js";
+import { compileTimingAttrs } from "@hyperframes/core";
 
 // ffmpeg is not preinstalled on GitHub's ubuntu-24.04 runners. The producer
 // regression test at packages/producer/tests/vfr-screen-recording/ runs inside
@@ -804,6 +805,16 @@ describe("parseVideoElements", () => {
     expect(main?.end).toBe(30);
   });
 
+  it("still resolves relative data-start after compileTimingAttrs", () => {
+    const raw =
+      '<video id="intro" src="a.mp4" data-start="0" data-duration="10"></video>' +
+      '<video id="main" src="b.mp4" data-start="intro" data-duration="20"></video>';
+    const { html } = compileTimingAttrs(raw);
+    const main = parseVideoElements(html).find((v) => v.id === "main");
+    expect(main?.start).toBe(10);
+    expect(main?.end).toBe(30);
+  });
+
   it("applies + and - offsets on a relative reference", () => {
     const videos = parseVideoElements(
       '<video id="intro" src="a.mp4" data-start="0" data-duration="10"></video>' +

packages/producer/src/services/htmlCompiler.test.ts

@@ -1050,6 +1050,7 @@ describe("template-wrapped sub-composition media offsets", () => {
     hostAttrs: string,
     mediaAttrs: string = 'data-start="0" data-duration="4"',
     extraMediaMarkup: string = "",
+    extraRootMarkup: string = "",
   ): {
     projectDir: string;
     indexPath: string;
@@ -1071,6 +1072,7 @@ describe("template-wrapped sub-composition media offsets", () => {
       data-height="360"
       data-duration="4"
     >
+      ${extraRootMarkup}
       <div
         id="scene-host"
         data-composition-id="scene"
@@ -1136,6 +1138,21 @@ describe("template-wrapped sub-composition media offsets", () => {
     });
   });
 
+  it("resolves a host data-start id-ref against a sibling clip", async () => {
+    const { projectDir, indexPath } = writeTemplateWrappedProject(
+      'data-start="intro" data-duration="2" data-width="640" data-height="360"',
+      'data-start="0" data-duration="4"',
+      "",
+      '<video id="intro" src="assets/clip.mp4" data-start="0" data-duration="10" muted></video>',
+    );
+
+    const compiled = await compileForRender(projectDir, indexPath, projectDir);
+    expect(compiled.videos.find((v) => v.id === "scene-video")).toMatchObject({
+      start: 10,
+      end: 14,
+    });
+  });
+
   it("preserves first-pass media offsets when durations are resolved after inlining", async () => {
     const { projectDir, indexPath } = writeTemplateWrappedProject(
       'data-start="2" data-width="640" data-height="360"',

packages/producer/src/services/renderMediaCollector.ts

@@ -20,6 +20,8 @@ import {
   parseVideoElements,
   parseImageElements,
   parseAudioElements,
+  resolveReferencedStart,
+  type RefResolverEl,
   type VideoElement,
   type ImageElement,
   type AudioElement,
@@ -56,7 +58,12 @@ function parseNumeric(value: string | null): number | null {
  * carrying just `data-duration` was unbounded there too, and widening that here
  * would silently retime existing compositions rather than fix identity.
  */
-function resolveHostWindow(element: Element): HostWindow {
+function resolveHostWindow(
+  element: Element,
+  doc: { getElementById(id: string): RefResolverEl | null; querySelector(selector: string): RefResolverEl | null },
+  startCache: Map<RefResolverEl, number>,
+  visiting: Set<RefResolverEl>,
+): HostWindow {
   const hosts: Element[] = [];
   for (let ancestor = element.parentElement; ancestor; ancestor = ancestor.parentElement) {
     if (ancestor.hasAttribute(COMPOSITION_HOST_ATTR)) hosts.push(ancestor);
@@ -67,7 +74,7 @@ function resolveHostWindow(element: Element): HostWindow {
   let limit = Infinity;
   // parentElement walks leaf → root; the offsets accumulate root → leaf.
   for (const host of hosts.reverse()) {
-    const hostStart = parseNumeric(host.getAttribute("data-start")) ?? 0;
+    const hostStart = resolveReferencedStart(doc, host, startCache, visiting);
     const hostEnd = parseNumeric(host.getAttribute("data-end"));
     if (hostEnd != null) limit = Math.min(limit, offset + hostEnd);
     offset += hostStart;
@@ -82,11 +89,16 @@ function resolveHostWindow(element: Element): HostWindow {
  */
 function collectHostWindows(html: string): Map<string, HostWindow> {
   const { document } = parseHTML(html);
+  const startCache = new Map<RefResolverEl, number>();
+  const visiting = new Set<RefResolverEl>();
   const windows = new Map<string, HostWindow>();
   for (const element of document.querySelectorAll(`[${MEDIA_RENDER_ID_ATTR}]`)) {
     const renderId = element.getAttribute(MEDIA_RENDER_ID_ATTR);
     if (!renderId) continue;
-    windows.set(renderId, resolveHostWindow(element as unknown as Element));
+    windows.set(
+      renderId,
+      resolveHostWindow(element as unknown as Element, document, startCache, visiting),
+    );
   }
   return windows;
 }