feat(studio): carry hfId on TimelineElement, wire through buildPatchTarget (R7, T5b)

Author: vanceingalls

packages/studio/src/hooks/useTimelineEditing.ts

@@ -45,9 +45,22 @@ interface UseTimelineEditingOptions {
 
 // ── Helpers ──
 
-function buildPatchTarget(element: { domId?: string; selector?: string; selectorIndex?: number }) {
+function buildPatchTarget(element: {
+  domId?: string;
+  hfId?: string;
+  selector?: string;
+  selectorIndex?: number;
+}) {
   if (element.domId) {
-    return { id: element.domId, selector: element.selector, selectorIndex: element.selectorIndex };
+    return {
+      id: element.domId,
+      hfId: element.hfId,
+      selector: element.selector,
+      selectorIndex: element.selectorIndex,
+    };
+  }
+  if (element.hfId) {
+    return { hfId: element.hfId, selector: element.selector, selectorIndex: element.selectorIndex };
   }
   if (element.selector) {
     return { selector: element.selector, selectorIndex: element.selectorIndex };

packages/studio/src/player/lib/timelineDOM.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import { parseTimelineFromDOM, createImplicitTimelineLayersFromDOM } from "./timelineDOM";
+
+function makeDoc(html: string): Document {
+  const d = document.implementation.createHTMLDocument();
+  d.body.innerHTML = html;
+  return d;
+}
+
+describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
+  it("harvests hfId from a data-start element that has data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="hero" class="clip" data-start="0" data-duration="5" data-hf-id="hf-abc123"></div>
+      </div>
+    `);
+
+    const elements = parseTimelineFromDOM(doc, 10);
+    const hero = elements.find((el) => el.domId === "hero");
+
+    expect(hero).toBeDefined();
+    expect(hero?.hfId).toBe("hf-abc123");
+  });
+
+  it("leaves hfId undefined when element has no data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="plain" class="clip" data-start="0" data-duration="5"></div>
+      </div>
+    `);
+
+    const elements = parseTimelineFromDOM(doc, 10);
+    const plain = elements.find((el) => el.domId === "plain");
+
+    expect(plain).toBeDefined();
+    expect(plain?.hfId).toBeUndefined();
+  });
+});
+
+describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
+  it("harvests hfId from an implicit layer child that has data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="layer" class="clip" data-hf-id="hf-xyz789"></div>
+      </div>
+    `);
+
+    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
+    const layer = layers.find((el) => el.domId === "layer");
+
+    expect(layer).toBeDefined();
+    expect(layer?.hfId).toBe("hf-xyz789");
+  });
+});

packages/studio/src/player/lib/timelineDOM.ts

@@ -72,8 +72,10 @@ export function createTimelineElementFromManifestClip(params: {
   let selectorIndex: number | undefined;
   let sourceFile: string | undefined;
 
+  let hfId: string | undefined;
   if (hostEl) {
     domId = hostEl.id || undefined;
+    hfId = hostEl.getAttribute("data-hf-id") ?? undefined;
     selector = getTimelineElementSelector(hostEl);
     selectorIndex =
       doc && selector ? getTimelineElementSelectorIndex(doc, hostEl, selector) : undefined;
@@ -98,6 +100,7 @@ export function createTimelineElementFromManifestClip(params: {
     duration: clip.duration,
     track: clip.track,
     domId,
+    hfId,
     selector,
     selectorIndex,
     sourceFile,
@@ -127,6 +130,7 @@ export function createTimelineElementFromManifestClip(params: {
     }
     if (hostEl) {
       entry.domId = hostEl.id || undefined;
+      entry.hfId = hostEl.getAttribute("data-hf-id") ?? undefined;
       entry.selector = getTimelineElementSelector(hostEl);
       entry.selectorIndex =
         doc && entry.selector
@@ -187,6 +191,7 @@ export function createImplicitTimelineLayersFromDOM(
 
     layers.push({
       domId: child.id || undefined,
+      hfId: child.getAttribute("data-hf-id") ?? undefined,
       duration: rootDuration,
       id: identity.id,
       key: identity.key,
@@ -262,6 +267,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       duration: dur,
       track: isNaN(track) ? 0 : track,
       domId: el.id || undefined,
+      hfId: el.getAttribute("data-hf-id") ?? undefined,
       selector,
       selectorIndex,
       sourceFile,

packages/studio/src/player/store/playerStore.ts

@@ -22,6 +22,8 @@ export interface TimelineElement {
   duration: number;
   track: number;
   domId?: string;
+  /** Stable `data-hf-id` attribute value — used as primary patch target when present */
+  hfId?: string;
   /** Best-effort selector used when patching source HTML back from timeline edits */
   selector?: string;
   /** Zero-based occurrence index for non-unique selectors */