@hyperframes/studio 0.5.0-alpha.13 → 0.5.0-alpha.15

package/src/components/editor/manualOffsetDrag.test.ts

@@ -0,0 +1,140 @@
+import { Window } from "happy-dom";
+import { describe, expect, it } from "vitest";
+import {
+  applyManualOffsetDragMatrix,
+  invertManualOffsetDragMatrix,
+  measureManualOffsetDragScreenToOffsetMatrix,
+  resolveManualOffsetForPointerDelta,
+  type ManualOffsetDragMatrix,
+} from "./manualOffsetDrag";
+import { STUDIO_OFFSET_X_PROP, STUDIO_OFFSET_Y_PROP } from "./manualEdits";
+
+function expectMatrixClose(actual: ManualOffsetDragMatrix, expected: ManualOffsetDragMatrix): void {
+  expect(actual.a).toBeCloseTo(expected.a, 6);
+  expect(actual.b).toBeCloseTo(expected.b, 6);
+  expect(actual.c).toBeCloseTo(expected.c, 6);
+  expect(actual.d).toBeCloseTo(expected.d, 6);
+}
+
+describe("manual offset drag matrix helpers", () => {
+  it("inverts identity movement", () => {
+    const inverse = invertManualOffsetDragMatrix({ a: 1, b: 0, c: 0, d: 1 });
+    if (!inverse) throw new Error("identity matrix should be invertible");
+
+    expectMatrixClose(inverse, { a: 1, b: 0, c: 0, d: 1 });
+  });
+
+  it("maps screen movement through a rotated coordinate system", () => {
+    const screenToOffset = invertManualOffsetDragMatrix({ a: 0, b: 1, c: -1, d: 0 });
+    if (!screenToOffset) throw new Error("rotation matrix should be invertible");
+
+    const offsetDelta = applyManualOffsetDragMatrix(screenToOffset, { x: 0, y: 10 });
+
+    expect(offsetDelta.x).toBeCloseTo(10, 6);
+    expect(offsetDelta.y).toBeCloseTo(0, 6);
+  });
+
+  it("rejects singular movement matrices", () => {
+    expect(invertManualOffsetDragMatrix({ a: 1, b: 1, c: 2, d: 2 })).toBeNull();
+  });
+
+  it("resolves final offsets from the measured inverse matrix", () => {
+    const offsetToScreen = { a: 2, b: 3, c: -1, d: 4 };
+    const screenToOffset = invertManualOffsetDragMatrix(offsetToScreen);
+    if (!screenToOffset) throw new Error("fixture matrix should be invertible");
+
+    const nextOffset = resolveManualOffsetForPointerDelta({
+      initialOffset: { x: 5, y: -2 },
+      screenToOffset,
+      dx: 7,
+      dy: 11,
+    });
+    const screenDelta = applyManualOffsetDragMatrix(offsetToScreen, {
+      x: nextOffset.x - 5,
+      y: nextOffset.y + 2,
+    });
+
+    expect(screenDelta.x).toBeCloseTo(7, 6);
+    expect(screenDelta.y).toBeCloseTo(11, 6);
+  });
+});
+
+describe("measureManualOffsetDragScreenToOffsetMatrix", () => {
+  it("measures the element center response and restores probe styles", () => {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    window.document.body.append(element);
+
+    element.getBoundingClientRect = () => {
+      const offsetX = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_X_PROP)) || 0;
+      const offsetY = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP)) || 0;
+      return new window.DOMRect(10 + 2 * offsetX - offsetY, 20 + 3 * offsetX + 4 * offsetY, 12, 8);
+    };
+
+    const measured = measureManualOffsetDragScreenToOffsetMatrix(element, { x: 0, y: 0 });
+    if (!measured.ok) throw new Error(measured.reason);
+
+    const expected = invertManualOffsetDragMatrix({ a: 2, b: 3, c: -1, d: 4 });
+    if (!expected) throw new Error("fixture matrix should be invertible");
+
+    expectMatrixClose(measured.matrix, expected);
+    expect(element.style.getPropertyValue(STUDIO_OFFSET_X_PROP)).toBe("");
+    expect(element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP)).toBe("");
+    expect(element.style.getPropertyValue("translate")).toBe("");
+  });
+
+  it("measures movement in parent viewport pixels when the element is inside a scaled iframe", () => {
+    const window = new Window();
+    const iframe = window.document.createElement("iframe");
+    window.document.body.append(iframe);
+    const iframeWindow = iframe.contentWindow;
+    const iframeDocument = iframe.contentDocument;
+    if (!iframeWindow || !iframeDocument) throw new Error("iframe fixture failed to initialize");
+
+    Object.defineProperty(iframeWindow, "frameElement", {
+      configurable: true,
+      value: iframe,
+    });
+    Object.defineProperty(iframeWindow, "innerWidth", {
+      configurable: true,
+      value: 200,
+    });
+    Object.defineProperty(iframeWindow, "innerHeight", {
+      configurable: true,
+      value: 100,
+    });
+    iframe.getBoundingClientRect = () => new window.DOMRect(50, 40, 100, 50);
+
+    const element = iframeDocument.createElement("div");
+    iframeDocument.body.append(element);
+    element.getBoundingClientRect = () => {
+      const offsetX = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_X_PROP)) || 0;
+      const offsetY = Number.parseFloat(element.style.getPropertyValue(STUDIO_OFFSET_Y_PROP)) || 0;
+      return new iframeWindow.DOMRect(20 + offsetX, 30 + offsetY, 40, 20);
+    };
+
+    const measured = measureManualOffsetDragScreenToOffsetMatrix(element, { x: 0, y: 0 });
+    if (!measured.ok) throw new Error(measured.reason);
+
+    expectMatrixClose(measured.matrix, { a: 2, b: -0, c: -0, d: 2 });
+
+    const nextOffset = resolveManualOffsetForPointerDelta({
+      initialOffset: { x: 0, y: 0 },
+      screenToOffset: measured.matrix,
+      dx: 50,
+      dy: 25,
+    });
+    expect(nextOffset).toEqual({ x: 100, y: 50 });
+  });
+
+  it("rejects elements whose movement response cannot be measured", () => {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    window.document.body.append(element);
+    element.getBoundingClientRect = () => new window.DOMRect(10, 20, 12, 8);
+
+    const measured = measureManualOffsetDragScreenToOffsetMatrix(element, { x: 0, y: 0 });
+
+    expect(measured.ok).toBe(false);
+  });
+});

package/src/components/editor/manualOffsetDrag.ts

@@ -0,0 +1,307 @@
+import type { DomEditSelection } from "./domEditing";
+import {
+  applyStudioPathOffset,
+  applyStudioPathOffsetDraft,
+  beginStudioManualEditGesture,
+  captureStudioPathOffset,
+  endStudioManualEditGesture,
+  readStudioPathOffset,
+  restoreStudioPathOffset,
+  type StudioPathOffsetSnapshot,
+} from "./manualEdits";
+
+const DEFAULT_OFFSET_PROBE_PX = 100;
+const MIN_PROBE_VECTOR_LENGTH_PX = 0.01;
+const MIN_MATRIX_DETERMINANT = 0.000001;
+
+export interface ManualOffsetDragMatrix {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+}
+
+export interface ManualOffsetDragRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  editScaleX: number;
+  editScaleY: number;
+}
+
+export interface ManualOffsetDragMember {
+  key: string;
+  selection: DomEditSelection;
+  element: HTMLElement;
+  initialOffset: { x: number; y: number };
+  initialPathOffset: StudioPathOffsetSnapshot;
+  gestureToken: string;
+  screenToOffset: ManualOffsetDragMatrix;
+  originRect: ManualOffsetDragRect;
+}
+
+export type ManualOffsetDragMemberResult =
+  | { ok: true; member: ManualOffsetDragMember }
+  | { ok: false; reason: string; selection: DomEditSelection };
+
+type Point = { x: number; y: number };
+
+function finitePoint(point: Point): boolean {
+  return Number.isFinite(point.x) && Number.isFinite(point.y);
+}
+
+function vectorLength(point: Point): number {
+  return Math.hypot(point.x, point.y);
+}
+
+function finiteRect(rect: DOMRect): boolean {
+  return (
+    Number.isFinite(rect.left) &&
+    Number.isFinite(rect.top) &&
+    Number.isFinite(rect.width) &&
+    Number.isFinite(rect.height)
+  );
+}
+
+function readViewportSize(win: Window): { width: number; height: number } {
+  const docEl = win.document.documentElement;
+  const width = win.innerWidth || docEl.clientWidth || 1;
+  const height = win.innerHeight || docEl.clientHeight || 1;
+  return {
+    width: width > 0 ? width : 1,
+    height: height > 0 ? height : 1,
+  };
+}
+
+function getFrameElement(win: Window): HTMLElement | null {
+  try {
+    const frameElement = win.frameElement;
+    if (!frameElement) return null;
+    const ownerWin = frameElement.ownerDocument.defaultView;
+    const htmlElement = ownerWin?.HTMLElement;
+    return htmlElement && frameElement instanceof htmlElement ? frameElement : null;
+  } catch {
+    return null;
+  }
+}
+
+function getRectCenter(element: HTMLElement): Point | null {
+  const rect = element.getBoundingClientRect();
+  if (!finiteRect(rect) || (rect.width <= 0 && rect.height <= 0)) {
+    return null;
+  }
+
+  let point = {
+    x: rect.left + rect.width / 2,
+    y: rect.top + rect.height / 2,
+  };
+
+  let win: Window | null = element.ownerDocument.defaultView;
+  while (win) {
+    const frameElement = getFrameElement(win);
+    if (!frameElement) break;
+
+    const frameRect = frameElement.getBoundingClientRect();
+    if (!finiteRect(frameRect) || frameRect.width <= 0 || frameRect.height <= 0) return null;
+
+    const viewport = readViewportSize(win);
+    point = {
+      x: frameRect.left + point.x * (frameRect.width / viewport.width),
+      y: frameRect.top + point.y * (frameRect.height / viewport.height),
+    };
+    win = frameElement.ownerDocument.defaultView;
+  }
+
+  return point;
+}
+
+export function invertManualOffsetDragMatrix(
+  matrix: ManualOffsetDragMatrix,
+): ManualOffsetDragMatrix | null {
+  const determinant = matrix.a * matrix.d - matrix.b * matrix.c;
+  if (!Number.isFinite(determinant) || Math.abs(determinant) < MIN_MATRIX_DETERMINANT) {
+    return null;
+  }
+
+  return {
+    a: matrix.d / determinant,
+    b: -matrix.b / determinant,
+    c: -matrix.c / determinant,
+    d: matrix.a / determinant,
+  };
+}
+
+export function applyManualOffsetDragMatrix(matrix: ManualOffsetDragMatrix, point: Point): Point {
+  return {
+    x: matrix.a * point.x + matrix.c * point.y,
+    y: matrix.b * point.x + matrix.d * point.y,
+  };
+}
+
+export function measureManualOffsetDragScreenToOffsetMatrix(
+  element: HTMLElement,
+  initialOffset: { x: number; y: number },
+  options: { probeSize?: number } = {},
+): { ok: true; matrix: ManualOffsetDragMatrix } | { ok: false; reason: string } {
+  const probeSize = options.probeSize ?? DEFAULT_OFFSET_PROBE_PX;
+  if (!Number.isFinite(probeSize) || probeSize <= 0) {
+    return { ok: false, reason: "Invalid movement probe size." };
+  }
+
+  const snapshot = captureStudioPathOffset(element);
+  try {
+    applyStudioPathOffsetDraft(element, initialOffset);
+    const origin = getRectCenter(element);
+    if (!origin) {
+      return { ok: false, reason: "Element has no measurable box." };
+    }
+
+    applyStudioPathOffsetDraft(element, {
+      x: initialOffset.x + probeSize,
+      y: initialOffset.y,
+    });
+    const probeX = getRectCenter(element);
+    if (!probeX) {
+      return { ok: false, reason: "Element X movement could not be measured." };
+    }
+
+    applyStudioPathOffsetDraft(element, {
+      x: initialOffset.x,
+      y: initialOffset.y + probeSize,
+    });
+    const probeY = getRectCenter(element);
+    if (!probeY) {
+      return { ok: false, reason: "Element Y movement could not be measured." };
+    }
+
+    const xColumn = {
+      x: (probeX.x - origin.x) / probeSize,
+      y: (probeX.y - origin.y) / probeSize,
+    };
+    const yColumn = {
+      x: (probeY.x - origin.x) / probeSize,
+      y: (probeY.y - origin.y) / probeSize,
+    };
+    if (
+      !finitePoint(xColumn) ||
+      !finitePoint(yColumn) ||
+      vectorLength(xColumn) < MIN_PROBE_VECTOR_LENGTH_PX ||
+      vectorLength(yColumn) < MIN_PROBE_VECTOR_LENGTH_PX
+    ) {
+      return { ok: false, reason: "Element movement response is too small to measure." };
+    }
+
+    const offsetToScreen = {
+      a: xColumn.x,
+      b: xColumn.y,
+      c: yColumn.x,
+      d: yColumn.y,
+    };
+    const screenToOffset = invertManualOffsetDragMatrix(offsetToScreen);
+    if (!screenToOffset) {
+      return { ok: false, reason: "Element movement response is not invertible." };
+    }
+
+    return { ok: true, matrix: screenToOffset };
+  } finally {
+    restoreStudioPathOffset(element, snapshot);
+  }
+}
+
+export function resolveManualOffsetForPointerDelta(input: {
+  initialOffset: { x: number; y: number };
+  screenToOffset: ManualOffsetDragMatrix;
+  dx: number;
+  dy: number;
+}): { x: number; y: number } {
+  const offsetDelta = applyManualOffsetDragMatrix(input.screenToOffset, {
+    x: input.dx,
+    y: input.dy,
+  });
+  return {
+    x: input.initialOffset.x + offsetDelta.x,
+    y: input.initialOffset.y + offsetDelta.y,
+  };
+}
+
+export function createManualOffsetDragMember(input: {
+  key: string;
+  selection: DomEditSelection;
+  element: HTMLElement;
+  rect: ManualOffsetDragRect;
+}): ManualOffsetDragMemberResult {
+  const initialOffset = readStudioPathOffset(input.element);
+  const initialPathOffset = captureStudioPathOffset(input.element);
+  const gestureToken = beginStudioManualEditGesture(input.element);
+  const measured = measureManualOffsetDragScreenToOffsetMatrix(input.element, initialOffset);
+  if (!measured.ok) {
+    restoreStudioPathOffset(input.element, initialPathOffset);
+    endStudioManualEditGesture(input.element, gestureToken);
+    return { ok: false, reason: measured.reason, selection: input.selection };
+  }
+
+  return {
+    ok: true,
+    member: {
+      key: input.key,
+      selection: input.selection,
+      element: input.element,
+      initialOffset,
+      initialPathOffset,
+      gestureToken,
+      screenToOffset: measured.matrix,
+      originRect: input.rect,
+    },
+  };
+}
+
+export function resolveManualOffsetDragMemberOffset(
+  member: ManualOffsetDragMember,
+  dx: number,
+  dy: number,
+): { x: number; y: number } {
+  return resolveManualOffsetForPointerDelta({
+    initialOffset: member.initialOffset,
+    screenToOffset: member.screenToOffset,
+    dx,
+    dy,
+  });
+}
+
+export function applyManualOffsetDragDraft(
+  member: ManualOffsetDragMember,
+  dx: number,
+  dy: number,
+): { x: number; y: number } {
+  const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
+  applyStudioPathOffsetDraft(member.element, offset);
+  return offset;
+}
+
+export function applyManualOffsetDragCommit(
+  member: ManualOffsetDragMember,
+  dx: number,
+  dy: number,
+): { x: number; y: number } {
+  const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
+  applyStudioPathOffset(member.element, offset);
+  return offset;
+}
+
+export function restoreManualOffsetDragMember(member: ManualOffsetDragMember): void {
+  restoreStudioPathOffset(member.element, member.initialPathOffset);
+  endStudioManualEditGesture(member.element, member.gestureToken);
+}
+
+export function restoreManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
+  for (const member of members) {
+    restoreManualOffsetDragMember(member);
+  }
+}
+
+export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
+  for (const member of members) {
+    endStudioManualEditGesture(member.element, member.gestureToken);
+  }
+}

package/src/components/renders/RenderQueue.tsx

@@ -2,12 +2,17 @@ import { memo, useState, useRef, useEffect } from "react";
 import { RenderQueueItem } from "./RenderQueueItem";
 import type { RenderJob } from "./useRenderQueue";
 
+type StartRenderHandler = (
+  format: "mp4" | "webm" | "mov",
+  quality: "draft" | "standard" | "high",
+) => void | Promise<void>;
+
 interface RenderQueueProps {
   jobs: RenderJob[];
   projectId: string;
   onDelete: (jobId: string) => void;
   onClearCompleted: () => void;
-  onStartRender: (format: "mp4" | "webm" | "mov", quality: "draft" | "standard" | "high") => void;
+  onStartRender: StartRenderHandler;
   isRendering: boolean;
 }
 
@@ -91,7 +96,7 @@ function FormatExportButton({
   onStartRender,
   isRendering,
 }: {
-  onStartRender: (format: "mp4" | "webm" | "mov", quality: "draft" | "standard" | "high") => void;
+  onStartRender: StartRenderHandler;
   isRendering: boolean;
 }) {
   const [format, setFormat] = useState<"mp4" | "webm" | "mov">("mp4");
@@ -129,7 +134,9 @@ function FormatExportButton({
         <option value="webm">WebM</option>
       </select>
       <button
-        onClick={() => onStartRender(format, quality)}
+        onClick={() => {
+          void onStartRender(format, quality);
+        }}
         disabled={isRendering}
         className="flex items-center gap-1 px-2 py-0.5 text-[10px] font-semibold rounded-r bg-studio-accent text-[#09090B] hover:brightness-110 transition-colors disabled:opacity-50"
       >

package/src/hooks/usePersistentEditHistory.test.ts

@@ -60,6 +60,7 @@ describe("createPersistentEditHistoryController", () => {
       },
     });
     expect(result.ok).toBe(true);
+    expect(result.paths).toEqual(["index.html"]);
 
     expect(controller.snapshot().canUndo).toBe(false);
     expect(controller.snapshot().canRedo).toBe(true);

package/src/hooks/usePersistentEditHistory.ts

@@ -39,6 +39,7 @@ interface ApplyResult {
   ok: boolean;
   reason?: "empty" | "content-mismatch";
   label?: string;
+  paths?: string[];
 }
 
 interface PersistentEditHistoryStoreOptions {
@@ -196,7 +197,7 @@ export function createPersistentEditHistoryStore({
         });
         return {
           state: result.state,
-          result: { ok: true, label: result.entry.label },
+          result: { ok: true, label: result.entry.label, paths: Object.keys(result.entry.files) },
         };
       });
     },
@@ -227,7 +228,7 @@ export function createPersistentEditHistoryStore({
         });
         return {
           state: result.state,
-          result: { ok: true, label: result.entry.label },
+          result: { ok: true, label: result.entry.label, paths: Object.keys(result.entry.files) },
         };
       });
     },

package/src/player/components/CompositionThumbnail.test.ts

@@ -13,7 +13,7 @@ describe("buildCompositionThumbnailUrl", () => {
         origin: "http://localhost:3000",
       }),
     ).toBe(
-      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v2&selector=.card&selectorIndex=2",
+      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v3&selector=.card&selectorIndex=2",
     );
   });
 });

package/src/player/components/CompositionThumbnail.tsx

@@ -15,7 +15,7 @@ interface CompositionThumbnailProps {
 }
 
 const CLIP_HEIGHT = 66;
-const THUMBNAIL_URL_VERSION = "v2";
+const THUMBNAIL_URL_VERSION = "v3";
 
 export function buildCompositionThumbnailUrl({
   previewUrl,

package/src/player/components/Player.tsx

@@ -1,5 +1,9 @@
 import { forwardRef, useRef, useState } from "react";
+import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readiness";
 import { useMountEffect } from "../../hooks/useMountEffect";
+// NOTE: importing "@hyperframes/player" registers a class extending HTMLElement
+// at module load, which throws under SSR. Defer the import to the mount effect
+// so it only runs in the browser.
 
 interface PlayerProps {
   projectId?: string;
@@ -24,14 +28,14 @@ function enableInteractiveIframe(player: HyperframesPlayerElement): void {
   iframe?.style.setProperty("pointer-events", "auto");
 }
 
-function isLottieAnimationReady(anim: unknown): boolean {
-  if (typeof anim !== "object" || anim === null) return true;
-  const maybe = anim as { isLoaded?: boolean; totalFrames?: number };
-  if (maybe.isLoaded === true) return true;
-  if (typeof maybe.totalFrames === "number" && maybe.totalFrames > 0) return true;
-  return false;
-}
-
+// Assets are considered ready when every `<video>`/`<audio>` has enough data
+// to play through without buffering, and every registered Lottie animation has
+// finished loading.
+//
+// Returns whichever value was returned last on cross-origin / transient DOM
+// races so a brief access failure (e.g. an iframe that just swapped src)
+// doesn't flicker the overlay state — we keep showing whatever was most
+// recently true.
 function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
   try {
     const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
@@ -47,7 +51,7 @@ function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): bool
     const lotties = win.__hfLottie;
     if (lotties?.length) {
       for (const anim of lotties) {
-        if (!isLottieAnimationReady(anim)) return true;
+        if (!isLottieAnimationLoaded(anim)) return true;
       }
     }
 
@@ -57,9 +61,18 @@ function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): bool
   }
 }
 
+/**
+ * Renders a composition preview using the <hyperframes-player> web component.
+ *
+ * The web component handles iframe scaling, dimension detection, and
+ * ResizeObserver internally. This wrapper bridges its inner iframe to the
+ * forwarded ref so useTimelinePlayer can access it for clip manifest parsing,
+ * timeline probing, and DOM inspection.
+ */
 export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
   ({ projectId, directUrl, onLoad, portrait, style }, ref) => {
     const containerRef = useRef<HTMLDivElement>(null);
+    const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
     const [assetsLoading, setAssetsLoading] = useState(false);
 
@@ -70,9 +83,11 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       let canceled = false;
       let cleanup: (() => void) | undefined;
 
+      // Dynamic import registers the custom element in the browser only.
       import("@hyperframes/player").then(() => {
         if (canceled) return;
 
+        // Create the web component imperatively to avoid JSX custom-element typing.
         const player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
         const src = directUrl || `/api/projects/${projectId}/preview`;
         player.setAttribute("src", src);
@@ -84,6 +99,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         container.appendChild(player);
         enableInteractiveIframe(player);
 
+        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
         const iframe = player.iframeElement;
         if (typeof ref === "function") {
           ref(iframe);
@@ -91,12 +107,35 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
         }
 
+        // Prevent the web component's built-in click-to-toggle behavior.
+        // The studio manages playback exclusively via useTimelinePlayer.
         const preventToggle = (e: Event) => e.stopImmediatePropagation();
         player.addEventListener("click", preventToggle, { capture: true });
 
+        // Forward the iframe's native load event to the studio's onIframeLoad.
         const handleLoad = () => {
+          loadCountRef.current++;
+          // Reveal animation on reload (hot-reload, composition switch)
+          if (loadCountRef.current > 1) {
+            container.classList.remove("preview-revealing");
+            void container.offsetWidth;
+            container.classList.add("preview-revealing");
+            const onEnd = () => container.classList.remove("preview-revealing");
+            container.addEventListener("animationend", onEnd, { once: true });
+          }
           onLoad();
 
+          // Show a loading overlay until every `<video>`/`<audio>` and Lottie
+          // asset is ready. Without this users can click play before audio has
+          // buffered — the runtime is resilient (queued play() resolves once
+          // data arrives), but the overlay communicates why the first frame
+          // or first audio beat may lag.
+          //
+          // Poll with a 10 s safety cap (100 ticks × 100 ms). If the cap
+          // trips we hide the overlay so the UI doesn't appear stuck forever,
+          // but we log a debug warning so the case is diagnosable — a long
+          // cold video or a broken asset can legitimately exceed 10 s on a
+          // slow network.
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           let lastUnloaded = hasUnloadedAssets(iframe, false);
           if (lastUnloaded) {
@@ -109,6 +148,11 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
                 if (assetPollRef.current) clearInterval(assetPollRef.current);
                 assetPollRef.current = null;
                 setAssetsLoading(false);
+                if (lastUnloaded) {
+                  console.debug(
+                    "[Player] Asset-loading overlay timed out after 10s; hiding anyway. Check network or asset integrity.",
+                  );
+                }
               }
             }, 100);
           } else {
@@ -123,6 +167,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
+          // Clear the forwarded ref
           if (typeof ref === "function") {
             ref(null);
           } else if (ref) {

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

@@ -15,6 +15,7 @@ import {
 
 function createDocument(markup: string): Document {
   const window = new Window();
+  Object.assign(window, { SyntaxError });
   window.document.body.innerHTML = markup;
   return window.document;
 }

package/src/utils/clipboard.test.ts

@@ -4,6 +4,7 @@ import { copyTextToClipboard } from "./clipboard";
 
 function installDocument(execCommand: (command: string) => boolean): void {
   const window = new Window();
+  Object.assign(window, { SyntaxError });
   Object.defineProperty(window.document, "execCommand", {
     configurable: true,
     value: execCommand,