@hyperframes/studio 0.8.80 → 0.8.82

package/src/hooks/useTimelineDeleteOps.ts

@@ -5,11 +5,11 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback, useRef, type MutableRefObject, type RefObject } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
-import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import { saveServerRewriteWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { getTimelineElementLabel } from "../utils/studioHelpers";
 import { buildPatchTarget, removeIframeTimelineElements } from "./timelineEditingHelpers";
-import { captureDurationRollback, readFileContent } from "./timelineTimingSync";
+import { captureDurationRollback } from "./timelineTimingSync";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
 import {
@@ -100,71 +100,68 @@ export function useTimelineDeleteOps({
         (candidate) => (candidate.sourceFile || activeCompPath || "index.html") === targetPath,
       );
       try {
-        const originalContent = await readFileContent(pid, targetPath);
-
-        // Remove every selected element before saving once. The server rewrites
-        // the file per call, so `removedContent` after the last one holds them
-        // all — which is what makes this a single history entry, and a single
-        // undo, rather than one per clip.
-        let removedContent = originalContent;
-        for (const target of sameFile) {
-          const patchTarget = buildPatchTarget(target);
-          if (!patchTarget) {
-            throw new Error(`Timeline element ${target.id} is missing a patchable target`);
-          }
-
-          const removeResponse = await fetch(
-            buildProjectApiPath(
-              pid,
-              `/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
-            ),
-            {
-              method: "POST",
-              headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-              body: JSON.stringify({ target: patchTarget }),
-            },
-          );
-          if (!removeResponse.ok) {
-            throw new Error(`Failed to delete ${target.id} from ${targetPath}`);
-          }
-
-          const removeData = (await removeResponse.json()) as {
-            changed?: boolean;
-            content?: string;
-          };
-          if (typeof removeData.content === "string") removedContent = removeData.content;
-        }
-        // Content-driven duration: shrink the composition to the furthest
-        // remaining clip end, read from the post-removal SOURCE (raw
-        // data-duration), so deleting the last/longest clip removes trailing
-        // empty space. Measured from the source, not the store, whose
-        // durations are runtime-truncated.
-        const deleteContentEnd = furthestClipEndFromSource(removedContent);
-        const patchedContent = setCompositionDurationToContent(removedContent, deleteContentEnd);
-        // Optimistically reflect the shrunk length in the readout/seek bar,
-        // rolling it back if the persist below fails (see captureDurationRollback).
-        const rollbackDuration = captureDurationRollback(previewIframeRef.current);
-        if (deleteContentEnd > 0 && targetPath === (activeCompPath || "index.html")) {
-          usePlayerStore.getState().setDuration(deleteContentEnd);
-        }
-
         // Shared with the ripple move below so a folded ripple is one undo
         // step with the delete, not two (editHistory.ts coalesces by key +
         // window across separate recordEdit calls, not by label).
         const coalesceKey = `main-track-ripple-delete:${deleteGestureSeq++}`;
         const deleteHistoryLabel = "Delete timeline clip";
+        let rollbackDuration = () => {};
         try {
-          await saveProjectFilesWithHistory({
+          await saveServerRewriteWithHistory({
             projectId: pid,
+            path: targetPath,
             label: deleteHistoryLabel,
             coalesceKey,
-            files: { [targetPath]: patchedContent },
-            readFile: async () => originalContent,
-            // remove-element already wrote the removal, so disk holds THAT — not the
-            // content read at the top. Undo still goes back to the original.
-            diskContent: { [targetPath]: removedContent },
             writeFile: writeProjectFile,
             recordEdit,
+            rewrite: async (originalContent) => {
+              // Remove every selected element before saving once. The server rewrites
+              // the file per call, so `removedContent` after the last one holds them
+              // all — which is what makes this a single history entry, and a single
+              // undo, rather than one per clip.
+              let removedContent = originalContent;
+              for (const target of sameFile) {
+                const patchTarget = buildPatchTarget(target);
+                if (!patchTarget) {
+                  throw new Error(`Timeline element ${target.id} is missing a patchable target`);
+                }
+
+                const removeResponse = await fetch(
+                  buildProjectApiPath(
+                    pid,
+                    `/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+                  ),
+                  {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
+                    body: JSON.stringify({ target: patchTarget }),
+                  },
+                );
+                if (!removeResponse.ok) {
+                  throw new Error(`Failed to delete ${target.id} from ${targetPath}`);
+                }
+
+                const removeData = (await removeResponse.json()) as {
+                  changed?: boolean;
+                  content?: string;
+                };
+                if (typeof removeData.content === "string") removedContent = removeData.content;
+              }
+              // Shrink to the furthest remaining clip end, read from the post-removal source:
+              // store durations are runtime-truncated.
+              const deleteContentEnd = furthestClipEndFromSource(removedContent);
+              const patchedContent = setCompositionDurationToContent(
+                removedContent,
+                deleteContentEnd,
+              );
+              // Optimistically reflect the shrunk length in the readout/seek bar,
+              // rolling it back if the persist below fails (see captureDurationRollback).
+              rollbackDuration = captureDurationRollback(previewIframeRef.current);
+              if (deleteContentEnd > 0 && targetPath === (activeCompPath || "index.html")) {
+                usePlayerStore.getState().setDuration(deleteContentEnd);
+              }
+              return { disk: removedContent, after: patchedContent };
+            },
           });
         } catch (error) {
           rollbackDuration();

package/src/hooks/useTimelineEditing.ts

@@ -8,7 +8,6 @@ import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
 import {
   applyTimelineStackingReorder,
   patchIframeDomTiming,
-  playbackStartAttributeForElement,
   persistTimelineEdit,
   formatTimelineAttributeNumber,
   formatTimelineMediaOffset,
@@ -16,6 +15,7 @@ import {
   buildTimelineMoveTimingPatch,
   buildTimelineResizeTimingPatch,
 } from "./timelineEditingHelpers";
+import { playbackStartAttributeForElement } from "../player/lib/timelineElementHelpers";
 import {
   captureDurationRollback,
   finishClipTimingFallback,
@@ -243,6 +243,7 @@ export function useTimelineEditing({
             label: "Move timeline clip",
             coalesceKey,
             recordEdit,
+            writeProjectFile,
             edit: { kind: "shift", delta: updates.start - element.start },
           }).finally(() => invalidateGsapCache?.());
         const moveFallback = () =>
@@ -346,6 +347,7 @@ export function useTimelineEditing({
           label: "Resize timeline clip",
           coalesceKey,
           recordEdit,
+          writeProjectFile,
           edit: {
             kind: "scale",
             from: { start: element.start, duration: element.duration },

package/src/hooks/useTimelineGroupEditing.ts

@@ -15,11 +15,11 @@ import {
   formatTimelineAttributeNumber,
   formatTimelineMediaOffset,
   patchIframeDomTiming,
-  playbackStartAttributeForElement,
   persistTimelineBatchEdit,
   type PersistTimelineBatchChange,
   type RecordEditInput,
 } from "./timelineEditingHelpers";
+import { playbackStartAttributeForElement } from "../player/lib/timelineElementHelpers";
 import {
   captureDurationRollback,
   finishGroupTimingGsapFallback,
@@ -330,6 +330,7 @@ export function useTimelineGroupEditing({
             errorLabel: "Failed to shift GSAP positions",
             coalesceKey,
             recordEdit,
+            writeProjectFile,
             activeCompPath,
             changes,
             resolveChangePath: (element) => targetPathFor(element, activeCompPath),
@@ -365,6 +366,7 @@ export function useTimelineGroupEditing({
       trySdkBatchPersist,
       showToast,
       invalidateGsapCache,
+      writeProjectFile,
     ],
   );
 
@@ -437,6 +439,7 @@ export function useTimelineGroupEditing({
             errorLabel: "Failed to scale GSAP positions",
             coalesceKey,
             recordEdit,
+            writeProjectFile,
             activeCompPath,
             changes,
             resolveChangePath: (element) => targetPathFor(element, activeCompPath),
@@ -478,6 +481,7 @@ export function useTimelineGroupEditing({
       trySdkBatchPersist,
       showToast,
       invalidateGsapCache,
+      writeProjectFile,
     ],
   );
 

package/src/index.ts

@@ -184,6 +184,14 @@ export type { TimelinePaneProps } from "./components/nle/TimelinePane";
 export { TimelineEditProvider } from "./contexts/TimelineEditContext";
 export type { TimelineEditCallbacks } from "./player/components/timelineCallbacks";
 export type { BlockedTimelineEditIntent } from "./player/components/timelineEditing";
+export { TimelineToolbar } from "./components/TimelineToolbar";
+export type { TimelineToolbarProps } from "./components/TimelineToolbar";
+export { TimelineHistoryButtons } from "./components/TimelineHistoryButtons";
+export type { TimelineHistoryButtonsProps } from "./components/TimelineHistoryButtons";
+export { AudioMeterStrip } from "./components/nle/AudioMeterStrip";
+export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
+export { useClipboard } from "./hooks/useClipboard";
+export type { UseClipboardOptions } from "./hooks/useClipboard";
 
 export {
   playSeamTransitionLoop,

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

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { buildCompositionThumbnailUrl, CompositionThumbnail } from "./CompositionThumbnail";
 
@@ -11,12 +12,6 @@ Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
   value: true,
 });
 
-class MockResizeObserver {
-  observe() {}
-  disconnect() {}
-  unobserve() {}
-}
-
 class MockImage {
   static instances: MockImage[] = [];
   onload: (() => void) | null = null;
@@ -146,6 +141,45 @@ describe("CompositionThumbnail", () => {
     );
   });
 
+  it.each([
+    { name: "a wide", width: 2700, height: 1000, tileWidth: 108 },
+    { name: "a square", width: 1000, height: 1000, tileWidth: 48 },
+    { name: "a portrait", width: 1080, height: 1920, tileWidth: 48 },
+  ])(
+    "shows $name picture whole at the clip's measured height",
+    async ({ width, height, tileWidth }) => {
+      Object.defineProperty(host, "clientWidth", { configurable: true, value: 500 });
+      Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+      const probe = await renderThumbnail();
+
+      await act(async () => {
+        probe.naturalWidth = width;
+        probe.naturalHeight = height;
+        probe.onload?.();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+
+      const img = host.querySelector("img")!;
+      expect(img.parentElement?.style.width).toBe(`${tileWidth}px`);
+      // A tile held at its minimum width letterboxes the picture instead of cropping it.
+      expect(img.classList.contains("object-contain")).toBe(true);
+    },
+  );
+
+  it("re-tiles at the height the resize observer reports", async () => {
+    const probe = await renderThumbnail();
+    await act(async () => {
+      probe.naturalWidth = 2700;
+      probe.naturalHeight = 1000;
+      probe.onload?.();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    act(() => reportResize(500, 40));
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
   it("aborts its scheduled off-DOM image probe when unmounted", async () => {
     const probe = await renderThumbnail();
     expect(host.querySelector("img")).toBeNull();

package/src/player/components/CompositionThumbnail.tsx

@@ -1,6 +1,6 @@
-import { memo, useCallback, useMemo, useRef, useState, type CSSProperties } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
+import { memo, useMemo, type CSSProperties } from "react";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
 import { computeThumbnailStrip, probeImageAspect } from "./thumbnailUtils";
@@ -22,7 +22,6 @@ interface CompositionThumbnailProps {
   rich?: boolean;
 }
 
-const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v3";
 export const THUMBNAIL_SEEK_TIME_SECONDS = 3;
 
@@ -122,8 +121,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   contentRevision = 0,
   priority = "visible",
 }: CompositionThumbnailProps) {
-  const [containerWidth, setContainerWidth] = useState(0);
-  const observerRef = useRef<ResizeObserver | null>(null);
+  const [container, setContainerRef] = useThumbnailStripSize();
   const url = buildCompositionThumbnailUrl({
     previewUrl,
     seekTime,
@@ -149,25 +147,12 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   const value =
     snapshot.status === "ready" && snapshot.value.kind === "image" ? snapshot.value : null;
   const { frameW, frameCount } = computeThumbnailStrip(
-    containerWidth,
+    container.width,
     value?.aspect ?? 16 / 9,
-    CLIP_HEIGHT,
+    container.height,
     48,
   );
 
-  const setContainerRef = useCallback((element: HTMLDivElement | null) => {
-    observerRef.current?.disconnect();
-    if (!element) return;
-    const target = element.parentElement ?? element;
-    setContainerWidth(target.clientWidth);
-    observerRef.current = new ResizeObserver(([entry]) =>
-      setContainerWidth(entry.contentRect.width),
-    );
-    observerRef.current.observe(target);
-  }, []);
-
-  useMountEffect(() => () => observerRef.current?.disconnect());
-
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
       {value && (
@@ -189,7 +174,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
                 src={value.url}
                 alt=""
                 draggable={false}
-                className="absolute inset-0 h-full w-full object-cover"
+                className="absolute inset-0 h-full w-full object-contain"
                 style={{ opacity: "var(--timeline-composition-thumbnail-opacity)" }}
               />
             </div>

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

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { ImageThumbnail } from "./ImageThumbnail";
 
@@ -30,12 +31,6 @@ class MockIntersectionObserver {
   }
 }
 
-class MockResizeObserver {
-  observe() {}
-  disconnect() {}
-  unobserve() {}
-}
-
 // --- Image stub: captures instances so tests fire load/error deterministically ---
 class MockImage {
   static instances: MockImage[] = [];
@@ -171,6 +166,32 @@ describe("ImageThumbnail", () => {
     expect(host.querySelector(".animate-pulse")).toBeNull();
   });
 
+  it("tiles a wide picture at the clip's measured height, whole", async () => {
+    Object.defineProperty(host, "clientWidth", { configurable: true, value: 500 });
+    Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+    render({ imageSrc: "/api/projects/p/preview/assets/wide.png" });
+    await resolveProbe((probe) => {
+      probe.naturalWidth = 2700;
+      probe.naturalHeight = 1000;
+      probe.onload?.();
+    });
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
+  it("re-tiles at the height the resize observer reports", async () => {
+    render({ imageSrc: "/api/projects/p/preview/assets/wide.png" });
+    await resolveProbe((probe) => {
+      probe.naturalWidth = 2700;
+      probe.naturalHeight = 1000;
+      probe.onload?.();
+    });
+
+    act(() => reportResize(500, 40));
+
+    expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
+  });
+
   it("renders the label above the strip when provided", async () => {
     render({ imageSrc: "/x.png", label: "hero", labelColor: "#abc" });
     await resolveProbe((probe) => {

package/src/player/components/ImageThumbnail.tsx

@@ -1,6 +1,6 @@
-import { memo, useCallback, useMemo, useRef, useState } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
+import { memo, useMemo } from "react";
 import { useThumbnailLease } from "../../hooks/useThumbnailLease";
+import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decodeImageThumbnail } from "../lib/thumbnailImageDecoder";
 import { computeThumbnailStrip } from "./thumbnailUtils";
@@ -25,8 +25,7 @@ export const ImageThumbnail = memo(function ImageThumbnail({
   priority = "visible",
   rich = false,
 }: ImageThumbnailProps) {
-  const [containerWidth, setContainerWidth] = useState(0);
-  const observerRef = useRef<ResizeObserver | null>(null);
+  const [container, setContainerRef] = useThumbnailStripSize();
   const request = useMemo(
     () => ({
       key: createThumbnailKey({ kind: "image", source: imageSrc, rich: Number(rich) }),
@@ -42,20 +41,7 @@ export const ImageThumbnail = memo(function ImageThumbnail({
   const snapshot = useThumbnailLease(request);
   const value = snapshot.status === "ready" ? snapshot.value : null;
   const aspect = value?.kind === "image" ? value.aspect : 16 / 9;
-  const { frameW, frameCount } = computeThumbnailStrip(containerWidth, aspect);
-
-  const setContainerRef = useCallback((element: HTMLDivElement | null) => {
-    observerRef.current?.disconnect();
-    if (!element) return;
-    const target = element.parentElement ?? element;
-    setContainerWidth(target.clientWidth);
-    observerRef.current = new ResizeObserver(([entry]) =>
-      setContainerWidth(entry.contentRect.width),
-    );
-    observerRef.current.observe(target);
-  }, []);
-
-  useMountEffect(() => () => observerRef.current?.disconnect());
+  const { frameW, frameCount } = computeThumbnailStrip(container.width, aspect, container.height);
 
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">

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

@@ -0,0 +1,52 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import { PlayerControls } from "./PlayerControls";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let host: HTMLDivElement;
+let root: Root;
+
+beforeEach(async () => {
+  usePlayerStore.setState({
+    isPlaying: true,
+    currentTime: 2,
+    duration: 30,
+    timeDisplayMode: "time",
+  });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () =>
+    root.render(React.createElement(PlayerControls, { onTogglePlay: () => {}, onSeek: () => {} })),
+  );
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+});
+
+describe("PlayerControls timecode", () => {
+  it("rewrites the timecode only when the shown text changes", async () => {
+    const timecode = host.querySelector("button.font-mono > span");
+    expect(timecode?.textContent).toBe("00:02");
+    const writes: MutationRecord[] = [];
+    const observer = new MutationObserver((records) => writes.push(...records));
+    observer.observe(timecode as Node, { childList: true, characterData: true, subtree: true });
+
+    for (let frame = 1; frame <= 30; frame++) liveTime.notify(2 + frame / 120);
+    await Promise.resolve();
+    expect(writes).toHaveLength(0);
+
+    liveTime.notify(3.01);
+    await Promise.resolve();
+    expect(timecode?.textContent).toBe("00:03");
+    expect(writes.length).toBeGreaterThan(0);
+    observer.disconnect();
+  });
+});

package/src/player/components/PlayerControls.tsx

@@ -213,10 +213,11 @@ export const PlayerControls = memo(function PlayerControls({
       currentTimeRef.current = time;
       if (!timeDisplayRef.current) return;
       const currentDuration = durationRef.current;
-      timeDisplayRef.current.textContent =
+      const text =
         timeDisplayModeRef.current === "frame"
           ? formatFrameTime(time, currentDuration)
           : formatTime(time);
+      if (timeDisplayRef.current.textContent !== text) timeDisplayRef.current.textContent = text;
     };
     const unsubscribe = liveTime.subscribe(updateTime);
     updateTime(usePlayerStore.getState().currentTime);

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

@@ -39,7 +39,7 @@ import {
 } from "./timelineLayout";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { formatTime } from "../lib/time";
-import { usePlayerStore } from "../store/playerStore";
+import { liveTime, usePlayerStore } from "../store/playerStore";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
 
 vi.mock("./timelineRowVirtualizationFlag", () => ({
@@ -153,6 +153,27 @@ function renderSharedAutomationTimeline(selectedElementId?: string) {
   return { host, root };
 }
 
+describe("Timeline playhead motion", () => {
+  it("moves by fractional pixels while playing and snaps to device pixels once paused", () => {
+    usePlayerStore.setState({
+      duration: 11,
+      timelineReady: true,
+      currentTime: 10,
+      isPlaying: true,
+      zoomMode: "manual",
+      manualZoomPercent: 100,
+      elements: [{ id: "clip-1", tag: "div", start: 10, duration: 1, track: 0 }],
+    });
+    const { root, playhead } = renderTimelineGeometry("clip-1");
+    const wrapperLeft = GUTTER + TRACKS_LEFT_PAD + 1000.3 - PLAYHEAD_HEAD_W / 2;
+    act(() => liveTime.notify(10.003));
+    expect(playhead.style.transform).toBe(`translateX(${wrapperLeft}px)`);
+    act(() => usePlayerStore.setState({ isPlaying: false }));
+    expect(playhead.style.transform).toBe(`translateX(${Math.round(wrapperLeft)}px)`);
+    act(() => root.unmount());
+  });
+});
+
 describe("Timeline provider boundary", () => {
   it("keeps all-collapsed horizontal positions at the gutter plus the pre-t=0 pad", () => {
     usePlayerStore.setState({
@@ -173,7 +194,9 @@ describe("Timeline provider boundary", () => {
     expect(clip.style.bottom).toBe(`${CLIP_Y}px`);
     expect(rulerOrigin.style.width).toBe(`${GUTTER + TRACKS_LEFT_PAD}px`);
     expect(rulerTick.style.left).toBe("999.5px");
-    expect(playhead.style.left).toBe(`${GUTTER + TRACKS_LEFT_PAD + 1000 - PLAYHEAD_HEAD_W / 2}px`);
+    expect(playhead.style.transform).toBe(
+      `translateX(${Math.round(GUTTER + TRACKS_LEFT_PAD + 1000 - PLAYHEAD_HEAD_W / 2)}px)`,
+    );
     expect(playhead.style.width).toBe(`${PLAYHEAD_HEAD_W}px`);
     expect(
       resolveTimelineAssetDrop(
@@ -283,7 +306,9 @@ describe("Timeline provider boundary", () => {
     expect(semanticRows[2]?.hasAttribute("aria-expanded")).toBe(false);
     expect(trackHeader.style.width).toBe(`${LABEL_COL_W}px`);
     expect(rulerOrigin.style.width).toBe(`${LABEL_COL_W + GUTTER}px`);
-    expect(playhead.style.left).toBe(`${LABEL_COL_W + GUTTER + 1000 - PLAYHEAD_HEAD_W / 2}px`);
+    expect(playhead.style.transform).toBe(
+      `translateX(${Math.round(LABEL_COL_W + GUTTER + 1000 - PLAYHEAD_HEAD_W / 2)}px)`,
+    );
     expect(diamondX).toBe(rulerX);
     expect(rulerX).toBe(LABEL_COL_W + GUTTER + 1000);
     expect(collapsedHeader.textContent).toContain("Outro");

package/src/player/components/TimelineCanvas.tsx

@@ -9,10 +9,10 @@ import {
   TRACKS_BOTTOM_PAD,
   TRACK_H,
   PLAYHEAD_HEAD_W,
-  getTimelinePlayheadLeft,
   getTimelineRowTop,
   getTimelineRowHeight,
 } from "./timelineLayout";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { TimelineLanes } from "./TimelineLanes";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
 import { useTimelineContext } from "./TimelineProvider";
@@ -234,7 +234,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
 
       {/* Playhead — hidden while dragging a beat so its guideline doesn't
           track the scrub and clutter the beat being moved. Explicit width +
-          the half-head offset baked into getTimelinePlayheadLeft keep the
+          the half-head offset baked into getTimelinePlayheadTransform keep the
           inner 1px line's CENTER exactly on contentOrigin + t * pps (the ruler
           ticks' center), instead of relying on shrink-wrap sizing. */}
       <TimelinePlayheadLayer scrollRef={props.scrollRef} contentOrigin={props.contentOrigin}>
@@ -242,7 +242,9 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           ref={props.playheadRef}
           className="absolute top-0 bottom-0 pointer-events-none"
           style={{
-            left: `${getTimelinePlayheadLeft(0, 0, props.contentOrigin)}px`,
+            left: 0,
+            transform: getTimelinePlayheadTransform(0, 0, props.contentOrigin, true),
+            willChange: "transform",
             width: PLAYHEAD_HEAD_W,
             display: beatDragging ? "none" : undefined,
           }}