@hyperframes/studio 0.8.76 → 0.8.78

package/src/components/nle/previewZoom.ts

@@ -17,6 +17,12 @@ export const DEFAULT_PREVIEW_ZOOM: PreviewZoomState = {
 const ZOOM_SENSITIVITY = 0.007;
 const MAX_DELTA = 10;
 
+export const isFitZoom = (zoomPercent: number) => Math.abs(zoomPercent - 100) < 0.5;
+
+export function isPreviewAtFit(state: PreviewZoomState): boolean {
+  return isFitZoom(state.zoomPercent) && Math.abs(state.panX) < 0.1 && Math.abs(state.panY) < 0.1;
+}
+
 export function toDomPrecision(value: number): number {
   return Math.round(value * 10000) / 10000;
 }
@@ -162,3 +168,30 @@ export function resolvePreviewWheelPan(input: {
     ...pan,
   };
 }
+
+export interface PreviewVisibleRegion {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export function resolvePreviewVisibleRegion(input: {
+  state: PreviewZoomState;
+  viewportWidth: number;
+  viewportHeight: number;
+  contentWidth: number;
+  contentHeight: number;
+}): PreviewVisibleRegion {
+  const scale = clampPreviewZoomPercent(input.state.zoomPercent) / 100;
+  const axis = (pan: number, view: number, content: number): [number, number] => {
+    const size = content * scale;
+    if (!(size > 0)) return [0, 1];
+    const at = (edge: number) => Math.min(1, Math.max(0, (edge - pan + size / 2) / size));
+    const start = at(-view / 2);
+    return [start, at(view / 2) - start];
+  };
+  const [left, width] = axis(input.state.panX, input.viewportWidth, input.contentWidth);
+  const [top, height] = axis(input.state.panY, input.viewportHeight, input.contentHeight);
+  return { left, top, width, height };
+}

package/src/hooks/useDomEditWiring.ts

@@ -207,9 +207,7 @@ export function useDomEditWiring(params: UseDomEditWiringParams) {
   } = useGsapAnimationsForElement(
     projectId ?? null,
     gsapSourceFile,
-    domEditSelection
-      ? { id: domEditSelection.id ?? null, selector: domEditSelection.selector ?? null }
-      : null,
+    domEditSelection,
     gsapCacheVersion,
     // Pass the preview iframe so class/selector tweens (e.g. `.dot`) resolve to
     // the live element and surface in the inspector — not just by #id match.

package/src/hooks/useGestureRecording.test.tsx

@@ -109,7 +109,7 @@ describe("useGestureRecording", () => {
     act(() => root.unmount());
 
     expect(cancelAnimationFrame).toHaveBeenCalledWith(17);
-    expect(set).toHaveBeenCalledWith("#card", {
+    expect(set).toHaveBeenCalledWith(element, {
       clearProps: "x,y,scale,scaleX,scaleY,rotation,rotationX,rotationY,opacity,z",
     });
     expect(element.style.visibility).toBe("hidden");

package/src/hooks/useGestureRecording.ts

@@ -30,8 +30,7 @@ interface BasePosition {
 
 interface GsapRuntime {
   timeline: { seek: (t: number) => void };
-  gsap: { set: (target: string, vars: Record<string, number | string>) => void };
-  selector: string;
+  gsap: { set: (target: Element, vars: Record<string, number | string>) => void };
   element: HTMLElement;
   startTime: number;
   maxSeekTime: number;
@@ -81,12 +80,11 @@ function readBasePosition(element: HTMLElement, iframeEl: HTMLIFrameElement): Ba
 function connectGsapRuntime(
   element: HTMLElement,
   iframeEl: HTMLIFrameElement,
-  selector: string | null,
   elementEndTime: number | undefined,
 ): GsapRuntime | null {
   try {
     const win = iframeEl.contentWindow as Window & {
-      gsap?: { set: (t: string, v: Record<string, number | string>) => void };
+      gsap?: { set: (t: Element, v: Record<string, number | string>) => void };
       __timelines?: Record<string, { seek: (t: number) => void; duration: () => number }>;
       __player?: { getTime: () => number };
     };
@@ -98,12 +96,11 @@ function connectGsapRuntime(
           ([key, value]) => key !== "__proxied" && typeof value?.seek === "function",
         )?.[1] ?? null)
       : null;
-    if (win?.gsap?.set && tl?.seek && selector) {
+    if (win?.gsap?.set && tl?.seek && element.id) {
       const tlDuration = tl.duration();
       return {
         timeline: tl,
         gsap: win.gsap,
-        selector,
         element,
         startTime: win.__player?.getTime() ?? 0,
         maxSeekTime:
@@ -126,7 +123,7 @@ function applyRuntimePreview(
   const seekTime = Math.min(runtime.startTime + time, runtime.maxSeekTime);
   runtime.timeline.seek(seekTime);
   runtime.element.style.setProperty("translate", "none");
-  runtime.gsap.set(runtime.selector, { ...properties });
+  runtime.gsap.set(runtime.element, { ...properties });
   runtime.element.style.visibility = "visible";
   liveTime.notify(seekTime);
   usePlayerStore.getState().setCurrentTime(seekTime);
@@ -256,7 +253,7 @@ function releaseRuntimePreview(r: RecordingRefs): void {
   element.style.visibility = savedVisibility;
   element.style.setProperty("translate", savedTranslate || "");
   try {
-    runtime.gsap.set(runtime.selector, {
+    runtime.gsap.set(runtime.element, {
       clearProps: "x,y,scale,scaleX,scaleY,rotation,rotationX,rotationY,opacity,z",
     });
   } catch {
@@ -324,8 +321,7 @@ export function useGestureRecording() {
       r.scale = computeIframeScale(iframeEl);
 
       // --- Phase 3: Connect to the iframe GSAP runtime ---
-      const selector = element.id ? `#${element.id}` : null;
-      r.runtime = connectGsapRuntime(element, iframeEl, selector, elementEndTime);
+      r.runtime = connectGsapRuntime(element, iframeEl, elementEndTime);
       // Clear the optimistic path offset only while a live runtime owns the
       // preview. releaseRuntimePreview restores it on every exit path.
       if (r.runtime && (base.cssOffX || base.cssOffY)) {

package/src/hooks/useGsapTweenCache.element.test.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+
+installReactActEnvironment();
+
+const dotTween = {
+  id: "dots",
+  targetSelector: ".dot",
+  method: "from",
+  position: 0,
+  properties: { opacity: 0 },
+} as GsapAnimation;
+vi.mock("./keyframeCacheAstLoad", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./keyframeCacheAstLoad")>()),
+  fetchParsedAnimations: async () => ({ animations: [dotTween] }),
+}));
+const { useGsapAnimationsForElement } = await import("./useGsapTweenCache");
+
+it("attributes a class tween by the selected element, not an earlier same-id copy in a sub-composition", async () => {
+  document.body.innerHTML =
+    '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><div id="card"></div></div>' +
+    '<div id="card" class="dot"></div>';
+  const element = document.querySelectorAll<HTMLElement>("#card")[1];
+  const selection = { id: "card", sourceFile: "index.html", element } as DomEditSelection;
+  const iframeRef = { current: { contentDocument: document } as unknown as HTMLIFrameElement };
+  let animations: GsapAnimation[] = [];
+  function Harness() {
+    animations = useGsapAnimationsForElement("p", "index.html", selection, 0, iframeRef).animations;
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  await act(async () => {});
+  expect(animations.map((animation) => animation.id)).toEqual(["dots"]);
+  act(() => root.unmount());
+});

package/src/hooks/useGsapTweenCache.ts

@@ -1,6 +1,8 @@
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import type { GsapAnimation, GsapKeyframesData } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { findPreviewNode } from "../components/editor/domEditingElement";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
 import {
   clearKeyframeCacheForElement,
@@ -73,7 +75,7 @@ export function getAnimationsForElement(
 export function useGsapAnimationsForElement(
   projectId: string | null,
   sourceFile: string,
-  target: GsapElementTarget | null,
+  target: DomEditSelection | null,
   version: number,
   iframeRef?: React.RefObject<HTMLIFrameElement | null>,
 ): {
@@ -157,24 +159,14 @@ export function useGsapAnimationsForElement(
     // gsap.from(".dot", {stagger})) attribute to every matching element, not
     // just the one whose exact selector equals the tween's. `version` re-runs
     // this after composition reloads.
-    let element: Element | null = null;
-    const doc = iframeRef?.current?.contentDocument;
-    if (doc) {
-      try {
-        element =
-          (targetId ? doc.getElementById(targetId) : null) ??
-          (targetSelector ? doc.querySelector(targetSelector) : null);
-      } catch {
-        element = null;
-      }
-    }
+    const element = target ? findPreviewNode(iframeRef?.current?.contentDocument, target) : null;
     return getAnimationsForElement(
       allAnimations,
       { id: targetId, selector: targetSelector },
       element,
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [allAnimations, targetId, targetSelector, version, iframeRef]);
+  }, [allAnimations, target, version, iframeRef]);
 
   // fallow-ignore-next-line complexity
   const animations = useMemo(() => {

package/src/index.ts

@@ -183,3 +183,10 @@ export type { TimelinePaneProps } from "./components/nle/TimelinePane";
 export { TimelineEditProvider } from "./contexts/TimelineEditContext";
 export type { TimelineEditCallbacks } from "./player/components/timelineCallbacks";
 export type { BlockedTimelineEditIntent } from "./player/components/timelineEditing";
+
+export {
+  playSeamTransitionLoop,
+  type SeamTransitionFrameSource,
+  type SeamTransitionLoopHandle,
+  type SeamTransitionLoopOptions,
+} from "@hyperframes/shader-transitions";

package/src/player/lib/automationStoreSync.test.ts

@@ -33,6 +33,30 @@ beforeEach(() => {
 });
 
 describe("syncStoredAutomationFromPreview", () => {
+  it("reads the element the timeline bound, not an earlier same-id copy in a sub-composition", () => {
+    usePlayerStore.setState({ elements: [el({ hfId: "hf-root" })] });
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="strip"><audio id="bgm" data-hf-id="hf-inner"></audio></div>' +
+      '<audio id="bgm" data-hf-id="hf-root"></audio>';
+    doc.querySelector('[data-hf-id="hf-inner"]')?.setAttribute("data-automation", TWO_POINTS);
+    doc.querySelector('[data-hf-id="hf-root"]')?.setAttribute("data-automation", RESTORED);
+    syncStoredAutomationFromPreview(doc);
+    expect(usePlayerStore.getState().elements[0]?.automation).toBe(RESTORED);
+  });
+
+  it("reads the copy in the element's own file when a sub-composition repeats its hf-id", () => {
+    usePlayerStore.setState({ elements: [el({ hfId: "hf-bgm" })] });
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="strip" data-composition-src="compositions/strip.html">' +
+      '<audio id="bgm" data-hf-id="hf-bgm"></audio></div><audio id="bgm" data-hf-id="hf-bgm"></audio>';
+    doc.querySelectorAll("audio")[0]?.setAttribute("data-automation", TWO_POINTS);
+    doc.querySelectorAll("audio")[1]?.setAttribute("data-automation", RESTORED);
+    syncStoredAutomationFromPreview(doc);
+    expect(usePlayerStore.getState().elements[0]?.automation).toBe(RESTORED);
+  });
+
   it("reads back an envelope an undo restored on the preview", () => {
     // The bug: a soft undo patches the preview document and re-runs the timeline, but
     // the store keeps its own copy of the attributes and that copy is what a lane

package/src/player/lib/automationStoreSync.ts

@@ -17,14 +17,7 @@ import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { groupInfoFor } from "./timelineGroupInfo";
-
-/** The preview node an element stands for, by dom id and then by `data-hf-id`. */
-function previewNodeFor(doc: Document, element: TimelineElement): Element | null {
-  const domId = element.domId ?? element.id;
-  const byId = domId ? doc.getElementById(domId) : null;
-  if (byId) return byId;
-  return element.hfId ? doc.querySelector(`[data-hf-id="${element.hfId}"]`) : null;
-}
+import { previewElementFinder } from "./timelineElementHelpers";
 
 /**
  * Re-read every element's automation and FX-chain attributes from the preview
@@ -62,10 +55,11 @@ function syncedFields(doc: Document, element: TimelineElement, node: Element) {
 
 export function syncStoredAutomationFromPreview(doc: Document | null | undefined): void {
   if (!doc) return;
+  const findNode = previewElementFinder(doc);
   usePlayerStore.setState((state) => {
     let changed = false;
     const elements = state.elements.map((element) => {
-      const node = previewNodeFor(doc, element);
+      const node = findNode(element);
       if (!node) return element;
       const fields = syncedFields(doc, element, node);
       // Same array back when nothing moved: `elements` keys memos all over the

package/src/player/lib/playbackScrub.ts

@@ -12,5 +12,5 @@ export function scrubMusicAtSeek(iframe: HTMLIFrameElement | null, nextTime: num
   if (!music || s.audioMuted) return;
   const rel = nextTime - music.start;
   const audioFileTime = rel >= 0 && rel <= music.duration ? (music.playbackStart ?? 0) + rel : null;
-  scrubPreviewAudio(iframe, audioFileTime, music.domId ?? music.id, s.audioVolume);
+  scrubPreviewAudio(iframe, audioFileTime, music, s.audioVolume);
 }

package/src/player/lib/timelineDOM.test.ts

@@ -285,6 +285,34 @@ describe("createTimelineElementFromManifestClip — source-scoped selector ident
     });
   });
 
+  it("keeps the host it was given when a sub-composition is mounted twice", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root" data-composition-file="index.html">
+        <div id="a" data-hf-id="hf-a" data-composition-id="card" data-composition-src="card.html"></div>
+        <div id="b" data-hf-id="hf-b" data-composition-id="card" data-composition-src="card.html"></div>
+      </div>
+    `);
+    const element = createTimelineElementFromManifestClip({
+      clip: {
+        id: "b",
+        label: "Card",
+        kind: "composition",
+        tagName: "div",
+        start: 4,
+        duration: 4,
+        track: 0,
+        compositionId: "card",
+        parentCompositionId: "root",
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 1,
+      doc,
+      hostEl: doc.getElementById("b"),
+    });
+    expect(element).toMatchObject({ domId: "b", hfId: "hf-b", compositionSrc: "card.html" });
+  });
+
   it("ignores an index.html duplicate when indexing a scene.html selector", () => {
     const doc = makeDoc(`
       <div data-composition-id="root" data-composition-file="index.html">

package/src/player/lib/timelineDOM.ts

@@ -171,8 +171,10 @@ export function createTimelineElementFromManifestClip(params: {
     entry.playbackRate ??= 1;
     let resolvedSrc = clip.compositionSrc;
     if (!resolvedSrc) {
-      hostEl =
-        doc?.querySelector(`[data-composition-id="${CSS.escape(clip.compositionId)}"]`) ?? hostEl;
+      if (hostEl?.getAttribute("data-composition-id") !== clip.compositionId) {
+        hostEl =
+          doc?.querySelector(`[data-composition-id="${CSS.escape(clip.compositionId)}"]`) ?? hostEl;
+      }
       resolvedSrc =
         hostEl?.getAttribute("data-composition-src") ??
         hostEl?.getAttribute("data-composition-file") ??

package/src/player/lib/timelineElementHelpers.ts

@@ -458,6 +458,39 @@ function findInClipScope(
   return lone;
 }
 
+export type PreviewTarget = Pick<TimelineElement, "hfId" | "domId" | "id" | "sourceFile">;
+
+/** Finds a row's preview element by `data-hf-id`, then id, preferring one in the row's own file: both repeat across
+ * files. Indexes the document once, so a pass over every row costs one scan. */
+export function previewElementFinder(
+  doc: Document,
+  selector = "[data-hf-id], [id]",
+): (target: PreviewTarget) => Element | null {
+  const byKey = new Map<string, Element[]>();
+  const add = (key: string, node: Element) => {
+    const nodes = byKey.get(key);
+    if (nodes) nodes.push(node);
+    else byKey.set(key, [node]);
+  };
+  for (const node of doc.querySelectorAll(selector)) {
+    const hfId = node.getAttribute("data-hf-id");
+    const id = node.getAttribute("id");
+    if (hfId) add(`hf:${hfId}`, node);
+    if (id) add(`id:${id}`, node);
+  }
+  return (target) => {
+    const matches = [
+      ...((target.hfId && byKey.get(`hf:${target.hfId}`)) || []),
+      ...(byKey.get(`id:${target.domId ?? target.id}`) ?? []),
+    ];
+    return (
+      matches.find((node) => getTimelineElementSourceFile(node) === target.sourceFile) ??
+      matches[0] ??
+      null
+    );
+  };
+}
+
 export function findClipElementById(doc: Document, clip: ClipManifestClip): Element | null {
   if (!clip.id) return null;
   const first = doc.getElementById(clip.id);

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -17,6 +17,31 @@ function makeDoc(html: string): Document {
 }
 
 describe("buildMissingCompositionElements — hfId (R7)", () => {
+  it("labels a row from its own host when a sub-composition repeats the host's id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main">
+        <div data-composition-id="strip" data-composition-src="compositions/strip.html"><div id="scene"></div></div>
+        <div id="scene" data-hf-id="hf-scene" data-composition-id="scene" data-composition-file="compositions/scene.html"></div>
+      </div>
+    `);
+    const row = {
+      id: "scene",
+      key: "scene",
+      tag: "div",
+      start: 0,
+      duration: 4,
+      track: 0,
+      hfId: "hf-scene",
+    };
+    const { updatedEls, patched } = buildMissingCompositionElements(
+      doc,
+      window as IframeWindow,
+      [row],
+      10,
+    );
+    expect([patched, updatedEls[0]?.compositionSrc]).toEqual([true, "compositions/scene.html"]);
+  });
+
   it("harvests hfId from data-hf-id on composition host elements", () => {
     const doc = makeDoc(`
       <div data-composition-id="root">
@@ -104,7 +129,7 @@ describe("scrubPreviewAudio", () => {
     audio.pause = vi.fn();
     iframe.contentDocument.body.append(audio);
 
-    scrubPreviewAudio(iframe, 0.5, "music", 0.4);
+    scrubPreviewAudio(iframe, 0.5, { id: "music" }, 0.4);
 
     expect(audio.volume).toBeCloseTo(0.1);
     stopScrubPreviewAudio();
@@ -112,13 +137,13 @@ describe("scrubPreviewAudio", () => {
 
   /**
    * The preview document is a different realm, so `instanceof HTMLAudioElement`
-   * is false for every node in it. That threw the `musicId` hint away and left
+   * is false for every node in it. That threw the `music` hint away and left
    * the first `<audio>` in the document as the only route — and the first
    * `<audio>` is often the voiceover, so scrubbing previewed the wrong track.
    * Two elements, music second, is what tells the two paths apart: with one
    * element the fallback reaches the right node by accident.
    */
-  it("previews the track named by musicId, not the first audio in the document", () => {
+  it("previews the track named by the music row, not the first audio in the document", () => {
     const iframe = document.createElement("iframe");
     document.body.append(iframe);
     const previewDoc = iframe.contentDocument;
@@ -139,13 +164,32 @@ describe("scrubPreviewAudio", () => {
     // The node really is cross-realm; this is the condition, not a contrivance.
     expect(music instanceof HTMLAudioElement).toBe(false);
 
-    scrubPreviewAudio(iframe, 0.5, "music-bed", 1);
+    scrubPreviewAudio(iframe, 0.5, { id: "music-bed" }, 1);
 
     expect(music.play).toHaveBeenCalled();
     expect(voiceover.play).not.toHaveBeenCalled();
     stopScrubPreviewAudio();
   });
 
+  it("previews the music row's own track when a sub-composition repeats its id", () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const previewDoc = iframe.contentDocument;
+    if (!previewDoc?.body) throw new Error("expected an iframe document");
+    previewDoc.body.innerHTML =
+      '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><audio id="music"></audio></div>' +
+      '<audio id="music" class="root"></audio>';
+    const [inner, root] = Array.from(previewDoc.querySelectorAll("audio"));
+    for (const audio of [inner, root])
+      Object.assign(audio!, { play: vi.fn(async () => {}), pause: vi.fn() });
+
+    scrubPreviewAudio(iframe, 0.5, { id: "music" }, 1);
+
+    expect(root!.play).toHaveBeenCalled();
+    expect(inner!.play).not.toHaveBeenCalled();
+    stopScrubPreviewAudio();
+  });
+
   /** A scrub audition is media running under a paused clock, which the runtime now
    *  stops on sight. So it borrows the element. That a leased element survives the
    *  tick is asserted runtime-side in core's `transportPark.test.ts`; here the
@@ -166,7 +210,7 @@ describe("scrubPreviewAudio", () => {
     const releasePausedMedia = vi.fn();
     (previewDoc.defaultView as IframeWindow).__hf = { leasePausedMedia, releasePausedMedia };
 
-    scrubPreviewAudio(iframe, 0.5, "music", 1);
+    scrubPreviewAudio(iframe, 0.5, { id: "music" }, 1);
 
     expect(leasePausedMedia).toHaveBeenCalledWith(music);
     expect(releasePausedMedia).not.toHaveBeenCalled();

package/src/player/lib/timelineIframeHelpers.ts

@@ -20,6 +20,8 @@ import {
   getTimelineElementDisplayLabel,
   buildTimelineElementIdentity,
   readTimelineElementZIndex,
+  previewElementFinder,
+  type PreviewTarget,
 } from "./timelineElementHelpers";
 import { postRuntimeControlMessage } from "./runtimeProtocol";
 import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
@@ -216,14 +218,14 @@ let scrubStopTimer: ReturnType<typeof setTimeout> | null = null;
 let scrubPrevMuted: boolean | null = null;
 let scrubPrevVolume: number | null = null;
 
-// Resolve the SAME element the store identified as music: prefer its id, then
-// the role attribute, and only fall back to the first <audio> (which could be a
-// voiceover, so the id hint matters).
+// Resolve the SAME element the store identified as music: prefer that row's own
+// element, then the role attribute, and only fall back to the first <audio>
+// (which could be a voiceover, so the row hint matters).
 /**
  * `doc` is the preview iframe's document, so its `<audio>` nodes are instances of
  * the IFRAME's `HTMLAudioElement`, never this module's. `instanceof
  * HTMLAudioElement` here is false for every one of them, which silently threw the
- * `musicId` hint away and fell through to "first `<audio>` in the document" — the
+ * `music` hint away and fell through to "first `<audio>` in the document" — the
  * very thing the comment above warns can be a voiceover. Ask what the node IS.
  * Same rule and same reasoning as packages/core/src/runtime/domRealm.ts.
  */
@@ -235,9 +237,9 @@ function isAudioNode(node: Element | null): node is HTMLAudioElement {
   );
 }
 
-function resolveScrubAudioEl(doc: Document, musicId?: string | null): HTMLAudioElement | null {
-  if (musicId) {
-    const byId = doc.getElementById(musicId);
+function resolveScrubAudioEl(doc: Document, music?: PreviewTarget | null): HTMLAudioElement | null {
+  if (music) {
+    const byId = previewElementFinder(doc, "audio")(music);
     if (isAudioNode(byId)) return byId;
   }
   return (
@@ -283,7 +285,7 @@ function applyScrub(el: HTMLAudioElement, audioFileTime: number, previewVolume:
 export function scrubPreviewAudio(
   iframe: HTMLIFrameElement | null,
   audioFileTime: number | null,
-  musicId?: string | null,
+  music?: PreviewTarget | null,
   previewVolume = 1,
 ): void {
   if (!iframe) return;
@@ -298,7 +300,7 @@ export function scrubPreviewAudio(
     return;
   }
   if (!doc) return;
-  const el = resolveScrubAudioEl(doc, musicId);
+  const el = resolveScrubAudioEl(doc, music);
   if (el) applyScrub(el, audioFileTime, previewVolume);
 }
 
@@ -512,12 +514,11 @@ export function buildMissingCompositionElements(
 
   // Patch existing elements that are missing compositionSrc
   let patched = false;
+  const findHost = previewElementFinder(doc);
   const updatedEls = (currentEls as TimelineElement[]).map((existing) => {
     if (existing.compositionSrc) return existing;
-    // Find the matching DOM host by element id or composition id
     const host =
-      doc.getElementById(existing.id) ??
-      doc.querySelector(`[data-composition-id="${CSS.escape(existing.id)}"]`);
+      findHost(existing) ?? doc.querySelector(`[data-composition-id="${CSS.escape(existing.id)}"]`);
     if (!host) return existing;
     const compSrc =
       host.getAttribute("data-composition-src") || host.getAttribute("data-composition-file");

package/src/telemetry/client.test.ts

@@ -30,6 +30,7 @@ describe("studio client shouldTrack", () => {
     setDev(false);
     setNoTelemetry(undefined);
     localStorage.clear();
+    delete window.__HF_CLI_TELEMETRY_DISABLED;
     vi.unstubAllGlobals();
   });
 
@@ -89,3 +90,28 @@ describe("studio client shouldTrack", () => {
     expect(shouldTrack()).toBe(false);
   });
 });
+
+it("suppresses actual render events in a CLI-opted-out Studio while the enabled control sends", async () => {
+  vi.useFakeTimers();
+  vi.resetModules();
+  setDev(false);
+  setNoTelemetry(undefined);
+  localStorage.clear();
+  const send = vi.fn().mockResolvedValue(new Response());
+  vi.stubGlobal("fetch", send);
+  try {
+    const { trackEvent } = await import("./client");
+    window.__HF_CLI_TELEMETRY_DISABLED = true;
+    trackEvent("render_complete", { duration: 1 });
+    await vi.advanceTimersByTimeAsync(1100);
+    expect(send).not.toHaveBeenCalled();
+    window.__HF_CLI_TELEMETRY_DISABLED = false;
+    trackEvent("render_complete", { duration: 1 });
+    await vi.advanceTimersByTimeAsync(1100);
+    expect(send).toHaveBeenCalledOnce();
+  } finally {
+    delete window.__HF_CLI_TELEMETRY_DISABLED;
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  }
+});

package/src/telemetry/policy.test.ts

@@ -15,6 +15,7 @@ describe("browserTelemetryAllowed", () => {
 
   beforeEach(async () => {
     localStorage.clear();
+    delete window.__HF_CLI_TELEMETRY_DISABLED;
     vi.resetModules();
     // vitest sets import.meta.env.DEV; the policy suppresses under it, so the
     // baseline has to be an explicitly production-like env.
@@ -28,6 +29,15 @@ describe("browserTelemetryAllowed", () => {
     vi.unstubAllEnvs();
   });
 
+  it("refuses a CLI opt-out even when browser storage permits telemetry", () => {
+    expect(browserTelemetryAllowed()).toBe(true);
+    window.__HF_CLI_TELEMETRY_DISABLED = true;
+    expect(browserTelemetryAllowed()).toBe(false);
+    expect(localStorage.getItem(DOCUMENTED_OPT_OUT)).toBeNull();
+    window.__HF_CLI_TELEMETRY_DISABLED = false;
+    expect(browserTelemetryAllowed()).toBe(true);
+  });
+
   it("allows telemetry with no control set", () => {
     expect(browserTelemetryAllowed()).toBe(true);
   });

package/src/telemetry/policy.ts

@@ -92,10 +92,17 @@ export function browserTelemetryAllowed(): boolean {
   }
 }
 
+declare global {
+  interface Window {
+    __HF_CLI_TELEMETRY_DISABLED?: boolean;
+  }
+}
+
 function allowed(): boolean {
   return (
     isApiKeyConfigured() &&
     !isBuildTimeOptOut() &&
+    !(typeof window !== "undefined" && window.__HF_CLI_TELEMETRY_DISABLED === true) &&
     !isViteDevMode() &&
     !isOptedOut() &&
     !isLegacyOptedOut() &&