@hyperframes/studio 0.8.60 → 0.8.62

package/src/player/components/VideoThumbnail.tsx

@@ -1,9 +1,17 @@
 import { memo, useCallback, useMemo, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
-import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
+import {
+  createThumbnailKey,
+  type ThumbnailPriority,
+  type ThumbnailSnapshot,
+} from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
-import { computeThumbnailStrip, THUMBNAIL_CLIP_HEIGHT } from "./thumbnailUtils";
+import {
+  computeThumbnailStrip,
+  quantizeThumbnailFrameCount,
+  THUMBNAIL_CLIP_HEIGHT,
+} from "./thumbnailUtils";
 
 interface VideoThumbnailProps {
   videoSrc: string;
@@ -15,7 +23,58 @@ interface VideoThumbnailProps {
   projectId?: string;
   sessionEpoch?: number;
   priority?: ThumbnailPriority;
-  rich?: boolean;
+}
+
+function createVideoThumbnailRequest(
+  props: Pick<VideoThumbnailProps, "videoSrc" | "sourceStart" | "sourceRangeDuration"> &
+    Required<Pick<VideoThumbnailProps, "duration" | "projectId" | "sessionEpoch" | "priority">>,
+  frameCount: number,
+  rich: boolean,
+) {
+  const {
+    videoSrc,
+    sourceStart,
+    sourceRangeDuration,
+    duration,
+    projectId,
+    sessionEpoch,
+    priority,
+  } = props;
+  return {
+    key: createThumbnailKey({
+      kind: "video",
+      source: videoSrc,
+      start: sourceStart,
+      duration: sourceRangeDuration ?? duration,
+      frames: frameCount,
+    }),
+    projectId,
+    sessionEpoch,
+    kind: "video" as const,
+    priority,
+    rich,
+    load: (signal: AbortSignal) =>
+      decodeVideoThumbnail(
+        {
+          source: videoSrc,
+          sourceStart,
+          sourceRangeDuration: sourceRangeDuration ?? duration,
+          frameCount,
+          fit: "cover",
+        },
+        signal,
+      ),
+  };
+}
+
+function selectThumbnailSnapshot(
+  poster: ThumbnailSnapshot,
+  rich: ThumbnailSnapshot,
+): ThumbnailSnapshot {
+  if (rich.status === "ready") return rich;
+  if (poster.status === "ready") return poster;
+  if (rich.status === "loading" || poster.status === "loading") return { status: "loading" };
+  return poster;
 }
 
 /** Sparse, bounded video frames supplied by the shared thumbnail scheduler. */
@@ -29,39 +88,36 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   projectId = videoSrc,
   sessionEpoch = 0,
   priority = "visible",
-  rich = false,
 }: VideoThumbnailProps) {
   const [containerWidth, setContainerWidth] = useState(0);
   const observerRef = useRef<ResizeObserver | null>(null);
-  const request = useMemo(
+  const requestFrameCount = quantizeThumbnailFrameCount(
+    computeThumbnailStrip(containerWidth, 16 / 9).frameCount,
+  );
+  const requestProps = useMemo(
     () => ({
-      key: createThumbnailKey({
-        kind: "video",
-        source: videoSrc,
-        start: sourceStart,
-        duration: sourceRangeDuration ?? duration,
-        frames: rich ? 6 : 1,
-      }),
+      videoSrc,
+      sourceStart,
+      sourceRangeDuration,
+      duration,
       projectId,
       sessionEpoch,
-      kind: "video" as const,
       priority,
-      rich,
-      load: (signal: AbortSignal) =>
-        decodeVideoThumbnail(
-          {
-            source: videoSrc,
-            sourceStart,
-            sourceRangeDuration: sourceRangeDuration ?? duration,
-            frameCount: rich ? 6 : 1,
-            fit: "cover",
-          },
-          signal,
-        ),
     }),
-    [duration, priority, projectId, rich, sessionEpoch, sourceRangeDuration, sourceStart, videoSrc],
+    [duration, priority, projectId, sessionEpoch, sourceRangeDuration, sourceStart, videoSrc],
+  );
+  const posterRequest = useMemo(
+    () => createVideoThumbnailRequest(requestProps, 1, false),
+    [requestProps],
+  );
+  const richRequest = useMemo(
+    () => createVideoThumbnailRequest(requestProps, requestFrameCount, true),
+    [requestFrameCount, requestProps],
   );
-  const snapshot = useThumbnailLease(request);
+  const measured = containerWidth > 0;
+  const posterSnapshot = useThumbnailLease(measured ? posterRequest : null);
+  const richSnapshot = useThumbnailLease(measured && requestFrameCount > 1 ? richRequest : null);
+  const snapshot = selectThumbnailSnapshot(posterSnapshot, richSnapshot);
   const value = snapshot.status === "ready" ? snapshot.value : null;
   const urls =
     value?.kind === "filmstrip" ? value.urls : value?.kind === "image" ? [value.url] : [];

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

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { audioPillFlags, isLinkedVideoAudio } from "./audioClipLink";
+
+const audio = { id: "bed", tag: "audio", src: "assets/City Ride.mp4?v=2" };
+
+describe("isLinkedVideoAudio", () => {
+  it("links an audio pill to a video of the same file", () => {
+    expect(
+      isLinkedVideoAudio(audio, [
+        audio,
+        { id: "picture", tag: "video", src: "/preview/assets/city ride.mp4" },
+      ]),
+    ).toBe(true);
+  });
+
+  it("greys a hidden clip and a muted group without dropping the link", () => {
+    expect(audioPillFlags({ ...audio, hidden: true }, [])).toEqual({
+      muted: true,
+      linked: false,
+    });
+    expect(audioPillFlags({ ...audio, audioGroupHidden: true }, [])).toEqual({
+      muted: true,
+      linked: false,
+    });
+  });
+
+  it("leaves a standalone audio file unlinked", () => {
+    expect(
+      isLinkedVideoAudio({ id: "vo", tag: "audio", src: "assets/voice.wav" }, [
+        { id: "picture", tag: "video", src: "assets/city.mp4" },
+      ]),
+    ).toBe(false);
+  });
+});

package/src/player/components/audioClipLink.ts

@@ -0,0 +1,33 @@
+import type { TimelineElement } from "../store/timelineElement";
+
+function mediaFileKey(src: string | undefined): string | null {
+  if (!src) return null;
+  const path = src.split(/[?#]/, 1)[0] ?? "";
+  const segment = path.split(/[/\\]/).pop()?.trim().toLowerCase() ?? "";
+  return segment.length > 0 ? segment : null;
+}
+
+export function audioPillFlags(
+  audio: Pick<TimelineElement, "id" | "tag" | "src" | "hidden" | "audioGroupHidden">,
+  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
+): { muted: boolean; linked: boolean } {
+  return {
+    muted: audio.hidden === true || audio.audioGroupHidden === true,
+    linked: isLinkedVideoAudio(audio, elements),
+  };
+}
+
+/** An audio pill whose file is also a video clip on this timeline. */
+export function isLinkedVideoAudio(
+  audio: Pick<TimelineElement, "id" | "tag" | "src">,
+  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
+): boolean {
+  if (audio.tag.trim().toLowerCase() !== "audio") return false;
+  const key = mediaFileKey(audio.src);
+  if (!key) return false;
+  return elements.some((element) => {
+    if (element.id === audio.id) return false;
+    if (element.tag.trim().toLowerCase() !== "video") return false;
+    return mediaFileKey(element.src) === key;
+  });
+}

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
+
+describe("loudnessToOpacity", () => {
+  it("maps silence to the floor and the file peak to fully opaque", () => {
+    expect(loudnessToOpacity(0)).toBe(0.64);
+    expect(loudnessToOpacity(1)).toBe(1);
+    expect(loudnessToOpacity(0.5)).toBeCloseTo(0.82, 5);
+  });
+
+  it("clamps out-of-range and non-finite peaks to the same floor or ceiling", () => {
+    expect(loudnessToOpacity(-0.2)).toBe(0.64);
+    expect(loudnessToOpacity(4)).toBe(1);
+    expect(loudnessToOpacity(Number.NaN)).toBe(0.64);
+  });
+});
+
+describe("decimatePeaks", () => {
+  it("keeps a transient that a single sample in the bucket would miss", () => {
+    const peaks = [0, 0, 0, 1, 0, 0, 0, 0];
+    expect(decimatePeaks(peaks, 0, 1, 2)).toEqual([1, 0]);
+  });
+
+  it("windows to the trimmed source slice", () => {
+    expect(decimatePeaks([0.1, 0.2, 0.9, 0.3], 0.5, 1, 1)).toEqual([0.9]);
+  });
+
+  it("returns no bars when there is nothing to draw", () => {
+    expect(decimatePeaks([], 0, 1, 4)).toEqual([]);
+    expect(decimatePeaks([0.5], 0, 1, 0)).toEqual([]);
+  });
+});

package/src/player/components/audioWaveformPeaks.ts

@@ -0,0 +1,46 @@
+/** Quietest bar that still clears the timeline contrast gate on the 70% pill. */
+const LOUDNESS_OPACITY_FLOOR = 0.64;
+
+const LOUDNESS_OPACITY_SPAN = 1 - LOUDNESS_OPACITY_FLOOR;
+
+/** Peak is 0–1 against the file's own maximum. Hotter peaks paint more opaque. */
+export function loudnessToOpacity(peak: number): number {
+  if (!Number.isFinite(peak)) return LOUDNESS_OPACITY_FLOOR;
+  const clamped = Math.min(1, Math.max(0, peak));
+  return LOUDNESS_OPACITY_FLOOR + LOUDNESS_OPACITY_SPAN * clamped;
+}
+
+/**
+ * Max-in-bucket over the trimmed peak window, one value per bar.
+ * A point sample drops a transient that sits between bar columns.
+ */
+export function decimatePeaks(
+  peaks: readonly number[],
+  startFraction: number,
+  endFraction: number,
+  barCount: number,
+): number[] {
+  if (barCount <= 0 || peaks.length === 0) return [];
+  const startFractionClamped = Math.min(1, Math.max(0, startFraction));
+  const endFractionClamped = Math.min(1, Math.max(startFractionClamped, endFraction));
+  const start = Math.floor(startFractionClamped * peaks.length);
+  const endIndex = Math.ceil(endFractionClamped * peaks.length);
+  const end = Math.max(start + 1, Math.min(peaks.length, endIndex));
+  const span = end - start;
+  const bars: number[] = [];
+  for (let index = 0; index < barCount; index++) {
+    let from = start + Math.floor((index * span) / barCount);
+    let to = start + Math.floor(((index + 1) * span) / barCount);
+    if (to <= from) {
+      from = Math.min(from, end - 1);
+      to = from + 1;
+    }
+    let max = 0;
+    for (let cursor = from; cursor < to; cursor++) {
+      const value = peaks[cursor] ?? 0;
+      if (value > max) max = value;
+    }
+    bars.push(max);
+  }
+  return bars;
+}

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

@@ -3,6 +3,7 @@ import {
   computeThumbnailStrip,
   encodePreviewPath,
   resolveMediaPreviewUrl,
+  quantizeThumbnailFrameCount,
   THUMBNAIL_CLIP_HEIGHT,
 } from "./thumbnailUtils";
 
@@ -19,6 +20,10 @@ describe("computeThumbnailStrip", () => {
     expect(frameCount * frameW).toBeGreaterThanOrEqual(500);
   });
 
+  it("paints tiles across the full clip past the shared visible-frame budget", () => {
+    expect(computeThumbnailStrip(14_400, 16 / 9).frameCount).toBeGreaterThan(33);
+  });
+
   it("returns one tile when the container width is unknown", () => {
     expect(computeThumbnailStrip(0, 16 / 9).frameCount).toBe(1);
     expect(computeThumbnailStrip(-10, 16 / 9).frameCount).toBe(1);
@@ -50,6 +55,18 @@ describe("computeThumbnailStrip", () => {
   });
 });
 
+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);
+  });
+});
+
 describe("resolveMediaPreviewUrl", () => {
   it("reroutes same-origin root media resolved by the preview iframe", () => {
     expect(

package/src/player/components/thumbnailUtils.ts

@@ -1,4 +1,5 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
+import { MAX_VISIBLE_THUMBNAIL_FRAMES } from "../lib/timelineViewportBudgets";
 /** Rendered height of a timeline-clip thumbnail strip, in CSS px. */
 export const THUMBNAIL_CLIP_HEIGHT = 66;
 
@@ -9,6 +10,12 @@ export interface ThumbnailStripLayout {
   frameCount: number;
 }
 
+/** 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)));
+}
+
 /**
  * Measure an image without mounting it in React's DOM. The scheduler owns the
  * abort signal, so an unmounted clip cannot leave Blink retaining a pending

package/src/player/components/timelineTheme.ts

@@ -32,6 +32,9 @@ export interface TimelineTheme {
   panelResizeActive: string;
   clipRadius: string;
   audioClipRadius: string;
+  transitionZone: string;
+  transitionBadge: string;
+  transitionBadgeInk: string;
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
@@ -69,6 +72,9 @@ export const defaultTimelineTheme: TimelineTheme = {
   panelResizeActive: "var(--timeline-resize-active)",
   clipRadius: "var(--timeline-clip-radius)",
   audioClipRadius: "var(--timeline-clip-audio-radius)",
+  transitionZone: "var(--timeline-transition-zone)",
+  transitionBadge: "var(--timeline-transition-badge)",
+  transitionBadgeInk: "var(--timeline-transition-badge-ink)",
 };
 
 export type ClipWidthLadder = "labeled" | "picture" | "frame";

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { deriveTimelineTransitionSeams } from "./timelineTransitionSeams";
+import type { TimelineElement } from "../store/playerStore";
+
+const clip = (
+  id: string,
+  start: number,
+  duration: number,
+  track = 0,
+  transitionLabel?: string,
+): TimelineElement => ({
+  id,
+  tag: "video",
+  start,
+  duration,
+  track,
+  transitionLabel,
+});
+
+describe("deriveTimelineTransitionSeams", () => {
+  it("finds a labelled transition and centers the seam in the shared time", () => {
+    const label = "hf:transition:out:in:crossfade";
+    const [seam] = deriveTimelineTransitionSeams([
+      clip("in", 1.8, 2, 0, label),
+      clip("out", 0, 2, 0, label),
+    ]);
+    expect(seam?.outgoing).toEqual(clip("out", 0, 2, 0, label));
+    expect(seam?.incoming).toEqual(clip("in", 1.8, 2, 0, label));
+    expect(seam?.centerTime).toBeCloseTo(1.9);
+    expect(seam?.duration).toBeCloseTo(0.2);
+  });
+
+  it("does not badge an unlabelled overlap", () => {
+    expect(deriveTimelineTransitionSeams([clip("out", 0, 2), clip("in", 1.8, 2)])).toEqual([]);
+  });
+
+  it("does not badge a cross-track overlap", () => {
+    const label = "hf:transition:out:in:crossfade";
+    expect(
+      deriveTimelineTransitionSeams([clip("out", 0, 2, 0, label), clip("in", 1.8, 2, 1, label)]),
+    ).toEqual([]);
+  });
+
+  it("rejects crisp gaps and touching edges", () => {
+    expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2.04, 1)])).toEqual([]);
+    expect(deriveTimelineTransitionSeams([clip("a", 0, 2), clip("b", 2, 1)])).toEqual([]);
+  });
+});

package/src/player/components/timelineTransitionSeams.ts

@@ -0,0 +1,36 @@
+import type { TimelineElement } from "../store/playerStore";
+
+export interface TimelineTransitionSeam {
+  outgoing: TimelineElement;
+  incoming: TimelineElement;
+  centerTime: number;
+  duration: number;
+}
+
+export function isTransitionPair(a: TimelineElement, b: TimelineElement): boolean {
+  return Boolean(a.transitionLabel && a.transitionLabel === b.transitionLabel);
+}
+
+export function deriveTimelineTransitionSeams(
+  elements: readonly TimelineElement[],
+): TimelineTransitionSeam[] {
+  const sorted = [...elements].sort((left, right) => left.start - right.start);
+  const seams: TimelineTransitionSeam[] = [];
+  for (let index = 0; index < sorted.length - 1; index += 1) {
+    const outgoing = sorted[index]!;
+    const incoming = sorted[index + 1]!;
+    if (outgoing.track !== incoming.track || !isTransitionPair(outgoing, incoming)) continue;
+    const outgoingEnd = outgoing.start + outgoing.duration;
+    const overlapStart = Math.max(outgoing.start, incoming.start);
+    const overlapEnd = Math.min(outgoingEnd, incoming.start + incoming.duration);
+    const duration = overlapEnd - overlapStart;
+    if (duration <= 0) continue;
+    seams.push({
+      outgoing,
+      incoming,
+      centerTime: overlapStart + duration / 2,
+      duration,
+    });
+  }
+  return seams;
+}

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

@@ -171,6 +171,24 @@ describe("normalizeToZones — CapCut-stable lanes follow the track-index (never
 });
 
 describe("normalizeToZones — legacy overlap spill (display-only, deterministic)", () => {
+  it("keeps a labelled transition pair on one row", () => {
+    const transitionLabel = "hf:transition:outgoing:incoming:crossfade";
+    const out = normalizeToZones([
+      { ...zClip("outgoing", 0, 2.5, 0, 0), transitionLabel },
+      { ...zClip("incoming", 2, 2.5, 0, 0), transitionLabel },
+    ]);
+    expect(trackOf(out, "outgoing")).toBe(0);
+    expect(trackOf(out, "incoming")).toBe(0);
+  });
+
+  it("still splits an unlabelled overlap", () => {
+    const out = normalizeToZones([
+      zClip("outgoing", 0, 2.5, 0, 0),
+      zClip("incoming", 2, 2.5, 0, 0),
+    ]);
+    expect(trackOf(out, "outgoing")).not.toBe(trackOf(out, "incoming"));
+  });
+
   it("splits time-overlapping SAME-track clips onto adjacent sub-lanes (no visible overlap)", () => {
     // a [0,5), b [2,7) overlaps a, c [6,9) sequential — all authored on track 1.
     // The editor forbids per-track overlap, but a legacy file can carry it; the

package/src/player/components/timelineZones.ts

@@ -1,5 +1,6 @@
 import type { TimelineElement } from "../store/playerStore";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isTransitionPair } from "./timelineTransitionSeams";
 
 /**
  * Free-form vertical zones, top → bottom: visual, audio. Canvas layering is
@@ -66,7 +67,9 @@ function packTrackLanes(
   const ordered = [...clips].sort(byStableId);
   const lanes: TimelineElement[][] = [];
   for (const el of ordered) {
-    let sub = lanes.findIndex((occ) => occ.every((o) => !overlaps(o, el)));
+    let sub = lanes.findIndex((occ) =>
+      occ.every((o) => !overlaps(o, el) || isTransitionPair(o, el)),
+    );
     if (sub === -1) {
       sub = lanes.length;
       lanes.push([]);

package/src/player/hooks/useShadowPreviewReload.ts

@@ -16,8 +16,13 @@ import type { PlaybackAdapter } from "../lib/playbackTypes";
 
 // The single wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
 // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
+// It only runs while the tab is visible: readiness is frame-driven, and a hidden tab renders none.
 export const SHADOW_READY_TIMEOUT_MS = 15_000;
 
+function isDocumentHidden(): boolean {
+  return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+
 type UseShadowPreviewReloadParams = Omit<
   UseTimelineSyncCallbacksParams,
   "probeIntervalRef" | "onAdapterReady" | "getAdapter" | "isCurrent" | "onLoadGiveUp"
@@ -55,11 +60,14 @@ export function useShadowPreviewReload({
   const onReloadFailedRef = useRef(onReloadFailed);
   onReloadFailedRef.current = onReloadFailed;
   const readyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
+  const budgetGenRef = useRef<number | null>(null);
   const cancelPendingLoadRef = useRef<() => void>(() => {});
   const [previewSlots, setPreviewSlots] = useState<PreviewIframeSlot[]>([{ gen: 0, role: "live" }]);
 
   const stopPendingShadow = useCallback(() => {
     clearTimeout(readyTimerRef.current);
+    budgetGenRef.current = null;
     cancelPendingLoadRef.current();
     pendingCommitRef.current = null;
     visuallyReadyGenRef.current = null;
@@ -145,18 +153,30 @@ export function useShadowPreviewReload({
     shadowIframeRef.current = node;
   }, []);
 
+  const armReadyTimer = useCallback(
+    (gen: number) => {
+      clearTimeout(readyTimerRef.current);
+      if (isDocumentHidden()) return;
+      readyTimerRef.current = setTimeout(
+        () => failShadow(gen, "it took too long to load"),
+        SHADOW_READY_TIMEOUT_MS,
+      );
+    },
+    [failShadow],
+  );
+  const armReadyTimerRef = useRef(armReadyTimer);
+  armReadyTimerRef.current = armReadyTimer;
+
   const beginShadowReload = useCallback(
     (url: string) => {
       shadowGenRef.current += 1;
       const gen = shadowGenRef.current;
       stopPendingShadow();
-      readyTimerRef.current = setTimeout(
-        () => failShadow(gen, "it took too long to load"),
-        SHADOW_READY_TIMEOUT_MS,
-      );
+      budgetGenRef.current = gen;
+      armReadyTimer(gen);
       setPreviewSlots((prev) => planShadowReload(prev, gen, url));
     },
-    [stopPendingShadow, failShadow],
+    [stopPendingShadow, armReadyTimer],
   );
 
   // Composition switch (not an edit reload): drop any in-flight shadow.
@@ -169,7 +189,22 @@ export function useShadowPreviewReload({
     setPreviewSlots(planShadowDiscard);
   }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);
 
-  useMountEffect(() => stopPendingShadow);
+  // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow.
+  useMountEffect(() => {
+    const onVisibilityChange = () => {
+      if (isDocumentHidden()) {
+        clearTimeout(readyTimerRef.current);
+        return;
+      }
+      const gen = budgetGenRef.current;
+      if (gen != null && gen === shadowGenRef.current) armReadyTimerRef.current(gen);
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      stopPendingShadow();
+    };
+  });
 
   return {
     previewSlots,

package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts

@@ -289,6 +289,50 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("does not spend the budget while the tab is hidden, and promotes once it is visible", () => {
+    vi.useFakeTimers();
+    const onPreviewReloadFailed = vi.fn();
+    const setVisibility = stubVisibility("hidden");
+    const { getApi, gen, root } = beginReload({ onPreviewReloadFailed });
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+    });
+
+    // A hidden tab renders no frames, so readiness cannot arrive; the wall clock must not fail it.
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS * 3));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    expect(getApi().previewSlots).toHaveLength(2);
+
+    act(() => setVisibility("visible"));
+    act(() => getApi().onShadowReadyChange(gen, true));
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    unmount(root);
+  });
+
+  it("restarts the full budget when a hidden tab becomes visible, then fails a shadow that stays silent", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const setVisibility = stubVisibility("visible");
+    const { getApi, live, root } = beginReload({ onPreviewReloadFailed });
+
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS - 1000));
+    act(() => setVisibility("hidden"));
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+
+    act(() => setVisibility("visible"));
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS - 1));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(1));
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    expect(getApi().iframeRef.current).toBe(live);
+    unmount(root);
+  });
+
   it("drops a shadow whose document reports an error and reports the cause", () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const onPreviewReloadFailed = vi.fn();
@@ -455,3 +499,12 @@ function unmount(root: ReturnType<typeof createRoot>) {
     root.unmount();
   });
 }
+
+function stubVisibility(initial: DocumentVisibilityState) {
+  let state = initial;
+  vi.spyOn(document, "visibilityState", "get").mockImplementation(() => state);
+  return (next: DocumentVisibilityState) => {
+    state = next;
+    document.dispatchEvent(new Event("visibilitychange"));
+  };
+}

package/src/player/lib/playbackTypes.ts

@@ -32,6 +32,8 @@ export interface TimelineLike {
   time: () => number;
   duration: () => number;
   isActive: () => boolean;
+  labels?: Record<string, number>;
+  getLabels?: () => Record<string, number>;
 }
 
 export interface ClipManifestClip extends RuntimeTimelineClipIdentity {