@hyperframes/studio 0.8.80 → 0.8.82

package/src/player/components/VideoThumbnail.test.tsx

@@ -2,6 +2,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { VideoThumbnail } from "./VideoThumbnail";
@@ -13,12 +14,6 @@ Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
   value: true,
 });
 
-class MockResizeObserver {
-  observe() {}
-  disconnect() {}
-  unobserve() {}
-}
-
 let host: HTMLDivElement;
 let root: Root | null = null;
 
@@ -36,8 +31,9 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-async function render(width = 0) {
+async function render(width = 0, height = 40) {
   Object.defineProperty(host, "clientWidth", { configurable: true, value: width });
+  Object.defineProperty(host, "clientHeight", { configurable: true, value: height });
   root = createRoot(host);
   await act(async () => {
     root!.render(
@@ -66,13 +62,13 @@ describe("VideoThumbnail", () => {
     expect(decodeVideoThumbnail).not.toHaveBeenCalled();
   });
 
-  it("requests a geometry-sized filmstrip by default", async () => {
+  it("requests a filmstrip sized by the measured clip height", async () => {
     vi.mocked(decodeVideoThumbnail).mockResolvedValue({
       value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
       weight: 256,
     });
 
-    await render(500);
+    await render(440);
 
     expect(decodeVideoThumbnail).toHaveBeenNthCalledWith(
       1,
@@ -93,7 +89,7 @@ describe("VideoThumbnail", () => {
       weight: 256,
     });
 
-    await render(500);
+    await render(300);
 
     const tiles = [...host.querySelectorAll("img")].map((img) => img.getAttribute("src"));
     expect(tiles).toEqual(["blob:0", "blob:2", "blob:4", "blob:5", "blob:7"]);
@@ -105,11 +101,37 @@ describe("VideoThumbnail", () => {
       weight: 128,
     });
 
-    await render(100);
+    await render(60);
 
     expect(decodeVideoThumbnail).toHaveBeenCalledTimes(1);
   });
 
+  it("tiles a wide picture at the clip's measured height, whole", async () => {
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "image", url: "blob:wide", aspect: 2.7 },
+      weight: 128,
+    });
+
+    await render(500, 40);
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
+  it("re-tiles at the height the resize observer reports", async () => {
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "image", url: "blob:wide", aspect: 2.7 },
+      weight: 128,
+    });
+    await render(0, 0);
+
+    await act(async () => {
+      reportResize(500, 40);
+      await Promise.resolve();
+    });
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
   it("clears the loading shimmer when the scheduled decode fails", async () => {
     vi.mocked(decodeVideoThumbnail).mockRejectedValue(new Error("decode failed"));
 

package/src/player/components/VideoThumbnail.tsx

@@ -1,17 +1,13 @@
-import { memo, useCallback, useMemo, useRef, useState } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
+import { memo, useMemo } from "react";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import {
   createThumbnailKey,
   type ThumbnailPriority,
   type ThumbnailSnapshot,
 } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
-import {
-  computeThumbnailStrip,
-  quantizeThumbnailFrameCount,
-  THUMBNAIL_CLIP_HEIGHT,
-} from "./thumbnailUtils";
+import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -89,10 +85,9 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   sessionEpoch = 0,
   priority = "visible",
 }: VideoThumbnailProps) {
-  const [containerWidth, setContainerWidth] = useState(0);
-  const observerRef = useRef<ResizeObserver | null>(null);
+  const [container, setContainerRef] = useThumbnailStripSize();
   const requestFrameCount = quantizeThumbnailFrameCount(
-    computeThumbnailStrip(containerWidth, 16 / 9).frameCount,
+    computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
   );
   const requestProps = useMemo(
     () => ({
@@ -114,7 +109,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
     [requestFrameCount, requestProps],
   );
-  const measured = containerWidth > 0;
+  const measured = container.width > 0;
   const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
   const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
   const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
@@ -122,24 +117,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   const urls =
     value?.kind === "filmstrip" ? value.urls : value?.kind === "image" ? [value.url] : [];
   const aspect = value?.kind === "image" || value?.kind === "filmstrip" ? value.aspect : 16 / 9;
-  const { frameW, frameCount } = computeThumbnailStrip(
-    containerWidth,
-    aspect,
-    THUMBNAIL_CLIP_HEIGHT,
-  );
-
-  const setContainerRef = useCallback((element: HTMLDivElement | null) => {
-    observerRef.current?.disconnect();
-    if (!element) return;
-    const target = element.parentElement ?? element;
-    setContainerWidth(target.clientWidth);
-    observerRef.current = new ResizeObserver(([entry]) =>
-      setContainerWidth(entry.contentRect.width),
-    );
-    observerRef.current.observe(target);
-  }, []);
-
-  useMountEffect(() => () => observerRef.current?.disconnect());
+  const { frameW, frameCount } = computeThumbnailStrip(container.width, aspect, container.height);
 
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">

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

@@ -4,49 +4,45 @@ import {
   encodePreviewPath,
   resolveMediaPreviewUrl,
   quantizeThumbnailFrameCount,
-  THUMBNAIL_CLIP_HEIGHT,
 } from "./thumbnailUtils";
 
 describe("computeThumbnailStrip", () => {
   it("sizes tiles by aspect ratio at the clip height", () => {
-    const { frameW } = computeThumbnailStrip(500, 16 / 9);
-    expect(frameW).toBe(Math.round(THUMBNAIL_CLIP_HEIGHT * (16 / 9)));
+    expect(computeThumbnailStrip(500, 16 / 9, 40).frameW).toBe(71);
+    expect(computeThumbnailStrip(500, 2.7, 40).frameW).toBe(108);
   });
 
   it("repeats tiles to cover the container width", () => {
-    const { frameW, frameCount } = computeThumbnailStrip(500, 1);
-    expect(frameW).toBe(THUMBNAIL_CLIP_HEIGHT);
-    expect(frameCount).toBe(Math.ceil(500 / THUMBNAIL_CLIP_HEIGHT));
+    const { frameW, frameCount } = computeThumbnailStrip(500, 1, 40);
+    expect(frameW).toBe(40);
+    expect(frameCount).toBe(13);
     expect(frameCount * frameW).toBeGreaterThanOrEqual(500);
   });
 
   it("paints tiles across the full clip past the shared visible-frame budget", () => {
-    expect(computeThumbnailStrip(14_400, 16 / 9).frameCount).toBeGreaterThan(33);
+    expect(computeThumbnailStrip(14_400, 16 / 9, 40).frameCount).toBeGreaterThan(33);
   });
 
-  it("returns one tile when the container width is unknown", () => {
-    expect(computeThumbnailStrip(0, 16 / 9).frameCount).toBe(1);
-    expect(computeThumbnailStrip(-10, 16 / 9).frameCount).toBe(1);
+  it("returns one tile until the container is measured", () => {
+    expect(computeThumbnailStrip(0, 16 / 9, 40).frameCount).toBe(1);
+    expect(computeThumbnailStrip(-10, 16 / 9, 40).frameCount).toBe(1);
+    expect(computeThumbnailStrip(500, 16 / 9, 0).frameCount).toBe(1);
   });
 
   it("falls back to 16:9 for degenerate aspects", () => {
-    const expected = Math.round(THUMBNAIL_CLIP_HEIGHT * (16 / 9));
-    expect(computeThumbnailStrip(300, 0).frameW).toBe(expected);
-    expect(computeThumbnailStrip(300, -2).frameW).toBe(expected);
-    expect(computeThumbnailStrip(300, Number.NaN).frameW).toBe(expected);
-    expect(computeThumbnailStrip(300, Number.POSITIVE_INFINITY).frameW).toBe(expected);
+    const expected = Math.round(40 * (16 / 9));
+    expect(computeThumbnailStrip(300, 0, 40).frameW).toBe(expected);
+    expect(computeThumbnailStrip(300, -2, 40).frameW).toBe(expected);
+    expect(computeThumbnailStrip(300, Number.NaN, 40).frameW).toBe(expected);
+    expect(computeThumbnailStrip(300, Number.POSITIVE_INFINITY, 40).frameW).toBe(expected);
   });
 
   it("never returns a zero-width tile (avoids divide-by-zero repeat counts)", () => {
-    const { frameW, frameCount } = computeThumbnailStrip(300, 0.001);
+    const { frameW, frameCount } = computeThumbnailStrip(300, 0.001, 40);
     expect(frameW).toBeGreaterThanOrEqual(1);
     expect(Number.isFinite(frameCount)).toBe(true);
   });
 
-  it("honors a custom clip height", () => {
-    expect(computeThumbnailStrip(300, 2, 40).frameW).toBe(80);
-  });
-
   it("keeps narrow tiles above a caller-owned minimum", () => {
     expect(computeThumbnailStrip(300, 0.25, 40, 48)).toEqual({
       frameW: 48,

package/src/player/components/thumbnailUtils.ts

@@ -1,7 +1,5 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { MAX_VISIBLE_THUMBNAIL_FRAMES } from "../lib/timelineViewportBudgets";
-/** Rendered height of a timeline-clip thumbnail strip, in CSS px. */
-export const THUMBNAIL_CLIP_HEIGHT = 66;
 
 export interface ThumbnailStripLayout {
   /** Width of a single tile, in CSS px. */
@@ -63,19 +61,20 @@ export function probeImageAspect(
 }
 
 /**
- * Compute the film-strip tile layout for a clip thumbnail: fixed-height tiles
- * sized by the media's aspect ratio, repeated to fill the clip width.
- * Degenerate aspects (0, negative, NaN, Infinity) fall back to 16:9.
+ * Compute the film-strip tile layout for a clip thumbnail: tiles as tall as
+ * the measured strip, sized by the media's aspect ratio, repeated to fill the
+ * clip width. Degenerate aspects (0, negative, NaN, Infinity) fall back to 16:9.
  */
 export function computeThumbnailStrip(
   containerWidth: number,
   aspect: number,
-  clipHeight: number = THUMBNAIL_CLIP_HEIGHT,
+  clipHeight: number,
   minFrameWidth = 1,
 ): ThumbnailStripLayout {
   const safeAspect = Number.isFinite(aspect) && aspect > 0 ? aspect : 16 / 9;
   const frameW = Math.max(minFrameWidth, Math.round(clipHeight * safeAspect));
-  const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
+  const measured = containerWidth > 0 && clipHeight > 0;
+  const frameCount = measured ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
   return { frameW, frameCount };
 }
 

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

@@ -880,6 +880,61 @@ describe("resolveTimelineResize", () => {
     expect(next.start).toBe(2);
   });
 
+  function headTrimmedFullyRight(clip: { start: number; duration: number }) {
+    const single = resolveTimelineResize(
+      { ...clip, originClientX: 0, pixelsPerSecond: 100, minStart: 0, maxEnd: 10 },
+      "start",
+      1000,
+    );
+    const group = resolveTimelineGroupResize([clip], "start", 10).members[0]!;
+    return { single: single.duration, group: group.duration };
+  }
+
+  it.each([
+    { start: 1, duration: 0.625 },
+    { start: 1.005, duration: 2 },
+  ])("keeps the minimum duration when a head trim runs off the grid (%o)", (clip) => {
+    const { single, group } = headTrimmedFullyRight(clip);
+    expect(Math.min(single, group)).toBeGreaterThanOrEqual(0.1);
+  });
+
+  it("keeps the minimum duration for any off-grid start and length on a 1 ms grid", () => {
+    const short: string[] = [];
+    for (let i = 0; i < 20; i++) {
+      for (let j = 0; j < 18; j++) {
+        const clip = { start: (1000 + i * 13) / 1000, duration: (100 + j * 17) / 1000 };
+        const { single, group } = headTrimmedFullyRight(clip);
+        if (Math.min(single, group) < 0.1 - 1e-9) short.push(`${clip.start}+${clip.duration}`);
+      }
+    }
+    expect(short).toEqual([]);
+  });
+
+  it("stops a group head trim where the single-clip trim stops", () => {
+    const { single, group } = headTrimmedFullyRight({ start: 1.003, duration: 2 });
+    expect(group).toBe(single);
+  });
+
+  it("moves on-grid group members together when the tightest member sits 5 ms off the grid", () => {
+    const members = [
+      { start: 1.005, duration: 2 },
+      { start: 0, duration: 5 },
+      { start: 0.24, duration: 5 },
+    ];
+    const next = resolveTimelineGroupResize(members, "start", 10).members;
+    expect(next.map((m) => m.start)).toEqual([2.9, 1.89, 2.13]);
+  });
+
+  it("never moves a group head trim left of zero near the minimum length", () => {
+    const [member] = resolveTimelineGroupResize(
+      [{ start: 0.004, duration: 0.1 }],
+      "start",
+      10,
+    ).members;
+    expect(member!.start).toBeGreaterThanOrEqual(0);
+    expect(member!.duration).toBeGreaterThanOrEqual(0.1);
+  });
+
   it("moves every group member by the same amount when one reaches its media start", () => {
     const members = [
       { start: 2, duration: 3, playbackStart: 1, playbackRate: 1.5 },

package/src/player/components/timelineGroupEditing.ts

@@ -1,3 +1,4 @@
+import { clampPlaybackRate } from "@hyperframes/parsers/media-duration";
 import { roundToCenti } from "../../utils/rounding";
 import type { TimelineElement } from "../store/playerStore";
 import { getTimelineEditCapabilities } from "./timelineEditCapabilities";
@@ -19,13 +20,17 @@ function ceilTimelineTime(value: number): number {
   return Math.ceil((value - SAVED_MEDIA_OFFSET_TOLERANCE) * 100) / 100;
 }
 
+function floorTimelineTime(value: number): number {
+  return Math.floor((value + SAVED_MEDIA_OFFSET_TOLERANCE) * 100) / 100;
+}
+
 export function resolveTimelineMinDuration(minDuration?: number): number {
   return Math.max(ABSOLUTE_TIMELINE_MIN_DURATION, minDuration ?? DEFAULT_TIMELINE_MIN_DURATION);
 }
 
 /** Playback rate never drops to zero (would make media-in-point math divide by ~0). */
-function resolveTimelinePlaybackRate(rate?: number): number {
-  return Math.max(0.1, rate ?? 1);
+export function resolveTimelinePlaybackRate(rate?: number): number {
+  return clampPlaybackRate(rate ?? 1);
 }
 
 interface TimelineStartTrimClip {
@@ -38,8 +43,8 @@ interface TimelineStartTrimClip {
 /**
  * Delta bounds for trimming a clip's START edge (shared by single-clip and group
  * resize). Left-bounded by how far the start can move toward `minStart` and by the
- * media in-point (`playbackStart / playbackRate`); right-bounded by `minDuration`.
- * Returned deltas are unrounded; applyClipStartTrimDelta does the rounding.
+ * media in-point (`playbackStart / playbackRate`); right-bounded by `minDuration`, the start
+ * floored onto the centisecond grid. Otherwise unrounded; applyClipStartTrimDelta rounds.
  */
 export function clipStartTrimDeltaBounds(
   clip: TimelineStartTrimClip,
@@ -51,7 +56,7 @@ export function clipStartTrimDeltaBounds(
     clip.playbackStart != null ? clip.playbackStart / playbackRate : Number.POSITIVE_INFINITY;
   return {
     minDelta: -Math.min(clip.start - minStart, maxLeftExtensionFromMedia),
-    maxDelta: clip.duration - minDuration,
+    maxDelta: floorTimelineTime(clip.start + clip.duration - minDuration) - clip.start,
   };
 }
 
@@ -137,7 +142,9 @@ export function clampTimelineGroupResizeDelta(
   const bounds = members.map((member) => clipStartTrimDeltaBounds(member, 0, minDuration));
   const minDelta = ceilTimelineTime(Math.max(...bounds.map((b) => b.minDelta)));
   const maxDelta = Math.min(...bounds.map((b) => b.maxDelta));
-  return roundTimelineTime(clamp(rawDelta, minDelta, maxDelta));
+  const delta = roundTimelineTime(clamp(rawDelta, minDelta, maxDelta));
+  const roundedPastTightestMember = delta > maxDelta + SAVED_MEDIA_OFFSET_TOLERANCE;
+  return roundedPastTightestMember ? maxDelta - SAVED_MEDIA_OFFSET_TOLERANCE : delta;
 }
 
 export function resolveTimelineGroupResize(

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

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
+
+const x = (transform: string) => Number(/translateX\(([-\d.e]+)px\)/.exec(transform)?.[1]);
+
+describe("getTimelinePlayheadTransform", () => {
+  it("keeps fractional pixels while playing, so slow motion does not stair-step", () => {
+    // Fit zoom on a two-minute film is about 13.3px a second: 120 frames of one second of playback.
+    const frames = Array.from({ length: 121 }, (_, i) => i / 120);
+    const playing = new Set(frames.map((t) => getTimelinePlayheadTransform(t, 13.3, 80, false, 1)));
+    const resting = new Set(frames.map((t) => getTimelinePlayheadTransform(t, 13.3, 80, true, 1)));
+    expect(playing.size).toBe(121);
+    expect(resting.size).toBeLessThan(20);
+  });
+
+  it("at rest puts the line on the device pixel layout gives its ruler tick", () => {
+    // The 1px line sits 4px into the 9px wrapper; the tick is laid out at t * pps - 0.5 and rounded by layout.
+    for (const dpr of [1, 1.5, 2]) {
+      for (let i = 0; i <= 400; i += 1) {
+        const t = i * 0.0137;
+        const wrapper = x(getTimelinePlayheadTransform(t, 13.3, 80, true, dpr));
+        const lineDevicePx = Math.round((wrapper + 4) * dpr);
+        const tickDevicePx = Math.round((80 + t * 13.3 - 0.5) * dpr);
+        expect(lineDevicePx, `t=${t} dpr=${dpr}`).toBe(tickDevicePx);
+      }
+    }
+  });
+
+  it("at time zero at 1x lands the line on the tick's column", () => {
+    expect(getTimelinePlayheadTransform(0, 100, 80, true, 1)).toBe("translateX(76px)");
+    expect(Math.round(80 - 0.5)).toBe(76 + 4);
+  });
+});

package/src/player/components/timelinePlayheadTransform.ts

@@ -0,0 +1,17 @@
+import { getTimelinePlayheadLeft } from "./timelineLayout";
+
+/**
+ * Moves the playhead by transform, with no relayout. Playing, it keeps fractional pixels so slow motion stays
+ * smooth; at rest it rounds to device pixels the way layout rounds the ruler ticks, so the line sits on its tick.
+ */
+export function getTimelinePlayheadTransform(
+  time: number,
+  pixelsPerSecond: number,
+  contentOrigin: number,
+  atRest: boolean,
+  devicePixelRatio = globalThis.devicePixelRatio || 1,
+): string {
+  const left = getTimelinePlayheadLeft(time, pixelsPerSecond, contentOrigin);
+  if (!atRest) return `translateX(${left}px)`;
+  return `translateX(${Math.round(left * devicePixelRatio) / devicePixelRatio}px)`;
+}

package/src/player/components/useTimelinePlayhead.ts

@@ -4,12 +4,12 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
   getTimelinePlaybackFollowScrollLeft,
-  getTimelinePlayheadLeft,
   getTimelineScrubTime,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
   shouldAutoScrollTimeline,
 } from "./timelineLayout";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
 interface UseTimelinePlayheadInput {
@@ -92,7 +92,12 @@ export function useTimelinePlayhead({
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(time, ppsRef.current, contentOrigin)}px`;
+      playheadRef.current.style.transform = getTimelinePlayheadTransform(
+        time,
+        ppsRef.current,
+        contentOrigin,
+        !usePlayerStore.getState().isPlaying,
+      );
     },
     [playheadRef, durationRef, ppsRef, contentOrigin],
   );
@@ -122,14 +127,24 @@ export function useTimelinePlayhead({
   }, [zoomMode, scrollRef]);
 
   useMountEffect(() => {
-    const unsub = liveTime.subscribe((t) => {
-      if (!playheadRef.current || durationRef.current <= 0) return;
-      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(
+    let lastLiveTime = usePlayerStore.getState().currentTime;
+    const place = (t: number, atRest: boolean) => {
+      if (!playheadRef.current || durationRef.current <= 0) return false;
+      playheadRef.current.style.transform = getTimelinePlayheadTransform(
         t,
         ppsRef.current,
         contentOriginRef.current,
-      )}px`;
+        atRest,
+      );
+      return true;
+    };
+    const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
+      if (prev.isPlaying && !state.isPlaying) place(lastLiveTime, true);
+    });
+    const unsub = liveTime.subscribe((t) => {
+      lastLiveTime = t;
+      if (!place(t, !usePlayerStore.getState().isPlaying)) return;
+      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
       const scroll = scrollRef.current;
       if (
         !scroll ||
@@ -150,7 +165,10 @@ export function useTimelinePlayhead({
         scroll.scrollLeft = nextScrollLeft;
       }
     });
-    return unsub;
+    return () => {
+      unsub();
+      unsubPlaying();
+    };
   });
 
   const seekFromX = useCallback(

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { timelineElementsChanged } from "./timelinePlayerSync";
+
+describe("timelineElementsChanged", () => {
+  const clip = { id: "v", tag: "video", start: 0, duration: 4, track: 1 };
+  it.each([
+    ["muted", { muted: true }],
+    ["sound", { hasAudio: true }],
+    ["volume", { volume: 0 }],
+    ["speed", { playbackRate: 2 }],
+    ["hidden", { hidden: true }],
+    ["audio group volume", { audioGroupVolume: 0 }],
+    ["audio group hidden", { audioGroupHidden: true }],
+    ["fade in", { fadeIn: 1 }],
+    ["fade out", { fadeOut: 1 }],
+  ])("sees a clip whose %s changed with no timing change", (_name, change) => {
+    expect(timelineElementsChanged([clip], [{ ...clip, ...change }])).toBe(true);
+    expect(timelineElementsChanged([{ ...clip, ...change }], [{ ...clip, ...change }])).toBe(false);
+  });
+});

package/src/player/hooks/timelinePlayerSync.ts

@@ -1,5 +1,22 @@
 import type { TimelineElement } from "../store/playerStore";
 
+const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
+  "id",
+  "start",
+  "duration",
+  "track",
+  "sourceDuration",
+  "muted",
+  "hasAudio",
+  "volume",
+  "playbackRate",
+  "hidden",
+  "audioGroupVolume",
+  "audioGroupHidden",
+  "fadeIn",
+  "fadeOut",
+];
+
 /** Whether a derived timeline changes any field that affects rendering. */
 export function timelineElementsChanged(
   previous: TimelineElement[],
@@ -8,13 +25,6 @@ export function timelineElementsChanged(
   if (next.length !== previous.length) return true;
   return next.some((element, index) => {
     const prior = previous[index];
-    return (
-      !prior ||
-      element.id !== prior.id ||
-      element.start !== prior.start ||
-      element.duration !== prior.duration ||
-      element.track !== prior.track ||
-      element.sourceDuration !== prior.sourceDuration
-    );
+    return !prior || RENDERED_FIELDS.some((key) => element[key] !== prior[key]);
   });
 }

package/src/player/hooks/useShadowPreviewReload.ts

@@ -12,7 +12,7 @@ import {
   type PreviewIframeSlot,
   type UseTimelineSyncCallbacksParams,
 } from "./useTimelineSyncCallbacks";
-import type { PlaybackAdapter } from "../lib/playbackTypes";
+import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { usePlayerStore } from "../store/playerStore";
 
@@ -23,6 +23,11 @@ export const SHADOW_READY_TIMEOUT_MS = 15_000;
 // A busy machine can need more than one budget; the shadow keeps loading for this many before it is dropped.
 export const SHADOW_READY_BUDGETS = 3;
 
+function restoreSeekPainted(iframe: HTMLIFrameElement | null): Promise<void> | undefined {
+  const win = iframe?.contentWindow as IframeWindow | null | undefined;
+  return win?.__hfWaitForSeekCompletion?.().catch(() => {});
+}
+
 function isDocumentHidden(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
@@ -136,10 +141,16 @@ export function useShadowPreviewReload({
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
   const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
   const markAdapterReady = useCallback(
-    (_iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
+    (iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
       if (gen == null || gen !== shadowGenRef.current) return;
-      pendingCommitRef.current = { gen, commit };
-      promoteWhenReady(gen);
+      const register = () => {
+        if (gen !== shadowGenRef.current) return;
+        pendingCommitRef.current = { gen, commit };
+        promoteWhenReady(gen);
+      };
+      const painted = restoreSeekPainted(iframe);
+      if (painted) void painted.then(register);
+      else register();
     },
     [promoteWhenReady],
   );

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

@@ -325,6 +325,25 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("promotes only once the shadow's restore seek has painted its frame", async () => {
+    const { getApi, live, gen, root } = beginReload();
+    const shadow = makeShadowWithSpies();
+    let seekPainted = () => {};
+    Object.assign(shadow.iframe.contentWindow!, {
+      __hfWaitForSeekCompletion: () => new Promise<void>((resolve) => (seekPainted = resolve)),
+    });
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(live);
+
+    await act(async () => seekPainted());
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    unmount(root);
+  });
+
   it("promotes when the loader clears before the adapter is ready", () => {
     const { getApi, gen, root } = beginReload();
     const shadow = makeShadowWithSpies();