@hyperframes/studio 0.8.30 → 0.8.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.30",
+  "version": "0.8.32",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/player": "0.8.30",
-    "@hyperframes/core": "0.8.30",
-    "@hyperframes/sdk": "0.8.30",
-    "@hyperframes/studio-server": "0.8.30",
-    "@hyperframes/parsers": "0.8.30"
+    "@hyperframes/core": "0.8.32",
+    "@hyperframes/parsers": "0.8.32",
+    "@hyperframes/player": "0.8.32",
+    "@hyperframes/studio-server": "0.8.32",
+    "@hyperframes/sdk": "0.8.32"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.30"
+    "@hyperframes/producer": "0.8.32"
   },
   "peerDependencies": {
     "react": "19",

package/src/player/components/timelineAuthoredMoveTarget.ts

@@ -10,6 +10,7 @@ export function canMoveTimelineElement(element: TimelineElement): boolean {
     kind: element.kind,
     duration: element.duration,
     domId: element.domId,
+    hfId: element.hfId,
     selector: element.selector,
     compositionSrc: element.compositionSrc,
     playbackStart: element.playbackStart,

package/src/player/components/timelineEditCapabilities.ts

@@ -23,8 +23,12 @@ function isDeterministicTimelineWindow(input: {
   return ["video", "audio", "img"].includes(input.tag.toLowerCase());
 }
 
-export function hasPatchableTimelineTarget(input: { domId?: string; selector?: string }): boolean {
-  return Boolean(input.domId || input.selector);
+export function hasPatchableTimelineTarget(input: {
+  domId?: string;
+  hfId?: string;
+  selector?: string;
+}): boolean {
+  return Boolean(input.domId || input.hfId || input.selector);
 }
 
 export function getTimelineEditCapabilities(input: {
@@ -32,6 +36,7 @@ export function getTimelineEditCapabilities(input: {
   kind?: "video" | "audio" | "image" | "element" | "composition";
   duration: number;
   domId?: string;
+  hfId?: string;
   selector?: string;
   compositionSrc?: string;
   playbackStart?: number;

package/src/player/components/timelineGroupEditing.ts

@@ -192,6 +192,7 @@ function canTrimEdge(element: TimelineElement, edge: TimelineGroupResizeEdge): b
     kind: element.kind,
     duration: element.duration,
     domId: element.domId,
+    hfId: element.hfId,
     selector: element.selector,
     compositionSrc: element.compositionSrc,
     playbackStart: element.playbackStart,

package/src/player/hooks/timelineDomBinding.test.ts

@@ -0,0 +1,122 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import { Window } from "happy-dom";
+import { buildTimelineElementsFromClips } from "./timelineSyncHydration";
+import { findTimelineDomNodeForClip } from "../lib/timelineElementHelpers";
+import { canMoveTimelineElement } from "../components/timelineAuthoredMoveTarget";
+import { buildTimelineGroupResizeMembers } from "../components/timelineGroupEditing";
+import { getTimelineEditCapabilities } from "../components/timelineEditCapabilities";
+import type { ClipManifestClip } from "../lib/playbackTypes";
+
+const clip = (overrides: Partial<ClipManifestClip> = {}): ClipManifestClip => ({
+  id: null,
+  label: "",
+  start: 0,
+  duration: 4,
+  track: 0,
+  kind: "element",
+  tagName: "div",
+  compositionId: null,
+  parentCompositionId: null,
+  compositionSrc: null,
+  assetUrl: null,
+  ...overrides,
+});
+function documentWith(body: string): Document {
+  const window = new Window();
+  Object.assign(window, { SyntaxError });
+  window.document.body.innerHTML = `<div data-composition-id="main" data-duration="10">${body}</div>`;
+  return window.document;
+}
+describe("live DOM manifest hydration", () => {
+  it("carries hfId through authored move and group trim capability callers", () => {
+    const elements = ["a", "b"].map((id) => ({
+      id,
+      key: id,
+      tag: "div",
+      start: 0,
+      duration: 4,
+      track: 0,
+      hfId: id,
+    }));
+    expect(canMoveTimelineElement(elements[0])).toBe(true);
+    for (const edge of ["start", "end"] as const) {
+      expect(
+        buildTimelineGroupResizeMembers(elements, new Set(["a", "b"]), "a", edge),
+      ).toHaveLength(2);
+    }
+  });
+  it("does not bind a cross-tag direct identity", () => {
+    const doc = documentWith('<div id="collision" data-start="0" data-duration="4"></div>');
+    expect(
+      findTimelineDomNodeForClip(doc, clip({ id: "collision", tagName: "img" }), 0),
+    ).toBeNull();
+  });
+  it("does not let an unmatched image steal the scene's editable identity", () => {
+    const doc = documentWith(
+      '<div class="clip scene" data-hf-id="scene-hf" data-start="2" data-duration="4"></div>',
+    );
+    const elements = buildTimelineElementsFromClips(
+      [clip({ id: "missing", tagName: "img", kind: "image" }), clip({ start: 2 })],
+      doc,
+    );
+    expect(elements[0].hfId).toBeUndefined();
+    expect(elements[1].hfId).toBe("scene-hf");
+    expect(getTimelineEditCapabilities(elements[1]).canMove).toBe(true);
+  });
+  it("allows hfId-only authored clips to move and trim while preserving locks", () => {
+    const input = { tag: "div", duration: 4, hfId: "scene-hf" };
+    expect(getTimelineEditCapabilities(input)).toEqual({
+      canMove: true,
+      canTrimStart: true,
+      canTrimEnd: true,
+    });
+    expect(getTimelineEditCapabilities({ ...input, timelineLocked: true }).canMove).toBe(false);
+    expect(getTimelineEditCapabilities({ ...input, timingSource: "implicit" }).canTrimEnd).toBe(
+      false,
+    );
+  });
+  it("uses at most one fallback candidate snapshot per hydration pass", () => {
+    const doc = documentWith(
+      Array.from(
+        { length: 300 },
+        (_, i) => `<div data-hf-id="h${i}" data-start="${i}" data-duration="4"></div>`,
+      ).join(""),
+    );
+    const query = vi.spyOn(doc, "querySelectorAll");
+    const clips = Array.from({ length: 300 }, (_, i) => clip({ start: i }));
+    expect(new Set(buildTimelineElementsFromClips(clips, doc).map((e) => e.hfId)).size).toBe(300);
+    expect(query.mock.calls.filter(([selector]) => selector === "[data-start]")).toHaveLength(1);
+  });
+  it("avoids candidate scans for hundreds of direct DOM and hf identities", () => {
+    const doc = documentWith(
+      Array.from(
+        { length: 300 },
+        (_, i) =>
+          `<div ${i % 2 ? "id" : "data-hf-id"}="direct${i}" data-start="${i}" data-duration="4"></div>`,
+      ).join(""),
+    );
+    const query = vi.spyOn(doc, "querySelectorAll");
+    const clips = Array.from({ length: 300 }, (_, i) => clip({ id: `direct${i}`, start: i }));
+    expect(buildTimelineElementsFromClips(clips, doc)).toHaveLength(300);
+    expect(query.mock.calls.filter(([selector]) => selector === "[data-start]")).toHaveLength(0);
+  });
+  it("resolves hf identities without a fallback scan and refreshes after DOM replacement", () => {
+    const doc = documentWith('<div data-hf-id="stable" data-start="2" data-duration="4"></div>');
+    const query = vi.spyOn(doc, "querySelectorAll");
+    const clips = [clip({ id: "stable", start: 0 })];
+    expect(buildTimelineElementsFromClips(clips, doc)[0].hfId).toBe("stable");
+    expect(query.mock.calls.filter(([selector]) => selector === "[data-start]")).toHaveLength(0);
+    doc.querySelector("[data-composition-id]")!.innerHTML =
+      '<div data-hf-id="replacement" data-start="2" data-duration="4"></div>';
+    expect(buildTimelineElementsFromClips([clip({ start: 2 })], doc)[0].hfId).toBe("replacement");
+  });
+  it("preserves DOM-id precedence and same-tag positional recovery after timing drift", () => {
+    const doc = documentWith(
+      '<div id="stable" data-start="5"></div><div data-hf-id="stable" data-start="0"></div>',
+    );
+    expect(findTimelineDomNodeForClip(doc, clip({ id: "stable" }), 0)?.id).toBe("stable");
+    expect(findTimelineDomNodeForClip(doc, clip({ start: 9 }), 0)?.id).toBe("stable");
+  });
+});

package/src/player/hooks/timelineSyncHydration.ts

@@ -9,6 +9,7 @@
  * an argument, so each is callable — and readable — on its own.
  */
 
+import { createTimelineDomNodeResolver } from "../lib/timelineElementHelpers";
 import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
@@ -20,7 +21,6 @@ import {
   buildStandaloneRootTimelineElement,
   createImplicitTimelineLayersFromDOM,
   createTimelineElementFromManifestClip,
-  findTimelineDomNodeForClip,
   getTimelineElementSelector,
   parseTimelineFromDOM,
 } from "../lib/timelineDOM";
@@ -195,19 +195,16 @@ export function safeContentDocument(iframe: HTMLIFrameElement | null): Document
 
 /**
  * The manifest's root clips as TimelineElements, each bound to the live DOM node
- * it was authored as. `usedHostEls` makes the binding one-to-one: two clips with
+ * it was authored as. The pass-scoped resolver makes the binding one-to-one: two clips with
  * the same shape must not both claim the same element.
  */
 export function buildTimelineElementsFromClips(
   clips: readonly ClipManifestClip[],
   iframeDoc: Document | null,
 ): TimelineElement[] {
-  const usedHostEls = new Set<Element>();
+  const resolveHost = iframeDoc ? createTimelineDomNodeResolver(iframeDoc) : null;
   return clips.map((clip, index) => {
-    const hostEl = iframeDoc
-      ? findTimelineDomNodeForClip(iframeDoc, clip, index, usedHostEls)
-      : null;
-    if (hostEl) usedHostEls.add(hostEl);
+    const hostEl = resolveHost?.(clip, index) ?? null;
     return createTimelineElementFromManifestClip({
       clip,
       fallbackIndex: index,

package/src/player/lib/timelineElementHelpers.ts

@@ -413,9 +413,12 @@ const MANIFEST_CLIP_ATTRS: ReadonlyArray<[string, (clip: ClipManifestClip) => nu
   ["data-track-index", (clip) => clip.track],
 ];
 
+function nodeMatchesClipTag(node: Element, clip: ClipManifestClip): boolean {
+  return !clip.tagName || node.tagName.toLowerCase() === clip.tagName.toLowerCase();
+}
+
 function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean {
-  const tagName = clip.tagName?.toLowerCase();
-  if (tagName && node.tagName.toLowerCase() !== tagName) return false;
+  if (!nodeMatchesClipTag(node, clip)) return false;
   // An attribute only constrains the match when it parses to a finite number:
   // missing or garbled reads as "unknown", not "mismatch".
   return MANIFEST_CLIP_ATTRS.every(([attr, expected]) => {
@@ -427,6 +430,7 @@ function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean
 function findTimelineDomNode(doc: Document, id: string): Element | null {
   return (
     doc.getElementById(id) ??
+    doc.querySelector(`[data-hf-id="${CSS.escape(id)}"]`) ??
     doc.querySelector(`[data-composition-id="${CSS.escape(id)}"]`) ??
     doc.querySelector(`.${CSS.escape(id)}`) ??
     null
@@ -438,15 +442,30 @@ export function findTimelineDomNodeForClip(
   clip: ClipManifestClip,
   fallbackIndex: number,
   usedNodes = new Set<Element>(),
+  getCandidates = () => getTimelineDomNodes(doc),
 ): Element | null {
   const byIdentity = clip.id ? findTimelineDomNode(doc, clip.id) : null;
-  if (byIdentity && !usedNodes.has(byIdentity)) return byIdentity;
+  if (byIdentity && !usedNodes.has(byIdentity) && nodeMatchesClipTag(byIdentity, clip))
+    return byIdentity;
 
-  const candidates = getTimelineDomNodes(doc).filter((node) => !usedNodes.has(node));
+  const candidates = getCandidates().filter((node) => !usedNodes.has(node));
   const exact = candidates.find((node) => nodeMatchesManifestClip(node, clip));
   if (exact) return exact;
 
-  return candidates[fallbackIndex] ?? null;
+  const positional = candidates[fallbackIndex];
+  return positional && nodeMatchesClipTag(positional, clip) ? positional : null;
+}
+
+/** One synchronous hydration pass: snapshot only on a miss, never across reloads. */
+export function createTimelineDomNodeResolver(doc: Document) {
+  let candidates: Element[] | undefined;
+  const usedNodes = new Set<Element>();
+  const getCandidates = () => (candidates ??= getTimelineDomNodes(doc));
+  return (clip: ClipManifestClip, index: number): Element | null => {
+    const node = findTimelineDomNodeForClip(doc, clip, index, usedNodes, getCandidates);
+    if (node) usedNodes.add(node);
+    return node;
+  };
 }
 
 // ---------------------------------------------------------------------------