@hyperframes/studio 0.8.59 → 0.8.61

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

@@ -36,7 +36,8 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-async function render(rich = false) {
+async function render(width = 0) {
+  Object.defineProperty(host, "clientWidth", { configurable: true, value: width });
   root = createRoot(host);
   await act(async () => {
     root!.render(
@@ -47,7 +48,6 @@ async function render(rich = false) {
         projectId="p"
         sessionEpoch={1}
         priority="visible"
-        rich={rich}
       />,
     );
     await Promise.resolve();
@@ -55,7 +55,7 @@ async function render(rich = false) {
 }
 
 describe("VideoThumbnail", () => {
-  it("renders a scheduler-provided sparse poster", async () => {
+  it("does not acquire a thumbnail lease before the clip is measured", async () => {
     vi.mocked(decodeVideoThumbnail).mockResolvedValue({
       value: { kind: "image", url: "blob:poster", aspect: 16 / 9 },
       weight: 128,
@@ -63,29 +63,40 @@ describe("VideoThumbnail", () => {
 
     await render();
 
-    expect(decodeVideoThumbnail).toHaveBeenCalledWith(
-      expect.objectContaining({ frameCount: 1 }),
-      expect.any(AbortSignal),
-    );
-    expect(host.querySelector('img[src="blob:poster"]')).not.toBeNull();
-    expect(host.querySelector(".animate-pulse")).toBeNull();
+    expect(decodeVideoThumbnail).not.toHaveBeenCalled();
   });
 
-  it("requests a rich filmstrip only for interaction actors", async () => {
+  it("requests a geometry-sized filmstrip by default", async () => {
     vi.mocked(decodeVideoThumbnail).mockResolvedValue({
       value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
       weight: 256,
     });
 
-    await render(true);
+    await render(500);
 
+    expect(decodeVideoThumbnail).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ frameCount: 1 }),
+      expect.any(AbortSignal),
+    );
     expect(decodeVideoThumbnail).toHaveBeenCalledWith(
-      expect.objectContaining({ frameCount: 6 }),
+      expect.objectContaining({ frameCount: 8 }),
       expect.any(AbortSignal),
     );
     expect(host.querySelectorAll("img").length).toBeGreaterThan(0);
   });
 
+  it("issues a single decode job for a narrow clip", async () => {
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "image", url: "blob:poster", aspect: 16 / 9 },
+      weight: 128,
+    });
+
+    await render(100);
+
+    expect(decodeVideoThumbnail).toHaveBeenCalledTimes(1);
+  });
+
   it("clears the loading shimmer when the scheduled decode fails", async () => {
     vi.mocked(decodeVideoThumbnail).mockRejectedValue(new Error("decode failed"));
 

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] : [];
@@ -112,8 +168,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
         <div
           className="absolute inset-0 animate-pulse motion-reduce:animate-none"
           style={{
-            background:
-              "linear-gradient(90deg, rgba(255,255,255,0.02) 0%, rgba(255,255,255,0.05) 50%, rgba(255,255,255,0.02) 100%)",
+            background: "var(--timeline-thumbnail-shimmer)",
           }}
         />
       )}
@@ -128,13 +183,12 @@ export const VideoThumbnail = memo(function VideoThumbnail({
         <div
           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%)",
+            background: "var(--timeline-thumbnail-label-gradient)",
           }}
         >
           <span
             className="block truncate text-[9px] font-semibold leading-tight"
-            style={{ color: labelColor, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }}
+            style={{ color: labelColor, textShadow: "var(--timeline-thumbnail-label-shadow)" }}
           >
             {label}
           </span>

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/timelineMotionStyles.test.ts

@@ -2,17 +2,17 @@ import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
 const studioCss = readFileSync(new URL("../../styles/studio.css", import.meta.url), "utf8");
+const themeCss = readFileSync(new URL("../../styles/theme.css", import.meta.url), "utf8");
+const timelineOverlaySources = [
+  "TimelineShortcutHint.tsx",
+  "LayerDisclosureRow.tsx",
+  "ImageThumbnail.tsx",
+  "AudioWaveform.tsx",
+  "VideoThumbnail.tsx",
+].map((fileName) => readFileSync(new URL(`./${fileName}`, import.meta.url), "utf8"));
 const timelineClipSource = readFileSync(new URL("./TimelineClip.tsx", import.meta.url), "utf8");
 const playheadSource = readFileSync(new URL("./PlayheadIndicator.tsx", import.meta.url), "utf8");
 
-const allowedTimelineTransitionProperties = [
-  "background-color",
-  "border-color",
-  "box-shadow",
-  "color",
-  "opacity",
-];
-
 function expectRule(css: string, selector: string): string {
   const selectorStart = css.indexOf(`${selector} {`);
   expect(selectorStart).toBeGreaterThanOrEqual(0);
@@ -31,28 +31,26 @@ function expectDeclaration(ruleBody: string, property: string): string {
   return declarationMatch?.[1].trim() ?? "";
 }
 
-function transitionProperties(transitionDeclaration: string): string[] {
-  const items: string[] = [];
-  let depth = 0;
-  let item = "";
-
-  for (const char of transitionDeclaration) {
-    if (char === "(") depth += 1;
-    if (char === ")") depth -= 1;
-    if (char === "," && depth === 0) {
-      items.push(item.trim());
-      item = "";
-      continue;
-    }
-    item += char;
-  }
-
-  if (item.trim().length > 0) items.push(item.trim());
-
-  return items.map((transition) => transition.split(/\s+/)[0]);
+function themeTokenValue(token: string): string {
+  const match = new RegExp(`${token}:\\s*([^;]+);`).exec(themeCss);
+  expect(match?.[1]).toBeDefined();
+  return match?.[1].trim() ?? "";
 }
 
 describe("timeline motion styles", () => {
+  it.each([
+    ["--timeline-track-label", "rgba(255, 255, 255, 0.5)"],
+    ["--timeline-tick-text", "rgba(255, 255, 255, 0.34)"],
+    ["--timeline-border-strong", "rgba(255, 255, 255, 0.2)"],
+    ["--timeline-group-member-tint", "rgba(255, 255, 255, 0.035)"],
+    ["--timeline-overlay-text", "rgba(255, 255, 255, 0.8)"],
+    ["--timeline-clip-shadow-dragging", "rgba(0, 0, 0, 0.4)"],
+    ["--timeline-playhead-glow", "rgba(60, 230, 172, 0.14)"],
+    ["--timeline-playhead-shadow", "rgba(0, 0, 0, 0.55)"],
+  ])("keeps the migrated default for %s", (token, expected) => {
+    expect(themeTokenValue(token)).toBe(expected);
+  });
+
   it("keeps clip motion reduced-motion gated and layout safe", () => {
     const mediaStart = studioCss.indexOf("@media (prefers-reduced-motion: no-preference)");
     expect(mediaStart).toBeGreaterThanOrEqual(0);
@@ -63,19 +61,73 @@ describe("timeline motion styles", () => {
 
     const motionMediaCss = studioCss.slice(mediaStart);
     const timelineClipMotionRule = expectRule(motionMediaCss, ".timeline-clip");
-    const clipTransition = expectDeclaration(timelineClipMotionRule, "transition");
 
-    expect(transitionProperties(clipTransition)).toEqual(allowedTimelineTransitionProperties);
-    expect(clipTransition).not.toMatch(/\b(?:all|left|width|top|bottom|transform)\b/);
+    expect(expectDeclaration(timelineClipMotionRule, "transition")).toBe(
+      "background-color 120ms ease-out",
+    );
   });
 
   it("layers the active mint bloom through opacity instead of a gradient background swap", () => {
     const baseTimelineClipRule = expectRule(studioCss, ".timeline-clip");
+    const timelineClipLabelRule = expectRule(studioCss, ".timeline-clip__label");
+    const timelineClipTimecodeRule = expectRule(studioCss, ".timeline-clip__timecode");
+    const audioClipRule = expectRule(studioCss, ".timeline-clip.is-audio");
+    const audioClipHoverRule = expectRule(studioCss, ".timeline-clip.is-audio.is-hovered");
+    const audioClipDraggingRule = expectRule(studioCss, ".timeline-clip.is-audio.is-dragging");
     const activeTimelineClipRule = expectRule(studioCss, ".timeline-clip[data-active]");
+    const selectedTimelineClipRule = expectRule(studioCss, ".timeline-clip.is-selected");
+    const activeSelectedTimelineClipRule = expectRule(
+      studioCss,
+      ".timeline-clip[data-active].is-selected",
+    );
     const bloomOverlayRule = expectRule(studioCss, ".timeline-clip::before");
     const activeBloomOverlayRule = expectRule(studioCss, ".timeline-clip[data-active]::before");
 
     expect(baseTimelineClipRule).toContain("background-color: var(--clip-bg)");
+    expect(baseTimelineClipRule).toContain("border: 1px solid var(--clip-border)");
+    expect(baseTimelineClipRule).toContain("box-shadow:");
+    expect(baseTimelineClipRule).toContain("inset 0 1px 0 var(--timeline-clip-highlight)");
+    expect(baseTimelineClipRule).toContain("var(--timeline-clip-shadow)");
+    expect(timelineClipLabelRule).toContain("background: var(--timeline-clip-chip-bg)");
+    expect(timelineClipLabelRule).toContain("color: var(--timeline-clip-chip-text)");
+    expect(timelineClipLabelRule).toContain("text-overflow: ellipsis");
+    expect(timelineClipLabelRule).toContain("max-width: calc(100% - 22px)");
+    expect(timelineClipTimecodeRule).toContain("color: var(--timeline-tick-text)");
+    expect(themeCss).toContain("--timeline-clip-bg: rgba(255, 255, 255, 0.12)");
+    expect(themeCss).toContain("--timeline-clip-border: rgba(255, 255, 255, 0.22)");
+    expect(themeCss).toContain("--timeline-track-label: rgba(255, 255, 255, 0.5)");
+    expect(themeCss).toContain("--timeline-tick-text: rgba(255, 255, 255, 0.34)");
+    expect(themeCss).toContain("--timeline-clip-label-active: rgba(232, 255, 247, 0.95)");
+    expect(themeCss).toContain("--timeline-clip-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.85)");
+    expect(themeCss).toContain("--timeline-clip-selection: rgba(255, 255, 255, 0.85)");
+    expect(themeCss).toContain("--timeline-clip-selection-highlight: rgb(255 255 255 / 0.55)");
+    expect(themeCss).toContain("--timeline-clip-radius: 8px");
+    expect(themeCss).toContain("--timeline-clip-audio-radius: 21px");
+    expect(themeCss).toContain("--timeline-clip-highlight: rgb(255 255 255 / 0.08)");
+    expect(themeCss).toContain("--timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.3)");
+    expect(themeCss).toContain("--timeline-clip-chip-bg: rgba(15, 22, 18, 0.73)");
+    expect(themeCss).toContain("--timeline-clip-chip-audio-bg: rgba(25, 16, 38, 0.7)");
+    expect(themeCss).toContain("--timeline-clip-chip-text: #ffffff");
+    expect(themeCss).toContain("--timeline-row-bg: #edf0ed");
+    expect(themeCss).toContain("--timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.12)");
+    expect(themeCss).toContain("--timeline-clip-selection: #0f766e");
+    expect(themeCss).toContain("--timeline-clip-audio-bg: rgba(167, 139, 250, 0.16)");
+    expect(themeCss).toContain("--timeline-clip-audio-border: rgba(167, 139, 250, 0.4)");
+    expect(themeCss).toContain("--timeline-clip-audio-bg-hover: rgba(167, 139, 250, 0.24)");
+    expect(themeCss).toContain("--timeline-clip-audio-bg-dragging: rgba(60, 52, 84, 0.96)");
+    expect(audioClipRule).toContain("background-color: var(--timeline-clip-audio-bg)");
+    expect(audioClipRule).toContain("border-color: var(--timeline-clip-audio-border)");
+    expect(audioClipHoverRule).toContain("background-color: var(--timeline-clip-audio-bg-hover)");
+    expect(audioClipDraggingRule).toContain("var(--timeline-clip-audio-bg-dragging)");
+    expect(themeCss).toContain("--timeline-clip-selection: rgba(255, 255, 255, 0.85)");
+    expect(selectedTimelineClipRule).toContain(
+      "outline: 1.5px solid var(--timeline-clip-selection)",
+    );
+    expect(selectedTimelineClipRule).toContain("outline-offset: -1.5px");
+    expect(activeSelectedTimelineClipRule).toContain(
+      "outline: 1.5px solid var(--timeline-clip-selection)",
+    );
+    expect(activeSelectedTimelineClipRule).toContain("outline-offset: -1.5px");
     expect(activeTimelineClipRule).not.toContain("background: linear-gradient");
     expect(activeTimelineClipRule).toContain("border-color: var(--clip-border-active)");
     expect(activeTimelineClipRule).not.toContain("box-shadow");
@@ -85,6 +137,20 @@ describe("timeline motion styles", () => {
     expect(activeBloomOverlayRule).toContain("opacity: 1");
   });
 
+  it("routes timeline overlay colours through theme tokens", () => {
+    const overlaySource = timelineOverlaySources.join("\n");
+
+    expect(overlaySource).toContain("var(--timeline-shortcut-bg)");
+    expect(overlaySource).toContain("var(--timeline-thumbnail-shimmer)");
+    expect(overlaySource).toContain("var(--timeline-thumbnail-label-gradient)");
+    expect(overlaySource).toContain("var(--timeline-thumbnail-label-shadow)");
+    expect(overlaySource).toContain('"--timeline-waveform-bar-rgb"');
+    expect(overlaySource).toContain("var(--timeline-waveform-error)");
+    expect(overlaySource).toContain("var(--timeline-waveform-label-shadow)");
+    expect(overlaySource).toContain("var(--timeline-text-solid)");
+    expect(overlaySource).toContain("var(--timeline-accent)");
+  });
+
   it("targets trim handle bars without changing drag geometry", () => {
     const handleClassMatches = timelineClipSource.match(/className="timeline-clip__handle-bar"/g);
 

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

@@ -1,11 +1,25 @@
 import { describe, expect, it } from "vitest";
 import {
+  clipWidthLadder,
+  defaultTimelineTheme,
   getClipHandleOpacity,
   getRenderedTimelineElement,
   getTimelineTrackStyle,
 } from "./timelineTheme";
 import { getTrackStyle } from "./timelineIcons";
 
+describe("clipWidthLadder", () => {
+  it("labels from 60px, keeps the picture below that, and uses one frame below 24px", () => {
+    expect(clipWidthLadder(200)).toBe("labeled");
+    expect(clipWidthLadder(60)).toBe("labeled");
+    expect(clipWidthLadder(59)).toBe("picture");
+    expect(clipWidthLadder(24)).toBe("picture");
+    expect(clipWidthLadder(23)).toBe("frame");
+    expect(defaultTimelineTheme.clipRadius).toBe("var(--timeline-clip-radius)");
+    expect(defaultTimelineTheme.audioClipRadius).toBe("var(--timeline-clip-audio-radius)");
+  });
+});
+
 describe("getTimelineTrackStyle", () => {
   it("uses one neutral clip style for every timeline tag", () => {
     const expectedStyle = {