@hyperframes/studio 0.7.94 → 0.7.96

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

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { ImageThumbnail } from "./ImageThumbnail";
 
 Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
@@ -68,6 +69,7 @@ beforeEach(() => {
 afterEach(() => {
   act(() => root?.unmount());
   root = null;
+  thumbnailScheduler.invalidateProject("p");
   globalThis.IntersectionObserver = originalIO;
   globalThis.ResizeObserver = originalRO;
   globalThis.Image = originalImage;
@@ -82,6 +84,10 @@ function render(props: { imageSrc: string; label?: string; labelColor?: string }
         imageSrc={props.imageSrc}
         label={props.label ?? ""}
         labelColor={props.labelColor ?? "#fff"}
+        projectId="p"
+        sessionEpoch={1}
+        priority="visible"
+        rich={false}
       />,
     );
   });
@@ -93,6 +99,13 @@ function lastProbe(): MockImage {
   return probe!;
 }
 
+async function resolveProbe(update: (probe: MockImage) => void): Promise<void> {
+  await act(async () => {
+    update(lastProbe());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
 /** Assert at least one tile rendered and the first tile serves `expectedSrc`. */
 function expectFirstTileSrc(expectedSrc: string): void {
   const imgs = [...host.querySelectorAll("img")];
@@ -107,15 +120,15 @@ describe("ImageThumbnail", () => {
     expect(host.querySelectorAll("img").length).toBe(0);
   });
 
-  it("probes the resolved src and renders repeated object-cover tiles on load", () => {
+  it("probes the resolved src and renders repeated object-cover tiles on load", async () => {
     render({ imageSrc: "/api/projects/p/preview/assets/pic.png" });
     const probe = lastProbe();
     expect(probe.src).toBe("/api/projects/p/preview/assets/pic.png");
 
-    act(() => {
-      probe.naturalWidth = 1920;
-      probe.naturalHeight = 1080;
-      probe.onload?.();
+    await resolveProbe((current) => {
+      current.naturalWidth = 1920;
+      current.naturalHeight = 1080;
+      current.onload?.();
     });
 
     const imgs = [...host.querySelectorAll("img")];
@@ -127,18 +140,18 @@ describe("ImageThumbnail", () => {
     expect(host.querySelector(".animate-pulse")).toBeNull();
   });
 
-  it("drops the shimmer and renders no tiles when a raster image fails to load", () => {
+  it("drops the shimmer and renders no tiles when a raster image fails to load", async () => {
     render({ imageSrc: "/api/projects/p/preview/assets/missing.png" });
-    act(() => lastProbe().onerror?.());
+    await resolveProbe((probe) => probe.onerror?.());
     expect(host.querySelectorAll("img").length).toBe(0);
     expect(host.querySelector(".animate-pulse")).toBeNull();
   });
 
-  it("renders tiles at 16:9 when an SVG has no intrinsic dimensions (naturalWidth=0)", () => {
+  it("renders tiles at 16:9 when an SVG has no intrinsic dimensions (naturalWidth=0)", async () => {
     render({ imageSrc: "/api/projects/p/preview/assets/logo.svg" });
     const probe = lastProbe();
 
-    act(() => {
+    await resolveProbe(() => {
       // naturalWidth stays 0 — SVG with no width/height attribute
       probe.onload?.();
     });
@@ -147,21 +160,20 @@ describe("ImageThumbnail", () => {
     expect(host.querySelector(".animate-pulse")).toBeNull();
   });
 
-  it("renders SVG tiles at 16:9 fallback even when the probe fires onerror", () => {
+  it("renders SVG tiles at 16:9 fallback even when the probe fires onerror", async () => {
     // Some browser/sandbox environments fire onerror for SVGs even though the
     // <img> element itself can render the file — we must not blank the strip.
     render({ imageSrc: "/api/projects/p/preview/assets/icon.svg" });
 
-    act(() => lastProbe().onerror?.());
+    await resolveProbe((probe) => probe.onerror?.());
 
     expectFirstTileSrc("/api/projects/p/preview/assets/icon.svg");
     expect(host.querySelector(".animate-pulse")).toBeNull();
   });
 
-  it("renders the label above the strip when provided", () => {
+  it("renders the label above the strip when provided", async () => {
     render({ imageSrc: "/x.png", label: "hero", labelColor: "#abc" });
-    act(() => {
-      const probe = lastProbe();
+    await resolveProbe((probe) => {
       probe.naturalWidth = 100;
       probe.naturalHeight = 100;
       probe.onload?.();

package/src/player/components/ImageThumbnail.tsx

@@ -1,135 +1,93 @@
-import { memo, useRef, useState, useCallback, useEffect } from "react";
+import { memo, useCallback, useMemo, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { computeThumbnailStrip } from "./thumbnailUtils";
+import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
+import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
+import { computeThumbnailStrip, probeImageAspect } from "./thumbnailUtils";
 
 interface ImageThumbnailProps {
   imageSrc: string;
   label: string;
   labelColor: string;
+  projectId?: string;
+  sessionEpoch?: number;
+  priority?: ThumbnailPriority;
+  rich?: boolean;
 }
 
-/**
- * Renders a film-strip of a still image for a timeline clip. The image is a
- * fixed-width tile (sized by its natural aspect ratio) repeated to fill the
- * clip width — matching VideoThumbnail's visual pattern. Loading is lazy
- * (IntersectionObserver) with the same shimmer fallback while decoding.
- */
+/** A scheduler-backed still-image strip. Mounting is the sole work trigger. */
 export const ImageThumbnail = memo(function ImageThumbnail({
   imageSrc,
   label,
   labelColor,
+  projectId = imageSrc,
+  sessionEpoch = 0,
+  priority = "visible",
+  rich = false,
 }: ImageThumbnailProps) {
   const [containerWidth, setContainerWidth] = useState(0);
-  const [visible, setVisible] = useState(false);
-  const [status, setStatus] = useState<"loading" | "loaded" | "error">("loading");
-  const [aspect, setAspect] = useState(16 / 9);
-  const ioRef = useRef<IntersectionObserver | null>(null);
-  const roRef = useRef<ResizeObserver | null>(null);
-
-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    ioRef.current?.disconnect();
-    roRef.current?.disconnect();
-    if (!el) return;
-
-    const measured = el.parentElement?.clientWidth || el.clientWidth;
-    setContainerWidth(measured);
-
-    ioRef.current = new IntersectionObserver(
-      ([entry]) => {
-        if (entry.isIntersecting) {
-          setVisible(true);
-          ioRef.current?.disconnect();
-        }
+  const observerRef = useRef<ResizeObserver | null>(null);
+  const request = useMemo(
+    () => ({
+      key: createThumbnailKey({ kind: "image", source: imageSrc, rich: Number(rich) }),
+      projectId,
+      sessionEpoch,
+      kind: "image" as const,
+      priority,
+      rich,
+      load: async (signal: AbortSignal) => {
+        const aspect = await probeImageAspect(imageSrc, signal, true);
+        return {
+          value: { kind: "image" as const, url: imageSrc, aspect },
+          weight:
+            TIMELINE_VIEWPORT_BUDGETS.posterMaxPhysicalWidth *
+            TIMELINE_VIEWPORT_BUDGETS.posterMaxPhysicalHeight *
+            4,
+        };
       },
-      { rootMargin: "200px" },
-    );
-    // fallow-ignore-next-line code-duplication
-    ioRef.current.observe(el);
+    }),
+    [imageSrc, priority, projectId, rich, sessionEpoch],
+  );
+  const snapshot = useThumbnailLease(request);
+  const value = snapshot.status === "ready" ? snapshot.value : null;
+  const aspect = value?.kind === "image" ? value.aspect : 16 / 9;
+  const { frameW, frameCount } = computeThumbnailStrip(containerWidth, aspect);
 
-    const target = el.parentElement || el;
-    roRef.current = new ResizeObserver(([entry]) => {
-      setContainerWidth(entry.contentRect.width);
-    });
-    roRef.current.observe(target);
+  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(() => () => {
-    ioRef.current?.disconnect();
-    roRef.current?.disconnect();
-  });
-
-  // Probe the image once visible — measures the natural aspect ratio so the
-  // tile width matches, and flips to the error state (plain clip background)
-  // if the src can't load. The browser cache makes the tile <img>s free.
-  //
-  // SVG handling: SVGs without intrinsic width/height report naturalWidth=0 on
-  // load (treat as success with the 16:9 default aspect) and may fire onerror
-  // in some environments even though the file is valid and can be displayed —
-  // fall back to loaded-at-16:9 rather than hiding the strip entirely.
-  // eslint-disable-next-line no-restricted-syntax
-  useEffect(() => {
-    if (!visible) return;
-    let cancelled = false;
-    setStatus("loading");
-
-    const isSvg = /\.svg($|\?)/i.test(imageSrc);
-
-    const probe = new Image();
-    probe.onload = () => {
-      if (cancelled) return;
-      if (probe.naturalWidth > 0 && probe.naturalHeight > 0) {
-        setAspect(probe.naturalWidth / probe.naturalHeight);
-      }
-      // naturalWidth===0 (e.g. SVG with no intrinsic dimensions) falls through
-      // to "loaded" with the default 16:9 aspect already set in state.
-      setStatus("loaded");
-    };
-    probe.onerror = () => {
-      if (cancelled) return;
-      // SVGs can fail the probe in certain browser/sandbox environments even
-      // though the <img> tiles themselves render fine (different security
-      // context). Show the strip at the 16:9 fallback rather than blanking.
-      if (isSvg) {
-        setStatus("loaded");
-      } else {
-        setStatus("error");
-      }
-    };
-    probe.src = imageSrc;
-
-    return () => {
-      cancelled = true;
-      probe.onload = null;
-      probe.onerror = null;
-      probe.src = "";
-    };
-  }, [visible, imageSrc]);
-
-  const { frameW, frameCount } = computeThumbnailStrip(containerWidth, aspect);
+  useMountEffect(() => () => observerRef.current?.disconnect());
 
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
-      {visible && status === "loaded" && (
+      {value?.kind === "image" && (
         <div className="absolute inset-0 flex">
-          {Array.from({ length: frameCount }).map((_, i) => (
+          {Array.from({ length: frameCount }, (_, index) => (
             <div
-              key={i}
-              className="flex-shrink-0 h-full relative overflow-hidden bg-neutral-900"
+              key={index}
+              className="relative h-full flex-shrink-0 overflow-hidden bg-neutral-900"
               style={{ width: frameW }}
             >
               <img
-                src={imageSrc}
+                src={value.url}
                 alt=""
                 draggable={false}
                 loading="lazy"
-                className="absolute inset-0 w-full h-full object-cover"
+                className="absolute inset-0 h-full w-full object-cover"
               />
             </div>
           ))}
         </div>
       )}
-
-      {visible && status === "loading" && (
+      {snapshot.status === "loading" && (
         <div
           className="absolute inset-0 animate-pulse"
           style={{
@@ -138,17 +96,16 @@ export const ImageThumbnail = memo(function ImageThumbnail({
           }}
         />
       )}
-
       {label && (
         <div
-          className="absolute bottom-0 left-0 right-0 z-10 px-1.5 pb-0.5 pt-3"
+          className="absolute inset-x-0 bottom-0 z-10 px-1.5 pb-0.5 pt-3"
           style={{
             background:
               "linear-gradient(to top, rgba(0,0,0,0.85) 0%, rgba(0,0,0,0.4) 60%, transparent 100%)",
           }}
         >
           <span
-            className="text-[9px] font-semibold truncate block leading-tight"
+            className="block truncate text-[9px] font-semibold leading-tight"
             style={{ color: labelColor, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }}
           >
             {label}

package/src/player/components/Timeline.tsx

@@ -64,7 +64,6 @@ export {
   getTimelineScrollTopForGeometryChange,
   getTimelineVisibleTimeRange,
 } from "./timelineViewportGeometry";
-
 export const Timeline = memo(function Timeline({
   onSeek,
   onDrillDown,
@@ -317,24 +316,25 @@ export const Timeline = memo(function Timeline({
       toggleSelectedKeyframe,
     });
 
-  const { clipIndex, renderTimeRange, pinnedClipIdentities } = useTimelineClipRenderWindow({
-    tracks,
-    viewport,
-    pixelsPerSecond: pps,
-    contentOrigin,
-    duration: displayDuration,
-    selectedElementId: selectedElementId ?? undefined,
-    draggedElementId: draggedClip ? getTimelineElementIdentity(draggedClip.element) : undefined,
-    resizingElementIds,
-    focusedElementId: timelineFocus.pinnedElementId,
-    focusedEaseElementId: focusedEaseSegment?.elementId,
-    clipContextMenuElementId: clipContextMenu
-      ? getTimelineElementIdentity(clipContextMenu.element)
-      : undefined,
-    keyframeContextMenuElementId: kfContextMenu
-      ? getTimelineElementIdentity(kfContextMenu.element)
-      : undefined,
-  });
+  const { clipIndex, renderTimeRange, visibleTimeRange, pinnedClipIdentities } =
+    useTimelineClipRenderWindow({
+      tracks,
+      viewport,
+      pixelsPerSecond: pps,
+      contentOrigin,
+      duration: displayDuration,
+      selectedElementId: selectedElementId ?? undefined,
+      draggedElementId: draggedClip ? getTimelineElementIdentity(draggedClip.element) : undefined,
+      resizingElementIds,
+      focusedElementId: timelineFocus.pinnedElementId,
+      focusedEaseElementId: focusedEaseSegment?.elementId,
+      clipContextMenuElementId: clipContextMenu
+        ? getTimelineElementIdentity(clipContextMenu.element)
+        : undefined,
+      keyframeContextMenuElementId: kfContextMenu
+        ? getTimelineElementIdentity(kfContextMenu.element)
+        : undefined,
+    });
   useTimelineActiveClips({
     scrollRef,
     currentTime,
@@ -504,6 +504,7 @@ export const Timeline = memo(function Timeline({
           rowsVirtualized={timelineFocus.rowVirtualizationActive}
           clipIndex={clipIndex}
           renderTimeRange={renderTimeRange}
+          visibleTimeRange={visibleTimeRange}
           pinnedClipIdentities={pinnedClipIdentities}
           trackOrder={trackOrder}
           tracks={tracks}

package/src/player/components/TimelineGestureOverlay.tsx

@@ -9,6 +9,7 @@ import { getTimelineDragOverlayPosition } from "./timelineClipDragPreview";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import type { TrackVisualStyle } from "./timelineIcons";
 import { isTimelineClipActive } from "./useTimelineActiveClips";
+import type { TimelineClipRenderContext } from "./TimelineTypes";
 
 interface TimelineGestureOverlayProps {
   drag: DraggedClipState | null;
@@ -22,6 +23,7 @@ interface TimelineGestureOverlayProps {
   renderClipContent?: (
     element: TimelineElement,
     style: { clip: string; label: string },
+    context: TimelineClipRenderContext,
   ) => ReactNode;
   renderClipOverlay?: (element: TimelineElement) => ReactNode;
 }
@@ -87,6 +89,7 @@ export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
               getTrackStyle(element.tag),
               renderClipContent,
               renderClipOverlay,
+              { priority: "interaction", rich: true },
             )}
           </TimelineClip>
         </div>

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

@@ -76,10 +76,14 @@ function renderLanes(options: RenderLanesOptions = {}): {
   host: HTMLDivElement;
   root: Root;
   rerender: (next: RenderLanesOptions) => void;
+  setSelectedElementId: ReturnType<typeof vi.fn>;
+  onSelectElement: ReturnType<typeof vi.fn>;
 } {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
+  const setSelectedElementId = vi.fn();
+  const onSelectElement = vi.fn();
   const render = (next: RenderLanesOptions) => {
     const elements = next.elements ?? [element("clip-a", TRACK_A)];
     const gsapAnimations = next.animations ?? new Map<string, GsapAnimation[]>();
@@ -118,6 +122,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
           })}
           clipIndex={createTimelineClipIndex(tracks)}
           renderTimeRange={{ start: 0, end: Number.POSITIVE_INFINITY }}
+          visibleTimeRange={{ start: 0, end: Number.POSITIVE_INFINITY }}
           pinnedClipIdentities={new Set()}
           trackOrder={displayTrackOrder}
           tracks={tracks}
@@ -137,7 +142,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
           setRangeSelection={vi.fn()}
           setResizingClip={vi.fn()}
           setDraggedClip={vi.fn()}
-          setSelectedElementId={vi.fn()}
+          setSelectedElementId={setSelectedElementId}
           shiftClickClipRef={createRef()}
           getPreviewElement={(el) => el}
           getTrackStyle={getTrackStyle}
@@ -149,6 +154,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
           onTogglePropertyGroupKeyframe={vi.fn()}
           onResizeElement={vi.fn()}
           onMoveElement={vi.fn()}
+          onSelectElement={onSelectElement}
           onRazorSplit={vi.fn()}
           onRazorSplitAll={vi.fn()}
         />,
@@ -156,7 +162,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
     });
   };
   render(options);
-  return { host, root, rerender: render };
+  return { host, root, rerender: render, setSelectedElementId, onSelectElement };
 }
 
 function visibilityLabels(host: HTMLElement): (string | null)[] {
@@ -347,3 +353,19 @@ describe("TimelineLanes disclosure target", () => {
     act(() => view.root.unmount());
   });
 });
+
+describe("TimelineLanes selection", () => {
+  it("keeps a selected clip selected when it is clicked again", () => {
+    const selected = element("clip-a", TRACK_A);
+    const view = renderLanes({
+      elements: [selected],
+      selectedElementIds: new Set([selected.id]),
+    });
+
+    act(() => view.host.querySelector<HTMLButtonElement>('[data-el-id="clip-a"]')?.click());
+
+    expect(view.setSelectedElementId).toHaveBeenCalledWith(selected.id);
+    expect(view.onSelectElement).toHaveBeenCalledWith(selected);
+    act(() => view.root.unmount());
+  });
+});

package/src/player/components/TimelineLanes.tsx

@@ -22,7 +22,7 @@ import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
-import { renderClipChildren } from "./timelineClipChildren";
+import { renderClipChildren, resolveClipRenderContext } from "./timelineClipChildren";
 import { TimelineTrackRow } from "./TimelineTrackRow";
 import { isTimelineClipActive } from "./useTimelineActiveClips";
 import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
@@ -57,6 +57,7 @@ export function TimelineLanes({
   rowsVirtualized,
   clipIndex,
   renderTimeRange,
+  visibleTimeRange,
   pinnedClipIdentities,
   trackOrder,
   tracks,
@@ -323,8 +324,7 @@ export function TimelineLanes({
                     const isSelected =
                       selectedElementId === elementKey || selectedElementIds.has(elementKey);
                     const isComposition = !!el.compositionSrc;
-                    // The element identity is already unique per clip. Never fold in the map
-                    // index, or a splice/reorder remounts every clip at/after the change.
+                    // Element identity stays stable across clip splices and reorders.
                     const clipKey = elementKey;
                     const isDraggingClip =
                       draggedClip?.started === true &&
@@ -332,6 +332,11 @@ export function TimelineLanes({
                       getTimelineElementIdentity(draggedElement) === elementKey;
                     if (isDraggingClip) return null;
                     const previewElement = getPreviewElement(el);
+                    const renderContext = resolveClipRenderContext(
+                      previewElement,
+                      visibleTimeRange,
+                      isSelected || hoveredClip === clipKey || pinnedClipIdentities.has(clipKey),
+                    );
                     // Passenger of a live multi-drag: preserve the formation without changing
                     // the passenger's timeline data until the owning drag commits.
                     const isPassenger =
@@ -475,15 +480,9 @@ export function TimelineLanes({
                               }
                               return;
                             }
-                            // Plain click single-selects: drop any marquee multi-selection.
-                            // Only a click on the PRIMARY selection toggles it off — a click
-                            // on a marquee-selected clip narrows the selection to that clip.
-                            const hadMultiSelection = selectedElementIds.size > 0;
-                            usePlayerStore.getState().clearSelectedElementIds();
-                            const nextElement =
-                              selectedElementId === elementKey && !hadMultiSelection ? null : el;
-                            setSelectedElementId(nextElement ? elementKey : null);
-                            onSelectElement?.(nextElement);
+                            // Clip selection is idempotent; empty timeline space owns deselection.
+                            setSelectedElementId(elementKey);
+                            onSelectElement?.(el);
                           }
                         }
                         onDoubleClick={(e) => {
@@ -497,6 +496,7 @@ export function TimelineLanes({
                           clipStyle,
                           renderClipContent,
                           renderClipOverlay,
+                          renderContext,
                         )}
                       </TimelineClip>
                     );

package/src/player/components/TimelineTypes.ts

@@ -4,6 +4,11 @@ import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
 
+export interface TimelineClipRenderContext {
+  priority: "overscan" | "visible" | "interaction";
+  rich: boolean;
+}
+
 export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
   /** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
   sessionEpoch?: number;
@@ -12,6 +17,7 @@ export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverri
   renderClipContent?: (
     element: TimelineElement,
     style: { clip: string; label: string },
+    context: TimelineClipRenderContext,
   ) => ReactNode;
   renderClipOverlay?: (element: TimelineElement) => ReactNode;
   onDeleteElement?: (element: TimelineElement) => Promise<void> | void;