@hyperframes/studio 0.5.0-alpha.1 → 0.5.0-alpha.11

package/src/icons/SystemIcons.tsx

@@ -53,6 +53,8 @@ import {
   CaretRight,
   ClipboardText,
   ArrowCounterClockwise,
+  Camera as PhCamera,
+  ArrowClockwise,
   Gear,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
@@ -127,4 +129,6 @@ export const ChevronDown = makeIcon(CaretDown);
 export const ChevronRight = makeIcon(CaretRight);
 export const ClipboardList = makeIcon(ClipboardText);
 export const RotateCcw = makeIcon(ArrowCounterClockwise);
+export const Camera = makeIcon(PhCamera);
+export const RotateCw = makeIcon(ArrowClockwise);
 export const Settings = makeIcon(Gear);

package/src/player/components/AudioWaveform.tsx

@@ -2,6 +2,7 @@ import { memo, useRef, useState, useCallback, useEffect } from "react";
 
 interface AudioWaveformProps {
   audioUrl: string;
+  waveformUrl?: string;
   label: string;
   labelColor: string;
 }
@@ -49,6 +50,7 @@ function fakePeaks(url: string, count: number): number[] {
 
 // Module-level cache so decoded audio persists across re-renders and re-mounts
 const peaksCache = new Map<string, number[]>();
+const decodeInFlight = new Map<string, Promise<number[]>>();
 
 /**
  * Audio waveform rendered from real PCM data via Web Audio API.
@@ -57,43 +59,56 @@ const peaksCache = new Map<string, number[]>();
  */
 export const AudioWaveform = memo(function AudioWaveform({
   audioUrl,
+  waveformUrl,
   label,
   labelColor,
 }: AudioWaveformProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const barsRef = useRef<HTMLDivElement | null>(null);
   const roRef = useRef<ResizeObserver | null>(null);
-  const [peaks, setPeaks] = useState<number[] | null>(peaksCache.get(audioUrl) ?? null);
+  const cacheKey = waveformUrl ?? audioUrl;
+  const [peaks, setPeaks] = useState<number[] | null>(peaksCache.get(cacheKey) ?? null);
 
-  // Fetch + decode audio once
   useEffect(() => {
-    if (peaks || !audioUrl) return;
-
-    const ctrl = new AbortController();
-    fetch(audioUrl, { signal: ctrl.signal })
-      .then((r) => r.arrayBuffer())
-      .then((buf) => {
-        const ctx = new AudioContext();
-        return ctx.decodeAudioData(buf).finally(() => ctx.close());
-      })
-      .then((decoded) => {
-        if (ctrl.signal.aborted) return;
-        const channel = decoded.getChannelData(0);
-        // Extract enough peaks for wide clips (up to 4000 bars)
-        const p = extractPeaks(channel, 4000);
-        peaksCache.set(audioUrl, p);
-        setPeaks(p);
-      })
-      .catch(() => {
-        if (ctrl.signal.aborted) return;
-        // Fallback to fake waveform
-        const p = fakePeaks(audioUrl, 4000);
-        peaksCache.set(audioUrl, p);
-        setPeaks(p);
-      });
-
-    return () => ctrl.abort();
-  }, [audioUrl, peaks]);
+    if (peaks || !cacheKey) return;
+
+    let cancelled = false;
+
+    let promise = decodeInFlight.get(cacheKey);
+    if (!promise) {
+      promise = (
+        waveformUrl
+          ? fetch(waveformUrl)
+              .then((r) => r.json())
+              .then((d: { peaks?: number[] }) => {
+                if (!Array.isArray(d.peaks)) throw new Error("bad response");
+                return d.peaks;
+              })
+          : fetch(audioUrl)
+              .then((r) => r.arrayBuffer())
+              .then((buf) => {
+                const ctx = new AudioContext();
+                return ctx.decodeAudioData(buf).finally(() => ctx.close());
+              })
+              .then((decoded) => extractPeaks(decoded.getChannelData(0), 4000))
+      )
+        .catch(() => fakePeaks(cacheKey, 4000))
+        .then((p) => {
+          peaksCache.set(cacheKey, p);
+          return p;
+        })
+        .finally(() => decodeInFlight.delete(cacheKey));
+
+      decodeInFlight.set(cacheKey, promise);
+    }
+
+    promise.then((p) => {
+      if (!cancelled) setPeaks(p);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [audioUrl, waveformUrl, cacheKey, peaks]);
 
   // Draw bars into the container using innerHTML (fast, zoom-resilient)
   const draw = useCallback(() => {

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

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { buildCompositionThumbnailUrl } from "./CompositionThumbnail";
+
+describe("buildCompositionThumbnailUrl", () => {
+  it("includes selector and occurrence index for precise element thumbnails", () => {
+    expect(
+      buildCompositionThumbnailUrl({
+        previewUrl: "/api/projects/demo/preview",
+        seekTime: 1,
+        duration: 2,
+        selector: ".card",
+        selectorIndex: 2,
+        origin: "http://localhost:3000",
+      }),
+    ).toBe(
+      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v2&selector=.card&selectorIndex=2",
+    );
+  });
+});

package/src/player/components/CompositionThumbnail.tsx

@@ -7,6 +7,7 @@ interface CompositionThumbnailProps {
   labelColor: string;
   accentColor?: string;
   selector?: string;
+  selectorIndex?: number;
   seekTime?: number;
   duration?: number;
   width?: number;
@@ -16,12 +17,44 @@ interface CompositionThumbnailProps {
 const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v2";
 
+export function buildCompositionThumbnailUrl({
+  previewUrl,
+  seekTime = 2,
+  duration = 5,
+  selector,
+  selectorIndex,
+  origin,
+}: {
+  previewUrl: string;
+  seekTime?: number;
+  duration?: number;
+  selector?: string;
+  selectorIndex?: number;
+  origin: string;
+}): string {
+  const thumbnailBase = previewUrl
+    .replace("/preview/comp/", "/thumbnail/")
+    .replace(/\/preview$/, "/thumbnail/index.html");
+  const midTime = seekTime + duration / 2;
+  const thumbnailUrl = new URL(thumbnailBase, origin);
+  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
+  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  if (selector) {
+    thumbnailUrl.searchParams.set("selector", selector);
+    if (selectorIndex != null && selectorIndex > 0) {
+      thumbnailUrl.searchParams.set("selectorIndex", String(selectorIndex));
+    }
+  }
+  return thumbnailUrl.toString();
+}
+
 export const CompositionThumbnail = memo(function CompositionThumbnail({
   previewUrl,
   label,
   labelColor,
   accentColor = "#6B7280",
   selector,
+  selectorIndex,
   seekTime = 2,
   duration = 5,
 }: CompositionThumbnailProps) {
@@ -48,15 +81,14 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
     roRef.current?.disconnect();
   });
 
-  const thumbnailBase = previewUrl
-    .replace("/preview/comp/", "/thumbnail/")
-    .replace(/\/preview$/, "/thumbnail/index.html");
-  const midTime = seekTime + duration / 2;
-  const thumbnailUrl = new URL(thumbnailBase, window.location.origin);
-  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
-  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
-  if (selector) thumbnailUrl.searchParams.set("selector", selector);
-  const url = thumbnailUrl.toString();
+  const url = buildCompositionThumbnailUrl({
+    previewUrl,
+    seekTime,
+    duration,
+    selector,
+    selectorIndex,
+    origin: window.location.origin,
+  });
   const frameW = Math.max(48, Math.round(CLIP_HEIGHT * aspect));
   const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
 
@@ -66,7 +98,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
         src={url}
         alt=""
         draggable={false}
-        loading="lazy"
+        loading="eager"
         onLoad={(e) => {
           const img = e.currentTarget;
           if (img.naturalWidth > 0 && img.naturalHeight > 0) {

package/src/player/components/EditModal.tsx

@@ -3,6 +3,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlayerStore } from "../store/playerStore";
 import { formatTime } from "../lib/time";
 import { buildPromptCopyText, buildTimelineAgentPrompt } from "./timelineEditing";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface EditPopoverProps {
   rangeStart: number;
@@ -62,16 +63,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   }, [start, end, elementsInRange, prompt]);
 
   const handleCopy = useCallback(async () => {
-    try {
-      await navigator.clipboard.writeText(buildClipboardText());
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = buildClipboardText();
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(buildClipboardText());
+    if (!copied) return;
     setCopiedAgentPrompt(true);
     setTimeout(() => {
       setCopiedAgentPrompt(false);
@@ -82,16 +75,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   const handleCopyPrompt = useCallback(async () => {
     const promptText = buildPromptCopyText(prompt);
     if (!promptText) return;
-    try {
-      await navigator.clipboard.writeText(promptText);
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = promptText;
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(promptText);
+    if (!copied) return;
     setCopiedPromptOnly(true);
     setTimeout(() => {
       setCopiedPromptOnly(false);

package/src/player/components/PlayerControls.tsx

@@ -1,14 +1,17 @@
 import { useRef, useState, useCallback, useEffect, memo } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import {
-  TIMELINE_TOGGLE_SHORTCUT_LABEL,
-  getTimelineToggleTitle,
-} from "../../utils/timelineDiscovery";
-import { formatTime } from "../lib/time";
+import { formatFrameTime, frameToSeconds, stepFrameTime, formatTime } from "../lib/time";
 import { usePlayerStore, liveTime } from "../store/playerStore";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
 const SEEK_EDGE_SNAP_PX = 8;
+type TimeDisplayMode = "time" | "frame";
+const SHORTCUT_HINTS = [
+  { key: "J", label: "Play backward" },
+  { key: "K", label: "Stop playback" },
+  { key: "L", label: "Play forward" },
+  { key: "←/→", label: "Step one frame backward or forward" },
+] as const;
 
 export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth: number): number {
   if (!Number.isFinite(rectWidth) || rectWidth <= 0) return 0;
@@ -23,23 +26,23 @@ export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth:
 interface PlayerControlsProps {
   onTogglePlay: () => void;
   onSeek: (time: number) => void;
-  timelineVisible?: boolean;
-  onToggleTimeline?: () => void;
 }
 
 export const PlayerControls = memo(function PlayerControls({
   onTogglePlay,
   onSeek,
-  timelineVisible,
-  onToggleTimeline,
 }: PlayerControlsProps) {
   // Subscribe to only the fields we render — each selector prevents cascading re-renders
   const isPlaying = usePlayerStore((s) => s.isPlaying);
   const duration = usePlayerStore((s) => s.duration);
   const timelineReady = usePlayerStore((s) => s.timelineReady);
   const playbackRate = usePlayerStore((s) => s.playbackRate);
+  const loopEnabled = usePlayerStore((s) => s.loopEnabled);
   const setPlaybackRate = usePlayerStore.getState().setPlaybackRate;
+  const setLoopEnabled = usePlayerStore.getState().setLoopEnabled;
   const [showSpeedMenu, setShowSpeedMenu] = useState(false);
+  const [timeDisplayMode, setTimeDisplayMode] = useState<TimeDisplayMode>("time");
+  const [jumpFrame, setJumpFrame] = useState("");
 
   const progressFillRef = useRef<HTMLDivElement>(null);
   const progressThumbRef = useRef<HTMLDivElement>(null);
@@ -49,6 +52,8 @@ export const PlayerControls = memo(function PlayerControls({
   const speedMenuContainerRef = useRef<HTMLDivElement>(null);
   const isDraggingRef = useRef(false);
   const currentTimeRef = useRef(0);
+  const timeDisplayModeRef = useRef(timeDisplayMode);
+  timeDisplayModeRef.current = timeDisplayMode;
 
   const durationRef = useRef(duration);
   durationRef.current = duration;
@@ -59,7 +64,10 @@ export const PlayerControls = memo(function PlayerControls({
       const pct = dur > 0 ? Math.min(100, (t / dur) * 100) : 0;
       if (progressFillRef.current) progressFillRef.current.style.width = `${pct}%`;
       if (progressThumbRef.current) progressThumbRef.current.style.left = `${pct}%`;
-      if (timeDisplayRef.current) timeDisplayRef.current.textContent = formatTime(t);
+      if (timeDisplayRef.current) {
+        timeDisplayRef.current.textContent =
+          timeDisplayModeRef.current === "frame" ? formatFrameTime(t, dur) : formatTime(t);
+      }
       if (sliderRef.current) sliderRef.current.setAttribute("aria-valuenow", String(Math.round(t)));
     };
     const unsub = liveTime.subscribe(updateProgress);
@@ -82,6 +90,13 @@ export const PlayerControls = memo(function PlayerControls({
     };
   });
 
+  useEffect(() => {
+    if (!timeDisplayRef.current) return;
+    const t = currentTimeRef.current;
+    timeDisplayRef.current.textContent =
+      timeDisplayMode === "frame" ? formatFrameTime(t, duration) : formatTime(t);
+  }, [duration, timeDisplayMode]);
+
   useEffect(() => {
     if (!showSpeedMenu) return;
     const handleMouseDown = (e: MouseEvent) => {
@@ -190,21 +205,44 @@ export const PlayerControls = memo(function PlayerControls({
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       if (!timelineReady || duration <= 0) return;
-      const step = e.shiftKey ? 5 : 1;
+      const step = e.shiftKey ? 10 : 1;
       if (e.key === "ArrowLeft") {
         e.preventDefault();
-        onSeek(Math.max(0, currentTimeRef.current - step));
+        onSeek(stepFrameTime(currentTimeRef.current, -step));
       } else if (e.key === "ArrowRight") {
         e.preventDefault();
-        onSeek(Math.min(duration, currentTimeRef.current + step));
+        onSeek(Math.min(duration, stepFrameTime(currentTimeRef.current, step)));
       }
     },
     [timelineReady, duration, onSeek],
   );
 
+  const commitJumpFrame = useCallback(() => {
+    const frame = Number.parseInt(jumpFrame, 10);
+    if (!Number.isFinite(frame) || duration <= 0) return;
+    onSeek(Math.min(duration, frameToSeconds(Math.max(0, frame))));
+  }, [duration, jumpFrame, onSeek]);
+
+  const handleJumpSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      commitJumpFrame();
+    },
+    [commitJumpFrame],
+  );
+
+  const handleJumpKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key !== "Enter") return;
+      e.preventDefault();
+      commitJumpFrame();
+    },
+    [commitJumpFrame],
+  );
+
   return (
     <div
-      className="px-4 py-2 flex items-center gap-3"
+      className="px-4 py-2 flex flex-wrap items-center gap-x-2 gap-y-1"
       style={{
         borderTop: "1px solid rgba(255,255,255,0.04)",
         // Add iOS safe-area inset so Safari's bottom URL bar doesn't occlude
@@ -236,12 +274,16 @@ export const PlayerControls = memo(function PlayerControls({
 
       {/* Time display */}
       <span
-        className="font-mono text-[11px] tabular-nums flex-shrink-0 min-w-[72px]"
+        className="font-mono text-[11px] tabular-nums flex-shrink-0 w-[118px]"
         style={{ color: "#A1A1AA" }}
       >
         <span ref={timeDisplayRef}>{formatTime(0)}</span>
-        <span style={{ color: "#3F3F46", margin: "0 2px" }}>/</span>
-        <span style={{ color: "#52525B" }}>{formatTime(duration)}</span>
+        {timeDisplayMode === "time" ? (
+          <>
+            <span style={{ color: "#3F3F46", margin: "0 2px" }}>/</span>
+            <span style={{ color: "#52525B" }}>{formatTime(duration)}</span>
+          </>
+        ) : null}
       </span>
 
       {/* Seek bar — teal progress fill */}
@@ -256,7 +298,7 @@ export const PlayerControls = memo(function PlayerControls({
         aria-valuemin={0}
         aria-valuemax={Math.round(duration)}
         aria-valuenow={0}
-        className="flex-1 h-6 flex items-center cursor-pointer group"
+        className="min-w-[96px] flex-1 h-6 flex items-center cursor-pointer group"
         // `touch-action: none` tells the browser we're handling every
         // pointer gesture on this element ourselves. Without it, iOS
         // Safari consumes horizontal swipes for its own swipe-back-to-
@@ -292,7 +334,7 @@ export const PlayerControls = memo(function PlayerControls({
         <button
           type="button"
           onClick={() => setShowSpeedMenu((v) => !v)}
-          className="px-2 py-1 rounded-md text-[10px] font-mono tabular-nums transition-colors"
+          className="w-10 px-2 py-1 rounded-md text-[10px] font-mono tabular-nums transition-colors"
           style={{ color: "#71717A", background: "rgba(255,255,255,0.04)" }}
         >
           {playbackRate === 1 ? "1x" : `${playbackRate}x`}
@@ -329,38 +371,64 @@ export const PlayerControls = memo(function PlayerControls({
         )}
       </div>
 
-      {/* Timeline toggle */}
-      {onToggleTimeline !== undefined && (
-        <button
-          type="button"
-          onClick={onToggleTimeline}
-          className={`h-7 flex items-center gap-1.5 rounded-md border px-2.5 text-[11px] font-medium transition-colors ${
-            timelineVisible
-              ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
-              : "border-neutral-700 text-neutral-300 hover:border-neutral-500 hover:bg-neutral-800"
-          }`}
-          title={getTimelineToggleTitle(Boolean(timelineVisible))}
-          aria-label={timelineVisible ? "Hide timeline editor" : "Show timeline editor"}
-        >
-          <svg
-            width="13"
-            height="13"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
+      <button
+        type="button"
+        onClick={() => setLoopEnabled(!loopEnabled)}
+        className={`h-7 w-14 rounded-md border px-2 text-[10px] font-medium transition-colors ${
+          loopEnabled
+            ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
+            : "border-neutral-700 text-neutral-400 hover:border-neutral-500 hover:bg-neutral-800"
+        }`}
+        title="Loop playback"
+        aria-label={loopEnabled ? "Disable loop playback" : "Enable loop playback"}
+        aria-pressed={loopEnabled}
+      >
+        Loop
+      </button>
+
+      <button
+        type="button"
+        onClick={() => setTimeDisplayMode((mode) => (mode === "time" ? "frame" : "time"))}
+        className="h-7 w-14 rounded-md border border-neutral-700 px-2 text-[10px] font-mono text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
+        title="Toggle time/frame display"
+        aria-label="Toggle time and frame display"
+      >
+        {timeDisplayMode === "time" ? "m:ss" : "frames"}
+      </button>
+
+      <form
+        onSubmit={handleJumpSubmit}
+        className="hidden sm:flex flex-shrink-0 w-[58px] items-center"
+      >
+        <input
+          value={jumpFrame}
+          onChange={(e) => setJumpFrame(e.target.value)}
+          inputMode="numeric"
+          pattern="[0-9]*"
+          aria-label="Jump to frame"
+          placeholder="frame"
+          className="h-7 w-[58px] rounded-md border border-neutral-700 bg-neutral-900 px-2 text-[10px] font-mono tabular-nums text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-studio-accent/60"
+          onKeyDown={handleJumpKeyDown}
+          onBlur={commitJumpFrame}
+        />
+      </form>
+
+      <div
+        className="hidden lg:flex items-center gap-1 text-[9px] font-mono text-neutral-500"
+        aria-label="Playback shortcuts: J backward, K stop, L forward, arrows step one frame"
+      >
+        {SHORTCUT_HINTS.map((shortcut) => (
+          <span
+            key={shortcut.key}
+            className="group relative rounded border border-neutral-800 px-1 py-0.5"
           >
-            <rect x="3" y="13" width="18" height="8" rx="1" />
-            <line x1="3" y1="9" x2="21" y2="9" />
-            <line x1="3" y1="5" x2="21" y2="5" />
-          </svg>
-          <span>Timeline</span>
-          <span className="hidden md:inline rounded bg-black/20 px-1 py-0.5 text-[9px] font-mono opacity-70">
-            {TIMELINE_TOGGLE_SHORTCUT_LABEL}
+            {shortcut.key}
+            <span className="pointer-events-none absolute bottom-full left-1/2 z-50 mb-1.5 hidden -translate-x-1/2 whitespace-nowrap rounded-md border border-neutral-700 bg-neutral-950 px-2 py-1 font-sans text-[10px] text-neutral-200 shadow-lg group-hover:block">
+              {shortcut.label}
+            </span>
           </span>
-        </button>
-      )}
+        ))}
+      </div>
     </div>
   );
 });

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

@@ -1,11 +1,14 @@
 import { describe, it, expect } from "vitest";
 import {
+  formatTimelineTickLabel,
   generateTicks,
   getDefaultDroppedTrack,
   getTimelineCanvasHeight,
   resolveTimelineAssetDrop,
   getTimelinePlayheadLeft,
+  getTimelineScrollLeftForZoomAnchor,
   getTimelineScrollLeftForZoomTransition,
+  shouldShowTimelineShortcutHint,
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
 } from "./Timeline";
@@ -78,6 +81,20 @@ describe("generateTicks", () => {
       expect(major[0]).toBe(0);
     }
   });
+
+  it("uses denser major labels as timeline zoom increases", () => {
+    const fitTicks = generateTicks(180, 10);
+    const zoomedTicks = generateTicks(180, 48);
+    expect(fitTicks.major[1] - fitTicks.major[0]).toBe(15);
+    expect(zoomedTicks.major[1] - zoomedTicks.major[0]).toBe(5);
+    expect(zoomedTicks.minor).toContain(1);
+    expect(zoomedTicks.minor).toContain(4);
+  });
+
+  it("keeps labels readable instead of placing one at every tiny tick", () => {
+    const { major } = generateTicks(180, 80);
+    expect(major[1] - major[0]).toBe(2);
+  });
 });
 
 describe("formatTime", () => {
@@ -118,6 +135,20 @@ describe("formatTime", () => {
   });
 });
 
+describe("formatTimelineTickLabel", () => {
+  it("uses minute-second labels for normal timeline intervals", () => {
+    expect(formatTimelineTickLabel(90, 180, 5)).toBe("1:30");
+  });
+
+  it("uses hour labels for long timelines", () => {
+    expect(formatTimelineTickLabel(3661, 4000, 60)).toBe("1:01:01");
+  });
+
+  it("shows subsecond labels when the major ruler interval is below one second", () => {
+    expect(formatTimelineTickLabel(1.5, 3, 0.5)).toBe("0:01.5");
+  });
+});
+
 describe("shouldAutoScrollTimeline", () => {
   it("never auto-scrolls in fit mode", () => {
     expect(shouldAutoScrollTimeline("fit", 1200, 800)).toBe(false);
@@ -144,6 +175,48 @@ describe("getTimelineScrollLeftForZoomTransition", () => {
     expect(getTimelineScrollLeftForZoomTransition("manual", "manual", 480)).toBe(480);
   });
 });
+
+describe("getTimelineScrollLeftForZoomAnchor", () => {
+  it("preserves the time under the pointer when zooming in", () => {
+    expect(
+      getTimelineScrollLeftForZoomAnchor({
+        pointerX: 300,
+        currentScrollLeft: 200,
+        gutter: 32,
+        currentPixelsPerSecond: 10,
+        nextPixelsPerSecond: 20,
+        duration: 120,
+      }),
+    ).toBe(668);
+  });
+
+  it("clamps negative scroll targets", () => {
+    expect(
+      getTimelineScrollLeftForZoomAnchor({
+        pointerX: 300,
+        currentScrollLeft: 0,
+        gutter: 32,
+        currentPixelsPerSecond: 20,
+        nextPixelsPerSecond: 5,
+        duration: 120,
+      }),
+    ).toBe(0);
+  });
+
+  it("preserves current scroll when inputs are invalid", () => {
+    expect(
+      getTimelineScrollLeftForZoomAnchor({
+        pointerX: 300,
+        currentScrollLeft: 120,
+        gutter: 32,
+        currentPixelsPerSecond: 0,
+        nextPixelsPerSecond: 20,
+        duration: 120,
+      }),
+    ).toBe(120);
+  });
+});
+
 describe("getTimelinePlayheadLeft", () => {
   it("converts time to a pixel offset from the gutter", () => {
     expect(getTimelinePlayheadLeft(4, 20)).toBe(112);
@@ -165,6 +238,17 @@ describe("getTimelineCanvasHeight", () => {
   });
 });
 
+describe("shouldShowTimelineShortcutHint", () => {
+  it("shows the hint when the timeline does not vertically overflow", () => {
+    expect(shouldShowTimelineShortcutHint(220, 220)).toBe(true);
+    expect(shouldShowTimelineShortcutHint(220.5, 220)).toBe(true);
+  });
+
+  it("hides the hint when timeline tracks need vertical scrolling", () => {
+    expect(shouldShowTimelineShortcutHint(221.5, 220)).toBe(false);
+  });
+});
+
 describe("shouldHandleTimelineDeleteKey", () => {
   it("handles Delete and Backspace when focus is not in an editor", () => {
     expect(shouldHandleTimelineDeleteKey({ key: "Delete" })).toBe(true);