@hyperframes/studio 0.4.38 → 0.5.0-alpha.10

package/src/player/components/PlayerControls.tsx

@@ -1,6 +1,10 @@
 import { useRef, useState, useCallback, useEffect, memo } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { formatFrameTime, frameToSeconds, stepFrameTime, formatTime } from "../lib/time";
+import {
+  TIMELINE_TOGGLE_SHORTCUT_LABEL,
+  getTimelineToggleTitle,
+} from "../../utils/timelineDiscovery";
+import { formatFrameTime, frameToSeconds, formatTime } from "../lib/time";
 import { usePlayerStore, liveTime } from "../store/playerStore";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
@@ -26,11 +30,15 @@ export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth:
 interface PlayerControlsProps {
   onTogglePlay: () => void;
   onSeek: (time: number) => void;
+  timelineVisible?: boolean;
+  onToggleTimeline?: () => void;
 }
 
 export const PlayerControls = memo(function PlayerControls({
   onTogglePlay,
   onSeek,
+  timelineVisible,
+  onToggleTimeline,
 }: PlayerControlsProps) {
   // Subscribe to only the fields we render — each selector prevents cascading re-renders
   const isPlaying = usePlayerStore((s) => s.isPlaying);
@@ -208,10 +216,10 @@ export const PlayerControls = memo(function PlayerControls({
       const step = e.shiftKey ? 10 : 1;
       if (e.key === "ArrowLeft") {
         e.preventDefault();
-        onSeek(stepFrameTime(currentTimeRef.current, -step));
+        onSeek(Math.max(0, currentTimeRef.current - frameToSeconds(step)));
       } else if (e.key === "ArrowRight") {
         e.preventDefault();
-        onSeek(Math.min(duration, stepFrameTime(currentTimeRef.current, step)));
+        onSeek(Math.min(duration, currentTimeRef.current + frameToSeconds(step)));
       }
     },
     [timelineReady, duration, onSeek],
@@ -429,6 +437,39 @@ export const PlayerControls = memo(function PlayerControls({
           </span>
         ))}
       </div>
+
+      {/* Timeline toggle */}
+      {onToggleTimeline !== undefined && (
+        <button
+          type="button"
+          onClick={onToggleTimeline}
+          className={`h-7 flex items-center gap-1.5 rounded-md border px-2.5 text-[11px] font-medium transition-colors ${
+            timelineVisible
+              ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
+              : "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
+          }`}
+          title={getTimelineToggleTitle(Boolean(timelineVisible))}
+          aria-label={timelineVisible ? "Hide timeline editor" : "Show timeline editor"}
+        >
+          <svg
+            width="13"
+            height="13"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+          >
+            <rect x="3" y="13" width="18" height="8" rx="1" />
+            <line x1="3" y1="9" x2="21" y2="9" />
+            <line x1="3" y1="5" x2="21" y2="5" />
+          </svg>
+          <span>Timeline</span>
+          <span className="hidden md:inline rounded bg-black/20 px-1 py-0.5 text-[9px] font-mono opacity-70">
+            {TIMELINE_TOGGLE_SHORTCUT_LABEL}
+          </span>
+        </button>
+      )}
     </div>
   );
 });

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

@@ -8,6 +8,7 @@ import {
   getTimelinePlayheadLeft,
   getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
+  shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
 } from "./Timeline";
@@ -237,6 +238,17 @@ describe("getTimelineCanvasHeight", () => {
   });
 });
 
+describe("shouldShowTimelineShortcutHint", () => {
+  it("shows the hint when the timeline does not vertically overflow", () => {
+    expect(shouldShowTimelineShortcutHint(220, 220)).toBe(true);
+    expect(shouldShowTimelineShortcutHint(220.5, 220)).toBe(true);
+  });
+
+  it("hides the hint when timeline tracks need vertical scrolling", () => {
+    expect(shouldShowTimelineShortcutHint(221.5, 220)).toBe(false);
+  });
+});
+
 describe("shouldHandleTimelineDeleteKey", () => {
   it("handles Delete and Backspace when focus is not in an editor", () => {
     expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);

package/src/player/components/Timeline.tsx

@@ -35,7 +35,7 @@ const TRACK_H = 72;
 const RULER_H = 24;
 const CLIP_Y = 3; // vertical inset inside track
 const CLIP_HANDLE_W = 18;
-const TIMELINE_SCROLL_BUFFER = 24;
+const TIMELINE_SCROLL_BUFFER = 20;
 
 interface TrackVisualStyle extends TimelineTrackStyle {
   icon: ReactNode;
@@ -216,6 +216,14 @@ export function getTimelineCanvasHeight(trackCount: number): number {
   return RULER_H + Math.max(0, trackCount) * TRACK_H + TIMELINE_SCROLL_BUFFER;
 }
 
+export function shouldShowTimelineShortcutHint(
+  scrollHeight: number,
+  clientHeight: number,
+): boolean {
+  if (!Number.isFinite(scrollHeight) || !Number.isFinite(clientHeight)) return true;
+  return scrollHeight - clientHeight <= 1;
+}
+
 export function shouldHandleTimelineDeleteKey(input: {
   key: string;
   metaKey?: boolean;
@@ -279,7 +287,6 @@ export function resolveTimelineAssetDrop(
     track: getDefaultDroppedTrack(input.trackOrder, rowIndex),
   };
 }
-
 /* ── Component ──────────────────────────────────────────────────── */
 interface TimelineProps {
   /** Called when user seeks via ruler/track click or playhead drag */
@@ -427,30 +434,51 @@ export const Timeline = memo(function Timeline({
   onDeleteElementRef.current = onDeleteElement;
   const suppressClickRef = useRef(false);
   const [showPopover, setShowPopover] = useState(false);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
   const [viewportWidth, setViewportWidth] = useState(0);
   const roRef = useRef<ResizeObserver | null>(null);
+  const shortcutHintRafRef = useRef(0);
+  const syncShortcutHintVisibility = useCallback(() => {
+    const scroll = scrollRef.current;
+    setShowShortcutHint(
+      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
+    );
+  }, []);
+  const scheduleShortcutHintVisibilitySync = useCallback(() => {
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    shortcutHintRafRef.current = requestAnimationFrame(() => {
+      shortcutHintRafRef.current = 0;
+      syncShortcutHintVisibility();
+    });
+  }, [syncShortcutHintVisibility]);
 
   // Callback ref: sets up ResizeObserver when the DOM element actually mounts.
   // useMountEffect can't work here because the component returns null on first
   // render (timelineReady=false), so containerRef.current is null when the
   // effect fires and the ResizeObserver is never created.
-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    if (roRef.current) {
-      roRef.current.disconnect();
-      roRef.current = null;
-    }
-    containerRef.current = el;
-    if (!el) return;
-    setViewportWidth(el.clientWidth);
-    roRef.current = new ResizeObserver(([entry]) => {
-      setViewportWidth(entry.contentRect.width);
-    });
-    roRef.current.observe(el);
-  }, []);
+  const setContainerRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      containerRef.current = el;
+      if (!el) return;
+      setViewportWidth(el.clientWidth);
+      scheduleShortcutHintVisibilitySync();
+      roRef.current = new ResizeObserver(([entry]) => {
+        setViewportWidth(entry.contentRect.width);
+        scheduleShortcutHintVisibilitySync();
+      });
+      roRef.current.observe(el);
+    },
+    [scheduleShortcutHintVisibilitySync],
+  );
 
   // Clean up ResizeObserver on unmount
   useMountEffect(() => () => {
     roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
   });
 
   // Effective duration: max of store duration and the furthest element end.
@@ -495,6 +523,7 @@ export const Timeline = memo(function Timeline({
     }
     return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
   }, [draggedClip, trackOrder]);
+  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const selectedElement = useMemo(
     () => elements.find((element) => (element.key ?? element.id) === selectedElementId) ?? null,
     [elements, selectedElementId],
@@ -544,7 +573,6 @@ export const Timeline = memo(function Timeline({
     );
     previousZoomModeRef.current = zoomMode;
   }, [zoomMode]);
-
   useMountEffect(() => {
     const unsub = liveTime.subscribe((t) => {
       const dur = durationRef.current;
@@ -1012,6 +1040,10 @@ export const Timeline = memo(function Timeline({
   );
   const majorTickInterval =
     major.length >= 2 ? Math.max(0.25, major[1] - major[0]) : effectiveDuration;
+  useEffect(() => {
+    syncShortcutHintVisibility();
+  }, [syncShortcutHintVisibility, timelineReady, elements.length, totalH]);
+
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
       if (resizingClip?.element.id === element.id) {
@@ -1236,7 +1268,6 @@ export const Timeline = memo(function Timeline({
     );
   }
 
-  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -1310,7 +1341,7 @@ export const Timeline = memo(function Timeline({
     <div
       ref={setContainerRef}
       aria-label="Timeline"
-      className={`border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
+      className={`relative border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
       style={{
         touchAction: "pan-x pan-y",
         background: theme.shellBackground,
@@ -1649,8 +1680,8 @@ export const Timeline = memo(function Timeline({
         </div>
       </div>
 
-      {/* Keyboard shortcut hint — always visible */}
-      {!showPopover && !rangeSelection && (
+      {/* Keyboard shortcut hint */}
+      {showShortcutHint && !showPopover && !rangeSelection && (
         <div className="absolute bottom-2 right-3 pointer-events-none z-20">
           <div
             className="flex items-center gap-1.5 px-2 py-1 rounded-md border"

package/src/player/components/TimelineClip.tsx

@@ -62,6 +62,25 @@ export const TimelineClip = memo(function TimelineClip({
         : theme.clipShadow;
   const capabilities = getTimelineEditCapabilities(el);
   const showHandles = handleOpacity > 0.01;
+  const baseBackgroundImage = isSelected ? theme.clipBackgroundActive : theme.clipBackground;
+  const glossBackgroundImage = isSelected
+    ? "linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0))"
+    : "linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0))";
+  const accentBackgroundImage = `linear-gradient(120deg, ${trackStyle.accent}${
+    isSelected ? "22" : "1e"
+  }, transparent 28%)`;
+  const compositionStripeBackgroundImage =
+    isComposition && !hasCustomContent
+      ? "repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)"
+      : undefined;
+  const clipBackgroundImage = [
+    compositionStripeBackgroundImage,
+    glossBackgroundImage,
+    accentBackgroundImage,
+    baseBackgroundImage,
+  ]
+    .filter(Boolean)
+    .join(", ");
 
   return (
     <div
@@ -75,13 +94,7 @@ export const TimelineClip = memo(function TimelineClip({
         top: clipY,
         bottom: clipY,
         borderRadius: theme.clipRadius,
-        background: isSelected
-          ? `linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}22, transparent 28%), ${theme.clipBackgroundActive}`
-          : `linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}1e, transparent 28%), ${theme.clipBackground}`,
-        backgroundImage:
-          isComposition && !hasCustomContent
-            ? `repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)`
-            : undefined,
+        backgroundImage: clipBackgroundImage,
         border: `1px solid ${borderColor}`,
         boxShadow,
         transition:

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

@@ -248,7 +248,7 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("disables move and trims for generic motion clips even when patchable", () => {
+  it("allows moving generic motion clips while keeping trims blocked", () => {
     expect(
       getTimelineEditCapabilities({
         tag: "section",
@@ -256,7 +256,7 @@ describe("getTimelineEditCapabilities", () => {
         selector: ".feature-card",
       }),
     ).toEqual({
-      canMove: false,
+      canMove: true,
       canTrimStart: false,
       canTrimEnd: false,
     });
@@ -428,7 +428,6 @@ describe("buildClipRangeSelection", () => {
     });
   });
 });
-
 describe("resolveTimelineAutoScroll", () => {
   it("does not scroll when the pointer stays away from the edges", () => {
     expect(
@@ -512,7 +511,6 @@ describe("buildTimelineElementAgentPrompt", () => {
     ).toContain("If this clip is animated with GSAP");
   });
 });
-
 describe("resolveTimelineResize", () => {
   it("shrinks clip duration from the right edge", () => {
     expect(

package/src/player/components/timelineEditing.ts

@@ -233,7 +233,7 @@ export function getTimelineEditCapabilities(input: {
   const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
   const hasDeterministicWindow = isDeterministicTimelineWindow(input);
   return {
-    canMove: canPatch && hasDeterministicWindow,
+    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
     canTrimEnd: canPatch && hasFiniteDuration && hasDeterministicWindow,
     canTrimStart: canPatch && hasFiniteDuration && canOffsetTrimClipStart(input),
   };
@@ -273,7 +273,6 @@ export function buildClipRangeSelection(
     anchorY: anchor.anchorY,
   };
 }
-
 export function buildTimelineAgentPrompt({
   rangeStart,
   rangeEnd,
@@ -347,7 +346,6 @@ export function buildTimelineElementAgentPrompt(element: {
 
   return lines.join("\n");
 }
-
 export function formatTimelineAttributeNumber(value: number): string {
   return Number(roundToCentiseconds(value).toFixed(2)).toString();
 }

package/src/player/components/timelineTheme.ts

@@ -63,12 +63,12 @@ const TRACK_STYLES: Record<string, TimelineTrackStyle> = {
 const DEFAULT_TRACK_STYLE: TimelineTrackStyle = createTrackStyle();
 
 export const defaultTimelineTheme: TimelineTheme = {
-  shellBackground: "#0A0A0B",
+  shellBackground: "#0A0E15",
   shellBorder: "rgba(255,255,255,0.05)",
   rulerBorder: "rgba(255,255,255,0.045)",
-  rowBackground: "#0A0A0B",
+  rowBackground: "#0A0E15",
   rowBorder: "rgba(255,255,255,0.05)",
-  gutterBackground: "#0A0A0B",
+  gutterBackground: "#0D121B",
   gutterBorder: "rgba(255,255,255,0.05)",
   textPrimary: "#E8EDF5",
   textSecondary: "#8391A8",

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

@@ -1,12 +1,39 @@
 import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
+  findTimelineDomNodeForClip,
+  getTimelineElementSelector,
+  type ClipManifestClip,
   mergeTimelineElementsPreservingDowngrades,
   resolveStandaloneRootCompositionSrc,
   shouldIgnorePlaybackShortcutEvent,
   shouldIgnorePlaybackShortcutTarget,
 } from "./useTimelinePlayer";
 
+function createDocument(markup: string): Document {
+  const window = new Window();
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+function createClip(overrides: Partial<ClipManifestClip>): ClipManifestClip {
+  return {
+    id: null,
+    label: "",
+    start: 0,
+    duration: 4,
+    track: 0,
+    kind: "element",
+    tagName: "div",
+    compositionId: null,
+    parentCompositionId: null,
+    compositionSrc: null,
+    assetUrl: null,
+    ...overrides,
+  };
+}
+
 function mockTargetMatching(selectorNeedle: string): EventTarget {
   return {
     closest: (selector: string) => (selector.includes(selectorNeedle) ? ({} as Element) : null),
@@ -87,6 +114,38 @@ describe("resolveStandaloneRootCompositionSrc", () => {
   });
 });
 
+describe("findTimelineDomNodeForClip", () => {
+  it("matches anonymous manifest clips back to repeated DOM nodes in timeline order", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main" data-start="0" data-duration="8">
+        <section id="identity-card" class="clip identity-card" data-start="0" data-duration="4" data-track-index="0"></section>
+        <div class="clip duplicate-card first" data-start="0" data-duration="4" data-track-index="1"></div>
+        <div class="clip duplicate-card second" data-start="0" data-duration="4" data-track-index="2"></div>
+      </div>
+    `);
+    const used = new Set<Element>();
+
+    const first = findTimelineDomNodeForClip(
+      doc,
+      createClip({ id: "__node__index_2", track: 1 }),
+      1,
+      used,
+    ) as HTMLElement;
+    used.add(first);
+    const second = findTimelineDomNodeForClip(
+      doc,
+      createClip({ id: "__node__index_3", track: 2 }),
+      2,
+      used,
+    ) as HTMLElement;
+
+    expect(first.className).toBe("clip duplicate-card first");
+    expect(second.className).toBe("clip duplicate-card second");
+    expect(getTimelineElementSelector(first)).toBe(".duplicate-card");
+    expect(getTimelineElementSelector(second)).toBe(".duplicate-card");
+  });
+});
+
 describe("mergeTimelineElementsPreservingDowngrades", () => {
   it("preserves missing current elements when a shorter manifest arrives", () => {
     expect(

package/src/player/hooks/useTimelinePlayer.ts

@@ -1,7 +1,7 @@
 import { useRef, useCallback } from "react";
 import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
+import { frameToSeconds, STUDIO_PREVIEW_FPS } from "../lib/time";
 import { useCaptionStore } from "../../captions/store";
 
 interface PlaybackAdapter {
@@ -22,7 +22,7 @@ interface TimelineLike {
   isActive: () => boolean;
 }
 
-interface ClipManifestClip {
+export interface ClipManifestClip {
   id: string | null;
   label: string;
   start: number;
@@ -253,12 +253,18 @@ function parseTimelineFromDOM(doc: Document, rootDuration: number): TimelineElem
   return els;
 }
 
-function getTimelineElementSelector(el: Element): string | undefined {
-  if (el instanceof HTMLElement && el.id) return `#${el.id}`;
+function isHtmlElement(el: Element): el is HTMLElement {
+  const HtmlElementCtor = el.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
+  return typeof HtmlElementCtor !== "undefined" && el instanceof HtmlElementCtor;
+}
+
+export function getTimelineElementSelector(el: Element): string | undefined {
+  if (isHtmlElement(el) && el.id) return `#${el.id}`;
   const compId = el.getAttribute("data-composition-id");
   if (compId) return `[data-composition-id="${compId}"]`;
-  if (el instanceof HTMLElement) {
-    const firstClass = el.className.split(/\s+/).find(Boolean);
+  if (isHtmlElement(el)) {
+    const classes = el.className.split(/\s+/).filter(Boolean);
+    const firstClass = classes.find((className) => className !== "clip") ?? classes[0];
     if (firstClass) return `.${firstClass}`;
   }
   return undefined;
@@ -305,6 +311,47 @@ function buildTimelineElementKey(params: {
   return `${scope}:${params.id}:${params.fallbackIndex}`;
 }
 
+function getTimelineDomNodes(doc: Document): Element[] {
+  const rootComp = doc.querySelector("[data-composition-id]");
+  return Array.from(doc.querySelectorAll("[data-start]")).filter((node) => node !== rootComp);
+}
+
+function numbersNearlyEqual(a: number, b: number): boolean {
+  return Math.abs(a - b) < 0.001;
+}
+
+function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean {
+  const tagName = clip.tagName?.toLowerCase();
+  if (tagName && node.tagName.toLowerCase() !== tagName) return false;
+
+  const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
+  if (Number.isFinite(start) && !numbersNearlyEqual(start, clip.start)) return false;
+
+  const duration = Number.parseFloat(node.getAttribute("data-duration") ?? "");
+  if (Number.isFinite(duration) && !numbersNearlyEqual(duration, clip.duration)) return false;
+
+  const track = Number.parseInt(node.getAttribute("data-track-index") ?? "", 10);
+  if (Number.isFinite(track) && track !== clip.track) return false;
+
+  return true;
+}
+
+export function findTimelineDomNodeForClip(
+  doc: Document,
+  clip: ClipManifestClip,
+  fallbackIndex: number,
+  usedNodes = new Set<Element>(),
+): Element | null {
+  const byIdentity = clip.id ? findTimelineDomNode(doc, clip.id) : null;
+  if (byIdentity && !usedNodes.has(byIdentity)) return byIdentity;
+
+  const candidates = getTimelineDomNodes(doc).filter((node) => !usedNodes.has(node));
+  const exact = candidates.find((node) => nodeMatchesManifestClip(node, clip));
+  if (exact) return exact;
+
+  return candidates[fallbackIndex] ?? null;
+}
+
 function findTimelineDomNode(doc: Document, id: string): Element | null {
   return (
     doc.getElementById(id) ??
@@ -350,7 +397,6 @@ export function buildStandaloneRootTimelineElement(params: {
     sourceFile: compositionSrc,
   };
 }
-
 function normalizePreviewViewport(doc: Document, win: Window): void {
   if (doc.documentElement) {
     doc.documentElement.style.overflow = "hidden";
@@ -697,7 +743,7 @@ export function useTimelinePlayer() {
     (deltaFrames: number) => {
       const adapter = getAdapter();
       const currentTime = adapter?.getTime() ?? usePlayerStore.getState().currentTime;
-      seek(stepFrameTime(currentTime, deltaFrames, STUDIO_PREVIEW_FPS));
+      seek(currentTime + frameToSeconds(deltaFrames, STUDIO_PREVIEW_FPS));
     },
     [getAdapter, seek],
   );
@@ -822,8 +868,18 @@ export function useTimelinePlayer() {
       const filtered = data.clips.filter(
         (clip) => !clip.parentCompositionId || !clipCompositionIds.has(clip.parentCompositionId),
       );
+      let iframeDoc: Document | null = null;
+      try {
+        iframeDoc = iframeRef.current?.contentDocument ?? null;
+      } catch {
+        iframeDoc = null;
+      }
+      const usedHostEls = new Set<Element>();
       const els: TimelineElement[] = filtered.map((clip, index) => {
-        let hostEl: Element | null = null;
+        let hostEl = iframeDoc
+          ? findTimelineDomNodeForClip(iframeDoc, clip, index, usedHostEls)
+          : null;
+        if (hostEl) usedHostEls.add(hostEl);
         const id = clip.id || clip.label || clip.tagName || "element";
         const entry: TimelineElement = {
           id,
@@ -832,16 +888,7 @@ export function useTimelinePlayer() {
           duration: clip.duration,
           track: clip.track,
         };
-        try {
-          const iframeDoc = iframeRef.current?.contentDocument;
-          if (iframeDoc && entry.id) {
-            hostEl = findTimelineDomNode(iframeDoc, entry.id);
-          }
-        } catch {
-          /* cross-origin */
-        }
         if (hostEl) {
-          const iframeDoc = iframeRef.current?.contentDocument;
           entry.domId = hostEl.id || undefined;
           entry.selector = getTimelineElementSelector(hostEl);
           entry.selectorIndex =
@@ -857,19 +904,13 @@ export function useTimelinePlayer() {
           // after inlining, so the clip manifest may not have compositionSrc.
           // Fall back to reading data-composition-file from the DOM.
           let resolvedSrc = clip.compositionSrc;
-          let hostEl: Element | null = null;
           if (!resolvedSrc) {
-            try {
-              const iframeDoc = iframeRef.current?.contentDocument;
-              hostEl =
-                iframeDoc?.querySelector(`[data-composition-id="${clip.compositionId}"]`) ?? hostEl;
-              resolvedSrc =
-                hostEl?.getAttribute("data-composition-src") ??
-                hostEl?.getAttribute("data-composition-file") ??
-                null;
-            } catch {
-              /* cross-origin */
-            }
+            hostEl =
+              iframeDoc?.querySelector(`[data-composition-id="${clip.compositionId}"]`) ?? hostEl;
+            resolvedSrc =
+              hostEl?.getAttribute("data-composition-src") ??
+              hostEl?.getAttribute("data-composition-file") ??
+              null;
           }
           if (resolvedSrc) {
             entry.compositionSrc = resolvedSrc;
@@ -1196,6 +1237,9 @@ export function useTimelinePlayer() {
     setIsPlaying(false);
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
 
+  const togglePlayRef = useRef(togglePlay);
+  togglePlayRef.current = togglePlay;
+
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
@@ -1304,8 +1348,6 @@ export function useTimelinePlayer() {
       stopRAFLoop();
       stopReverseLoop();
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-      // Don't reset() on cleanup — preserve timeline elements across iframe refreshes
-      // to prevent blink. New data will replace old when the iframe reloads.
     };
   });
 

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { formatFrameTime, frameToSeconds, secondsToFrame, stepFrameTime, formatTime } from "./time";
+import { formatFrameTime, frameToSeconds, secondsToFrame, formatTime } from "./time";
 
 describe("formatTime", () => {
   it("formats zero seconds", () => {
@@ -72,14 +72,4 @@ describe("frame helpers", () => {
   it("formats current and total frame display", () => {
     expect(formatFrameTime(1, 5)).toBe("30f / 150f");
   });
-
-  it("steps from a truncated runtime time by integer frame index", () => {
-    expect(stepFrameTime(0.0333333, 1)).toBe(2 / 30);
-    expect(stepFrameTime(0.0666666, 1)).toBe(3 / 30);
-    expect(stepFrameTime(0.0666666, -1)).toBe(1 / 30);
-  });
-
-  it("clamps frame stepping at zero", () => {
-    expect(stepFrameTime(0, -1)).toBe(0);
-  });
 });

package/src/player/lib/time.ts

@@ -19,12 +19,6 @@ export function frameToSeconds(frame: number, fps = STUDIO_PREVIEW_FPS): number
   return frame / fps;
 }
 
-export function stepFrameTime(time: number, deltaFrames: number, fps = STUDIO_PREVIEW_FPS): number {
-  const currentFrame = secondsToFrame(time, fps);
-  const nextFrame = Math.max(0, currentFrame + deltaFrames);
-  return frameToSeconds(nextFrame, fps);
-}
-
 export function formatFrameTime(time: number, duration: number, fps = STUDIO_PREVIEW_FPS): string {
   const currentFrame = secondsToFrame(time, fps);
   const totalFrames = secondsToFrame(duration, fps);