@hyperframes/studio 0.8.139 → 0.8.140

package/src/player/components/timelineZoomInput.ts

@@ -0,0 +1,456 @@
+import { useSyncExternalStore } from "react";
+import { flushSync } from "react-dom";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
+import { usePlayerStore } from "../store/playerStore";
+import { markTimelineMotion, TIMELINE_REST_MS } from "./timelineMotion";
+import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
+import {
+  clampTimelineZoomPercent,
+  getNextTimelineZoomPercent,
+  getTimelinePixelsPerSecond,
+  getTimelineZoomPercent,
+} from "./timelineZoom";
+
+/** Where a zoom holds its place: `time` stays `x` px from the viewport's left edge. */
+export interface TimelineZoomAnchor {
+  time: number;
+  x: number;
+}
+
+/** The mounted timeline's scroll viewport, which every zoom measures and previews against. */
+export interface TimelineZoomViewport {
+  scroll: HTMLDivElement;
+  contentOrigin: number;
+}
+
+/** How an eased zoom ended: it reached its range, or a person's zoom or the caller stopped it. */
+export type TimelineZoomResult = "done" | "cancelled";
+
+/**
+ * A zoom drawn by scaling what is already laid out, on the compositor, until it is committed.
+ * `shift` is the scrollLeft minus the scrollLeft the zoom will have: the translate that places it.
+ */
+interface ZoomPreview {
+  percent: number;
+  pps: number;
+  shift: number;
+  basePps: number;
+  /** The times laid out (clips mounted, ruler drawn) when it began; past them it shows gaps. */
+  drawn: TimelineTimeRange;
+  byPerson: boolean;
+}
+
+const RANGE_MARGIN_PX = 24;
+const SMOOTH_ZOOM_MS = 220;
+/** Past this the scaled-up preview turns soft. */
+const MAX_PREVIEW_SCALE = 4;
+/** Rounding at a drawn edge (whole-pixel content width, the fit track's 2px) is not a gap. */
+const EDGE_SLACK_PX = 2;
+const SCALED = "[data-timeline-zoom-scale]";
+
+let viewport: TimelineZoomViewport | null = null;
+/** While a preview shows, scales rows and strips React mounts into the timeline before they paint. */
+let mounts: MutationObserver | null = null;
+let preview: ZoomPreview | null = null;
+let frame = 0;
+let restTimer: ReturnType<typeof setTimeout> | null = null;
+let anchorForCommit: TimelineZoomAnchor | null = null;
+let animation = 0;
+let easingTo: number | null = null;
+let resolveEase: ((result: TimelineZoomResult) => void) | null = null;
+const previewListeners = new Set<() => void>();
+
+export function currentTimelineZoomPercent(): number {
+  if (preview) return preview.percent;
+  const s = usePlayerStore.getState();
+  return getTimelineZoomPercent(s.zoomMode, s.manualZoomPercent, s.timelineFitPps);
+}
+
+/** The scale the timeline shows and the scrollLeft that scale would have. */
+function shown(scroll: HTMLDivElement): { pps: number; left: number } {
+  if (preview) return { pps: preview.pps, left: scroll.scrollLeft - preview.shift };
+  return { pps: usePlayerStore.getState().timelinePps, left: scroll.scrollLeft };
+}
+
+/** The time under `x` px from the timeline viewport's left edge, as it is drawn now. */
+export function timelineTimeAtX(x: number): number | null {
+  if (!viewport) return null;
+  const { pps, left } = shown(viewport.scroll);
+  return pps > 0 ? (left + x - viewport.contentOrigin) / pps : null;
+}
+
+/** The scale and time-zero position to place something at a time by, while a zoom is previewed. */
+export function timelineZoomMapping(pps: number, contentOrigin: number) {
+  return preview
+    ? { pps: preview.pps, contentOrigin: contentOrigin + preview.shift }
+    : { pps, contentOrigin };
+}
+
+/** Whether a zoom is drawn scaled right now, so boxes read off the page are scaled too. */
+export const isTimelineZoomPreviewing = (): boolean => preview !== null;
+
+/** Called each frame a zoom preview moves, and once when it is laid out or dropped. */
+export function subscribeTimelineZoomPreview(listener: () => void): () => void {
+  previewListeners.add(listener);
+  return () => previewListeners.delete(listener);
+}
+
+const subscribeShownZoom = (listener: () => void) => {
+  const unsubscribePreview = subscribeTimelineZoomPreview(listener);
+  const unsubscribeStore = usePlayerStore.subscribe(listener);
+  return () => {
+    unsubscribePreview();
+    unsubscribeStore();
+  };
+};
+
+/** The zoom percent the timeline shows, kept current through a preview. */
+export function useShownTimelineZoomPercent(): number {
+  return useSyncExternalStore(subscribeShownZoom, currentTimelineZoomPercent);
+}
+
+function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
+  anchorForCommit = anchor;
+  usePlayerStore.setState((s) => {
+    const clamped = clampTimelineZoomPercent(percent, s.timelineFitPps);
+    return {
+      zoomMode: "manual",
+      manualZoomPercent: clamped,
+      // Only a person's zoom counts: the timeline and its host read it as the person taking over.
+      userZoomCount: s.userZoomCount + (byPerson ? 1 : 0),
+      timelinePps: getTimelinePixelsPerSecond(s.timelineFitPps, "manual", clamped),
+    };
+  });
+}
+
+const emitPreview = () => previewListeners.forEach((listener) => listener());
+
+/** Stops the pending preview frame, rest timer and mount watch. */
+function cancelPending() {
+  mounts?.disconnect();
+  mounts = null;
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = null;
+  cancelAnimationFrame(frame);
+  frame = 0;
+}
+
+function clearScaled(scroll: HTMLElement) {
+  scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+    el.style.transform = "";
+    el.style.transformOrigin = "";
+    el.style.willChange = "";
+  });
+}
+
+/** Whether the preview shows time outside what was mounted, or is scaled up too far. */
+function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigin: number) {
+  if (p.pps / p.basePps > MAX_PREVIEW_SCALE) return true;
+  const left = scroll.scrollLeft - p.shift;
+  const start = left / p.pps;
+  const end = (left + scroll.clientWidth - contentOrigin) / p.pps;
+  const slack = EDGE_SLACK_PX / p.pps;
+  return start < p.drawn.start - slack || end > p.drawn.end + slack;
+}
+
+/** The times laid out now: the render window clips, ruler ticks and beat lines are drawn in. */
+function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number): TimelineTimeRange {
+  const contentEnd = (scroll.scrollWidth - contentOrigin) / pps;
+  return getTimelineRenderTimeRange(scroll, pps, contentOrigin, contentEnd);
+}
+
+function scalePreview(scroll: HTMLElement) {
+  if (!preview) return;
+  const transform = `translateX(${preview.shift}px) scaleX(${preview.pps / preview.basePps})`;
+  scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
+    // The attribute's value is where time zero sits in the element, when not at its left edge.
+    el.style.transformOrigin = `${el.dataset.timelineZoomScale || 0}px 0`;
+    el.style.willChange = "transform";
+    el.style.transform = transform;
+  });
+}
+
+const holdsScaled = (node: Node) =>
+  node instanceof Element && (node.matches(SCALED) || node.querySelector(SCALED) !== null);
+
+function watchMounts(scroll: HTMLElement): MutationObserver {
+  const observer = new MutationObserver((records) => {
+    if (records.some((record) => [...record.addedNodes].some(holdsScaled))) scalePreview(scroll);
+  });
+  observer.observe(scroll, { childList: true, subtree: true });
+  return observer;
+}
+
+function drawPreview() {
+  cancelAnimationFrame(frame);
+  frame = 0;
+  const view = viewport;
+  if (!preview || !view) return;
+  if (previewNeedsLayout(preview, view.scroll, view.contentOrigin)) {
+    commitPreview();
+    return;
+  }
+  scalePreview(view.scroll);
+  mounts ??= watchMounts(view.scroll);
+  emitPreview();
+}
+
+/** Lays the previewed zoom out for real and drops the scaling in the same frame. */
+function commitPreview() {
+  cancelPending();
+  const view = viewport;
+  const done = preview;
+  if (!view || !done) return;
+  const left = view.scroll.scrollLeft - done.shift;
+  // Ending at the scale already laid out (an eased zoom-out) needs a scroll, not a layout.
+  if (done.pps !== done.basePps) {
+    flushSync(() =>
+      writeZoom(done.percent, { time: left / done.pps, x: view.contentOrigin }, done.byPerson),
+    );
+  }
+  preview = null;
+  if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) view.scroll.scrollLeft = left;
+  clearScaled(view.scroll);
+  emitPreview();
+}
+
+/** The playhead's place if on screen, else the middle with the playhead brought to it. */
+function defaultAnchor(view: TimelineZoomViewport, pps: number, left: number): TimelineZoomAnchor {
+  const { currentTime } = usePlayerStore.getState();
+  const x = view.contentOrigin + currentTime * pps - left;
+  const onScreen = x >= view.contentOrigin && x <= view.scroll.clientWidth;
+  return {
+    time: currentTime,
+    x: onScreen ? x : (view.contentOrigin + view.scroll.clientWidth) / 2,
+  };
+}
+
+function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
+  const view = viewport;
+  const fitPps = usePlayerStore.getState().timelineFitPps;
+  if (!view || !(fitPps > 0)) {
+    writeZoom(percent, anchor, byPerson);
+    return;
+  }
+  const clamped = clampTimelineZoomPercent(percent, fitPps);
+  const pps = getTimelinePixelsPerSecond(fitPps, "manual", clamped);
+  const { scroll, contentOrigin } = view;
+  const now = shown(scroll);
+  const at = anchor ?? defaultAnchor(view, now.pps, now.left);
+  preview ??= {
+    percent: clamped,
+    pps,
+    shift: 0,
+    basePps: now.pps,
+    drawn: drawnRange(scroll, now.pps, contentOrigin),
+    byPerson,
+  };
+  // The content's width at this scale: the fit track (getTimelineFitPps), never narrower.
+  const fitTrack = scroll.clientWidth - contentOrigin - 2;
+  const width = contentOrigin + fitTrack * Math.max(1, pps / fitPps);
+  const maxLeft = Math.max(0, width - scroll.clientWidth);
+  const left = Math.max(0, Math.min(maxLeft, at.time * pps + contentOrigin - at.x));
+  preview.percent = clamped;
+  preview.pps = pps;
+  preview.shift = scroll.scrollLeft - left;
+  preview.byPerson ||= byPerson;
+  if (!frame) frame = requestAnimationFrame(drawPreview);
+  if (restTimer) clearTimeout(restTimer);
+  restTimer = setTimeout(commitPreview, TIMELINE_REST_MS);
+  // After the commit timer of the same delay, so the zoom is laid out before the timeline rests.
+  markTimelineMotion();
+}
+
+/** A person's zoom input: previewed each frame, laid out once it rests. */
+export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor | null = null) {
+  stopEase();
+  request(percent, anchor, true);
+}
+
+/** Lays out a pending zoom now, so a press meets the real layout. */
+export function settleTimelineZoom(): void {
+  if (preview) commitPreview();
+}
+
+/** After a scroll: scales what it mounted, or lays the zoom out if it shows past what is drawn. */
+export function redrawTimelineZoomPreview(): void {
+  if (preview && !frame) frame = requestAnimationFrame(drawPreview);
+}
+
+/** Drops any pending or easing zoom without laying it out, as Fit does. */
+export function cancelTimelineZoom(): void {
+  stopEase();
+  dropPreview();
+}
+
+function dropPreview() {
+  cancelPending();
+  if (!preview) return;
+  if (viewport) clearScaled(viewport.scroll);
+  preview = null;
+  emitPreview();
+}
+
+function stopEase(result: TimelineZoomResult = "cancelled") {
+  cancelAnimationFrame(animation);
+  animation = 0;
+  easingTo = null;
+  const done = resolveEase;
+  resolveEase = null;
+  done?.(result);
+}
+
+/** The anchor of the zoom being committed; read once by the timeline as it lays the zoom out. */
+export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
+  const anchor = anchorForCommit;
+  anchorForCommit = null;
+  return anchor;
+}
+
+export function registerTimelineZoomViewport(next: TimelineZoomViewport): () => void {
+  viewport = next;
+  return () => {
+    // Another timeline mounted since keeps its registration.
+    if (viewport !== next) return;
+    viewport = null;
+    // A re-render registers again in the same commit; only a real unmount drops the zoom.
+    queueMicrotask(() => {
+      if (!viewport) cancelTimelineZoom();
+    });
+  };
+}
+
+const reducedMotion = () =>
+  typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/** The stretch a range zoom fills: from `x` px in, `width` px wide, inside the margins. */
+function rangeBox(view: TimelineZoomViewport): { x: number; width: number } {
+  const x = view.contentOrigin + RANGE_MARGIN_PX;
+  return { x, width: Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX) };
+}
+
+/** The seconds the timeline shows between its margins: what zoomTimelineToRange would fill. */
+export function currentTimelineRange(): { start: number; end: number } | null {
+  const view = viewport;
+  const pps = view ? shown(view.scroll).pps : 0;
+  if (!view || !(pps > 0)) return null;
+  const { x, width } = rangeBox(view);
+  const start = timelineTimeAtX(x)!;
+  return { start, end: start + width / pps };
+}
+
+/**
+ * Zooms and scrolls so `start`..`end` (seconds) fills the timeline, eased unless `smooth` is false
+ * or motion is reduced. Resolves on landing; "cancelled" on a person's zoom, abort, or a newer one.
+ */
+export function zoomTimelineToRange(
+  start: number,
+  end: number,
+  options: { smooth?: boolean; signal?: AbortSignal } = {},
+): Promise<TimelineZoomResult> {
+  return easeToRange(start, end, options, false);
+}
+
+function easeToRange(
+  start: number,
+  end: number,
+  { smooth = true, signal }: { smooth?: boolean; signal?: AbortSignal },
+  byPerson: boolean,
+): Promise<TimelineZoomResult> {
+  const view = viewport;
+  const fitPps = usePlayerStore.getState().timelineFitPps;
+  stopEase();
+  if (!view || !(end > start) || !(fitPps > 0) || signal?.aborted)
+    return Promise.resolve("cancelled");
+  let resolveThis: (result: TimelineZoomResult) => void = () => {};
+  const result = new Promise<TimelineZoomResult>((resolve) => (resolveThis = resolve));
+  resolveEase = resolveThis;
+  signal?.addEventListener("abort", () => resolveEase === resolveThis && stopEase(), {
+    once: true,
+  });
+  const { x, width } = rangeBox(view);
+  const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
+  const finish = () => {
+    commitPreview();
+    stopEase("done");
+  };
+  if (!smooth || reducedMotion()) {
+    request(toPercent, { time: start, x }, byPerson);
+    // Laid out next frame, never inside a caller's render or effect.
+    animation = requestAnimationFrame(finish);
+    return result;
+  }
+  easeZoom(view, fitPps, toPercent, { time: start, x }, byPerson, finish);
+  return result;
+}
+
+/** Eases from the zoom shown now to `toPercent`, landing `to.time` at `to.x`, then `finish`es. */
+function easeZoom(
+  view: TimelineZoomViewport,
+  fitPps: number,
+  toPercent: number,
+  to: TimelineZoomAnchor,
+  byPerson: boolean,
+  finish: () => void,
+) {
+  const { time: start, x } = to;
+  const fromPercent = currentTimelineZoomPercent();
+  const from = shown(view.scroll);
+  const toPps = getTimelinePixelsPerSecond(fitPps, "manual", toPercent);
+  const fromStart = timelineTimeAtX(x)!;
+  const old = currentTimelineRange()!;
+  // The one point both views put at the same place on screen; zooming about it, in log space,
+  // moves every frame straight from the old view to the new. Equal scales are a plain scroll.
+  const shift = from.pps === toPps ? null : (start - fromStart) / (1 / from.pps - 1 / toPps);
+  const anchorAt = (k: number): TimelineZoomAnchor =>
+    shift === null
+      ? { time: fromStart + (start - fromStart) * k, x }
+      : { time: fromStart + shift / from.pps, x: x + shift };
+  // Zooming out to a view that holds the old one: lay the target out once, in the first frame,
+  // and ease by scaling it down from the old view, instead of laying out again partway.
+  const holdsOld =
+    old.start >= start && old.end <= start + (old.end - old.start) * (from.pps / toPps);
+  let layoutFirst = toPps < from.pps && from.pps / toPps <= MAX_PREVIEW_SCALE && holdsOld;
+  const began = performance.now();
+  easingTo = toPercent;
+  const step = (now: number) => {
+    if (layoutFirst) {
+      layoutFirst = false;
+      request(toPercent, to, byPerson);
+      commitPreview();
+    }
+    const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
+    const k = 1 - (1 - t) ** 3;
+    request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k), byPerson);
+    // Drawn in this frame, not the next: the first one would otherwise paint a laid-out zoom-out bare.
+    drawPreview();
+    if (t < 1) animation = requestAnimationFrame(step);
+    else finish();
+  };
+  animation = requestAnimationFrame(step);
+}
+
+/**
+ * A zoom button: twice or half the scale, eased, keeping the playhead where it is on screen,
+ * or centring it when it is off screen.
+ */
+export function zoomTimelineStep(direction: "in" | "out"): void {
+  const fitPps = usePlayerStore.getState().timelineFitPps;
+  const nextPercent = getNextTimelineZoomPercent(
+    direction,
+    "manual",
+    easingTo ?? currentTimelineZoomPercent(),
+    fitPps,
+  );
+  const view = viewport;
+  if (!view || !(fitPps > 0)) {
+    requestTimelineZoom(nextPercent);
+    return;
+  }
+  const { x, width } = rangeBox(view);
+  const nextPps = getTimelinePixelsPerSecond(fitPps, "manual", nextPercent);
+  const now = shown(view.scroll);
+  const at = defaultAnchor(view, now.pps, now.left);
+  const start = at.time - (at.x - x) / nextPps;
+  void easeToRange(start, start + width / nextPps, {}, true);
+}

package/src/player/components/useTimelineGeometry.ts

@@ -77,8 +77,6 @@ export function useTimelineGeometry({
   const displayDuration = pps > 0 ? displayContentWidth / pps : effectiveDuration;
   const zoomModeRef = useRef(zoomMode);
   zoomModeRef.current = zoomMode;
-  const manualZoomPercentRef = useRef(manualZoomPercent);
-  manualZoomPercentRef.current = manualZoomPercent;
   fitPpsRef.current = fitPps;
 
   // Restore the horizontal scroll offset after an edit re-derives the elements
@@ -133,6 +131,5 @@ export function useTimelineGeometry({
     displayDuration,
     clipStateVersion: expandedElements,
     zoomModeRef,
-    manualZoomPercentRef,
   };
 }

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

@@ -2,7 +2,7 @@
 
 import { act, useRef } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 
@@ -22,20 +22,16 @@ function scrollBox(scrollLeft: number) {
 }
 
 interface HarnessProps {
-  pps: number;
+  /** Omitted: the scale the store publishes, as the timeline reads it. */
+  pps?: number;
   scroll: HTMLDivElement;
-  percent?: number;
   dragging?: boolean;
   zoomMode?: ZoomMode;
 }
 
-function Harness({
-  pps,
-  scroll,
-  percent = 100,
-  dragging = false,
-  zoomMode = "manual",
-}: HarnessProps) {
+function Harness({ pps: fixedPps, scroll, dragging = false, zoomMode = "manual" }: HarnessProps) {
+  const storePps = usePlayerStore((s) => s.timelinePps);
+  const pps = fixedPps ?? storePps;
   const scrollRef = useRef(scroll);
   const durationRef = useRef(60);
   useTimelinePlayhead({
@@ -46,17 +42,13 @@ function Harness({
     isDragging: { current: dragging },
     currentTime: 0,
     zoomMode,
-    manualZoomPercent: percent,
     zoomModeRef: { current: zoomMode },
-    manualZoomPercentRef: { current: percent },
     fitPps: pps,
     fitPpsRef: { current: pps },
     effectiveDuration: 60,
     pps,
     timelineReady: true,
     elementsLength: 1,
-    setZoomMode: () => {},
-    setManualZoomPercent: () => {},
     contentOrigin: ORIGIN,
   });
   return null;
@@ -115,13 +107,13 @@ describe("useTimelinePlayhead zoom anchor", () => {
     usePlayerStore.setState({ currentTime: 6 });
     const scroll = scrollBox(400);
     const before = onScreenX(scroll, 6, 100);
-    mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+    mount({ pps: 100, scroll })({ pps: 200 }, true);
     expect(onScreenX(scroll, 6, 200)).toBeCloseTo(before);
   });
 
   it("stays at 00:00 when a zoom is set with the playhead at 0, as a zoom restored on open is", () => {
     const scroll = scrollBox(0);
-    mount({ pps: 100, scroll, percent: 100 })({ pps: 250, percent: 250 }, true);
+    mount({ pps: 100, scroll })({ pps: 250 }, true);
     expect(scroll.scrollLeft).toBe(0);
   });
 
@@ -137,7 +129,7 @@ describe("useTimelinePlayhead zoom anchor", () => {
   it("brings an off-screen playhead into view when the toolbar zooms", () => {
     usePlayerStore.setState({ currentTime: 30 });
     const scroll = scrollBox(0);
-    mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+    mount({ pps: 100, scroll })({ pps: 200 }, true);
     expectVisible(scroll, 30, 200);
   });
 });
@@ -146,28 +138,21 @@ describe("useTimelinePlayhead zoom anchor, percent written by Studio itself", ()
   it("keeps 00:00 when the window resizes after an edit pinned the zoom", () => {
     usePlayerStore.setState({ currentTime: 6 });
     const scroll = scrollBox(0);
-    const update = mount({ pps: 100, scroll, percent: 200 });
-    update({ percent: 100 });
-    update({ pps: 130, percent: 100 });
+    const update = mount({ pps: 100, scroll });
+    update({});
+    update({ pps: 130 });
     expect(scroll.scrollLeft).toBe(0);
   });
 
   it("leaves an off-screen playhead alone when a length change re-pins the zoom", () => {
     usePlayerStore.setState({ currentTime: 30 });
     const scroll = scrollBox(400);
-    const update = mount({ pps: 100, scroll, percent: 150 });
-    update({ pps: 90, percent: 150 });
-    update({ pps: 101, percent: 168 });
+    const update = mount({ pps: 100, scroll });
+    update({ pps: 90 });
+    update({ pps: 101 });
     const x = onScreenX(scroll, 30, 101);
     expect(x > 800 || x < ORIGIN).toBe(true);
   });
-
-  it("anchors a person's zoom that lands on the percent already stored", () => {
-    usePlayerStore.setState({ currentTime: 30 });
-    const scroll = scrollBox(0);
-    mount({ pps: 100, scroll, percent: 200 })({ pps: 200, percent: 200 }, true);
-    expectVisible(scroll, 30, 200);
-  });
 });
 
 describe("useTimelinePlayhead follow while paused", () => {
@@ -252,3 +237,85 @@ describe("useTimelinePlayhead follow while paused", () => {
     expect(scroll.scrollLeft).toBe(0);
   });
 });
+
+describe("useTimelinePlayhead wheel zoom", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({
+      toFake: ["requestAnimationFrame", "cancelAnimationFrame", "setTimeout", "clearTimeout"],
+    });
+    usePlayerStore.setState({
+      zoomMode: "manual",
+      manualZoomPercent: 100,
+      timelineFitPps: 100,
+      timelinePps: 100,
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  /** A wheel step 432px in, previewed for one frame. */
+  const previewWheel = (scroll: HTMLDivElement, init: WheelEventInit) =>
+    act(() => {
+      const event = new WheelEvent("wheel", { deltaY: -50, cancelable: true, ...init });
+      // happy-dom's WheelEvent drops the MouseEvent fields of its init.
+      Object.defineProperties(event, {
+        clientX: { value: 432 },
+        ctrlKey: { value: Boolean(init.ctrlKey) },
+        metaKey: { value: Boolean(init.metaKey) },
+      });
+      scroll.dispatchEvent(event);
+      vi.advanceTimersToNextFrame();
+    });
+
+  /** A wheel step, then the rest at which its zoom is laid out. */
+  const wheel = (scroll: HTMLDivElement, init: WheelEventInit) => {
+    previewWheel(scroll, init);
+    act(() => vi.advanceTimersByTime(200));
+  };
+
+  it("zooms on Cmd+wheel as on a pinch, and leaves a plain wheel to scroll", () => {
+    const scroll = scrollBox(0);
+    mount({ scroll });
+    wheel(scroll, {});
+    expect(usePlayerStore.getState().manualZoomPercent).toBe(100);
+    wheel(scroll, { metaKey: true });
+    expect(usePlayerStore.getState().manualZoomPercent).toBeGreaterThan(100);
+  });
+
+  it("keeps previewing a pinch through a scroll, laying it out only at rest", () => {
+    const scroll = scrollBox(0);
+    mount({ scroll });
+    previewWheel(scroll, { ctrlKey: true });
+    act(() => {
+      scroll.dispatchEvent(new Event("scroll"));
+      vi.advanceTimersToNextFrame();
+    });
+    expect(usePlayerStore.getState().timelinePps).toBe(100);
+    act(() => vi.advanceTimersByTime(200));
+    expect(usePlayerStore.getState().timelinePps).toBeGreaterThan(100);
+  });
+
+  it("lays a pending pinch out at once when the timeline is pressed", () => {
+    const scroll = scrollBox(0);
+    mount({ scroll });
+    previewWheel(scroll, { ctrlKey: true });
+    expect(usePlayerStore.getState().timelinePps).toBe(100);
+    act(() => {
+      scroll.dispatchEvent(new Event("pointerdown"));
+    });
+    expect(usePlayerStore.getState().timelinePps).toBeGreaterThan(100);
+  });
+
+  it("keeps the time under the pointer in place as a pinch lays out", () => {
+    // Zoomed to 150%, so a 300px scroll is one the content allows.
+    usePlayerStore.setState({ manualZoomPercent: 150, timelinePps: 150 });
+    const scroll = scrollBox(300);
+    mount({ scroll });
+    // Pointer 432px in: (300 + 432 - 32) / 150 s sits there before and after.
+    wheel(scroll, { ctrlKey: true });
+    const pps = usePlayerStore.getState().timelinePps;
+    expect(pps).toBeGreaterThan(150);
+    expect(ORIGIN + (700 / 150) * pps - scroll.scrollLeft).toBeCloseTo(432);
+  });
+});