@hyperframes/studio 0.8.74 → 0.8.76

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";
@@ -157,7 +157,6 @@ export function useTimelineDeleteOps({
           await saveProjectFilesWithHistory({
             projectId: pid,
             label: deleteHistoryLabel,
-            kind: "timeline",
             coalesceKey,
             files: { [targetPath]: patchedContent },
             readFile: async () => originalContent,
@@ -172,6 +171,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 +184,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 +201,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 +224,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/hooks/useTimelineEditing.test.tsx

@@ -112,7 +112,6 @@ function renderTimelineEditingHook(input: {
   writeProjectFile?: (path: string, content: string) => Promise<void>;
   recordEdit?: (input: {
     label: string;
-    kind: string;
     coalesceKey?: string;
     files: Record<string, { before: string; after: string }>;
   }) => Promise<void>;

package/src/hooks/useTimelineEditingTypes.ts

@@ -2,13 +2,11 @@ import type { MutableRefObject, RefObject } from "react";
 import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
 import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
-import type { EditHistoryKind } from "../utils/editHistory";
 import type { PublishSdkSession } from "../utils/sdkCutover";
 import type { CanEditTimelineElement } from "./timelineEditPermission";
 
 interface RecordEditInput {
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   files: Record<string, { before: string; after: string }>;
 }

package/src/hostMount.test.tsx

@@ -8,8 +8,15 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 // Backend/storage mocking only, standing in for a host's own server and
 // persistence — not part of the host's integration code under test.
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createStudioApi,
+  openProjectHistory,
+  type StudioApiAdapter,
+} from "@hyperframes/studio-server";
 import { studioFileContentVersion } from "./utils/studioFileVersion";
-import { createMemoryEditHistoryStorage } from "./utils/editHistoryStorage";
 import {
   flushStudioPendingEdits,
   useTimelineEditing,
@@ -27,45 +34,66 @@ import {
 const ORIGINAL_HTML = '<div id="clip" data-start="0" data-track-index="0"></div>';
 
 let root: Root | null = null;
-afterEach(() => {
+const cleanups: Array<() => unknown> = [];
+afterEach(async () => {
   act(() => root?.unmount());
   document.body.innerHTML = "";
   vi.unstubAllGlobals();
+  for (const step of cleanups.splice(0).reverse()) await step();
 });
 
-/** A minimal disk with etag-guarded PUT, faithful enough to exercise a real
- *  conflict: a stale If-Match gets a 409 with the current version + content. */
-function stubHostProjectDisk(
+function tempDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+/** A project folder with etag-guarded PUT, faithful enough to exercise a real
+ *  conflict: a stale If-Match gets a 409 with the current version + content.
+ *  History requests go to the real history routes over the real engine. */
+async function stubHostProjectDisk(
   initial: Record<string, string>,
   options?: { editElsewhereAfterFirstRead?: boolean },
 ) {
-  const content = { ...initial };
+  const dir = tempDir("hf-host-mount-");
+  for (const [path, text] of Object.entries(initial)) writeFileSync(join(dir, path), text);
+  const history = await openProjectHistory({
+    projectDir: dir,
+    historyRoot: tempDir("hf-host-mount-history-"),
+  });
+  cleanups.push(() => history.close());
+  const api = createStudioApi({
+    listProjects: () => [],
+    resolveProject: (id: string) => (id === "p1" ? { id, dir } : null),
+    history: () => history,
+  } as unknown as StudioApiAdapter);
   const readsSeen = new Set<string>();
+  const read = (path: string) => readFileSync(join(dir, path), "utf8");
   // The real backend's etag is a content hash (useProjectFileWriter derives
   // If-Match the same way) — an arbitrary counter here would make every
   // write from a host that hasn't just read the file look stale.
-  const versionOf = (path: string) => studioFileContentVersion(content[path]);
+  const versionOf = (path: string) => studioFileContentVersion(read(path));
 
   async function handlePut(path: string, init: RequestInit | undefined) {
     const ifMatch = new Headers(init?.headers).get("If-Match");
     const currentVersion = await versionOf(path);
     if (ifMatch && ifMatch !== currentVersion) {
-      return new Response(JSON.stringify({ currentVersion, currentContent: content[path] }), {
+      return new Response(JSON.stringify({ currentVersion, currentContent: read(path) }), {
         status: 409,
       });
     }
-    content[path] = String(init?.body ?? "");
+    writeFileSync(join(dir, path), String(init?.body ?? ""));
     return new Response(JSON.stringify({ version: await versionOf(path) }), { status: 200 });
   }
 
   async function handleGet(path: string) {
-    const served = content[path];
+    const served = read(path);
     // Simulates another writer landing between this read and the caller's
     // own write: content moves on right after being served once, so the
     // caller's hash of what it just read no longer matches disk.
     if (options?.editElsewhereAfterFirstRead && !readsSeen.has(path)) {
       readsSeen.add(path);
-      content[path] = `${served} <!--edited elsewhere-->`;
+      writeFileSync(join(dir, path), `${served} <!--edited elsewhere-->`);
     }
     return new Response(
       JSON.stringify({ content: served, version: await studioFileContentVersion(served) }),
@@ -74,12 +102,15 @@ function stubHostProjectDisk(
   }
 
   const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
-    const match = String(input).match(/\/files\/([^?]+)/);
-    const path = match ? decodeURIComponent(match[1]) : "";
+    const url = String(input);
+    if (url.includes("/history")) return api.request(url.replace(/^\/api/, ""), init);
+    const match = url.match(/\/files\/([^?]+)/);
+    if (!match) return new Response("{}", { status: 404 });
+    const path = decodeURIComponent(match[1]);
     return (init?.method ?? "GET") === "PUT" ? handlePut(path, init) : handleGet(path);
   });
   vi.stubGlobal("fetch", fetchMock);
-  return { content, fetchMock };
+  return { read, fetchMock };
 }
 
 type TimelineEditingHandle = {
@@ -108,13 +139,10 @@ function mountHost(
   const bannerHost = document.createElement("div");
   document.body.append(bannerHost);
   const bannerRoot = createRoot(bannerHost);
-  // Created once: a fresh storage object on every render would change
-  // usePersistentEditHistory's effect deps each time and loop forever.
-  const storage = createMemoryEditHistoryStorage();
 
   function Harness() {
     const writer = useProjectFileWriter({ projectId: "p1" });
-    const editHistory = usePersistentEditHistory({ projectId: "p1", storage });
+    const editHistory = usePersistentEditHistory({ projectId: "p1" });
     const historyActions = useEditHistoryActions({
       editHistory,
       readOptionalProjectFile: writer.readOptionalProjectFile,
@@ -170,7 +198,7 @@ function mountHost(
 
 describe("public export surface: a host mounting hand editing outside EditorShell", () => {
   it("writes a move through the history path and undo restores it", async () => {
-    const disk = stubHostProjectDisk({ "index.html": ORIGINAL_HTML });
+    const disk = await stubHostProjectDisk({ "index.html": ORIGINAL_HTML });
     const iframe = document.createElement("iframe");
     document.body.append(iframe);
     iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;
@@ -187,16 +215,19 @@ describe("public export surface: a host mounting hand editing outside EditorShel
     await act(async () => {
       await timelineEditing.handleTimelineElementMove(clip, { start: 5, track: 0 });
     });
-    expect(disk.content["index.html"]).toContain('data-start="5"');
+    expect(disk.read("index.html")).toContain('data-start="5"');
 
     await act(async () => {
       await undo();
     });
-    expect(disk.content["index.html"]).toContain('data-start="0"');
+    expect(disk.read("index.html")).toContain('data-start="0"');
   });
 
   it("surfaces the conflict banner on a 409", async () => {
-    stubHostProjectDisk({ "index.html": ORIGINAL_HTML }, { editElsewhereAfterFirstRead: true });
+    await stubHostProjectDisk(
+      { "index.html": ORIGINAL_HTML },
+      { editElsewhereAfterFirstRead: true },
+    );
     const iframe = document.createElement("iframe");
     document.body.append(iframe);
     iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;

package/src/main.tsx

@@ -5,8 +5,11 @@ import { StudioApp } from "./App";
 import { StudioErrorBoundary } from "./components/StudioErrorBoundary";
 import { readIconTokens } from "./styles/iconTokens";
 import { trackStudioEvent } from "./utils/studioTelemetry";
+import { prefetchPreviewForHash } from "./utils/previewPrefetch";
 import "./styles/studio.css";
 
+prefetchPreviewForHash(window.location.hash);
+window.addEventListener("hashchange", () => prefetchPreviewForHash(window.location.hash));
 trackStudioEvent("session_start");
 
 function errorProps(value: unknown): {

package/src/player/components/CompositionThumbnail.tsx

@@ -24,6 +24,20 @@ interface CompositionThumbnailProps {
 
 const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v3";
+export const THUMBNAIL_SEEK_TIME_SECONDS = 3;
+
+export function resolveThumbnailSeekTime(durationSeconds: number | null | undefined): number {
+  if (
+    Number.isFinite(durationSeconds) &&
+    durationSeconds != null &&
+    durationSeconds > 0 &&
+    durationSeconds <= THUMBNAIL_SEEK_TIME_SECONDS
+  ) {
+    return durationSeconds / 2;
+  }
+
+  return THUMBNAIL_SEEK_TIME_SECONDS;
+}
 
 export function buildCompositionThumbnailUrl({
   previewUrl,

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

@@ -9,6 +9,7 @@ import {
   readPreviewErrorMessage,
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
+import { usePlayerStore } from "../store/playerStore";
 
 vi.mock("@hyperframes/player", () => ({}));
 
@@ -271,6 +272,54 @@ describe("ready to show", () => {
     expect(onReadyToShowChange).toHaveBeenLastCalledWith(false);
   });
 
+  it("marks the preview booted when it can show and play, not at ready", async () => {
+    usePlayerStore.setState({ previewBooted: false });
+    const { player } = await mountPlayer({});
+    const el = player as TestHyperframesPlayer;
+
+    loadAndReady(el);
+    act(() => void el.dispatchEvent(new Event("assetsready")));
+    await twoFrames();
+    expect(usePlayerStore.getState().previewBooted).toBe(false);
+
+    painted(el);
+    await twoFrames();
+    expect(usePlayerStore.getState().previewBooted).toBe(true);
+  });
+
+  it("marks the preview booted at its first frame while media is still buffering", async () => {
+    usePlayerStore.setState({ previewBooted: false });
+    const onReadyToShowChange = vi.fn();
+    const { player } = await mountPlayer({ onReadyToShowChange });
+    const el = player as TestHyperframesPlayer;
+    document.body.appendChild(el.iframeElement);
+    const doc = el.iframeElement.contentDocument!;
+    const audio = doc.createElement("audio");
+    Object.defineProperty(audio, "readyState", { value: 0, configurable: true });
+    Object.defineProperty(audio, "networkState", { value: 2, configurable: true });
+    doc.body.appendChild(audio);
+
+    loadAndReady(el);
+    painted(el);
+    await twoFrames();
+    expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+    expect(usePlayerStore.getState().previewBooted).toBe(true);
+  });
+
+  it("stops deferring editing work when the preview never shows", async () => {
+    vi.useFakeTimers();
+    try {
+      usePlayerStore.setState({ previewBooted: false });
+      await mountPlayer({});
+      act(() => void vi.advanceTimersByTime(4999));
+      expect(usePlayerStore.getState().previewBooted).toBe(false);
+      act(() => void vi.advanceTimersByTime(1));
+      expect(usePlayerStore.getState().previewBooted).toBe(true);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("reports the document start time with the painted iframe", async () => {
     const onPainted = vi.fn();
     const now = vi.spyOn(performance, "now").mockReturnValue(100);

package/src/player/components/Player.tsx

@@ -4,6 +4,7 @@ import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readin
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { HyperframesLoader } from "../../components/ui";
+import { usePlayerStore } from "../store/playerStore";
 // Importing "@hyperframes/player" registers a class extending HTMLElement at
 // module load, which throws under SSR, hence the dynamic import behind a
 // `typeof window` guard. Kicking it here rather than in the mount effect puts
@@ -57,6 +58,7 @@ function getShaderTransitionLoading(event: Event): boolean | null {
 }
 
 const COMPOSITION_LOADING_OVERLAY_DELAY_MS = 400;
+const PREVIEW_BOOT_DEADLINE_MS = 5000;
 const DEFAULT_PREVIEW_ERROR = "The composition preview did not become ready.";
 
 export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
@@ -427,13 +429,13 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       setAssetsLoading(false);
     };
 
-    const readyToShow =
-      loaded &&
-      painted &&
-      !compositionLoading &&
-      !shaderTransitionLoading &&
-      !assetsLoading &&
-      !previewError;
+    const firstFrameShown =
+      loaded && painted && !compositionLoading && !shaderTransitionLoading && !previewError;
+    const readyToShow = firstFrameShown && !assetsLoading;
+    // Work waiting on the boot starts at the first frame, while media still buffers.
+    useEffect(() => {
+      if (firstFrameShown) usePlayerStore.getState().markPreviewBooted();
+    }, [firstFrameShown]);
     // `painted` means the player's own loader has finished fading; two frames of grace on top.
     useEffect(() => {
       if (!readyToShow) {
@@ -450,6 +452,18 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       };
     }, [readyToShow]);
 
+    useEffect(() => {
+      if (previewError) usePlayerStore.getState().markPreviewBooted();
+    }, [previewError]);
+
+    useEffect(() => {
+      const timer = setTimeout(
+        () => usePlayerStore.getState().markPreviewBooted(),
+        PREVIEW_BOOT_DEADLINE_MS,
+      );
+      return () => clearTimeout(timer);
+    }, [projectId]);
+
     const showCompositionOverlay =
       !suppressLoadingOverlay &&
       !compositionOverlayDeferred &&

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.tsx

@@ -1,5 +1,5 @@
-import { memo, useCallback, useRef, useSyncExternalStore, type RefObject } from "react";
-import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
+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";
@@ -41,11 +41,8 @@ function tickIndexUnderHeader(major: number[], pps: number, scrollLeft: number):
   return found;
 }
 
-/**
- * Paints over the one label the header corner would slice, once a scroll settles. Moving it
- * on every tick crossing cost 2-3x the scroll budget on a large timeline, so mid-scroll a
- * fragment can still show.
- */
+// 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,
@@ -57,39 +54,9 @@ const HeaderSlicedLabelMask = memo(function HeaderSlicedLabelMask({
   pps: number;
   background: string;
 }) {
-  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],
-  );
-  const index = useSyncExternalStore(
-    subscribe,
-    () =>
-      scrollingRef.current
-        ? -1
-        : tickIndexUnderHeader(major, pps, scrollRef.current?.scrollLeft ?? 0),
-    () => -1,
-  );
+  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];