@hyperframes/studio 0.8.90 → 0.8.92

package/src/player/components/timelineMultiDragPreview.ts

@@ -1,3 +1,7 @@
+import type { TimelineElement } from "../store/playerStore";
+import { clampToHostStart } from "../store/timelineElement";
+import { canMoveTimelineElement } from "./timelineAuthoredMoveTarget";
+
 /**
  * Pure geometry for the LIVE multi-selection drag preview.
  *
@@ -9,11 +13,11 @@
  * behind individually — the whole formation moves by one delta, spacing locked.
  *
  * That single delta is the GRABBED clip's `draggedPreviewStart − draggedOriginStart`.
- * The preview start is ALREADY group-clamped upstream (updateDraggedClipPreview
- * runs clampGroupMoveDelta before setting it), so this delta is the clamped delta:
+ * The preview start is ALREADY group-clamped upstream (computeDragPreview floors it
+ * at groupMoveFloor), so this delta is the clamped delta:
  * the instant any member would cross 0 the grabbed clip stops and every passenger
  * stops with it — the formation never deforms. On DROP the commit shifts every
- * selected clip by this same delta (see timelineClipDragCommit / useTimelineClipDrag).
+ * moving clip (resolveGroupMovers) by this same delta (see timelineClipDragCommit).
  *
  * Track changes apply to the grabbed clip only (mirroring the commit); passengers
  * keep their lanes, so only their x moves.
@@ -81,26 +85,23 @@ export function multiDragPassengerOffsetPx(
   return multiDragDeltaSeconds(input) * pps;
 }
 
-/**
- * Clamp a group move so the WHOLE selection moves as ONE rigid formation.
- *
- * The grabbed clip proposes a raw delta (its desired preview start minus its
- * origin start, after its own snapping). Applied naively, a passenger could be
- * pushed below 0 (or past any other member bound), and the commit's per-clip
- * `Math.max(0, …)` would then deform the formation — the grabbed clip out-runs
- * the group while a passenger sticks at the wall. This ports main's model
- * (useTimelineClipGroupDrag / clampTimelineGroupMoveDelta): the applied delta is
- * bounded by the MOST-CONSTRAINED member, so the grabbed clip STOPS the instant
- * any member hits 0 and the formation never deforms.
- *
- * `memberStarts` are the pre-drag starts of every selected clip (the grabbed clip
- * included). Only the lower bound (start ≥ 0) constrains a move; the timeline has
- * no fixed right wall (the composition grows on commit).
- */
-export function clampGroupMoveDelta(rawDelta: number, memberStarts: readonly number[]): number {
-  if (memberStarts.length === 0) return rawDelta;
-  // Leftmost member sets the floor: delta ≥ -min(start) keeps every start ≥ 0.
-  const minStart = Math.min(...memberStarts);
-  const minDelta = minStart === 0 ? 0 : -minStart; // avoid -0
-  return rawDelta < minDelta ? minDelta : rawDelta;
+/** The selected clips a group drag moves: a locked clip swept into the selection stays put.
+ *  Null when the grabbed clip is not part of a multi-selection. */
+export function resolveGroupMovers(
+  elements: readonly TimelineElement[],
+  selectedKeys: ReadonlySet<string> | null | undefined,
+  dragKey: string,
+): TimelineElement[] | null {
+  if (!selectedKeys || selectedKeys.size <= 1 || !selectedKeys.has(dragKey)) return null;
+  return elements.filter((e) => selectedKeys.has(e.key ?? e.id) && canMoveTimelineElement(e));
+}
+
+/** The lowest start the grabbed clip may take so the whole group moves rigidly and no clip
+ *  crosses its own floor, its host composition's start (the commit floors each one there). */
+export function groupMoveFloor(
+  grabbed: TimelineElement,
+  movers: readonly TimelineElement[],
+): number {
+  const room = Math.min(...[grabbed, ...movers].map((e) => e.start - clampToHostStart(e, 0)));
+  return grabbed.start - room;
 }

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

@@ -27,6 +27,7 @@ function inputs(overrides: Partial<TimelineMetaBuilderInputs> = {}): TimelineMet
       ref: vi.fn(),
       tabIndex: -1,
       labelMode: false,
+      contentOrigin: 80,
       zoomMode: "fit",
       onScroll: vi.fn(),
       onFocus: vi.fn(),

package/src/player/components/timelineProviderStateBuilders.ts

@@ -5,23 +5,26 @@ import type {
 } from "./TimelineProvider";
 import type { ResizingClipState } from "./useTimelineClipDrag";
 import type { DraggedClipState } from "./timelineClipDragTypes";
-import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import { resolveGroupMovers, type MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+import type { TimelineElement } from "../store/playerStore";
 
 export function resolveMultiDragPreview(
   draggedClip: DraggedClipState | null,
   selectedKeys: ReadonlySet<string>,
+  elements: readonly TimelineElement[],
 ): MultiDragPreviewInput | null {
-  // The dragged clip is a free ghost; selected companions follow the same
-  // clamped delta so the formation stays rigid at the lane boundary.
+  // The dragged clip is a free ghost; the clips that move with it follow the same
+  // clamped delta so the formation stays rigid. A locked selected clip stays put.
   if (!draggedClip?.started) return null;
   const draggedKey = getTimelineElementIdentity(draggedClip.element);
+  const movers = resolveGroupMovers(elements, selectedKeys, draggedKey);
   return {
     dragStarted: true,
     draggedKey,
     draggedOriginStart: draggedClip.element.start,
     draggedPreviewStart: draggedClip.previewStart,
-    selectedKeys,
+    selectedKeys: movers ? new Set(movers.map(getTimelineElementIdentity)) : selectedKeys,
   };
 }
 
@@ -46,9 +49,13 @@ type ContainerInputs = Omit<TimelineContainerProps, "className"> & {
 
 type ViewportInputs = Omit<
   TimelineViewportProps,
-  "className" | "data-timeline-scroll-viewport" | "data-timeline-auto-scroll-left-inset"
+  | "className"
+  | "data-timeline-scroll-viewport"
+  | "data-timeline-auto-scroll-left-inset"
+  | "data-timeline-content-origin"
 > & {
   labelMode: boolean;
+  contentOrigin: number;
   zoomMode: "fit" | "manual";
 };
 
@@ -69,7 +76,7 @@ export function buildTimelineMeta({
   labelColumnWidth,
   razorGuide,
 }: TimelineMetaBuilderInputs): TimelineMeta {
-  const { labelMode, zoomMode, ...viewportProps } = viewport;
+  const { labelMode, zoomMode, contentOrigin, ...viewportProps } = viewport;
   const containerClassName = `relative border-t select-none h-full overflow-hidden ${container.isDragOver ? container.accentClass : ""} ${container.activeTool === "razor" ? "cursor-crosshair" : container.shiftHeld ? "cursor-crosshair" : "cursor-default"}`;
   const viewportClassName = `${zoomMode === "fit" ? "overflow-x-hidden" : "overflow-x-auto"} overflow-y-auto h-full outline-hidden`;
   return {
@@ -87,6 +94,7 @@ export function buildTimelineMeta({
       ...viewportProps,
       "data-timeline-scroll-viewport": true,
       "data-timeline-auto-scroll-left-inset": labelMode ? labelColumnWidth : 0,
+      "data-timeline-content-origin": contentOrigin,
       className: viewportClassName,
     },
     razorGuide,

package/src/player/components/timelineShellMeta.tsx

@@ -0,0 +1,99 @@
+import type { MutableRefObject, PointerEvent } from "react";
+import type {
+  TimelineContainerProps,
+  TimelineMeta,
+  TimelineViewportProps,
+} from "./TimelineProvider";
+import {
+  buildTimelineMeta,
+  shouldIgnoreTimelinePointerDown,
+} from "./timelineProviderStateBuilders";
+import { TimelineRazorGuideOverlay } from "./TimelineRazorInteraction";
+import { LABEL_COL_W } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+
+type ViewportHandlers = Pick<
+  TimelineViewportProps,
+  "onDragOver" | "onDragLeave" | "onDrop" | "onPointerMove" | "onPointerUp" | "onPointerCancel"
+>;
+
+export interface TimelineShellMetaInputs {
+  isDragOver: boolean;
+  hasFileDrop: boolean;
+  drop: Pick<ViewportHandlers, "onDragOver" | "onDragLeave" | "onDrop">;
+  pointer: Pick<ViewportHandlers, "onPointerMove" | "onPointerUp" | "onPointerCancel"> & {
+    onPointerDown: TimelineViewportProps["onPointerDown"];
+  };
+  setContainerRef: TimelineContainerProps["ref"];
+  setScrollRef: TimelineViewportProps["ref"];
+  focusProps: Pick<TimelineViewportProps, "onFocus" | "onBlur">;
+  elementCount: number;
+  activeTool: string;
+  shiftHeld: boolean;
+  labelMode: boolean;
+  contentOrigin: number;
+  zoomMode: "fit" | "manual";
+  theme: Pick<TimelineTheme, "shellBackground" | "shellBorder">;
+  razor: {
+    razorGuideX: number | null;
+    updateRazorGuide: TimelineContainerProps["onMouseMove"];
+    clearRazorGuide: () => void;
+    splitAllAtPointer: (event: PointerEvent<HTMLDivElement>) => boolean;
+  };
+  lastScrollLeftRef: MutableRefObject<number>;
+  recordTimelineScroll: (scroll: HTMLDivElement) => void;
+  syncScrollViewport: (scroll: HTMLDivElement, isScrolling?: boolean) => void;
+}
+
+/** The timeline shell's container and scroll viewport props: drop, pointer, scroll and razor wiring. */
+export function buildTimelineShellMeta(input: TimelineShellMetaInputs): TimelineMeta {
+  const { drop, pointer, razor, theme, activeTool } = input;
+  return buildTimelineMeta({
+    emptyState: { isDragOver: input.isDragOver, onFileDrop: input.hasFileDrop, ...drop },
+    container: {
+      ref: input.setContainerRef,
+      "aria-label": "Timeline track view",
+      "data-timeline-element-count": input.elementCount,
+      isDragOver: input.isDragOver,
+      activeTool,
+      shiftHeld: input.shiftHeld,
+      accentClass: "ring-1 ring-inset ring-studio-accent/60",
+      onMouseMove: razor.updateRazorGuide,
+      onMouseLeave: razor.clearRazorGuide,
+      style: {
+        touchAction: "pan-x pan-y",
+        background: theme.shellBackground,
+        borderColor: theme.shellBorder,
+      },
+    },
+    viewport: {
+      ref: input.setScrollRef,
+      tabIndex: -1,
+      labelMode: input.labelMode,
+      contentOrigin: input.contentOrigin,
+      zoomMode: input.zoomMode,
+      onScroll: (e) => {
+        input.lastScrollLeftRef.current = e.currentTarget.scrollLeft;
+        input.recordTimelineScroll(e.currentTarget);
+        input.syncScrollViewport(e.currentTarget, true);
+      },
+      ...input.focusProps,
+      ...drop,
+      onPointerDown: (e) => {
+        if (shouldIgnoreTimelinePointerDown(e.target)) return;
+        if (razor.splitAllAtPointer(e)) return;
+        pointer.onPointerDown(e);
+      },
+      onPointerMove: pointer.onPointerMove,
+      onPointerUp: pointer.onPointerUp,
+      onPointerCancel: pointer.onPointerCancel,
+      onLostPointerCapture: pointer.onPointerCancel,
+    },
+    elementCount: input.elementCount,
+    labelColumnWidth: LABEL_COL_W,
+    razorGuide:
+      activeTool === "razor" && razor.razorGuideX !== null ? (
+        <TimelineRazorGuideOverlay x={razor.razorGuideX} />
+      ) : null,
+  });
+}

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

@@ -622,7 +622,7 @@ describe("expanded sub-comp children — lane scoping", () => {
   const child = (id: string, track: number, start: number, duration: number) =>
     el(id, track, start, duration, {
       sourceFile: "scene.html",
-      expandedParentStart: 5,
+      expandedHostKey: "host",
     });
 
   it("a child mirrors onto a SIBLING's lane and persists the sibling's AUTHORED track", () => {
@@ -630,7 +630,7 @@ describe("expanded sub-comp children — lane scoping", () => {
     // file) but sits elsewhere in time → its lane is free over t's span.
     const c1 = el("c1", 0.25, 20, 3, {
       sourceFile: "scene.html",
-      expandedParentStart: 5,
+      expandedHostKey: "host",
       authoredTrack: 2,
     });
     const c2 = child("c2", 0.5, 5, 5);

package/src/player/components/timelineZMirror.ts

@@ -102,7 +102,7 @@ function expandedChildAllowedLanes(
   element: TimelineElement,
   elements: TimelineElement[],
 ): ReadonlySet<number> | null {
-  if (element.expandedParentStart == null) return null;
+  if (element.expandedHostKey == null) return null;
   const selfKey = keyOf(element);
   return new Set(
     elements

package/src/player/components/useTimelineClipDrag.resize.test.tsx

@@ -513,9 +513,9 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
     const h = renderResizeHarness([a], [], { onSeek });
     h.startResize(a, "end");
     h.movePointer(50);
-    expect(onSeek).toHaveBeenLastCalledWith(3.5 - 1 / 30, { keepPlaying: true });
+    expect(onSeek).toHaveBeenLastCalledWith(3.5 - 1 / 30, { keepPlaying: true, follow: false });
     await h.dropPointer();
-    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true });
+    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true, follow: false });
     h.unmount();
   });
 
@@ -525,7 +525,7 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
     const h = renderResizeHarness([a], [], { onSeek });
     h.startResize(a, "start");
     h.movePointer(50);
-    expect(onSeek).toHaveBeenLastCalledWith(1.5, { keepPlaying: true });
+    expect(onSeek).toHaveBeenLastCalledWith(1.5, { keepPlaying: true, follow: false });
     h.unmount();
   });
 
@@ -545,7 +545,7 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
     h.movePointer(80);
     h.movePointer(120);
     await h.dropPointer();
-    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true });
+    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true, follow: false });
     h.unmount();
   });
 
@@ -571,7 +571,10 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
     const clip = h.getResizingClip()!;
     expect(clip.previewStart + clip.previewDuration).toBeCloseTo(3.1, 3);
     expect(clip).toMatchObject({ snapTime: null, snapType: null });
-    expect(onSeek).toHaveBeenLastCalledWith(expect.closeTo(3.1 - 1 / 30, 3), { keepPlaying: true });
+    expect(onSeek).toHaveBeenLastCalledWith(expect.closeTo(3.1 - 1 / 30, 3), {
+      keepPlaying: true,
+      follow: false,
+    });
     h.unmount();
   });
 });

package/src/player/components/useTimelineClipDrag.ts

@@ -66,7 +66,7 @@ interface UseTimelineClipDragInput {
   onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
   /** Seeks the preview; a trim shows the frame at its dragged edge. */
-  onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
+  onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;
   setShowPopover: (show: boolean) => void;
   /** Stable ref to the range selection setter — wired after mount to break circular dependency. */
   setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
@@ -311,6 +311,7 @@ export function useTimelineClipDrag({
         // and it only resumes playback if it was already playing.
         onSeekRef.current?.(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration), {
           keepPlaying: true,
+          follow: false,
         });
         publishResizingClip(
           resizingClipRef.current ? { ...resizingClipRef.current, started: true, ...v } : null,
@@ -361,7 +362,7 @@ export function useTimelineClipDrag({
     if (trimSeekOriginRef.current != null) {
       // Paused: put the playhead back. Playing: leave it, a backward jump would rewind live playback.
       if (!usePlayerStore.getState().isPlaying) {
-        onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true });
+        onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true, follow: false });
       }
       trimSeekOriginRef.current = null;
     }

package/src/player/components/useTimelineDragPreviewState.ts

@@ -0,0 +1,34 @@
+import { useCallback, useMemo } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import type { ResizingClipState } from "./useTimelineClipDrag";
+import {
+  resolveMultiDragPreview,
+  resolveResizingElementIds,
+} from "./timelineProviderStateBuilders";
+import { getTimelinePreviewElement } from "./timelineViewModel";
+import { resolveSnapGuide } from "./timelineSnapping";
+
+/** What the lanes draw for a live move or trim: the ghost, the clips riding along, the snap guide. */
+export function useTimelineDragPreviewState(
+  draggedClip: DraggedClipState | null,
+  resizingClip: ResizingClipState | null,
+  selectedElementIds: ReadonlySet<string>,
+  timelineElements: readonly TimelineElement[],
+) {
+  const getPreviewElement = useCallback(
+    (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
+    [resizingClip],
+  );
+  const multiDragPreview = useMemo(
+    () => resolveMultiDragPreview(draggedClip, selectedElementIds, timelineElements),
+    [draggedClip, selectedElementIds, timelineElements],
+  );
+  return {
+    resizingElementIds: resolveResizingElementIds(resizingClip),
+    getPreviewElement,
+    draggedElement: draggedClip?.element ?? null,
+    multiDragPreview,
+    snapGuide: resolveSnapGuide(draggedClip, resizingClip),
+  };
+}

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

@@ -1,12 +1,15 @@
 // @vitest-environment happy-dom
 
-import { act, createRef } from "react";
-import { createRoot } from "react-dom/client";
-import { describe, expect, it } from "vitest";
+import { act, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
+const ORIGIN = 32;
+
 function scrollBox(scrollLeft: number) {
   const el = document.createElement("div");
   let left = scrollLeft;
@@ -18,18 +21,34 @@ function scrollBox(scrollLeft: number) {
   return el;
 }
 
-function Harness({ pps, scroll }: { pps: number; scroll: HTMLDivElement }) {
+interface HarnessProps {
+  pps: number;
+  scroll: HTMLDivElement;
+  percent?: number;
+  dragging?: boolean;
+  zoomMode?: ZoomMode;
+}
+
+function Harness({
+  pps,
+  scroll,
+  percent = 100,
+  dragging = false,
+  zoomMode = "manual",
+}: HarnessProps) {
+  const scrollRef = useRef(scroll);
+  const durationRef = useRef(60);
   useTimelinePlayhead({
-    playheadRef: createRef(),
-    scrollRef: { current: scroll },
+    playheadRef: { current: document.createElement("div") },
+    scrollRef,
     ppsRef: { current: pps },
-    durationRef: { current: 60 },
-    isDragging: { current: false },
+    durationRef,
+    isDragging: { current: dragging },
     currentTime: 0,
-    zoomMode: "manual",
-    manualZoomPercent: 100,
-    zoomModeRef: { current: "manual" },
-    manualZoomPercentRef: { current: 100 },
+    zoomMode,
+    manualZoomPercent: percent,
+    zoomModeRef: { current: zoomMode },
+    manualZoomPercentRef: { current: percent },
     fitPps: pps,
     fitPpsRef: { current: pps },
     effectiveDuration: 60,
@@ -38,28 +57,198 @@ function Harness({ pps, scroll }: { pps: number; scroll: HTMLDivElement }) {
     elementsLength: 1,
     setZoomMode: () => {},
     setManualZoomPercent: () => {},
-    contentOrigin: 32,
+    contentOrigin: ORIGIN,
   });
   return null;
 }
 
-function zoom(scrollLeft: number, fromPps: number, toPps: number) {
-  const scroll = scrollBox(scrollLeft);
-  const host = document.createElement("div");
-  const root = createRoot(host);
-  act(() => root.render(<Harness pps={fromPps} scroll={scroll} />));
-  act(() => root.render(<Harness pps={toPps} scroll={scroll} />));
-  act(() => root.unmount());
-  return scroll.scrollLeft;
+const roots: Root[] = [];
+function mount(props: HarnessProps) {
+  const root = createRoot(document.createElement("div"));
+  roots.push(root);
+  act(() => root.render(<Harness {...props} />));
+  return (next: Partial<HarnessProps>, byPerson = false) =>
+    act(() => {
+      if (byPerson) usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
+      root.render(<Harness {...props} {...next} />);
+    });
 }
 
-describe("useTimelinePlayhead centre anchor", () => {
-  it("keeps a view at the start at the start when the scale changes", () => {
-    expect(zoom(0, 100, 114)).toBe(0);
+beforeEach(() => {
+  usePlayerStore.setState({ currentTime: 0, isPlaying: false, beatDragging: false });
+});
+afterEach(() => {
+  for (const root of roots.splice(0)) act(() => root.unmount());
+});
+
+/** Where the playhead at `time` sits inside the 800px viewport. */
+const onScreenX = (scroll: HTMLDivElement, time: number, pps: number) =>
+  ORIGIN + time * pps - scroll.scrollLeft;
+function expectVisible(scroll: HTMLDivElement, time: number, pps: number) {
+  const x = onScreenX(scroll, time, pps);
+  expect(x).toBeGreaterThanOrEqual(ORIGIN);
+  expect(x).toBeLessThanOrEqual(800);
+}
+
+describe("useTimelinePlayhead zoom anchor", () => {
+  it("keeps a view at the start at the start when the window resizes", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll })({ pps: 114 });
+    expect(scroll.scrollLeft).toBe(0);
   });
 
-  it("keeps the time at the viewport centre when the view is scrolled", () => {
+  it("keeps the time at the viewport centre when a scrolled window resizes", () => {
+    const scroll = scrollBox(400);
     // Centre time (400 + 400 - 32) / 100 = 7.68s lands at 32 + 7.68 * 200 - 400.
-    expect(zoom(400, 100, 200)).toBe(1168);
+    mount({ pps: 100, scroll })({ pps: 200 });
+    expect(scroll.scrollLeft).toBe(1168);
+  });
+
+  it("keeps a view at 00:00 on a resize even when the playhead is mid-film", () => {
+    usePlayerStore.setState({ currentTime: 6 });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll })({ pps: 150 });
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps the playhead where it is on screen when the toolbar zooms", () => {
+    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);
+    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);
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps the centre on a resize after a toolbar zoom that hit the zoom limit", () => {
+    usePlayerStore.setState({ currentTime: 6 });
+    const scroll = scrollBox(400);
+    const update = mount({ pps: 100, scroll });
+    update({}, true);
+    update({ pps: 200 });
+    expect(scroll.scrollLeft).toBe(1168);
+  });
+
+  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);
+    expectVisible(scroll, 30, 200);
+  });
+});
+
+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 });
+    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 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", () => {
+  it("scrolls a paused seek that lands off screen into view", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(30));
+    expectVisible(scroll, 30, 100);
+  });
+
+  it("leaves the view alone when a paused seek lands on screen, even past the follow line", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(7));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("scrolls back to the playhead when a person seeks to the time it already has", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(30));
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notifySeek(30));
+    expectVisible(scroll, 30, 100);
+  });
+
+  it("keeps a person's scroll when a reload republishes the seek rounded to a frame", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(12.3456));
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notify(Math.floor(12.3456 * 30) / 30));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps a person's scroll when a reload follows a keyboard pause", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => usePlayerStore.setState({ isPlaying: true }));
+    act(() => liveTime.notify(30));
+    act(() => {
+      usePlayerStore.getState().setCurrentTime(30.012);
+      usePlayerStore.setState({ isPlaying: false });
+    });
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notify(30.012));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps a person's scroll when a reload stops a reverse shuttle", () => {
+    usePlayerStore.setState({ currentTime: 30 });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => usePlayerStore.setState({ isPlaying: true }));
+    act(() => liveTime.notify(29));
+    act(() => liveTime.notify(20));
+    act(() => usePlayerStore.setState({ isPlaying: false }));
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notify(20));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("does not scroll while the playhead is being dragged", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, dragging: true });
+    act(() => liveTime.notifySeek(30));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("does not scroll while a beat is being dragged past the edge", () => {
+    usePlayerStore.setState({ beatDragging: true });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(30));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("does not scroll in Fit", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, zoomMode: "fit" });
+    act(() => liveTime.notifySeek(30));
+    expect(scroll.scrollLeft).toBe(0);
   });
 });