@hyperframes/studio 0.8.73 → 0.8.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.73",
+  "version": "0.8.75",
   "description": "",
   "repository": {
     "type": "git",
@@ -52,11 +52,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.73",
-    "@hyperframes/sdk": "0.8.73",
-    "@hyperframes/player": "0.8.73",
-    "@hyperframes/studio-server": "0.8.73",
-    "@hyperframes/parsers": "0.8.73"
+    "@hyperframes/core": "0.8.75",
+    "@hyperframes/player": "0.8.75",
+    "@hyperframes/parsers": "0.8.75",
+    "@hyperframes/sdk": "0.8.75",
+    "@hyperframes/studio-server": "0.8.75"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -72,7 +72,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.73"
+    "@hyperframes/producer": "0.8.75"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/timelineEditingHelpers.ts

@@ -182,6 +182,17 @@ export function patchIframeDomTiming(
   }
 }
 
+/** Takes deleted clips out of the live preview at once: until the reload lands, anything that re-reads the
+ *  preview (composition enrichment) would otherwise put them back on the timeline. */
+export function removeIframeTimelineElements(
+  iframe: HTMLIFrameElement | null,
+  elements: TimelineElement[],
+  activeCompositionPath: string | null = null,
+): void {
+  for (const element of elements)
+    findTimelineElementInIframe(iframe, element, activeCompositionPath)?.remove();
+}
+
 export function playbackStartAttributeForElement(
   element: Pick<TimelineElement, "kind" | "playbackStartAttr">,
 ): "data-media-start" | "data-playback-start" {

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -2,7 +2,7 @@
 
 import { act } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { TimelineElement } from "../player";
+import { usePlayerStore, type TimelineElement } from "../player";
 import { applyRippleShifts, useTimelineDeleteOps } from "./useTimelineDeleteOps";
 import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
@@ -78,9 +78,30 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
       return null;
     }
     mountReactHarness(<Harness />);
-    return { b: elements[1], getHook: () => hook! };
+    return { elements, b: elements[1], getHook: () => hook! };
   }
 
+  it("drops the deleted clip from the timeline while the ripple is still saving", async () => {
+    let finishRipple = () => {};
+    const handleTimelineGroupMove = vi.fn(
+      () => new Promise<void>((resolve) => (finishRipple = resolve)),
+    );
+    const { elements, b, getHook } = mountDeleteHarness({ handleTimelineGroupMove });
+    usePlayerStore.getState().setElements(elements);
+
+    let deleting = Promise.resolve();
+    await act(async () => {
+      deleting = getHook().handleTimelineElementDelete(b);
+      await vi.waitFor(() => expect(handleTimelineGroupMove).toHaveBeenCalled());
+    });
+    expect(usePlayerStore.getState().elements.map((e) => e.id)).toEqual(["hf-a", "hf-c"]);
+
+    await act(async () => {
+      finishRipple();
+      await deleting;
+    });
+  });
+
   // editHistory.ts's coalescing keeps the LAST recordEdit call's label, so the
   // folded ripple move must carry the delete's label, not its own.
   it("passes the delete's own label to the folded ripple move, not 'Move timeline clips'", async () => {
@@ -228,3 +249,65 @@ describe("useTimelineDeleteOps: undo race", () => {
     });
   });
 });
+
+// Regression: the live preview kept a deleted clip until its reload landed, and composition
+// enrichment re-read it from there, so the clip stayed drawn after the file dropped it.
+describe("useTimelineDeleteOps: live preview", () => {
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-composition-id="main" data-duration="4">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+</div>
+</body></html>`;
+
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(JSON.stringify({ changed: true, content: html }))),
+    );
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+  });
+
+  it("takes the deleted clip out of the live preview before its reload", async () => {
+    const preview = document.implementation.createHTMLDocument();
+    preview.documentElement.innerHTML = html;
+    const iframe = { contentDocument: preview } as unknown as HTMLIFrameElement;
+    const clip = (id: string, start: number): TimelineElement => ({
+      id,
+      tag: "div",
+      start,
+      duration: 2,
+      track: 0,
+      hfId: id,
+      sourceFile: "index.html",
+    });
+    const elements = [clip("hf-a", 0), clip("hf-b", 2)];
+    let hook: ReturnType<typeof useTimelineDeleteOps> | null = null;
+    function Harness() {
+      hook = useTimelineDeleteOps({
+        projectIdRef: { current: "test-project" },
+        activeCompPath: "index.html",
+        timelineElements: elements,
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        recordEdit: vi.fn().mockResolvedValue(undefined),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: iframe },
+        handleTimelineGroupMove: vi.fn().mockResolvedValue(undefined),
+      });
+      return null;
+    }
+    mountReactHarness(<Harness />);
+
+    await act(async () => {
+      await hook!.handleTimelineElementDelete(elements[1]);
+    });
+
+    expect(preview.querySelector('[data-hf-id="hf-b"]')).toBeNull();
+    expect(preview.querySelector('[data-hf-id="hf-a"]')).not.toBeNull();
+  });
+});

package/src/hooks/useTimelineDeleteOps.ts

@@ -8,7 +8,7 @@ import { usePlayerStore } from "../player";
 import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { getTimelineElementLabel } from "../utils/studioHelpers";
-import { buildPatchTarget } from "./timelineEditingHelpers";
+import { buildPatchTarget, removeIframeTimelineElements } from "./timelineEditingHelpers";
 import { captureDurationRollback, readFileContent } from "./timelineTimingSync";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
@@ -172,6 +172,7 @@ export function useTimelineDeleteOps({
           throw error;
         }
 
+        removeIframeTimelineElements(previewIframeRef.current, sameFile, activeCompPath);
         const deletedKeys = new Set(sameFile.map((te) => te.key ?? te.id));
         const survivors = timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id));
 
@@ -184,10 +185,11 @@ export function useTimelineDeleteOps({
           sameFile,
           usePlayerStore.getState().rippleEditEnabled,
         );
-        let rippleApplied: TimelineGroupMoveChange[] | null = null;
+        const rippleChanges = rippleShifts ? resolveShiftedElements(survivors, rippleShifts) : null;
+        // The timeline follows the delete's write at once, as the owner of the ripple's optimistic update.
+        usePlayerStore.getState().setElements(applyRippleShifts(survivors, rippleChanges));
         let rippleFailed = false;
-        if (rippleShifts) {
-          const rippleChanges = resolveShiftedElements(survivors, rippleShifts);
+        if (rippleChanges) {
           try {
             await handleTimelineGroupMove(rippleChanges, {
               coalesceKey,
@@ -200,18 +202,17 @@ export function useTimelineDeleteOps({
               // the generic one would tell the user about one action twice.
               suppressFailureToast: true,
             });
-            rippleApplied = rippleChanges;
           } catch (error) {
             // The delete already committed; a failed ripple leaves the gap the
             // toggle-off behaviour would have left anyway — not worth undoing
             // an otherwise-successful delete over.
             rippleFailed = true;
+            usePlayerStore.getState().setElements(survivors);
             console.error("[Timeline] ripple-edit failed to persist after delete", error);
             showToast("Clip deleted, but the gap could not be closed.", "error");
           }
         }
 
-        usePlayerStore.getState().setElements(applyRippleShifts(survivors, rippleApplied));
         usePlayerStore.getState().setSelectedElementId(null);
         usePlayerStore.getState().setSelectedElementIds(new Set());
         forceReloadSdkSession?.();
@@ -224,7 +225,7 @@ export function useTimelineDeleteOps({
             "info",
           );
         }
-        if (rippleApplied && !rippleNoticeShownRef.current) {
+        if (rippleChanges && !rippleFailed && !rippleNoticeShownRef.current) {
           rippleNoticeShownRef.current = true;
           showToast(
             "Ripple closed the gap on the main track. Undo (⌘Z) restores it, or turn off " +

package/src/player/components/PlayheadIndicator.tsx

@@ -11,6 +11,9 @@
  */
 import { PLAYHEAD_HEAD_W } from "./timelineLayout";
 
+/** Widest part of the playhead, centred on its line. */
+export const PLAYHEAD_GLOW_W = 13;
+
 interface PlayheadIndicatorProps {
   /** CSS color, defaults to the HF accent variable */
   color?: string;
@@ -50,7 +53,7 @@ export function PlayheadIndicator({
         className="absolute top-0 bottom-0"
         style={{
           left: "50%",
-          width: 13,
+          width: PLAYHEAD_GLOW_W,
           transform: "translateX(-50%)",
           background: `radial-gradient(closest-side, ${glowColor}, transparent)`,
         }}

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

@@ -88,9 +88,7 @@ function getHorizontalGeometry(host: HTMLElement, clipId: string, tickLabel: str
   if (!ruler) throw new Error("Missing timeline ruler");
   const rulerOrigin = ruler.previousElementSibling;
   if (!(rulerOrigin instanceof HTMLElement)) throw new Error("Missing timeline ruler origin");
-  const playhead = Array.from(host.querySelectorAll<HTMLElement>("div")).find(
-    (node) => node.style.zIndex === "100",
-  );
+  const playhead = host.querySelector<HTMLElement>("[data-timeline-playhead-layer] > div");
   if (!playhead) throw new Error("Missing timeline playhead");
   return { clip, trackHeader, rulerTick, rulerOrigin, playhead };
 }

package/src/player/components/Timeline.virtualization.test.tsx

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
 
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -430,6 +431,26 @@ describe("Timeline without row virtualization", { timeout: 30_000 }, () => {
     };
   }
 
+  it("clips a scrolled-off playhead at the track headers once the scroll settles", async () => {
+    const { host, dispose } = await renderUnvirtualizedTimeline();
+    try {
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]")!;
+      const layer = () => host.querySelector<HTMLElement>("[data-timeline-playhead-layer]");
+      await scrollTimelineHorizontally(scroller, 166);
+      expect(layer()?.style.clipPath).toBe("");
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, TIMELINE_SCROLL_SETTLE_MS + 20));
+      });
+      // The ruler's corner is as wide as the track headers; the glow may overhang by 6.5px.
+      const headerWidth = parseFloat(
+        host.querySelector<HTMLElement>(".sticky.left-0")!.style.width,
+      );
+      expect(layer()?.style.clipPath).toContain(`${166 + headerWidth - 6.5}px)`);
+    } finally {
+      dispose();
+    }
+  });
+
   it("mounts every clip rather than a window", async () => {
     const { host, dispose } = await renderUnvirtualizedTimeline();
     try {

package/src/player/components/TimelineCanvas.tsx

@@ -1,6 +1,7 @@
 import { memo } from "react";
 import { TimelineRulerPart } from "./TimelineRulerPart";
 import { PlayheadIndicator } from "./PlayheadIndicator";
+import { TimelinePlayheadLayer } from "./TimelinePlayheadLayer";
 import {
   RULER_H,
   CLIP_Y,
@@ -236,18 +237,19 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           the half-head offset baked into getTimelinePlayheadLeft keep the
           inner 1px line's CENTER exactly on contentOrigin + t * pps (the ruler
           ticks' center), instead of relying on shrink-wrap sizing. */}
-      <div
-        ref={props.playheadRef}
-        className="absolute top-0 bottom-0 pointer-events-none"
-        style={{
-          left: `${getTimelinePlayheadLeft(0, 0, props.contentOrigin)}px`,
-          width: PLAYHEAD_HEAD_W,
-          zIndex: 100,
-          display: beatDragging ? "none" : undefined,
-        }}
-      >
-        <PlayheadIndicator scrubbing={props.isScrubbing} />
-      </div>
+      <TimelinePlayheadLayer scrollRef={props.scrollRef} contentOrigin={props.contentOrigin}>
+        <div
+          ref={props.playheadRef}
+          className="absolute top-0 bottom-0 pointer-events-none"
+          style={{
+            left: `${getTimelinePlayheadLeft(0, 0, props.contentOrigin)}px`,
+            width: PLAYHEAD_HEAD_W,
+            display: beatDragging ? "none" : undefined,
+          }}
+        >
+          <PlayheadIndicator scrubbing={props.isScrubbing} />
+        </div>
+      </TimelinePlayheadLayer>
     </div>
   );
 });

package/src/player/components/TimelinePlayheadLayer.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode, RefObject } from "react";
+import { PLAYHEAD_GLOW_W } from "./PlayheadIndicator";
+import { useSettledScrollLeft } from "./useSettledScrollLeft";
+
+// Clips the playhead at the track headers' edge once a scroll settles, so one scrolled off to
+// the left does not draw over the track names. Half the glow may pass the edge so 00:00 looks
+// as before; mid-scroll it is not clipped.
+export function TimelinePlayheadLayer({
+  scrollRef,
+  contentOrigin,
+  children,
+}: {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  contentOrigin: number;
+  children: ReactNode;
+}) {
+  const settledScrollLeft = useSettledScrollLeft(scrollRef);
+  return (
+    <div
+      data-timeline-playhead-layer=""
+      className="absolute inset-0 pointer-events-none"
+      style={{
+        zIndex: 100,
+        clipPath:
+          settledScrollLeft === null
+            ? undefined
+            : `inset(0 0 0 ${settledScrollLeft + contentOrigin - PLAYHEAD_GLOW_W / 2}px)`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,98 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TimelineRuler } from "./TimelineRuler";
+import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
+import type { TimelineTheme } from "./timelineTheme";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("TimelineRuler", () => {
+  it("masks the one tick label the track header would slice, once the scroll settles", () => {
+    vi.useFakeTimers();
+    const scroller = document.createElement("div");
+    let scrollLeft = 0;
+    Object.defineProperty(scroller, "scrollLeft", { get: () => scrollLeft });
+    const host = document.createElement("div");
+    scroller.append(host);
+    const root = createRoot(host);
+    act(() =>
+      root.render(
+        <TimelineRuler
+          major={[0, 10, 20]}
+          minor={[]}
+          pps={20}
+          trackContentWidth={600}
+          totalH={100}
+          effectiveDuration={30}
+          majorTickInterval={10}
+          theme={{} as TimelineTheme}
+          contentOrigin={80}
+          scrollRef={{ current: scroller }}
+        />,
+      ),
+    );
+    const mask = () =>
+      host.querySelector<HTMLElement>("[data-timeline-ruler-label-mask]")?.style.left ?? null;
+    const scrollTo = (left: number) =>
+      act(() => {
+        scrollLeft = left;
+        scroller.dispatchEvent(new Event("scroll"));
+      });
+    const settle = () => act(() => vi.advanceTimersByTime(TIMELINE_SCROLL_SETTLE_MS));
+
+    expect(mask()).toBeNull();
+    // The 10s label starts at 200 - 0.5 + 5 = 204.5 in ruler space.
+    scrollTo(204);
+    expect(mask()).toBeNull();
+    settle();
+    expect(mask()).toBe("4.5px");
+    scrollTo(205);
+    expect(mask()).toBeNull();
+    settle();
+    expect(mask()).toBe("204.5px");
+    act(() => root.unmount());
+  });
+
+  it("masks right away when the scroll element is swapped mid-scroll", () => {
+    vi.useFakeTimers();
+    const make = (left: number) => {
+      const el = document.createElement("div");
+      Object.defineProperty(el, "scrollLeft", { get: () => left });
+      return el;
+    };
+    const first = make(205);
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const render = (el: HTMLDivElement) =>
+      act(() =>
+        root.render(
+          <TimelineRuler
+            major={[0, 10, 20]}
+            minor={[]}
+            pps={20}
+            trackContentWidth={600}
+            totalH={100}
+            effectiveDuration={30}
+            majorTickInterval={10}
+            theme={{} as TimelineTheme}
+            contentOrigin={80}
+            scrollRef={{ current: el }}
+          />,
+        ),
+      );
+    render(first);
+    act(() => first.dispatchEvent(new Event("scroll")));
+    render(make(205));
+    expect(host.querySelector<HTMLElement>("[data-timeline-ruler-label-mask]")?.style.left).toBe(
+      "204.5px",
+    );
+    act(() => root.unmount());
+  });
+});

package/src/player/components/TimelineRuler.tsx

@@ -1,4 +1,5 @@
-import { memo } from "react";
+import { memo, type RefObject } from "react";
+import { useSettledScrollLeft } from "./useSettledScrollLeft";
 import type { TimelineTheme } from "./timelineTheme";
 import { RULER_H, getTimelineBeatEntries } from "./timelineLayout";
 import { formatTimelineTickLabel } from "./timelineRulerGeometry";
@@ -19,8 +20,62 @@ interface TimelineRulerProps {
   beatAnalysis?: MusicBeatAnalysis | null;
   contentOrigin: number;
   renderTimeRange?: TimelineTimeRange;
+  scrollRef?: RefObject<HTMLDivElement | null>;
 }
 
+const TICK_LABEL_INSET_PX = 5;
+
+// Index of the major tick whose label starts under the track-header corner, which
+// covers ruler x < scrollLeft; -1 when none does.
+function tickIndexUnderHeader(major: number[], pps: number, scrollLeft: number): number {
+  let lo = 0;
+  let hi = major.length - 1;
+  let found = -1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (major[mid]! * pps - 0.5 + TICK_LABEL_INSET_PX < scrollLeft) {
+      found = mid;
+      lo = mid + 1;
+    } else hi = mid - 1;
+  }
+  return found;
+}
+
+// Paints over the one label the header corner would slice, once a scroll settles; mid-scroll a
+// fragment can still show.
+const HeaderSlicedLabelMask = memo(function HeaderSlicedLabelMask({
+  scrollRef,
+  major,
+  pps,
+  background,
+}: {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  major: number[];
+  pps: number;
+  background: string;
+}) {
+  const settledScrollLeft = useSettledScrollLeft(scrollRef);
+  const index =
+    settledScrollLeft === null ? -1 : tickIndexUnderHeader(major, pps, settledScrollLeft);
+  if (index < 0) return null;
+  const labelLeft = major[index]! * pps - 0.5 + TICK_LABEL_INSET_PX;
+  const next = major[index + 1];
+  return (
+    <div
+      data-timeline-ruler-label-mask=""
+      className="absolute pointer-events-none"
+      style={{
+        left: labelLeft,
+        top: 4,
+        height: 12,
+        // Up to the next label, so only this label's text band is covered.
+        width: next === undefined ? 80 : (next - major[index]!) * pps - TICK_LABEL_INSET_PX,
+        background,
+      }}
+    />
+  );
+});
+
 export const TimelineRuler = memo(function TimelineRuler({
   major,
   minor,
@@ -33,6 +88,7 @@ export const TimelineRuler = memo(function TimelineRuler({
   beatAnalysis,
   contentOrigin,
   renderTimeRange,
+  scrollRef,
 }: TimelineRulerProps) {
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const beatTimes = beatAnalysis?.beatTimes ?? [];
@@ -131,7 +187,7 @@ export const TimelineRuler = memo(function TimelineRuler({
                 className="absolute font-mono tabular-nums leading-none whitespace-nowrap"
                 style={{
                   color: theme.tickText,
-                  left: 5,
+                  left: TICK_LABEL_INSET_PX,
                   top: 5,
                   fontSize: 10,
                 }}
@@ -143,6 +199,14 @@ export const TimelineRuler = memo(function TimelineRuler({
               <div className="w-px" style={{ height: RULER_H, background: theme.tickMajor }} />
             </div>
           ))}
+          {scrollRef && (
+            <HeaderSlicedLabelMask
+              scrollRef={scrollRef}
+              major={major}
+              pps={pps}
+              background={theme.shellBackground}
+            />
+          )}
         </div>
       </div>
     </>

package/src/player/components/TimelineRulerPart.tsx

@@ -17,6 +17,7 @@ export function TimelineRulerPart() {
       beatAnalysis={props.beatAnalysis}
       contentOrigin={props.contentOrigin}
       renderTimeRange={props.rowsVirtualized ? props.renderTimeRange : undefined}
+      scrollRef={props.scrollRef}
     />
   );
 }

package/src/player/components/useSettledScrollLeft.ts

@@ -0,0 +1,38 @@
+import { useCallback, useRef, useSyncExternalStore, type RefObject } from "react";
+import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
+
+// The timeline viewport's scrollLeft once a scroll settles, or null while it is scrolling. Readers
+// re-render twice per gesture, never per frame: per-frame work cost 2-3x the viewport gate's budget
+// on a large unvirtualized timeline.
+export function useSettledScrollLeft(scrollRef: RefObject<HTMLDivElement | null>): number | null {
+  const scrollingRef = useRef(false);
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const el = scrollRef.current;
+      let settle: ReturnType<typeof setTimeout> | undefined;
+      const onScroll = () => {
+        if (!scrollingRef.current) {
+          scrollingRef.current = true;
+          onChange();
+        }
+        clearTimeout(settle);
+        settle = setTimeout(() => {
+          scrollingRef.current = false;
+          onChange();
+        }, TIMELINE_SCROLL_SETTLE_MS);
+      };
+      el?.addEventListener("scroll", onScroll, { passive: true });
+      return () => {
+        clearTimeout(settle);
+        scrollingRef.current = false;
+        el?.removeEventListener("scroll", onScroll);
+      };
+    },
+    [scrollRef],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => (scrollingRef.current ? null : (scrollRef.current?.scrollLeft ?? 0)),
+    () => null,
+  );
+}

package/src/player/components/useTimelineScrollViewport.ts

@@ -3,6 +3,9 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { shouldShowTimelineShortcutHint } from "./timelineLayout";
 import { STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED } from "./timelineRowVirtualizationFlag";
 
+/** How long the timeline waits after the last scroll event before treating the scroll as settled. */
+export const TIMELINE_SCROLL_SETTLE_MS = 100;
+
 export interface TimelineScrollViewportSnapshot {
   readonly scrollLeft: number;
   readonly scrollTop: number;
@@ -91,7 +94,7 @@ export function useTimelineScrollViewport(
       scrollingRef.current = false;
       if (viewportRafRef.current) cancelAnimationFrame(viewportRafRef.current);
       publish();
-    }, 100);
+    }, TIMELINE_SCROLL_SETTLE_MS);
   }, []);
 
   const syncShortcutHintVisibility = useCallback(() => {