@hyperframes/studio 0.8.63 → 0.8.65

package/src/player/components/Timeline.virtualization.test.tsx

@@ -140,7 +140,7 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
     usePlayerStore.getState().reset();
   });
 
-  it("defers rich clip content while scrolling without replacing the clip shell", async () => {
+  it("keeps a clip's picture on screen while the timeline scrolls", async () => {
     const [{ Timeline }, { usePlayerStore }] = await Promise.all([
       import("./Timeline"),
       import("../store/playerStore"),
@@ -167,17 +167,62 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
       expect(scroller).not.toBeNull();
       expect(clip).not.toBeNull();
       expect(clip?.title).toBe("Clip 0 • 0.0s – 10.0s");
-      expect(host.querySelector("[data-rich-content]")).not.toBeNull();
+      const picture = host.querySelector("[data-rich-content]");
+      expect(picture).not.toBeNull();
 
       if (scroller) await dispatchScroll(scroller);
       expect(host.querySelector('[data-el-id="clip-0"]')).toBe(clip);
-      expect(host.querySelector("[data-rich-content]")).toBeNull();
+      expect(host.querySelector("[data-rich-content]")).toBe(picture);
 
       await act(async () => {
         await new Promise((resolve) => setTimeout(resolve, 110));
       });
       expect(host.querySelector('[data-el-id="clip-0"]')).toBe(clip);
-      expect(host.querySelector("[data-rich-content]")).not.toBeNull();
+      expect(host.querySelector("[data-rich-content]")).toBe(picture);
+    } finally {
+      act(() => root.unmount());
+      usePlayerStore.getState().reset();
+    }
+  });
+
+  it("gives a clip that appears mid-scroll its picture once the scroll settles", async () => {
+    const [{ Timeline }, { usePlayerStore }] = await Promise.all([
+      import("./Timeline"),
+      import("../store/playerStore"),
+    ]);
+    const clip = (id: string, start: number) => ({
+      id,
+      label: id,
+      tag: "div",
+      start,
+      duration: 5,
+      track: 0,
+    });
+    usePlayerStore.setState({ duration: 60, timelineReady: true, elements: [clip("clip-0", 0)] });
+
+    const { host, root } = await mountTimeline(
+      React.createElement(Timeline, {
+        renderClipContent: (element: { id: string }) =>
+          React.createElement("span", { "data-rich-content": element.id }),
+      }),
+    );
+    try {
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 110));
+      });
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]");
+      if (scroller) await dispatchScroll(scroller);
+      act(() => {
+        usePlayerStore.setState({ elements: [clip("clip-0", 0), clip("clip-1", 5)] });
+      });
+      expect(host.querySelector('[data-el-id="clip-1"]')).not.toBeNull();
+      expect(host.querySelector('[data-rich-content="clip-1"]')).toBeNull();
+      expect(host.querySelector('[data-rich-content="clip-0"]')).not.toBeNull();
+
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 110));
+      });
+      expect(host.querySelector('[data-rich-content="clip-1"]')).not.toBeNull();
     } finally {
       act(() => root.unmount());
       usePlayerStore.getState().reset();

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

@@ -14,6 +14,16 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import type { DraggedClipState, BlockedClipState } from "./useTimelineClipDrag";
+import * as transitionSeams from "./timelineTransitionSeams";
+
+vi.mock("./timelineTransitionSeams", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./timelineTransitionSeams")>();
+  return {
+    ...actual,
+    deriveTimelineTransitionSeams: vi.fn(actual.deriveTimelineTransitionSeams),
+    deriveTimelineTransitionSeamsByTrack: vi.fn(actual.deriveTimelineTransitionSeamsByTrack),
+  };
+});
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -497,3 +507,21 @@ describe("TimelineLanes clip joins", () => {
     act(() => view.root.unmount());
   });
 });
+
+describe("TimelineLanes transition seams", () => {
+  it("derives transition seams once for every row, not once per row", () => {
+    const derivations = [
+      transitionSeams.deriveTimelineTransitionSeams,
+      transitionSeams.deriveTimelineTransitionSeamsByTrack,
+    ].map((derive) => vi.mocked(derive));
+    for (const derive of derivations) derive.mockClear();
+
+    const view = renderLanes({
+      elements: [element("clip-a", 0), element("clip-b", TRACK_A), element("clip-c", TRACK_B)],
+    });
+
+    expect(view.host.querySelectorAll("[data-timeline-row]").length).toBeGreaterThanOrEqual(3);
+    expect(derivations.reduce((calls, derive) => calls + derive.mock.calls.length, 0)).toBe(1);
+    act(() => view.root.unmount());
+  });
+});

package/src/player/components/TimelineLanes.tsx

@@ -33,6 +33,7 @@ import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
 import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
 import { TimelineTransitionOverlays } from "./TimelineTransitionOverlays";
+import { deriveTimelineTransitionSeamsByTrack } from "./timelineTransitionSeams";
 
 export function TimelineLanes({
   pps,
@@ -105,8 +106,9 @@ export function TimelineLanes({
   const { collapsedGroupIds, expandedLaneOwnerIds, toggleGroupExpanded, toggleLaneOwnerExpanded } =
     useTimelineGroupDisclosure();
   const automationLanes = useAutomationLanes();
-  const allTransitionElements = useMemo(
-    () => tracks.flatMap(([, elements]) => elements.map(getPreviewElement)),
+  const transitionSeamsByTrack = useMemo(
+    () =>
+      deriveTimelineTransitionSeamsByTrack(tracks.flatMap(([, els]) => els.map(getPreviewElement))),
     [getPreviewElement, tracks],
   );
   // A group's automation clock is COMPOSITION time (groups doc §1.3), so its
@@ -551,8 +553,7 @@ export function TimelineLanes({
                   })
                 }
                 <TimelineTransitionOverlays
-                  transitionElements={allTransitionElements}
-                  track={trackNum}
+                  seams={transitionSeamsByTrack.get(trackNum) ?? []}
                   rowElements={draggedClip?.started ? [] : automationElements}
                   rowBackground={rowBackground}
                   pixelsPerSecond={pps}

package/src/player/components/TimelineTransitionOverlays.tsx

@@ -1,13 +1,12 @@
 import { CLIP_Y } from "./timelineLayout";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
-import { deriveTimelineTransitionSeams } from "./timelineTransitionSeams";
+import type { TimelineTransitionSeam } from "./timelineTransitionSeams";
 import { TimelineTransitionBadge } from "./TimelineTransitionBadge";
 import { TimelineClipJoins } from "./TimelineClipJoins";
 
 interface TimelineTransitionOverlaysProps {
-  transitionElements: readonly TimelineElement[];
-  track: number;
+  seams: readonly TimelineTransitionSeam[];
   rowElements: readonly TimelineElement[];
   rowBackground: string;
   pixelsPerSecond: number;
@@ -17,8 +16,7 @@ interface TimelineTransitionOverlaysProps {
 
 /** What a row draws where its clips meet: a hairline at an exact join, a badge over a transition. */
 export function TimelineTransitionOverlays({
-  transitionElements,
-  track,
+  seams,
   rowElements,
   rowBackground,
   pixelsPerSecond,
@@ -26,9 +24,6 @@ export function TimelineTransitionOverlays({
   clipBarHeight,
 }: TimelineTransitionOverlaysProps) {
   const top = CLIP_Y + (clipBarHeight ?? rowHeight - 2 * CLIP_Y) / 2;
-  const seams = deriveTimelineTransitionSeams(transitionElements).filter(
-    (seam) => seam.incoming.track === track,
-  );
   return (
     <>
       <TimelineClipJoins

package/src/player/components/timelineClipChildren.tsx

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 import type { TrackVisualStyle } from "./timelineIcons";
@@ -29,6 +29,16 @@ function ClipLintDot({ element }: { element: TimelineElement }) {
   );
 }
 
+/**
+ * Mounts a clip's content only once the timeline is at rest, then keeps it through later scrolls,
+ * so a scroll never blanks a picture already on screen and never mounts a screenful of new ones.
+ */
+export function ClipContentOnceShown({ hold, children }: { hold: boolean; children: ReactNode }) {
+  const [shown, setShown] = useState(!hold);
+  if (!shown && !hold) setShown(true);
+  return shown ? children : null;
+}
+
 export function renderClipChildren(
   element: TimelineElement,
   clipStyle: TrackVisualStyle,

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

@@ -3,7 +3,6 @@
 import { describe, expect, it, vi } from "vitest";
 import {
   buildTimelineMeta,
-  resolveRenderClipContent,
   resolveResizingElementIds,
   shouldIgnoreTimelinePointerDown,
   type TimelineMetaBuilderInputs,
@@ -85,12 +84,6 @@ describe("buildTimelineMeta", () => {
 });
 
 describe("timeline provider branch helpers", () => {
-  it("resolves virtualized clip content", () => {
-    const render = () => null;
-    expect(resolveRenderClipContent(true, true, render)).toBeUndefined();
-    expect(resolveRenderClipContent(false, true, render)).toBe(render);
-  });
-
   it("resolves resizing element ids", () => {
     expect(resolveResizingElementIds(null)).toBeUndefined();
     expect(resolveResizingElementIds({ element: { id: "clip" } } as never)).toEqual(["clip"]);

package/src/player/components/timelineProviderStateBuilders.ts

@@ -4,7 +4,6 @@ import type {
   TimelineViewportProps,
 } from "./TimelineProvider";
 import type { ResizingClipState } from "./useTimelineClipDrag";
-import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
@@ -34,14 +33,6 @@ export function resolveResizingElementIds(
   return undefined;
 }
 
-export function resolveRenderClipContent(
-  rowVirtualizationActive: boolean,
-  isScrolling: boolean,
-  renderClipContent: TimelineLaneBaseProps["renderClipContent"],
-): TimelineLaneBaseProps["renderClipContent"] {
-  return rowVirtualizationActive && isScrolling ? undefined : renderClipContent;
-}
-
 export function shouldIgnoreTimelinePointerDown(target: EventTarget | null): boolean {
   return target instanceof Element && target.closest("button, input, select, a") !== null;
 }

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

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { deriveTimelineTransitionSeams } from "./timelineTransitionSeams";
+import {
+  deriveTimelineTransitionSeams,
+  deriveTimelineTransitionSeamsByTrack,
+} from "./timelineTransitionSeams";
 import type { TimelineElement } from "../store/playerStore";
 
 const clip = (
@@ -46,3 +49,20 @@ describe("deriveTimelineTransitionSeams", () => {
     expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2, 1)])).toEqual([]);
   });
 });
+
+describe("deriveTimelineTransitionSeamsByTrack", () => {
+  it("finds each track's transitions even when another track's clip starts between them", () => {
+    const label = "hf:transition:out:in:crossfade";
+    const other = "hf:transition:a:b:wipe";
+    const byTrack = deriveTimelineTransitionSeamsByTrack([
+      clip("out", 0, 2, 0, label),
+      clip("in", 1.8, 2, 0, label),
+      clip("a", 5, 2, 2, other),
+      clip("b", 6.5, 2, 2, other),
+      clip("alone", 0, 3, 1),
+    ]);
+    expect(byTrack.get(0)?.map((seam) => seam.incoming.id)).toEqual(["in"]);
+    expect(byTrack.get(2)?.map((seam) => seam.incoming.id)).toEqual(["b"]);
+    expect(byTrack.has(1)).toBe(false);
+  });
+});

package/src/player/components/timelineTransitionSeams.ts

@@ -34,3 +34,24 @@ export function deriveTimelineTransitionSeams(
   }
   return seams;
 }
+
+/**
+ * Transition seams keyed by track, derived once for every row. Pairs are found within a track, so a clip on
+ * another track that starts between a transition's two clips cannot hide it.
+ */
+export function deriveTimelineTransitionSeamsByTrack(
+  elements: readonly TimelineElement[],
+): ReadonlyMap<number, readonly TimelineTransitionSeam[]> {
+  const tracks = new Map<number, TimelineElement[]>();
+  for (const element of elements) {
+    const track = tracks.get(element.track);
+    if (track) track.push(element);
+    else tracks.set(element.track, [element]);
+  }
+  const byTrack = new Map<number, readonly TimelineTransitionSeam[]>();
+  for (const [track, trackElements] of tracks) {
+    const seams = deriveTimelineTransitionSeams(trackElements);
+    if (seams.length > 0) byTrack.set(track, seams);
+  }
+  return byTrack;
+}

package/src/player/components/useTimelineProviderState.tsx

@@ -11,7 +11,6 @@ import type { ClipContextMenuState, TimelineContextValue } from "./TimelineProvi
 import {
   buildTimelineMeta,
   resolveMultiDragPreview,
-  resolveRenderClipContent,
   resolveResizingElementIds,
   shouldIgnoreTimelinePointerDown,
 } from "./timelineProviderStateBuilders";
@@ -22,6 +21,7 @@ import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
 import { GUTTER, LABEL_COL_W, TRACKS_LEFT_PAD } from "./timelineLayout";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
+import { ClipContentOnceShown } from "./timelineClipChildren";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineProps } from "./TimelineTypes";
 import {
@@ -509,10 +509,16 @@ export function useTimelineProviderState({
     onRazorSplit: editContext.onRazorSplit,
     onRazorSplitAll: editContext.onRazorSplitAll,
   };
-  const timelineRenderClipContent = resolveRenderClipContent(
-    timelineFocus.rowVirtualizationActive,
-    viewport.isScrolling,
-    renderClipContent,
+  const holdNewClipContent = timelineFocus.rowVirtualizationActive && viewport.isScrolling;
+  const timelineRenderClipContent = useMemo<typeof renderClipContent>(
+    () =>
+      renderClipContent &&
+      ((element, style, context) => (
+        <ClipContentOnceShown hold={holdNewClipContent}>
+          {renderClipContent(element, style, context)}
+        </ClipContentOnceShown>
+      )),
+    [holdNewClipContent, renderClipContent],
   );
   const timelineMeta = buildTimelineMeta({
     emptyState: {

package/src/player/hooks/useShadowPreviewReload.ts

@@ -13,6 +13,7 @@ import {
   type UseTimelineSyncCallbacksParams,
 } from "./useTimelineSyncCallbacks";
 import type { PlaybackAdapter } from "../lib/playbackTypes";
+import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 
 // The single wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
 // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
@@ -82,6 +83,7 @@ export function useShadowPreviewReload({
       isRefreshingRef.current = false;
       pendingSeekRef.current = null;
       setPreviewSlots(planShadowDiscard);
+      thumbnailScheduler.setPreviewReloading(false);
       const message = `The preview did not reload (${cause}). The previous preview is still showing.`;
       logReload("shadow-failed", { cause });
       console.error(`[studio] ${message}`);
@@ -105,6 +107,7 @@ export function useShadowPreviewReload({
       applyPreviewAudioState();
       setPreviewSlots((prev) => planShadowPromotion(prev, gen));
       onPromotedRef.current?.();
+      thumbnailScheduler.setPreviewReloading(false);
     },
     [stopPendingShadow, iframeRef, attachIframeShortcutListeners, applyPreviewAudioState],
   );
@@ -175,6 +178,8 @@ export function useShadowPreviewReload({
       budgetGenRef.current = gen;
       armReadyTimer(gen);
       setPreviewSlots((prev) => planShadowReload(prev, gen, url));
+      // Thumbnails of the edit wait for the new preview instead of competing with it.
+      thumbnailScheduler.setPreviewReloading(true);
     },
     [stopPendingShadow, armReadyTimer],
   );
@@ -187,6 +192,7 @@ export function useShadowPreviewReload({
     isRefreshingRef.current = false;
     pendingSeekRef.current = null;
     setPreviewSlots(planShadowDiscard);
+    thumbnailScheduler.setPreviewReloading(false);
   }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);
 
   // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow.
@@ -203,6 +209,7 @@ export function useShadowPreviewReload({
     return () => {
       document.removeEventListener("visibilitychange", onVisibilityChange);
       stopPendingShadow();
+      thumbnailScheduler.setPreviewReloading(false);
     };
   });
 

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

@@ -153,6 +153,39 @@ describe("ThumbnailScheduler", () => {
     expect(richLoad).toHaveBeenCalledTimes(1);
   });
 
+  it("holds composition renders while the preview reloads and re-runs the ones it preempted", async () => {
+    const scheduler = new ThumbnailScheduler();
+    const signals: AbortSignal[] = [];
+    const composition = vi.fn((signal: AbortSignal) => {
+      signals.push(signal);
+      return new Promise<ThumbnailLoadedResult>((resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")));
+        if (signals.length > 1) resolve(result("scene"));
+      });
+    });
+    const image = vi.fn(async () => result("still"));
+    const scene = request("scene", composition, "visible", { kind: "composition" });
+    const still = request("still", image);
+
+    scheduler.acquire(scene, vi.fn());
+    expect(composition).toHaveBeenCalledTimes(1);
+    scheduler.setPreviewReloading(true);
+    await flush();
+    expect(signals[0]?.aborted).toBe(true);
+    expect(scheduler.getSnapshot(scene)).toEqual({ status: "queued" });
+    scheduler.acquire(still, vi.fn());
+    expect(image).toHaveBeenCalledTimes(1);
+    expect(composition).toHaveBeenCalledTimes(1);
+
+    scheduler.setPreviewReloading(false);
+    await flush();
+    expect(composition).toHaveBeenCalledTimes(2);
+    expect(scheduler.getSnapshot(scene)).toMatchObject({
+      status: "ready",
+      value: { url: "scene" },
+    });
+  });
+
   it("aborts queued and active jobs after the final release", async () => {
     const scheduler = new ThumbnailScheduler(
       resolveTimelineViewportBudgets({ concurrentVideoDecodes: 1 }),

package/src/player/lib/thumbnailScheduler.ts

@@ -65,6 +65,8 @@ interface ThumbnailEntry {
   cached: boolean;
   lastAccess: number;
   snapshot: ThumbnailSnapshot;
+  /** Aborted by the preview-reload hold, to run again once the hold lifts. */
+  preempted: boolean;
 }
 
 const PRIORITY_SCORE: Readonly<Record<ThumbnailPriority, number>> = {
@@ -112,6 +114,7 @@ export class ThumbnailScheduler {
   private nextLeaseId = 1;
   private nextSequence = 1;
   private scrolling = false;
+  private previewReloading = false;
   private cacheBytes = 0;
   private waveformCacheBytes = 0;
   private readonly activeByBucket = { video: 0, composition: 0, general: 0 };
@@ -155,6 +158,7 @@ export class ThumbnailScheduler {
         cached: false,
         lastAccess: this.nextSequence++,
         snapshot: Object.freeze({ status: "queued" }),
+        preempted: false,
       };
       this.entries.set(scopedKey, entry);
     }
@@ -210,6 +214,24 @@ export class ThumbnailScheduler {
     if (!scrolling) this.pump();
   }
 
+  /**
+   * Hold server-rendered composition thumbnails while the preview loads a new document: both
+   * are served by the same Studio server, and the preview is what the person is waiting for.
+   */
+  setPreviewReloading(reloading: boolean): void {
+    if (this.previewReloading === reloading) return;
+    this.previewReloading = reloading;
+    if (!reloading) {
+      this.pump();
+      return;
+    }
+    for (const entry of this.entries.values()) {
+      if (entry.state !== "loading" || entry.request.kind !== "composition") continue;
+      entry.preempted = true;
+      entry.controller?.abort();
+    }
+  }
+
   /** Evict project cache entries that are no longer owned by mounted consumers. */
   invalidateProject(projectId: string): void {
     for (const [key, entry] of this.entries) {
@@ -257,6 +279,7 @@ export class ThumbnailScheduler {
 
     for (const entry of queued) {
       if (this.scrolling && entry.request.rich) continue;
+      if (this.previewReloading && entry.request.kind === "composition") continue;
       const bucket = concurrencyBucket(entry.request.kind);
       if (this.activeByBucket[bucket] >= this.bucketLimit(bucket)) continue;
       this.start(entry, bucket);
@@ -281,6 +304,7 @@ export class ThumbnailScheduler {
           this.deleteEntry(entry.scopedKey, entry);
           return;
         }
+        if (this.requeuePreempted(entry)) return;
         entry.state = "error";
         entry.error = errorFrom(reason);
         entry.failedAt = this.now();
@@ -303,6 +327,7 @@ export class ThumbnailScheduler {
   ): void {
     if (controller.signal.aborted || this.entries.get(entry.scopedKey) !== entry) {
       this.safeDispose(result.dispose);
+      this.requeuePreempted(entry);
       return;
     }
     this.validateResult(result);
@@ -317,6 +342,15 @@ export class ThumbnailScheduler {
     if (!entry.cached && entry.leases.size === 0) this.deleteEntry(entry.scopedKey, entry);
   }
 
+  private requeuePreempted(entry: ThumbnailEntry): boolean {
+    if (!entry.preempted || this.entries.get(entry.scopedKey) !== entry) return false;
+    entry.preempted = false;
+    entry.state = "queued";
+    entry.snapshot = Object.freeze({ status: "queued" });
+    this.notify(entry);
+    return true;
+  }
+
   private validateResult(result: ThumbnailLoadedResult): void {
     if (Number.isFinite(result.weight) && result.weight >= 0) return;
     this.safeDispose(result.dispose);

package/src/player/store/playerStore.test.ts

@@ -1,6 +1,7 @@
 // @vitest-environment happy-dom
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { usePlayerStore, liveTime, type TimelineElement } from "./playerStore";
+import { thumbnailRevisionOf } from "./thumbnailSlice";
 
 /** The playback/selection state `reset()` restores (persistent prefs asserted separately). */
 function expectResettableDefaults(state: ReturnType<typeof usePlayerStore.getState>): void {
@@ -32,25 +33,38 @@ describe("usePlayerStore", () => {
   });
 
   describe("thumbnail content revision", () => {
-    it("advances once per accepted persisted file event", () => {
-      const before = usePlayerStore.getState().thumbnailContentRevision;
+    const revisionOf = (path: string) =>
+      thumbnailRevisionOf(usePlayerStore.getState().thumbnailRevisions, path);
 
-      usePlayerStore.getState().bumpThumbnailContentRevision();
+    it("advances only the compositions an accepted file event names", () => {
+      const scene = revisionOf("compositions/scene-a.html");
+      const sibling = revisionOf("compositions/scene-b.html");
 
-      expect(usePlayerStore.getState().thumbnailContentRevision).toBe(before + 1);
+      usePlayerStore.getState().bumpThumbnailRevisions(["compositions/scene-a.html"]);
+
+      expect(revisionOf("compositions/scene-a.html")).toBe(scene + 1);
+      expect(revisionOf("compositions/scene-b.html")).toBe(sibling);
+    });
+
+    it("advances every composition when the event names none", () => {
+      const sibling = revisionOf("compositions/scene-b.html");
+
+      usePlayerStore.getState().bumpThumbnailRevisions(null);
+
+      expect(revisionOf("compositions/scene-b.html")).toBe(sibling + 1);
     });
 
     it("remains monotonic across soft resets while project identity stays with the session epoch", () => {
       const store = usePlayerStore.getState();
       store.beginTimelineSession("project-a");
-      store.bumpThumbnailContentRevision();
-      const revision = usePlayerStore.getState().thumbnailContentRevision;
+      store.bumpThumbnailRevisions(null);
+      const revision = revisionOf("index.html");
       const firstEpoch = usePlayerStore.getState().timelineSessionEpoch;
 
       store.reset();
-      expect(usePlayerStore.getState().thumbnailContentRevision).toBe(revision);
+      expect(revisionOf("index.html")).toBe(revision);
       store.beginTimelineSession("project-b");
-      expect(usePlayerStore.getState().thumbnailContentRevision).toBe(revision);
+      expect(revisionOf("index.html")).toBe(revision);
       expect(usePlayerStore.getState().timelineSessionEpoch).toBe(firstEpoch + 1);
     });
   });

package/src/player/store/thumbnailSlice.ts

@@ -2,23 +2,45 @@ import type { StoreApi } from "zustand";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { defaultThumbnailMode, type ThumbnailMode } from "../lib/thumbnailPolicy";
 
+/** Revision that moves every composition's thumbnails at once. */
+const EVERY_COMPOSITION = "*";
+
+/** Mounts may be written `./scene.html`; the server reports `scene.html`. */
+function revisionKey(path: string): string {
+  return (path.split(/[?#]/)[0] ?? "").replace(/\\/g, "/").replace(/^\.?\//, "");
+}
+
 export interface ThumbnailSlice {
   thumbnailMode: ThumbnailMode;
-  /** Monotonic identity for persisted project content shown by mounted thumbnails. */
-  thumbnailContentRevision: number;
+  /** Monotonic identity, per composition path, for persisted content shown by mounted thumbnails. */
+  thumbnailRevisions: Readonly<Record<string, number>>;
   setThumbnailMode: (mode: ThumbnailMode) => void;
-  bumpThumbnailContentRevision: () => void;
+  /** `null` moves every composition, e.g. after a root or asset change. */
+  bumpThumbnailRevisions: (compositions: readonly string[] | null) => void;
+}
+
+export function thumbnailRevisionOf(
+  revisions: Readonly<Record<string, number>>,
+  compositionPath: string,
+): number {
+  return (revisions[EVERY_COMPOSITION] ?? 0) + (revisions[revisionKey(compositionPath)] ?? 0);
 }
 
 export function createThumbnailSlice(set: StoreApi<ThumbnailSlice>["setState"]): ThumbnailSlice {
   return {
     thumbnailMode: defaultThumbnailMode(readStudioUiPreferences().thumbnailMode),
-    thumbnailContentRevision: 0,
+    thumbnailRevisions: {},
     setThumbnailMode: (mode) => {
       writeStudioUiPreferences({ thumbnailMode: mode });
       set({ thumbnailMode: mode });
     },
-    bumpThumbnailContentRevision: () =>
-      set((state) => ({ thumbnailContentRevision: state.thumbnailContentRevision + 1 })),
+    bumpThumbnailRevisions: (compositions) =>
+      set(({ thumbnailRevisions }) => {
+        const next = { ...thumbnailRevisions };
+        for (const path of compositions?.map(revisionKey) ?? [EVERY_COMPOSITION]) {
+          next[path] = (next[path] ?? 0) + 1;
+        }
+        return { thumbnailRevisions: next };
+      }),
   };
 }