@hyperframes/studio 0.7.93 → 0.7.95

package/src/player/components/timelineClipChildren.tsx

@@ -1,6 +1,20 @@
 import { type ReactNode } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 import type { TrackVisualStyle } from "./timelineIcons";
+import type { TimelineClipRenderContext } from "./TimelineTypes";
+
+export function resolveClipRenderContext(
+  element: TimelineElement,
+  visibleTimeRange: TimelineTimeRange,
+  interactive: boolean,
+): TimelineClipRenderContext {
+  if (interactive) return { priority: "interaction", rich: true };
+  const visible =
+    element.start < visibleTimeRange.end &&
+    element.start + element.duration > visibleTimeRange.start;
+  return { priority: visible ? "visible" : "overscan", rich: false };
+}
 
 function ClipLintDot({ element }: { element: TimelineElement }) {
   const lint = usePlayerStore((s) => s.lintFindingsByElement.get(element.key ?? element.id));
@@ -18,9 +32,14 @@ export function renderClipChildren(
   element: TimelineElement,
   clipStyle: TrackVisualStyle,
   renderClipContent:
-    | ((element: TimelineElement, style: { clip: string; label: string }) => ReactNode)
+    | ((
+        element: TimelineElement,
+        style: { clip: string; label: string },
+        context: TimelineClipRenderContext,
+      ) => ReactNode)
     | undefined,
   renderClipOverlay: ((element: TimelineElement) => ReactNode) | undefined,
+  context: TimelineClipRenderContext = { priority: "visible", rich: false },
 ): ReactNode {
   return (
     <>
@@ -31,7 +50,7 @@ export function renderClipChildren(
         // diamonds hang outside its bounds), so the thumbnail layer must clip
         // itself to the clip's rounded corners or sharp corners poke out.
         <div className="absolute inset-0 overflow-hidden" style={{ borderRadius: "inherit" }}>
-          {renderClipContent(element, clipStyle)}
+          {renderClipContent(element, clipStyle, context)}
         </div>
       )}
     </>

package/src/player/components/timelineLaneProps.ts

@@ -10,6 +10,7 @@ import type { TimelineClipIndex, TimelineTimeRange } from "../lib/timelineClipIn
 import type { TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
 import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import type { TimelineClipRenderContext } from "./TimelineTypes";
 
 /**
  * Props shared by the scroll container ({@link import("./TimelineCanvas")}) and
@@ -33,6 +34,7 @@ export interface TimelineLaneBaseProps {
   rowsVirtualized: boolean;
   clipIndex: TimelineClipIndex;
   renderTimeRange: TimelineTimeRange;
+  visibleTimeRange: TimelineTimeRange;
   pinnedClipIdentities: ReadonlySet<string>;
   trackOrder: number[];
   tracks: [number, TimelineElement[]][];
@@ -48,6 +50,7 @@ export interface TimelineLaneBaseProps {
   renderClipContent?: (
     element: TimelineElement,
     style: { clip: string; label: string },
+    context: TimelineClipRenderContext,
   ) => ReactNode;
   renderClipOverlay?: (element: TimelineElement) => ReactNode;
   onDrillDown?: (element: TimelineElement) => void;

package/src/player/components/useTimelineClipRenderWindow.ts

@@ -1,6 +1,9 @@
 import { useMemo } from "react";
 import { createTimelineClipIndex } from "../lib/timelineClipIndex";
-import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
+import {
+  getTimelineRenderTimeRange,
+  getTimelineVisibleTimeRange,
+} from "./timelineViewportGeometry";
 import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
 
 interface UseTimelineClipRenderWindowInput {
@@ -37,6 +40,10 @@ export function useTimelineClipRenderWindow({
     () => getTimelineRenderTimeRange(viewport, pixelsPerSecond, contentOrigin, duration),
     [contentOrigin, duration, pixelsPerSecond, viewport],
   );
+  const visibleTimeRange = useMemo(
+    () => getTimelineVisibleTimeRange(viewport, pixelsPerSecond, contentOrigin, duration),
+    [contentOrigin, duration, pixelsPerSecond, viewport],
+  );
   const pinnedClipIdentities = useMemo(
     () =>
       new Set(
@@ -60,5 +67,5 @@ export function useTimelineClipRenderWindow({
       selectedElementId,
     ],
   );
-  return { clipIndex, renderTimeRange, pinnedClipIdentities };
+  return { clipIndex, renderTimeRange, visibleTimeRange, pinnedClipIdentities };
 }

package/src/player/hooks/useTimelinePlayer.ts

@@ -86,6 +86,7 @@ export function useTimelinePlayer() {
             state.duration,
             resolvedDuration,
           ),
+          state.timelineProjectId,
         ),
       );
 
@@ -105,15 +106,19 @@ export function useTimelinePlayer() {
 
       // Asynchronously enrich media elements still missing sourceDuration
       // (header-only probe, cheap), applying each resolved value to the store.
-      void probeMissingSourceDurations(mergedElements, (key, durationSeconds) => {
-        usePlayerStore.setState((state) => {
-          const idx = state.elements.findIndex((e) => (e.key ?? e.id) === key);
-          if (idx === -1 || state.elements[idx].sourceDuration != null) return {};
-          const patched = state.elements.slice();
-          patched[idx] = { ...state.elements[idx], sourceDuration: durationSeconds };
-          return { elements: patched };
-        });
-      });
+      void probeMissingSourceDurations(
+        mergedElements,
+        state.timelineProjectId,
+        (key, durationSeconds) => {
+          usePlayerStore.setState((state) => {
+            const idx = state.elements.findIndex((e) => (e.key ?? e.id) === key);
+            if (idx === -1 || state.elements[idx].sourceDuration != null) return {};
+            const patched = state.elements.slice();
+            patched[idx] = { ...state.elements[idx], sourceDuration: durationSeconds };
+            return { elements: patched };
+          });
+        },
+      );
     },
     [setElements, setTimelineReady, setDuration],
   );

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

@@ -0,0 +1,143 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  applyCachedSourceDurations,
+  getMediaProbeDiagnostics,
+  probeMediaUrl,
+  probeMissingSourceDurations,
+  resetMediaProbeRegistry,
+} from "./mediaProbe";
+
+const dispose = vi.fn();
+const getDurationFromMetadata = vi.fn(async () => 5);
+const requestedSources: string[] = [];
+
+vi.mock("mediabunny", () => ({
+  ALL_FORMATS: {},
+  UrlSource: class {
+    constructor(readonly url: string) {
+      requestedSources.push(url);
+    }
+  },
+  Input: class {
+    getDurationFromMetadata = getDurationFromMetadata;
+    getPrimaryVideoTrack = vi.fn(async () => ({ displayWidth: 640, displayHeight: 360 }));
+    getAudioTracks = vi.fn(async () => []);
+    dispose = dispose;
+  },
+}));
+
+beforeEach(() => {
+  resetMediaProbeRegistry();
+  vi.clearAllMocks();
+  requestedSources.length = 0;
+  getDurationFromMetadata.mockResolvedValue(5);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("media probe registry", () => {
+  it("deduplicates and caches successful probes", async () => {
+    const [first, second] = await Promise.all([
+      probeMediaUrl("/video.mp4"),
+      probeMediaUrl("/video.mp4"),
+    ]);
+    expect(first).toEqual(second);
+    expect(getDurationFromMetadata).toHaveBeenCalledTimes(1);
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(getMediaProbeDiagnostics()).toEqual({ cached: 1, failed: 0, inflight: 0 });
+  });
+
+  it("bounds retained successes to the configured registry count", async () => {
+    for (let index = 0; index < 513; index++) {
+      await probeMediaUrl(`/video-${index}.mp4`);
+    }
+    expect(getMediaProbeDiagnostics().cached).toBe(512);
+  });
+
+  it("limits concurrent metadata probes and drains the queue", async () => {
+    const resolvers: Array<(duration: number) => void> = [];
+    getDurationFromMetadata.mockImplementation(
+      () => new Promise<number>((resolve) => resolvers.push(resolve)),
+    );
+
+    const probes = Array.from({ length: 5 }, (_, index) => probeMediaUrl(`/queued-${index}.mp4`));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(getDurationFromMetadata).toHaveBeenCalledTimes(4);
+
+    resolvers[0]?.(5);
+    await vi.waitFor(() => expect(getDurationFromMetadata).toHaveBeenCalledTimes(5));
+
+    for (const resolve of resolvers.slice(1)) resolve(5);
+    await expect(Promise.all(probes)).resolves.toHaveLength(5);
+    expect(getMediaProbeDiagnostics()).toEqual({ cached: 5, failed: 0, inflight: 0 });
+  });
+
+  it("retries failures only after the failure TTL", async () => {
+    vi.useFakeTimers();
+    getDurationFromMetadata.mockRejectedValue(new Error("bad source"));
+    await expect(probeMediaUrl("/bad.mp4")).resolves.toBeNull();
+    await expect(probeMediaUrl("/bad.mp4")).resolves.toBeNull();
+    expect(getDurationFromMetadata).toHaveBeenCalledTimes(1);
+
+    vi.advanceTimersByTime(30_001);
+    await expect(probeMediaUrl("/bad.mp4")).resolves.toBeNull();
+    expect(getDurationFromMetadata).toHaveBeenCalledTimes(2);
+  });
+
+  it("probes same-origin rooted media through the active project preview", async () => {
+    const apply = vi.fn();
+    await probeMissingSourceDurations(
+      [
+        {
+          id: "clip",
+          tag: "video",
+          src: `${window.location.origin}/assets/clip.mp4`,
+        },
+      ],
+      "project-a",
+      apply,
+    );
+
+    expect(requestedSources).toEqual([
+      `${window.location.origin}/api/projects/project-a/preview/assets/clip.mp4`,
+    ]);
+    expect(apply).toHaveBeenCalledWith("clip", 5);
+    expect(
+      applyCachedSourceDurations(
+        [
+          {
+            id: "clip",
+            tag: "video",
+            src: `${window.location.origin}/assets/clip.mp4`,
+          },
+        ],
+        "project-a",
+      ),
+    ).toEqual([
+      {
+        id: "clip",
+        tag: "video",
+        src: `${window.location.origin}/assets/clip.mp4`,
+        sourceDuration: 5,
+      },
+    ]);
+
+    await probeMissingSourceDurations(
+      [
+        {
+          id: "clip",
+          tag: "video",
+          src: `${window.location.origin}/assets/clip.mp4`,
+        },
+      ],
+      "project-a",
+      apply,
+    );
+    expect(requestedSources).toHaveLength(1);
+  });
+});

package/src/player/lib/mediaProbe.ts

@@ -1,4 +1,7 @@
-interface MediaProbeResult {
+import { resolveMediaPreviewUrl } from "../components/thumbnailUtils";
+import { TIMELINE_VIEWPORT_BUDGETS } from "./timelineViewportBudgets";
+
+export interface MediaProbeResult {
   duration: number;
   width?: number;
   height?: number;
@@ -6,11 +9,24 @@ interface MediaProbeResult {
   hasAudio: boolean;
 }
 
-const cache = new Map<string, MediaProbeResult>();
+interface CachedProbe {
+  result: MediaProbeResult;
+  lastAccess: number;
+}
+
+const cache = new Map<string, CachedProbe>();
 const inflight = new Map<string, Promise<MediaProbeResult | null>>();
 // URLs whose probe failed (CORS, 404, non-media). Remembered so the rAF-driven
 // timeline re-derive doesn't re-fetch them every frame and flood the console.
-const failed = new Set<string>();
+const failed = new Map<string, { failedAt: number; lastAccess: number }>();
+let accessSequence = 0;
+let activeProbes = 0;
+let registryEpoch = 0;
+const probeQueue: Array<{
+  key: string;
+  epoch: number;
+  resolve: (result: MediaProbeResult | null) => void;
+}> = [];
 
 let mediabunnyModule: typeof import("mediabunny") | null | false = null;
 
@@ -65,7 +81,26 @@ async function probeOne(url: string): Promise<MediaProbeResult | null> {
 }
 
 function getCachedProbe(url: string): MediaProbeResult | undefined {
-  return cache.get(normalizeUrl(url));
+  const cached = cache.get(normalizeUrl(url));
+  if (cached) cached.lastAccess = ++accessSequence;
+  return cached?.result;
+}
+
+function resolveProbeSource(src: string, projectId: string | null): string {
+  return projectId ? resolveMediaPreviewUrl(src, projectId, window.location.origin) : src;
+}
+
+function evictMetadataOverflow(): void {
+  const overflow = cache.size + failed.size - TIMELINE_VIEWPORT_BUDGETS.metadataRegistryEntries;
+  if (overflow <= 0) return;
+  const entries = [
+    ...Array.from(cache, ([key, value]) => ({ key, at: value.lastAccess, failed: false })),
+    ...Array.from(failed, ([key, value]) => ({ key, at: value.lastAccess, failed: true })),
+  ].sort((left, right) => left.at - right.at);
+  for (const entry of entries.slice(0, overflow)) {
+    if (entry.failed) failed.delete(entry.key);
+    else cache.delete(entry.key);
+  }
 }
 
 /**
@@ -76,11 +111,11 @@ function getCachedProbe(url: string): MediaProbeResult | undefined {
  */
 export function applyCachedSourceDurations<
   T extends { src?: string; tag: string; sourceDuration?: number },
->(elements: T[]): T[] {
+>(elements: T[], projectId: string | null): T[] {
   return elements.map((el) => {
     const tag = el.tag.toLowerCase();
     if (!el.src || el.sourceDuration != null || (tag !== "audio" && tag !== "video")) return el;
-    const cached = getCachedProbe(el.src);
+    const cached = getCachedProbe(resolveProbeSource(el.src, projectId));
     return cached?.duration && cached.duration > 0
       ? { ...el, sourceDuration: cached.duration }
       : el;
@@ -94,39 +129,96 @@ export function applyCachedSourceDurations<
  */
 export async function probeMissingSourceDurations<
   T extends { src?: string; tag: string; sourceDuration?: number; key?: string; id: string },
->(elements: T[], apply: (key: string, durationSeconds: number) => void): Promise<void> {
-  const needs = elements.filter(
-    (el) =>
-      el.src &&
-      el.sourceDuration == null &&
-      ["video", "audio"].includes(el.tag.toLowerCase()) &&
-      !getCachedProbe(el.src) &&
-      !failed.has(normalizeUrl(el.src)),
-  );
+>(
+  elements: T[],
+  projectId: string | null,
+  apply: (key: string, durationSeconds: number) => void,
+): Promise<void> {
+  const needs = elements.flatMap((el) => {
+    if (
+      !el.src ||
+      el.sourceDuration != null ||
+      !["video", "audio"].includes(el.tag.toLowerCase())
+    ) {
+      return [];
+    }
+    const source = resolveProbeSource(el.src, projectId);
+    return !getCachedProbe(source) && !hasFreshFailure(normalizeUrl(source))
+      ? [{ el, source }]
+      : [];
+  });
   if (needs.length === 0) return;
   await Promise.allSettled(
-    needs.map(async (el) => {
-      const result = await probeMediaUrl(el.src!);
+    needs.map(async ({ el, source }) => {
+      const result = await probeMediaUrl(source);
       if (result) apply(el.key ?? el.id, result.duration);
     }),
   );
 }
 
-async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
+function hasFreshFailure(key: string): boolean {
+  const failedAt = failed.get(key);
+  if (failedAt === undefined) return false;
+  if (Date.now() - failedAt.failedAt < TIMELINE_VIEWPORT_BUDGETS.metadataFailureTtlMs) {
+    failedAt.lastAccess = ++accessSequence;
+    return true;
+  }
+  failed.delete(key);
+  return false;
+}
+
+export async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
   const key = normalizeUrl(url);
-  const cached = cache.get(key);
+  const cached = getCachedProbe(key);
   if (cached) return cached;
-  if (failed.has(key)) return null;
+  if (hasFreshFailure(key)) return null;
 
   let pending = inflight.get(key);
   if (pending) return pending;
 
-  pending = probeOne(key).then((result) => {
-    inflight.delete(key);
-    if (result) cache.set(key, result);
-    else failed.add(key);
-    return result;
+  pending = new Promise<MediaProbeResult | null>((resolve) => {
+    probeQueue.push({ key, epoch: registryEpoch, resolve });
+    pumpProbeQueue();
   });
   inflight.set(key, pending);
   return pending;
 }
+
+function pumpProbeQueue(): void {
+  while (activeProbes < TIMELINE_VIEWPORT_BUDGETS.concurrentMetadataJobs) {
+    const queued = probeQueue.shift();
+    if (!queued) return;
+    if (queued.epoch !== registryEpoch) {
+      queued.resolve(null);
+      continue;
+    }
+    activeProbes++;
+    void probeOne(queued.key)
+      .then((result) => {
+        if (queued.epoch !== registryEpoch) return null;
+        inflight.delete(queued.key);
+        if (result) cache.set(queued.key, { result, lastAccess: ++accessSequence });
+        else failed.set(queued.key, { failedAt: Date.now(), lastAccess: ++accessSequence });
+        evictMetadataOverflow();
+        return result;
+      })
+      .then(queued.resolve)
+      .finally(() => {
+        activeProbes--;
+        pumpProbeQueue();
+      });
+  }
+}
+
+export function getMediaProbeDiagnostics() {
+  return { cached: cache.size, failed: failed.size, inflight: inflight.size };
+}
+
+export function resetMediaProbeRegistry(): void {
+  registryEpoch++;
+  for (const queued of probeQueue.splice(0)) queued.resolve(null);
+  cache.clear();
+  failed.clear();
+  inflight.clear();
+  accessSequence = 0;
+}

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

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { defaultThumbnailMode, effectiveThumbnailMode } from "./thumbnailPolicy";
+
+describe("thumbnail runtime policy", () => {
+  it("defaults missing preferences adaptively after activation", () => {
+    expect(defaultThumbnailMode(undefined, "follow-preference")).toBe("adaptive");
+    expect(defaultThumbnailMode(undefined, "legacy-default")).toBe("hidden");
+  });
+
+  it("forces the safe renderer without overwriting user intent", () => {
+    expect(effectiveThumbnailMode("adaptive", "force-hidden")).toBe("hidden");
+    expect(effectiveThumbnailMode("adaptive", "follow-preference")).toBe("adaptive");
+  });
+});

package/src/player/lib/thumbnailPolicy.ts

@@ -0,0 +1,24 @@
+export type ThumbnailMode = "adaptive" | "hidden";
+export type ThumbnailRuntimePolicy = "follow-preference" | "force-hidden" | "legacy-default";
+
+// "Adaptive" currently means the scheduler pauses rich work while scrolling.
+// The mode name leaves room for finer-grained runtime heuristics later.
+
+const rawPolicy = import.meta.env.VITE_STUDIO_TIMELINE_THUMBNAIL_POLICY;
+
+const studioThumbnailRuntimePolicy: ThumbnailRuntimePolicy =
+  rawPolicy === "force-hidden" || rawPolicy === "legacy-default" ? rawPolicy : "follow-preference";
+
+export function defaultThumbnailMode(
+  storedMode: ThumbnailMode | undefined,
+  policy: ThumbnailRuntimePolicy = studioThumbnailRuntimePolicy,
+): ThumbnailMode {
+  return storedMode ?? (policy === "legacy-default" ? "hidden" : "adaptive");
+}
+
+export function effectiveThumbnailMode(
+  preferredMode: ThumbnailMode,
+  policy: ThumbnailRuntimePolicy = studioThumbnailRuntimePolicy,
+): ThumbnailMode {
+  return policy === "force-hidden" ? "hidden" : preferredMode;
+}