@hyperframes/studio 0.8.139 → 0.8.140

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

@@ -6,6 +6,7 @@ import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { createHappyDomRootHarness } from "./testRootHarness";
 import { VideoThumbnail } from "./VideoThumbnail";
+import { markTimelineMotion } from "./timelineMotion";
 
 vi.mock("../lib/thumbnailVideoDecoder", () => ({ decodeVideoThumbnail: vi.fn() }));
 
@@ -29,25 +30,35 @@ afterEach(() => {
 // Registered after the reset above, so each test's strip unmounts before the cache is cleared.
 const harness = createHappyDomRootHarness();
 
+function clip(
+  videoSrc = "/api/projects/p/preview/assets/clip.mp4",
+  priority: "visible" | "overscan" = "visible",
+) {
+  return (
+    <VideoThumbnail
+      videoSrc={videoSrc}
+      label=""
+      labelColor="#fff"
+      projectId="p"
+      sessionEpoch={1}
+      priority={priority}
+    />
+  );
+}
+
 async function render(width = 0, height = 40) {
   Object.defineProperty(host, "clientWidth", { configurable: true, value: width });
   Object.defineProperty(host, "clientHeight", { configurable: true, value: height });
   const root = harness.mount(host);
   await act(async () => {
-    root.render(
-      <VideoThumbnail
-        videoSrc="/api/projects/p/preview/assets/clip.mp4"
-        label=""
-        labelColor="#fff"
-        projectId="p"
-        sessionEpoch={1}
-        priority="visible"
-      />,
-    );
+    root.render(clip());
     await Promise.resolve();
   });
+  return root;
 }
 
+const shownSources = () => [...host.querySelectorAll("img")].map((img) => img.getAttribute("src"));
+
 describe("VideoThumbnail", () => {
   it("does not acquire a thumbnail lease before the clip is measured", async () => {
     vi.mocked(decodeVideoThumbnail).mockResolvedValue({
@@ -70,7 +81,7 @@ describe("VideoThumbnail", () => {
 
     expect(decodeVideoThumbnail).toHaveBeenNthCalledWith(
       1,
-      expect.objectContaining({ frameCount: 1 }),
+      expect.objectContaining({ frameCount: 1, contentVersion: "project=p&session=1" }),
       expect.any(AbortSignal),
     );
     expect(decodeVideoThumbnail).toHaveBeenCalledWith(
@@ -90,7 +101,8 @@ describe("VideoThumbnail", () => {
     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"]);
+    // Seven slices and the end frame: the last tile shows the end.
+    expect(tiles).toEqual(["blob:0", "blob:2", "blob:3", "blob:4", "blob:7"]);
   });
 
   describe("on a 10-minute clip at full zoom", () => {
@@ -249,3 +261,183 @@ describe("VideoThumbnail", () => {
     expect(host.querySelector("img")).toBeNull();
   });
 });
+
+describe("VideoThumbnail during a zoom", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+      weight: 256,
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const rest = () =>
+    act(async () => {
+      vi.runOnlyPendingTimers();
+      await Promise.resolve();
+    });
+
+  it("decodes a clip that scrolls in mid-zoom only once the timeline rests", async () => {
+    markTimelineMotion();
+    await render(440);
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+    await rest();
+    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({ frameCount: 1 }),
+      expect.any(AbortSignal),
+    );
+  });
+
+  it("shows the strip it has, not the poster, while a zoom's new width decodes", async () => {
+    vi.mocked(decodeVideoThumbnail).mockImplementation(async ({ frameCount }) =>
+      frameCount === 1
+        ? { value: { kind: "image", url: "blob:poster", aspect: 16 / 9 }, weight: 1 }
+        : {
+            value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+            weight: 2,
+          },
+    );
+    await render(440);
+    expect(
+      new Set([...host.querySelectorAll("img")].map((img) => img.getAttribute("src"))),
+    ).toEqual(new Set(["blob:a", "blob:b"]));
+    // The new width's decode never lands during this test.
+    vi.mocked(decodeVideoThumbnail).mockImplementation(() => new Promise(() => {}));
+    await act(async () => {
+      reportResize(880, 40);
+      await Promise.resolve();
+    });
+    await rest();
+    const shown = [...host.querySelectorAll("img")].map((img) => img.getAttribute("src"));
+    expect(shown.length).toBeGreaterThan(0);
+    expect(shown).not.toContain("blob:poster");
+  });
+
+  it("keeps holding the strip when the clip moves between on and off screen mid-decode", async () => {
+    vi.mocked(decodeVideoThumbnail).mockImplementation(async ({ frameCount }) =>
+      frameCount === 1
+        ? { value: { kind: "image", url: "blob:poster", aspect: 16 / 9 }, weight: 1 }
+        : { value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 }, weight: 2 },
+    );
+    const root = await render(440);
+    vi.mocked(decodeVideoThumbnail).mockImplementation(() => new Promise(() => {}));
+    await act(async () => {
+      reportResize(880, 40);
+      root.render(clip(undefined, "overscan"));
+      await Promise.resolve();
+    });
+    await rest();
+    expect(new Set(shownSources())).toEqual(new Set(["blob:a", "blob:b"]));
+  });
+
+  it("holds the strip, and decodes only the new width, when the cache is over its budget", async () => {
+    const disposed: number[] = [];
+    vi.mocked(decodeVideoThumbnail).mockImplementation(async ({ frameCount }) =>
+      frameCount === 1
+        ? { value: { kind: "image", url: "blob:poster", aspect: 16 / 9 }, weight: 1 }
+        : {
+            value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+            weight: 2,
+            dispose: () => disposed.push(frameCount),
+          },
+    );
+    await render(440);
+    const held = vi.mocked(decodeVideoThumbnail).mock.calls.at(-1)![0].frameCount;
+    // Fill the project's cache past its entry budget, so a strip without a lease is evicted.
+    await act(async () => {
+      for (let i = 0; i < 100; i++) {
+        const lease = thumbnailScheduler.acquire(
+          {
+            key: `filler-${i}`,
+            projectId: "p",
+            sessionEpoch: 1,
+            kind: "image",
+            priority: "visible",
+            load: async () => ({
+              value: { kind: "image", url: `blob:f${i}`, aspect: 1 },
+              weight: 1,
+            }),
+          },
+          () => {},
+        );
+        for (let tick = 0; tick < 5; tick++) await Promise.resolve();
+        lease.release();
+      }
+    });
+    const decodes = vi.mocked(decodeVideoThumbnail).mock.calls.length;
+    vi.mocked(decodeVideoThumbnail).mockImplementation(() => new Promise(() => {}));
+    await act(async () => {
+      reportResize(880, 40);
+      await Promise.resolve();
+    });
+    await rest();
+    const newWidths = vi
+      .mocked(decodeVideoThumbnail)
+      .mock.calls.slice(decodes)
+      .map(([r]) => r.frameCount);
+    expect(newWidths).not.toContain(held);
+    expect(disposed).toEqual([]);
+    expect(new Set(shownSources())).toEqual(new Set(["blob:a", "blob:b"]));
+  });
+
+  it("never holds one clip's strip for another while the other decodes", async () => {
+    vi.mocked(decodeVideoThumbnail).mockImplementation(({ source }) =>
+      source.endsWith("clip.mp4")
+        ? Promise.resolve({
+            value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+            weight: 2,
+          })
+        : new Promise(() => {}),
+    );
+    const root = await render(440);
+    expect(shownSources()).toContain("blob:a");
+    await act(async () => {
+      root.render(clip("/api/projects/p/preview/assets/other.mp4"));
+      await Promise.resolve();
+    });
+    await rest();
+    expect(shownSources()).toEqual([]);
+  });
+
+  it("lets go of the strip it held once the clip narrows to one frame", async () => {
+    vi.mocked(decodeVideoThumbnail).mockImplementation(async ({ frameCount }) =>
+      frameCount === 1
+        ? { value: { kind: "image", url: "blob:poster", aspect: 16 / 9 }, weight: 1 }
+        : { value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 }, weight: 2 },
+    );
+    await render(440);
+    await act(async () => {
+      reportResize(50, 40);
+      await Promise.resolve();
+    });
+    await rest();
+    expect(new Set(shownSources())).toEqual(new Set(["blob:poster"]));
+    // Widening again shows the poster until the new width lands, not the strip it once held.
+    vi.mocked(decodeVideoThumbnail).mockImplementation(() => new Promise(() => {}));
+    await act(async () => {
+      reportResize(880, 40);
+      await Promise.resolve();
+    });
+    await rest();
+    expect(new Set(shownSources())).toEqual(new Set(["blob:poster"]));
+  });
+
+  it("keeps its filmstrip while the zoom resizes it, and decodes the new width at rest", async () => {
+    await render(440);
+    vi.mocked(decodeVideoThumbnail).mockClear();
+    await act(async () => {
+      markTimelineMotion();
+      reportResize(880, 40);
+      await Promise.resolve();
+    });
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
+    await rest();
+    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
+      expect.objectContaining({ frameCount: 16 }),
+      expect.any(AbortSignal),
+    );
+  });
+});

package/src/player/components/VideoThumbnail.tsx

@@ -1,4 +1,4 @@
-import { memo, useMemo } from "react";
+import { memo, useMemo, useState } from "react";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import {
@@ -8,7 +8,12 @@ import {
 } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
 import { ThumbnailTiles } from "./ThumbnailTiles";
-import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
+import {
+  computeThumbnailStrip,
+  quantizeThumbnailFrameCount,
+  thumbnailFrameForTile,
+} from "./thumbnailUtils";
+import { useValueAtRest } from "./timelineMotion";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -54,6 +59,7 @@ function createVideoThumbnailRequest(
       decodeVideoThumbnail(
         {
           source: videoSrc,
+          contentVersion: createThumbnailKey({ project: projectId, session: sessionEpoch }),
           sourceStart,
           sourceRangeDuration: sourceRangeDuration ?? duration,
           frameCount,
@@ -67,13 +73,31 @@ function createVideoThumbnailRequest(
 function selectThumbnailSnapshot(
   poster: ThumbnailSnapshot,
   rich: ThumbnailSnapshot,
+  shown: ThumbnailSnapshot,
 ): ThumbnailSnapshot {
   if (rich.status === "ready") return rich;
+  if (shown.status === "ready") return shown;
   if (poster.status === "ready") return poster;
   if (rich.status === "loading" || poster.status === "loading") return { status: "loading" };
   return poster;
 }
 
+type VideoThumbnailRequest = ReturnType<typeof createVideoThumbnailRequest>;
+
+function useVideoThumbnailSnapshot(
+  poster: VideoThumbnailRequest | null,
+  rich: VideoThumbnailRequest | null,
+  media: string,
+): ThumbnailSnapshot {
+  const posterSnapshot = useThumbnailLease(poster);
+  const richSnapshot = useThumbnailLease(rich);
+  const [shown, setShown] = useState({ media, request: rich });
+  const settled = richSnapshot.status === "ready" || rich === null;
+  if (settled && shown.request !== rich) setShown({ media, request: rich });
+  const shownSnapshot = useThumbnailLease(shown.media === media ? shown.request : null);
+  return selectThumbnailSnapshot(posterSnapshot, richSnapshot, shownSnapshot);
+}
+
 /** Sparse, bounded video frames supplied by the shared thumbnail scheduler. */
 export const VideoThumbnail = memo(function VideoThumbnail({
   videoSrc,
@@ -87,8 +111,10 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   priority = "visible",
 }: VideoThumbnailProps) {
   const [container, setContainerRef, watchGap] = useThumbnailStripSize();
-  const requestFrameCount = quantizeThumbnailFrameCount(
-    computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+  const requestFrameCount = useValueAtRest(
+    quantizeThumbnailFrameCount(
+      computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
+    ),
   );
   const requestProps = useMemo(
     () => ({
@@ -110,10 +136,12 @@ export const VideoThumbnail = memo(function VideoThumbnail({
     () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
     [requestFrameCount, requestProps],
   );
-  const measured = container.width > 0;
-  const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
-  const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
-  const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
+  const measured = useValueAtRest(container.width > 0);
+  const snapshot = useVideoThumbnailSnapshot(
+    measured ? posterRequest : null,
+    measured && requestFrameCount > 1 ? richRequest : null,
+    posterRequest.key,
+  );
   const value = snapshot.status === "ready" ? snapshot.value : null;
   const urls =
     value?.kind === "filmstrip" ? value.urls : value?.kind === "image" ? [value.url] : [];
@@ -130,7 +158,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
           watchGap={watchGap}
         >
           {(index) => {
-            const src = urls[Math.round((index * (urls.length - 1)) / Math.max(1, frameCount - 1))];
+            const src = urls[thumbnailFrameForTile(index, frameCount, urls.length)];
             return (
               <div
                 key={index}

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

@@ -4,7 +4,9 @@ import {
   encodePreviewPath,
   resolveMediaPreviewUrl,
   quantizeThumbnailFrameCount,
+  thumbnailFrameForTile,
 } from "./thumbnailUtils";
+import { MAX_VISIBLE_THUMBNAIL_FRAMES } from "../lib/timelineViewportBudgets";
 
 describe("computeThumbnailStrip", () => {
   it("sizes tiles by aspect ratio at the clip height", () => {
@@ -51,15 +53,27 @@ describe("computeThumbnailStrip", () => {
   });
 });
 
+describe("thumbnailFrameForTile", () => {
+  it("shows the clip's last frame in the last tile, and the slice under each other tile's centre", () => {
+    // 8 slices and the end frame.
+    expect([0, 1, 2].map((tile) => thumbnailFrameForTile(tile, 3, 9))).toEqual([1, 4, 8]);
+    // 2 slices and the end frame across 4 tiles.
+    expect([0, 1, 2, 3].map((tile) => thumbnailFrameForTile(tile, 4, 3))).toEqual([0, 0, 1, 2]);
+    expect(thumbnailFrameForTile(0, 1, 9)).toBe(4);
+  });
+});
+
 describe("quantizeThumbnailFrameCount", () => {
   it("uses doubling buckets and never exceeds the 4K geometry ceiling", () => {
     expect(quantizeThumbnailFrameCount(5)).toBe(8);
     expect(quantizeThumbnailFrameCount(32)).toBe(32);
-    expect(quantizeThumbnailFrameCount(34)).toBe(33);
   });
 
-  it("caps decode requests at the shared visible-frame budget", () => {
-    expect(quantizeThumbnailFrameCount(124)).toBe(33);
+  it("caps decode requests at the largest step within the visible-frame budget", () => {
+    // A step that is not a power of two would share no frames with the step below it.
+    expect(MAX_VISIBLE_THUMBNAIL_FRAMES).toBeGreaterThan(32);
+    expect(quantizeThumbnailFrameCount(34)).toBe(32);
+    expect(quantizeThumbnailFrameCount(124)).toBe(32);
   });
 });
 

package/src/player/components/thumbnailUtils.ts

@@ -11,7 +11,23 @@ export interface ThumbnailStripLayout {
 /** Quantize request identities so a pixel-by-pixel resize does not thrash the cache. */
 export function quantizeThumbnailFrameCount(frameCount: number): number {
   const safeCount = Math.max(1, Number.isFinite(frameCount) ? Math.ceil(frameCount) : 1);
-  return Math.min(MAX_VISIBLE_THUMBNAIL_FRAMES, 2 ** Math.ceil(Math.log2(safeCount)));
+  const cap = 2 ** Math.floor(Math.log2(MAX_VISIBLE_THUMBNAIL_FRAMES));
+  return Math.min(cap, 2 ** Math.ceil(Math.log2(safeCount)));
+}
+
+/**
+ * The decoded frame tile `index` of `tileCount` shows, of a strip's `frameCount`: the last tile
+ * shows the clip's last frame; the others the slice (videoThumbnailTimestamps) holding their centre.
+ */
+export function thumbnailFrameForTile(
+  index: number,
+  tileCount: number,
+  frameCount: number,
+): number {
+  if (frameCount < 2) return 0;
+  if (tileCount > 1 && index >= tileCount - 1) return frameCount - 1;
+  const slices = frameCount - 1;
+  return Math.min(slices - 1, Math.floor(((index + 0.5) * slices) / tileCount));
 }
 
 /**

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

@@ -27,13 +27,13 @@ import { resolveInsertRow } from "./timelineCollision";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 
 describe("horizontal timeline window", () => {
-  it("adds the shared quarter-viewport overscan on each side and clamps to duration", () => {
+  it("adds the shared half-viewport overscan on each side and clamps to duration", () => {
     expect(getTimelineRenderTimeRange({ scrollLeft: 300, clientWidth: 500 }, 100, 200, 20)).toEqual(
-      { start: 0, end: 7.25 },
+      { start: 0, end: 8.5 },
     );
     expect(
       getTimelineRenderTimeRange({ scrollLeft: 1_900, clientWidth: 500 }, 100, 200, 20),
-    ).toEqual({ start: 15.75, end: 20 });
+    ).toEqual({ start: 14.5, end: 20 });
   });
 
   it("generates globally aligned ticks directly inside the bounded window", () => {

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

@@ -0,0 +1,27 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { markTimelineMotion, TIMELINE_REST_MS, whenTimelineIdle } from "./timelineMotion";
+
+afterEach(() => {
+  vi.runOnlyPendingTimers();
+  vi.useRealTimers();
+});
+
+it("waits for a zoom to rest before resolving, and resolves at once when nothing moves", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "requestIdleCallback"] });
+  markTimelineMotion();
+  let idle = false;
+  void whenTimelineIdle().then(() => (idle = true));
+  await vi.advanceTimersByTimeAsync(TIMELINE_REST_MS - 50);
+  expect(idle).toBe(false);
+  // Another zoom step pushes the rest back.
+  markTimelineMotion();
+  await vi.advanceTimersByTimeAsync(TIMELINE_REST_MS - 50);
+  expect(idle).toBe(false);
+  await vi.advanceTimersByTimeAsync(TIMELINE_REST_MS);
+  expect(idle).toBe(true);
+
+  let again = false;
+  void whenTimelineIdle().then(() => (again = true));
+  await vi.advanceTimersByTimeAsync(1);
+  expect(again).toBe(true);
+});

package/src/player/components/timelineMotion.ts

@@ -0,0 +1,62 @@
+import { useState, useSyncExternalStore } from "react";
+
+/** How long the timeline must go without a zoom step to count as at rest. */
+export const TIMELINE_REST_MS = 150;
+
+let moving = false;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
+const listeners = new Set<() => void>();
+
+const emit = () => listeners.forEach((listener) => listener());
+
+/** A zoom step: work that only matters at rest (redraws, decodes) waits for the zoom to end. */
+export function markTimelineMotion(): void {
+  if (!moving) {
+    moving = true;
+    emit();
+  }
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = setTimeout(() => {
+    restTimer = null;
+    moving = false;
+    emit();
+  }, TIMELINE_REST_MS);
+}
+
+const onIdle = (callback: () => void) => {
+  if (typeof requestIdleCallback === "function") requestIdleCallback(callback, { timeout: 1000 });
+  else setTimeout(callback, 0);
+};
+
+/** Resolves at an idle moment with no zoom moving the timeline: long work waits there, not mid-zoom. */
+export function whenTimelineIdle(): Promise<void> {
+  return new Promise((resolve) => {
+    const check = () => {
+      if (!moving) return resolve();
+      const stop = subscribeTimelineMotion(() => {
+        if (moving) return;
+        stop();
+        onIdle(check);
+      });
+    };
+    onIdle(check);
+  });
+}
+
+export function isTimelineMoving(): boolean {
+  return moving;
+}
+
+export function subscribeTimelineMotion(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** `value` at rest; while the timeline moves, the value it had when it last rested. */
+export function useValueAtRest<T>(value: T): T {
+  // Re-renders only when a zoom starts and when it rests.
+  const moving = useSyncExternalStore(subscribeTimelineMotion, isTimelineMoving, () => false);
+  const [held, setHeld] = useState(value);
+  if (!moving && !Object.is(held, value)) setHeld(value);
+  return moving ? held : value;
+}