@hyperframes/studio 0.8.138 → 0.8.140

package/src/player/components/useTimelinePlayhead.ts

@@ -2,6 +2,17 @@ import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
+import {
+  currentTimelineZoomPercent,
+  requestTimelineZoom,
+  registerTimelineZoomViewport,
+  redrawTimelineZoomPreview,
+  settleTimelineZoom,
+  subscribeTimelineZoomPreview,
+  takeTimelineZoomAnchor,
+  timelineTimeAtX,
+  timelineZoomMapping,
+} from "./timelineZoomInput";
 import {
   getTimelinePlaybackFollowScrollLeft,
   getTimelineScrubTime,
@@ -36,17 +47,13 @@ interface UseTimelinePlayheadInput {
   isDragging: React.RefObject<boolean>;
   currentTime: number;
   zoomMode: ZoomMode;
-  manualZoomPercent: number;
   zoomModeRef: React.RefObject<ZoomMode>;
-  manualZoomPercentRef: React.RefObject<number>;
   fitPps: number;
   fitPpsRef: React.RefObject<number>;
   effectiveDuration: number;
   pps: number;
   timelineReady: boolean;
   elementsLength: number;
-  setZoomMode: (mode: ZoomMode) => void;
-  setManualZoomPercent: (percent: number) => void;
   onSeek?: (time: number) => void;
   contentOrigin: number;
 }
@@ -60,28 +67,23 @@ export function useTimelinePlayhead({
   currentTime,
   zoomMode,
   zoomModeRef,
-  manualZoomPercentRef,
   fitPps: _fitPps,
   fitPpsRef,
   effectiveDuration,
   pps,
   timelineReady,
   elementsLength,
-  setZoomMode,
-  setManualZoomPercent,
   onSeek,
   contentOrigin,
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // A toolbar zoom keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
-  // The pinch handler anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+  // A zoom keeps its anchor (pinch: pointer, else playhead) in place; a resize keeps the centre.
   const previousAnchorPpsRef = useRef(pps);
   const userZoomCount = usePlayerStore((s) => s.userZoomCount);
   const previousZoomCountRef = useRef(userZoomCount);
   const lastLiveTimeRef = useRef(usePlayerStore.getState().currentTime);
   const lastSeekCountRef = useRef(liveTime.seekCount());
-  const skipCenterAnchorRef = useRef(false);
   const contentOriginRef = useRef(contentOrigin);
   contentOriginRef.current = contentOrigin;
 
@@ -91,12 +93,15 @@ export function useTimelinePlayhead({
     previousAnchorPpsRef.current = pps;
     const prevZoomCount = previousZoomCountRef.current;
     previousZoomCountRef.current = userZoomCount;
-    // Always consume the skip flag, even when pps didn't change — otherwise a
-    // pinch that produced no pps change (already at the zoom clamp) would strand
-    // it true and the next toolbar zoom would wrongly skip center-anchoring.
-    const skip = skipCenterAnchorRef.current;
-    skipCenterAnchorRef.current = false;
-    if (!scroll || pps === prevPps || skip) return;
+    // Consumed even when pps didn't change (at the clamp), so it never lingers for a later zoom.
+    const anchor = takeTimelineZoomAnchor();
+    if (!scroll || pps === prevPps) return;
+    if (anchor) {
+      const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+      const left = anchor.time * pps + contentOrigin - anchor.x;
+      scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, left));
+      return;
+    }
     const zoomed = userZoomCount !== prevZoomCount;
     if (!zoomed && scroll.scrollLeft < 1) return;
     const time = Math.max(0, lastLiveTimeRef.current);
@@ -121,10 +126,11 @@ export function useTimelinePlayhead({
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
+      const at = timelineZoomMapping(ppsRef.current, contentOrigin);
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
         time,
-        ppsRef.current,
-        contentOrigin,
+        at.pps,
+        at.contentOrigin,
         !usePlayerStore.getState().isPlaying,
       );
     },
@@ -158,14 +164,18 @@ export function useTimelinePlayhead({
   useMountEffect(() => {
     const place = (t: number, atRest: boolean) => {
       if (!playheadRef.current || durationRef.current <= 0) return false;
+      const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
         t,
-        ppsRef.current,
-        contentOriginRef.current,
+        at.pps,
+        at.contentOrigin,
         atRest,
       );
       return true;
     };
+    const unsubPreview = subscribeTimelineZoomPreview(() =>
+      place(lastLiveTimeRef.current, !usePlayerStore.getState().isPlaying),
+    );
     const dragging = () => isDragging.current || usePlayerStore.getState().beatDragging;
     const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
       if (prev.isPlaying && !state.isPlaying) place(lastLiveTimeRef.current, true);
@@ -177,7 +187,8 @@ export function useTimelinePlayhead({
       lastLiveTimeRef.current = t;
       const playing = usePlayerStore.getState().isPlaying;
       if (!place(t, !playing)) return;
-      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
+      const at = timelineZoomMapping(ppsRef.current, contentOriginRef.current);
+      const playheadX = at.contentOrigin + Math.max(0, t) * at.pps;
       const scroll = scrollRef.current;
       // Paused, only a seek scrolls: a reload's republish, frame-rounded, must not undo a person's scroll.
       if (!scroll || dragging() || zoomModeRef.current === "fit" || (!playing && !sought)) return;
@@ -197,6 +208,7 @@ export function useTimelinePlayhead({
     return () => {
       unsub();
       unsubPlaying();
+      unsubPreview();
     };
   });
 
@@ -237,62 +249,44 @@ export function useTimelinePlayhead({
     [scrollRef, isDragging, zoomModeRef, seekFromX],
   );
 
+  // Trackpad pinch arrives as ctrl+wheel; Cmd+wheel zooms too, as Mac editors do.
   const handlePinchWheel = useCallback(
     (e: WheelEvent) => {
-      if (!e.ctrlKey) return;
+      if (!e.ctrlKey && !e.metaKey) return;
       const scroll = scrollRef.current;
       if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0)
         return;
       e.preventDefault();
       e.stopPropagation();
-      const rect = scroll.getBoundingClientRect();
-      const nextZoomPercent = getPinchTimelineZoomPercent(
-        e.deltaY,
-        zoomModeRef.current,
-        manualZoomPercentRef.current,
-        fitPpsRef.current,
+      const x = e.clientX - scroll.getBoundingClientRect().left;
+      requestTimelineZoom(
+        getPinchTimelineZoomPercent(
+          e.deltaY,
+          "manual",
+          currentTimelineZoomPercent(),
+          fitPpsRef.current,
+        ),
+        { time: Math.max(0, timelineTimeAtX(x) ?? 0), x },
       );
-      if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual")
-        return;
-      const nextPps = fitPpsRef.current * (nextZoomPercent / 100);
-      const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
-        pointerX: e.clientX - rect.left,
-        currentScrollLeft: scroll.scrollLeft,
-        contentOrigin,
-        currentPixelsPerSecond: ppsRef.current,
-        nextPixelsPerSecond: nextPps,
-        duration: durationRef.current,
-      });
-      // Pinch anchors at the cursor (below), so skip the center-anchor effect.
-      skipCenterAnchorRef.current = true;
-      setZoomMode("manual");
-      setManualZoomPercent(nextZoomPercent);
-      requestAnimationFrame(() => {
-        const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
-        scroll.scrollLeft = Math.min(maxScrollLeft, nextScrollLeft);
-      });
     },
-    [
-      scrollRef,
-      durationRef,
-      fitPpsRef,
-      ppsRef,
-      zoomModeRef,
-      manualZoomPercentRef,
-      setManualZoomPercent,
-      setZoomMode,
-      contentOrigin,
-    ],
+    [scrollRef, durationRef, fitPpsRef, ppsRef],
   );
 
   useEffect(() => {
     const scroll = scrollRef.current;
     if (!scroll) return;
     scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+    // A press meets the zoom it sees, not the one still waiting to be laid out.
+    scroll.addEventListener("pointerdown", settleTimelineZoom, { capture: true });
+    scroll.addEventListener("scroll", redrawTimelineZoomPreview, { passive: true });
+    const unregisterZoomViewport = registerTimelineZoomViewport({ scroll, contentOrigin });
     return () => {
       scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+      scroll.removeEventListener("pointerdown", settleTimelineZoom, { capture: true });
+      scroll.removeEventListener("scroll", redrawTimelineZoomPreview);
+      unregisterZoomViewport();
     };
-  }, [handlePinchWheel, scrollRef, timelineReady, elementsLength]);
+  }, [handlePinchWheel, scrollRef, timelineReady, elementsLength, contentOrigin]);
 
   return { seekFromX, autoScrollDuringDrag, dragScrollRaf };
 }

package/src/player/components/useTimelineProviderState.tsx

@@ -131,7 +131,7 @@ export function useTimelineProviderState({
   const timelineSessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
   const sessionEpoch = sessionEpochProp ?? timelineSessionEpoch;
   const setFocusedEaseSegment = usePlayerStore((s) => s.setFocusedEaseSegment);
-  const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
+  const { zoomMode, manualZoomPercent } = useTimelineZoom();
   const playheadRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -258,22 +258,21 @@ export function useTimelineProviderState({
       timelineElements.length,
       displayLayout.totalH,
     ]);
-  const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef, manualZoomPercentRef } =
-    useTimelineGeometry({
-      viewportWidth: viewport.clientWidth,
-      effectiveDuration,
-      zoomMode,
-      manualZoomPercent,
-      ppsRef,
-      fitPpsRef,
-      draggedClip,
-      resizingClip,
-      expandedElements: timelineElements,
-      isDragging,
-      scrollRef,
-      lastScrollLeftRef,
-      contentOrigin,
-    });
+  const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef } = useTimelineGeometry({
+    viewportWidth: viewport.clientWidth,
+    effectiveDuration,
+    zoomMode,
+    manualZoomPercent,
+    ppsRef,
+    fitPpsRef,
+    draggedClip,
+    resizingClip,
+    expandedElements: timelineElements,
+    isDragging,
+    scrollRef,
+    lastScrollLeftRef,
+    contentOrigin,
+  });
   const timelineFocus = useTimelineLogicalFocus({
     scrollRef,
     tracks,
@@ -342,17 +341,13 @@ export function useTimelineProviderState({
     isDragging,
     currentTime,
     zoomMode,
-    manualZoomPercent,
     zoomModeRef,
-    manualZoomPercentRef,
     fitPps,
     fitPpsRef,
     effectiveDuration,
     pps,
     timelineReady,
     elementsLength: timelineElements.length,
-    setZoomMode,
-    setManualZoomPercent,
     onSeek,
     contentOrigin,
   });

package/src/player/components/useTimelineZoom.ts

@@ -1,6 +1,6 @@
 // fallow-ignore-file dead-code
-import { useCallback } from "react";
 import { usePlayerStore, type ZoomMode } from "../store/playerStore";
+import { cancelTimelineZoom, requestTimelineZoom } from "./timelineZoomInput";
 
 export interface TimelineZoomState {
   zoomMode: ZoomMode;
@@ -9,18 +9,13 @@ export interface TimelineZoomState {
   setManualZoomPercent: (percent: number) => void;
 }
 
-/** Shared zoom-related store selectors used by Timeline and TimelineToolbar. */
 export function useTimelineZoom(): TimelineZoomState {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
-  const setZoomMode = usePlayerStore((s) => s.setZoomMode);
-  const setStorePercent = usePlayerStore((s) => s.setManualZoomPercent);
-  const setManualZoomPercent = useCallback(
-    (percent: number) => {
-      usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
-      setStorePercent(percent);
-    },
-    [setStorePercent],
-  );
-  return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent };
+  const setStoreZoomMode = usePlayerStore((s) => s.setZoomMode);
+  const setZoomMode = (mode: ZoomMode) => {
+    cancelTimelineZoom();
+    setStoreZoomMode(mode);
+  };
+  return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent: requestTimelineZoom };
 }

package/src/player/hooks/useShadowPreviewReload.ts

@@ -18,7 +18,7 @@ import {
   type UseTimelineSyncCallbacksParams,
 } from "./useTimelineSyncCallbacks";
 import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
-import { thumbnailScheduler } from "../lib/thumbnailScheduler";
+import { setPreviewReloading } from "../previewReloading";
 import { announcePreviewPromoted } from "../sceneSwap";
 import { afterStudioPendingEdits, isStudioEditSaving } from "../../utils/studioPendingEdits";
 import { usePlayerStore } from "../store/playerStore";
@@ -110,7 +110,7 @@ export function useShadowPreviewReload({
       isRefreshingRef.current = false;
       pendingSeekRef.current = null;
       setPreviewSlots(planShadowDiscard);
-      thumbnailScheduler.setPreviewReloading(false);
+      setPreviewReloading(false);
       const message = `The preview did not reload (${cause}). The previous preview is still showing.`;
       logReload("shadow-failed", { cause });
       console.error(`[studio] ${message}`);
@@ -188,7 +188,7 @@ export function useShadowPreviewReload({
       if (liveTime != null) handOverPlaybackRef.current(liveTime, playing);
       announcePreviewPromoted({ retired, live: shadow });
       onPromotedRef.current?.();
-      thumbnailScheduler.setPreviewReloading(false);
+      setPreviewReloading(false);
     },
     [
       stopPendingShadow,
@@ -285,7 +285,7 @@ export function useShadowPreviewReload({
       armReadyTimer(gen);
       setPreviewSlots((prev) => planShadowReload(prev, gen, url));
       // Thumbnails of the edit wait for the new preview instead of competing with it.
-      thumbnailScheduler.setPreviewReloading(true);
+      setPreviewReloading(true);
     },
     [stopPendingShadow, armReadyTimer, gestureSavesOnScreen],
   );
@@ -300,7 +300,7 @@ export function useShadowPreviewReload({
     pendingSeekRef.current = null;
     usePlayerStore.getState().setTimelineReady(false);
     setPreviewSlots(planShadowDiscard);
-    thumbnailScheduler.setPreviewReloading(false);
+    setPreviewReloading(false);
   }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);
 
   // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow.
@@ -317,7 +317,7 @@ export function useShadowPreviewReload({
     return () => {
       document.removeEventListener("visibilitychange", onVisibilityChange);
       stopPendingShadow();
-      thumbnailScheduler.setPreviewReloading(false);
+      setPreviewReloading(false);
     };
   });
 

package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts

@@ -6,6 +6,7 @@ import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
 import { usePlayerStore } from "../store/playerStore";
+import { isPreviewChanging } from "../previewReloading";
 import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
 import {
   makeAdapterWindow,
@@ -752,6 +753,19 @@ describe("useTimelinePlayer scene swap", () => {
     expect(roles(getApi())).toEqual(["live"]);
   });
 
+  it("counts as a preview change until the swap lands, so a canvas press waits for the new scenes", async () => {
+    let reply: (r: Response) => void = () => {};
+    vi.spyOn(globalThis, "fetch").mockImplementation(
+      () => new Promise<Response>((resolve) => (reply = resolve)),
+    );
+    const { getApi } = liveFilm(vi.fn(async () => {}));
+    act(() => getApi().refreshPlayer());
+    expect(isPreviewChanging()).toBe(true);
+    reply(new Response("<html>v2</html>"));
+    await settle();
+    expect(isPreviewChanging()).toBe(false);
+  });
+
   it("falls back to the full reload when the preview refuses the swap", async () => {
     vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
     const { getApi } = liveFilm(async () => {

package/src/player/hooks/useTimelinePlayer.ts

@@ -43,6 +43,7 @@ import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 import { safeContentDocument } from "./timelineSyncHydration";
 import { sceneSwapFor } from "../sceneSwap";
+import { whileScriptWrites } from "../previewReloading";
 
 export interface UseTimelinePlayerOptions {
   /** Runs right after a reloaded preview becomes the live iframe. */
@@ -504,11 +505,13 @@ export function useTimelinePlayer({
       !!iframe.contentDocument && isStudioManualEditGestureLiveIn(iframe.contentDocument);
     if (!swap || isRefreshingRef.current || swapWouldReplaceGestureNode)
       return reloadWholeFilm(url.toString());
-    swap(url.toString(), isCurrent, cancel.signal).catch((error: unknown) => {
-      if (!isCurrent()) return;
-      logReload("scene-swap-refused", { reason: String(error) });
-      reloadWholeFilm(url.toString());
-    });
+    whileScriptWrites(() => swap(url.toString(), isCurrent, cancel.signal)).catch(
+      (error: unknown) => {
+        if (!isCurrent()) return;
+        logReload("scene-swap-refused", { reason: String(error) });
+        reloadWholeFilm(url.toString());
+      },
+    );
   }, [reloadWholeFilm, previewGeneration]);
   const pauseRef = useRef(pause);
   pauseRef.current = pause;

package/src/player/lib/thumbnailScheduler.test.ts

@@ -219,6 +219,26 @@ describe("ThumbnailScheduler", () => {
     expect(scheduler.getDiagnostics()).toMatchObject({ queued: 0, active: 0, leases: 0 });
   });
 
+  it("starts nothing that a release later in the same batch drops", async () => {
+    const scheduler = new ThumbnailScheduler(
+      resolveTimelineViewportBudgets({ concurrentVideoDecodes: 1 }),
+    );
+    const video = (key: string, load: ThumbnailRequest["load"]) =>
+      scheduler.acquire(request(key, load, "visible", { kind: "video" }), vi.fn());
+    const activeLease = video("active", () => deferred<ThumbnailLoadedResult>().promise);
+    const droppedLoad = vi.fn(async () => result("dropped"));
+    const droppedLease = video("dropped", droppedLoad);
+    const keptLoad = vi.fn(async () => result("kept"));
+    video("kept", keptLoad);
+
+    // A timeline jump unmounts its clips in one commit, the loading one first.
+    activeLease.release();
+    droppedLease.release();
+    await flush();
+    expect(droppedLoad).not.toHaveBeenCalled();
+    expect(keptLoad).toHaveBeenCalledTimes(1);
+  });
+
   it("frees an aborted job's slot at once, even when its loader ignores the abort", async () => {
     const scheduler = new ThumbnailScheduler(
       resolveTimelineViewportBudgets({ concurrentVideoDecodes: 1 }),
@@ -231,7 +251,6 @@ describe("ThumbnailScheduler", () => {
     lease.release();
     const nextLoad = vi.fn(async () => result("next"));
     scheduler.acquire(request("next", nextLoad, "visible", { kind: "video" }), vi.fn());
-    await flush();
     expect(nextLoad).toHaveBeenCalledTimes(1);
   });
 

package/src/player/lib/thumbnailScheduler.ts

@@ -316,7 +316,7 @@ export class ThumbnailScheduler {
       slotFree = true;
       this.activeByBucket[bucket]--;
       this.activeByKind[entry.request.kind]--;
-      this.pump();
+      queueMicrotask(() => this.pump());
     };
     controller.signal.addEventListener("abort", freeSlot, { once: true });
     this.notify(entry);