@hyperframes/studio 0.8.64 → 0.8.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.64",
+  "version": "0.8.65",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.64",
-    "@hyperframes/parsers": "0.8.64",
-    "@hyperframes/player": "0.8.64",
-    "@hyperframes/sdk": "0.8.64",
-    "@hyperframes/studio-server": "0.8.64"
+    "@hyperframes/player": "0.8.65",
+    "@hyperframes/sdk": "0.8.65",
+    "@hyperframes/parsers": "0.8.65",
+    "@hyperframes/core": "0.8.65",
+    "@hyperframes/studio-server": "0.8.65"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.64"
+    "@hyperframes/producer": "0.8.65"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/manualEdits.ts

@@ -9,7 +9,11 @@ export {
   type StudioPathOffsetSnapshot,
 } from "./manualEditsTypes";
 
-export { readFileChangeField, readStudioFileChangePath } from "./manualEditsParsing";
+export {
+  readFileChangeAffectedCompositions,
+  readFileChangeField,
+  readStudioFileChangePath,
+} from "./manualEditsParsing";
 
 export {
   beginStudioManualEditGesture,

package/src/components/editor/manualEditsParsing.ts

@@ -15,15 +15,17 @@ function normalizeStudioFileChangePath(path: string): string {
     .replace(/^\.?\//, "");
 }
 
+function asPayloadRecord(payload: unknown): Record<string, unknown> | null {
+  return payload && typeof payload === "object" ? (payload as Record<string, unknown>) : null;
+}
+
 /**
  * Read one string field out of an ALREADY-DECODED file-change payload. Every
  * reader of that payload goes through here, so no reader can disagree with its
  * siblings about the shape. Decoding a raw delivery is the transport's job.
  */
 export function readFileChangeField(payload: unknown, key: string): string | null {
-  if (!payload || typeof payload !== "object") return null;
-  const record = payload as Record<string, unknown>;
-  const value = record[key];
+  const value = asPayloadRecord(payload)?.[key];
   return typeof value === "string" ? value : null;
 }
 
@@ -31,3 +33,13 @@ export function readStudioFileChangePath(payload: unknown): string | null {
   const path = readFileChangeField(payload, "path") ?? readFileChangeField(payload, "filePath");
   return path === null ? null : normalizeStudioFileChangePath(path);
 }
+
+/**
+ * The compositions whose thumbnails a change can alter, or `null` for all of them. Anything
+ * but a list of paths (an older server, the Vite dev host) reads as "all".
+ */
+export function readFileChangeAffectedCompositions(payload: unknown): readonly string[] | null {
+  const value = asPayloadRecord(payload)?.affectedCompositions;
+  if (!Array.isArray(value) || !value.every((path) => typeof path === "string")) return null;
+  return value.map(normalizeStudioFileChangePath);
+}

package/src/components/sidebar/CompositionsPanel.masterComposition.test.tsx

@@ -17,7 +17,7 @@ afterEach(() => {
   if (root) act(() => root?.unmount());
   root = null;
   document.body.innerHTML = "";
-  usePlayerStore.setState({ thumbnailContentRevision: 0 });
+  usePlayerStore.setState({ thumbnailRevisions: {} });
 });
 
 describe("CompositionsPanel root badge source", () => {

package/src/components/sidebar/CompositionsTab.drag.test.tsx

@@ -18,7 +18,7 @@ afterEach(() => {
   if (root) act(() => root?.unmount());
   root = null;
   document.body.innerHTML = "";
-  usePlayerStore.setState({ thumbnailContentRevision: 0 });
+  usePlayerStore.setState({ thumbnailRevisions: {} });
 });
 
 function mount(onSelect = vi.fn(), onAddToTimeline = vi.fn()) {
@@ -68,7 +68,7 @@ describe("composition card drag", () => {
     act(() => thumbnail.dispatchEvent(new Event("error")));
     expect(host.textContent).toContain("Preview unavailable");
 
-    act(() => usePlayerStore.getState().bumpThumbnailContentRevision());
+    act(() => usePlayerStore.getState().bumpThumbnailRevisions(null));
 
     const retry = host.querySelector<HTMLImageElement>('img[src*="/thumbnail/"]');
     expect(retry).not.toBeNull();

package/src/components/sidebar/CompositionsTab.rootBadge.test.tsx

@@ -18,7 +18,7 @@ afterEach(() => {
   if (root) act(() => root?.unmount());
   root = null;
   document.body.innerHTML = "";
-  usePlayerStore.setState({ thumbnailContentRevision: 0 });
+  usePlayerStore.setState({ thumbnailRevisions: {} });
 });
 
 function mount(compositions: string[], masterCompositionPath: string | null) {

package/src/components/sidebar/CompositionsTab.tsx

@@ -3,6 +3,7 @@ import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { buildCompositionThumbnailUrl } from "../../player/components/CompositionThumbnail";
 import { setPreviewMediaMuted } from "../../player/lib/timelineIframeHelpers";
 import { usePlayerStore } from "../../player/store/playerStore";
+import { thumbnailRevisionOf } from "../../player/store/thumbnailSlice";
 import { TIMELINE_COMPOSITION_MIME } from "../../utils/timelineCompositionDrop";
 import { Tooltip } from "../ui/Tooltip";
 
@@ -388,7 +389,7 @@ export const CompositionsTab = memo(function CompositionsTab({
   isRendering,
   lintFindingsByFile,
 }: CompositionsTabProps) {
-  const contentRevision = usePlayerStore((state) => state.thumbnailContentRevision);
+  const thumbnailRevisions = usePlayerStore((state) => state.thumbnailRevisions);
   if (compositions.length === 0) {
     return (
       <div className="flex-1 flex items-center justify-center px-4">
@@ -411,7 +412,7 @@ export const CompositionsTab = memo(function CompositionsTab({
           onAddToTimeline={onAddToTimeline ? () => onAddToTimeline(comp) : undefined}
           isRendering={isRendering}
           lintInfo={lintFindingsByFile?.get(comp)}
-          contentRevision={contentRevision}
+          contentRevision={thumbnailRevisionOf(thumbnailRevisions, comp)}
         />
       ))}
     </div>

package/src/hooks/useExternalFileChangeCoordinator.test.tsx

@@ -104,7 +104,7 @@ describe("external file change coordinator", () => {
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(reloadSdkSession).not.toHaveBeenCalled();
     expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
-    expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html");
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html", null);
   });
 
   it("accepts a matching content echo without a write token and suppresses every reload", async () => {
@@ -125,7 +125,7 @@ describe("external file change coordinator", () => {
     );
 
     expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
-    expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html");
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html", null);
     expect(drainPendingChanges).not.toHaveBeenCalled();
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(reloadSdkSession).not.toHaveBeenCalled();
@@ -345,7 +345,34 @@ describe("external file change coordinator", () => {
 
       expect(drainPendingChanges).not.toHaveBeenCalled();
       expect(reloadPreview).not.toHaveBeenCalled();
-      expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html");
+      expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html", null);
+    });
+
+    it("hands the server's affected compositions to the thumbnail refresh", async () => {
+      const onAcceptedPersistedFileChange = vi.fn();
+      await mountCoordinator({ onAcceptedPersistedFileChange });
+
+      await act(async () =>
+        handler?.(
+          sseDelivery({
+            path: "compositions/scene-a.html",
+            version: "v3",
+            affectedCompositions: ["index.html", "compositions/scene-a.html"],
+          }),
+        ),
+      );
+      await act(async () =>
+        handler?.(
+          sseDelivery({ path: "assets/logo.svg", version: "v4", affectedCompositions: "all" }),
+        ),
+      );
+
+      expect(onAcceptedPersistedFileChange).toHaveBeenNthCalledWith(
+        1,
+        "compositions/scene-a.html",
+        ["index.html", "compositions/scene-a.html"],
+      );
+      expect(onAcceptedPersistedFileChange).toHaveBeenNthCalledWith(2, "assets/logo.svg", null);
     });
 
     it("reloads once when one watcher event reaches two subscribers", async () => {

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef, useState, type MutableRefObject } from "react";
-import { readFileChangeField, readStudioFileChangePath } from "../components/editor/manualEdits";
+import {
+  readFileChangeAffectedCompositions,
+  readFileChangeField,
+  readStudioFileChangePath,
+} from "../components/editor/manualEdits";
 import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 import type { ExternalConflictSnapshot } from "../utils/externalConflictStorage";
 import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
@@ -56,7 +60,10 @@ interface ExternalFileChangeCoordinatorOptions {
   readProjectFile: (path: string) => Promise<string>;
   onUseExternalFile?: (path: string, content: string) => void;
   resetSaveQueues?: () => void;
-  onAcceptedPersistedFileChange: (path: string) => void;
+  onAcceptedPersistedFileChange: (
+    path: string,
+    affectedCompositions: readonly string[] | null,
+  ) => void;
 }
 
 export interface ExternalFileChangeCoordinatorHandle {
@@ -253,7 +260,7 @@ export function useExternalFileChangeCoordinator({
         }
         if (!mountedRef.current || generation !== generationRef.current) return;
         setBlocked(null);
-        onAcceptedPersistedFileChange(path);
+        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(payload));
         reloadAcceptedGeneration(path);
         return;
       }
@@ -377,7 +384,7 @@ export function useExternalFileChangeCoordinator({
       const ownWriteToken = consumeStudioWriteToken(token);
       const ownContentEcho = content != null && isSelfWriteEcho(path, content);
       if (ownWriteToken || ownContentEcho) {
-        onAcceptedPersistedFileChange(path);
+        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(payload));
         logReload("suppressed", {
           path,
           why: ownWriteToken ? "own write token" : "own content echo",
@@ -430,7 +437,7 @@ export function useExternalFileChangeCoordinator({
       onUseExternalFile?.(path, external);
       await deleteConflictSnapshot?.(projectId, path);
       setBlocked(null);
-      onAcceptedPersistedFileChange(path);
+      onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(current.payload));
       reloadAcceptedGeneration(path);
     },
     [

package/src/hooks/useRenderClipContent.test.ts

@@ -271,11 +271,29 @@ describe("useRenderClipContent", () => {
     }
   });
 
+  it("finds the revision of a composition mounted with a ./ path", () => {
+    usePlayerStore.setState({
+      thumbnailMode: "adaptive",
+      thumbnailRevisions: { "compositions/nested.html": 2 },
+    });
+
+    const content = renderClipContent({
+      id: "nested",
+      tag: "div",
+      start: 0,
+      duration: 4,
+      track: 0,
+      compositionSrc: "./compositions/nested.html",
+    });
+
+    expect(isValidElement(content) && content.props).toMatchObject({ contentRevision: 2 });
+  });
+
   it("forwards persisted content revision to mounted composition thumbnails", () => {
     usePlayerStore.setState({
       thumbnailMode: "adaptive",
       timelineSessionEpoch: 7,
-      thumbnailContentRevision: 11,
+      thumbnailRevisions: { "*": 11, "compositions/nested.html": 2, "compositions/other.html": 5 },
     });
 
     const content = renderClipContent({
@@ -293,7 +311,8 @@ describe("useRenderClipContent", () => {
       expect(content.props).toMatchObject({
         projectId: "my-project",
         sessionEpoch: 7,
-        contentRevision: 11,
+        // its own composition's revision plus the all-compositions one, not a sibling's
+        contentRevision: 13,
       });
     }
   });

package/src/hooks/useRenderClipContent.ts

@@ -2,6 +2,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback, type ReactNode } from "react";
 import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
+import { compositionPathOfPreviewUrl } from "../player/components/CompositionThumbnail";
 import type { TimelineElement } from "../player";
 import type { TimelineClipRenderContext } from "../player/components/TimelineTypes";
 import { audioPillFlags } from "../player/components/audioClipLink";
@@ -9,6 +10,7 @@ import { AudioWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
 import { usePlayerStore } from "../player/store/playerStore";
+import { thumbnailRevisionOf } from "../player/store/thumbnailSlice";
 import { effectiveThumbnailMode } from "../player/lib/thumbnailPolicy";
 
 export function normalizeCompositionSrc(
@@ -114,7 +116,7 @@ export function useRenderClipContent({
   const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
   const effectiveMode = effectiveThumbnailMode(thumbnailMode);
   const sessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
-  const contentRevision = usePlayerStore((s) => s.thumbnailContentRevision);
+  const thumbnailRevisions = usePlayerStore((s) => s.thumbnailRevisions);
   const elements = usePlayerStore((s) => s.elements);
   return useCallback(
     // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
@@ -159,7 +161,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
-          contentRevision,
+          contentRevision: thumbnailRevisionOf(thumbnailRevisions, compSrc),
           priority: context.priority,
           rich: context.rich,
         });
@@ -186,7 +188,10 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
-          contentRevision,
+          contentRevision: thumbnailRevisionOf(
+            thumbnailRevisions,
+            compositionPathOfPreviewUrl(activePreviewUrl),
+          ),
           priority: context.priority,
           rich: context.rich,
         });
@@ -239,7 +244,7 @@ export function useRenderClipContent({
           duration: el.duration,
           projectId: pid,
           sessionEpoch,
-          contentRevision,
+          contentRevision: thumbnailRevisionOf(thumbnailRevisions, "index.html"),
           priority: context.priority,
           rich: context.rich,
         });
@@ -254,7 +259,7 @@ export function useRenderClipContent({
       effectiveTimelineDuration,
       effectiveMode,
       sessionEpoch,
-      contentRevision,
+      thumbnailRevisions,
       elements,
     ],
   );

package/src/hooks/useStudioExternalFileChanges.ts

@@ -49,8 +49,11 @@ export function useStudioExternalFileChanges({
 }: UseStudioExternalFileChangesOptions) {
   const { flushPendingSourceSave, discardPendingSourceSave } = fileManager;
   const { drainPendingDomEditSaves, resetDomEditSaveQueueBreaker } = previewPersistence;
-  const bumpThumbnailContentRevision = usePlayerStore(
-    (state) => state.bumpThumbnailContentRevision,
+  const bumpThumbnailRevisions = usePlayerStore((state) => state.bumpThumbnailRevisions);
+  const onAcceptedPersistedFileChange = useCallback(
+    (_path: string, affectedCompositions: readonly string[] | null) =>
+      bumpThumbnailRevisions(affectedCompositions),
+    [bumpThumbnailRevisions],
   );
   const drainPendingChanges = useCallback(async () => {
     const source = await flushPendingSourceSave();
@@ -81,6 +84,6 @@ export function useStudioExternalFileChanges({
     readProjectFile: fileManager.readProjectFile,
     onUseExternalFile: fileManager.updateEditingFileContent,
     resetSaveQueues: resetDomEditSaveQueueBreaker,
-    onAcceptedPersistedFileChange: bumpThumbnailContentRevision,
+    onAcceptedPersistedFileChange,
   });
 }

package/src/player/components/CompositionThumbnail.tsx

@@ -66,6 +66,12 @@ export function buildCompositionThumbnailUrl({
   return thumbnailUrl.toString();
 }
 
+/** The composition a preview URL renders: `/preview/comp/<path>`, or the root for `/preview`. */
+export function compositionPathOfPreviewUrl(previewUrl: string): string {
+  const match = /\/preview\/comp\/([^?#]+)/.exec(previewUrl);
+  return match?.[1] ? decodeURIComponent(match[1]) : "index.html";
+}
+
 async function loadCompositionImage(url: string, signal: AbortSignal) {
   const response = await fetch(url, { signal });
   if (!response.ok) throw new Error(`Composition thumbnail failed (${response.status})`);

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;
 }