@hyperframes/studio 0.8.75 → 0.8.77

package/src/components/nle/NLEPreview.test.ts

@@ -10,6 +10,7 @@ import { readPreviewComplexity } from "../../player/hooks/usePreviewFirstFrameTe
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
 const playerMounts: string[] = [];
+let livePlayerProps: { onReadyToShowChange?: (ready: boolean) => void } = {};
 
 vi.mock("../../player", async () => {
   const React = await import("react");
@@ -18,11 +19,13 @@ vi.mock("../../player", async () => {
     Player: React.forwardRef(function MockPlayer(
       props: {
         onLoad?: () => void;
+        onReadyToShowChange?: (ready: boolean) => void;
         suppressLoadingOverlay?: boolean;
         style?: React.CSSProperties;
       },
       ref: React.ForwardedRef<HTMLIFrameElement>,
     ) {
+      if (!props.suppressLoadingOverlay) livePlayerProps = props;
       React.useEffect(() => {
         props.onLoad?.();
       }, [props]);
@@ -37,11 +40,6 @@ vi.mock("../../player", async () => {
   };
 });
 
-vi.mock("../../utils/studioUiPreferences", () => ({
-  readStudioUiPreferences: () => ({}),
-  writeStudioUiPreferences: () => {},
-}));
-
 let resizeCallbacks: Array<() => void> = [];
 
 class MockResizeObserver {
@@ -90,23 +88,25 @@ function renderPreview(
   document.body.append(host);
   const root = createRoot(host);
   const iframeRef = createRef<HTMLIFrameElement>();
-
-  act(() => {
-    root.render(
-      React.createElement(NLEPreview, {
-        projectId: "timeline-edit-playground",
-        iframeRef,
-        onIframeLoad: () => {},
-        previewSlots,
-        onShadowIframeLoad: () => {},
-        onShadowReadyChange: () => {},
-        onShadowError: () => {},
-        setShadowIframeNode: () => {},
-        resetPreviewSlots: () => {},
-        fillBox,
-      }),
-    );
-  });
+  const render = (directUrl?: string, projectId = "timeline-edit-playground") =>
+    act(() => {
+      root.render(
+        React.createElement(NLEPreview, {
+          projectId,
+          directUrl,
+          iframeRef,
+          onIframeLoad: () => {},
+          previewSlots,
+          onShadowIframeLoad: () => {},
+          onShadowReadyChange: () => {},
+          onShadowError: () => {},
+          setShadowIframeNode: () => {},
+          resetPreviewSlots: () => {},
+          fillBox,
+        }),
+      );
+    });
+  render();
 
   const viewport = host.querySelector('[aria-label="Composition preview"]') as HTMLDivElement;
   const stage = host.querySelector('[data-testid="preview-zoom-stage"]') as HTMLDivElement;
@@ -121,8 +121,12 @@ function renderPreview(
   return {
     host,
     root,
+    render,
     viewport,
     stage,
+    openProject(projectId: string) {
+      render(undefined, projectId);
+    },
     cleanup() {
       act(() => {
         root.unmount();
@@ -256,6 +260,111 @@ describe("NLEPreview", () => {
     view.cleanup();
   });
 
+  describe("zoom", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      localStorage.clear();
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+      localStorage.clear();
+    });
+
+    /** A pinch (ctrl + wheel) over the preview, then the settle that follows it. */
+    function pinchIn(view: ReturnType<typeof renderPreview>, steps: number) {
+      act(() => {
+        for (let step = 0; step < steps; step += 1) {
+          const pinch = new WheelEvent("wheel", {
+            bubbles: true,
+            cancelable: true,
+            clientX: 400,
+            clientY: 300,
+            deltaY: -10,
+          });
+          // happy-dom drops ctrlKey from the WheelEvent init; a trackpad pinch sets it.
+          Object.defineProperty(pinch, "ctrlKey", { value: true });
+          view.stage.dispatchEvent(pinch);
+        }
+      });
+      act(() => vi.advanceTimersByTime(300));
+    }
+    const chip = (view: ReturnType<typeof renderPreview>) =>
+      view.host.querySelector('[data-testid="preview-zoom-chip"]');
+    const navigator = (view: ReturnType<typeof renderPreview>) =>
+      view.host.querySelector('[data-testid="preview-zoom-navigator"]');
+
+    it("labels a pan away from Fit without a zoom as panned", () => {
+      const view = renderPreview();
+      act(() => {
+        view.stage.dispatchEvent(
+          new WheelEvent("wheel", { bubbles: true, cancelable: true, deltaX: -30, deltaY: 0 }),
+        );
+      });
+      act(() => vi.advanceTimersByTime(300));
+      expect(chip(view)?.textContent).toBe("Panned·Fit");
+      view.cleanup();
+    });
+
+    it("keeps a click on Fit from reaching the pane behind it", () => {
+      const view = renderPreview();
+      // Above React's root, as the preview pane's handler is: React stops the event before either.
+      const pane = vi.fn();
+      document.body.addEventListener("pointerdown", pane);
+      pinchIn(view, 10);
+      act(() => {
+        view.host
+          .querySelector('[data-testid="preview-zoom-fit"]')!
+          .dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));
+      });
+      document.body.removeEventListener("pointerdown", pane);
+      expect(pane).not.toHaveBeenCalled();
+      view.cleanup();
+    });
+
+    it("opens at Fit even when an older Studio saved a zoom", () => {
+      localStorage.setItem(
+        "hf-studio-ui-preferences",
+        JSON.stringify({ previewZoom: { zoomPercent: 245, panX: 0, panY: 0 } }),
+      );
+      const view = renderPreview();
+      expect(view.stage.style.transform).toContain("scale(1)");
+      expect(chip(view)).toBeNull();
+      view.cleanup();
+    });
+
+    it("says how far it is zoomed, shows where in the frame, and Fit puts it back", () => {
+      const view = renderPreview();
+      expect([chip(view), navigator(view)]).toEqual([null, null]);
+
+      pinchIn(view, 10);
+      expect(chip(view)?.textContent).toMatch(/^Zoomed 2\d\d%·Fit$/);
+      const region = view.host.querySelector<HTMLElement>(
+        '[data-testid="preview-zoom-navigator-region"]',
+      );
+      expect(Number.parseFloat(region!.style.width)).toBeLessThan(100);
+
+      act(() => {
+        view.host.querySelector<HTMLButtonElement>('[data-testid="preview-zoom-fit"]')!.click();
+      });
+      act(() => vi.advanceTimersByTime(300));
+      expect(view.stage.style.transform).toContain("scale(1)");
+      expect([chip(view), navigator(view)]).toEqual([null, null]);
+      view.cleanup();
+    });
+
+    it("keeps a zoom only while the project is open: nothing is saved, and another project opens at Fit", () => {
+      const view = renderPreview();
+      pinchIn(view, 10);
+      expect(chip(view)).not.toBeNull();
+      expect(localStorage.getItem("hf-studio-ui-preferences") ?? "").not.toContain("previewZoom");
+
+      view.openProject("another-project");
+      expect(view.stage.style.transform).toContain("scale(1)");
+      expect(chip(view)).toBeNull();
+      view.cleanup();
+    });
+  });
+
   it("insets the picture by default and fills a same-shape box when fillBox is on", () => {
     const box = { width: 640, height: 360 };
     const inset = renderPreview(undefined, { box });
@@ -283,6 +392,77 @@ describe("NLEPreview", () => {
     view.cleanup();
   });
 
+  it("covers the live preview with the cached frame-0 poster until it is ready to show", () => {
+    const view = renderPreview();
+    const poster = () =>
+      view.stage.querySelector<HTMLImageElement>('[data-testid="preview-poster"]');
+    expect(poster()?.getAttribute("src")).toBe(
+      "/api/projects/timeline-edit-playground/thumbnail/index.html?t=0&output=source&cached=1",
+    );
+    expect(poster()?.style.zIndex).toBe("2");
+
+    act(() => livePlayerProps.onReadyToShowChange?.(false));
+    expect(poster()?.hidden).toBe(false);
+    act(() => livePlayerProps.onReadyToShowChange?.(true));
+    expect(poster()?.hidden).toBe(true);
+    act(() => poster()?.dispatchEvent(new Event("load")));
+    expect(poster()).toBeNull();
+    view.cleanup();
+  });
+
+  describe("a missing poster", () => {
+    const renderUrl =
+      "/api/projects/timeline-edit-playground/thumbnail/index.html?t=0&output=source";
+    const fetchSpy = vi.fn(() => Promise.resolve(new Response()));
+    beforeEach(() => {
+      fetchSpy.mockClear();
+      vi.stubGlobal("fetch", fetchSpy);
+    });
+    afterEach(() => vi.unstubAllGlobals());
+
+    const settle = (
+      view: ReturnType<typeof renderPreview>,
+      steps: Array<"ready" | "missing" | "loaded">,
+    ) => {
+      for (const step of steps) {
+        const poster = view.stage.querySelector('[data-testid="preview-poster"]');
+        act(() =>
+          step === "ready"
+            ? livePlayerProps.onReadyToShowChange?.(true)
+            : poster?.dispatchEvent(new Event(step === "missing" ? "error" : "load")),
+        );
+      }
+    };
+
+    it("is rendered for the next open when the live frame is ready first", () => {
+      const view = renderPreview();
+      settle(view, ["ready", "missing"]);
+      expect(fetchSpy.mock.calls).toEqual([[renderUrl]]);
+      expect(view.stage.querySelector('[data-testid="preview-poster"]')).toBeNull();
+      view.cleanup();
+    });
+
+    it("is rendered once the live frame is ready when it is missing first", () => {
+      const view = renderPreview();
+      settle(view, ["missing"]);
+      expect(fetchSpy).not.toHaveBeenCalled();
+      settle(view, ["ready", "ready"]);
+      expect(fetchSpy.mock.calls).toEqual([[renderUrl]]);
+      view.cleanup();
+    });
+
+    it("is rendered on a return from a sub-composition when the live frame is ready first", () => {
+      const view = renderPreview();
+      settle(view, ["loaded", "ready"]);
+      view.render("/api/projects/timeline-edit-playground/preview/comp/compositions/intro.html");
+      settle(view, ["ready"]);
+      view.render();
+      settle(view, ["ready", "missing"]);
+      expect(fetchSpy.mock.calls).toEqual([[renderUrl]]);
+      view.cleanup();
+    });
+  });
+
   it("mounts the live player once when the composition switches", () => {
     playerMounts.length = 0;
     const Harness = ({ projectId }: { projectId: string }) => {

package/src/components/nle/NLEPreview.tsx

@@ -2,7 +2,15 @@ import {
   readPreviewCompositionSize,
   type PreviewCompositionSize,
 } from "../../utils/previewCompositionSize";
-import { memo, useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
 import { Player } from "../../player";
 import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
 import {
@@ -10,6 +18,7 @@ import {
   canStartPreviewPan,
   clampPreviewPan,
   clampPreviewZoomPercent,
+  isPreviewAtFit,
   ownsPreviewPanTarget,
   resolvePreviewWheelPan,
   resolvePreviewWheelZoom,
@@ -17,8 +26,9 @@ import {
   type PreviewZoomState,
 } from "./previewZoom";
 import { RULER_GUTTER_PX, usePreviewGuidesStore } from "../editor/previewGuidesStore";
-import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { PreviewZoomOverlay, usePreviewNavigator } from "./PreviewZoomOverlay";
 import { usePreviewFirstFrameTelemetry } from "../../player/hooks/usePreviewFirstFrameTelemetry";
+import { PreviewPoster, usePreviewPoster } from "./PreviewPoster";
 interface NLEPreviewProps {
   projectId: string;
   iframeRef: RefObject<HTMLIFrameElement | null>;
@@ -64,25 +74,6 @@ const SHADOW_IFRAME_STYLE: React.CSSProperties = {
   pointerEvents: "none",
 };
 
-function isPreviewAtFit(state: PreviewZoomState): boolean {
-  return (
-    Math.abs(state.zoomPercent - 100) < 0.5 &&
-    Math.abs(state.panX) < 0.1 &&
-    Math.abs(state.panY) < 0.1
-  );
-}
-
-function loadInitialZoom(): PreviewZoomState {
-  const stored = readStudioUiPreferences().previewZoom;
-  return stored
-    ? {
-        zoomPercent: clampPreviewZoomPercent(stored.zoomPercent),
-        panX: stored.panX,
-        panY: stored.panY,
-      }
-    : DEFAULT_PREVIEW_ZOOM;
-}
-
 export function resolvePreviewStageSize(
   viewportWidth: number,
   viewportHeight: number,
@@ -154,12 +145,13 @@ export const NLEPreview = memo(function NLEPreview({
   const liveGenRef = useRef<number | null>(null);
   const reportPreviewFirstFrame = usePreviewFirstFrameTelemetry(previewSlots);
   const [compositionSize, setCompositionSize] = useState<PreviewCompositionSize | null>(null);
+  const poster = usePreviewPoster(projectId, activeKey, directUrl);
   const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
   const insetPx = fillBox ? 0 : PREVIEW_STAGE_INSET_PX;
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
 
-  const zoomRef = useRef<PreviewZoomState>(loadInitialZoom());
-  const [settledZoom, setSettledZoom] = useState<PreviewZoomState>(() => zoomRef.current);
+  const zoomRef = useRef<PreviewZoomState>(DEFAULT_PREVIEW_ZOOM);
+  const [settledZoom, setSettledZoom] = useState<PreviewZoomState>(DEFAULT_PREVIEW_ZOOM);
   const hudRef = useRef<HTMLDivElement>(null);
   const hudTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const settleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -230,14 +222,33 @@ export const NLEPreview = memo(function NLEPreview({
   const stageSizeRef = useRef(stageSize);
   stageSizeRef.current = stageSize;
 
-  const writeTransform = useCallback((state: PreviewZoomState) => {
-    const stage = stageRef.current;
-    if (!stage) return;
-    const s = toDomPrecision(state.zoomPercent / 100);
-    const px = toDomPrecision(state.panX);
-    const py = toDomPrecision(state.panY);
-    stage.style.transform = `translate3d(${px}px, ${py}px, 0) scale(${s})`;
-  }, []);
+  const { draw: drawNavigator, setRegion: setNavigatorRegion } = usePreviewNavigator(
+    viewportRef,
+    stageSize,
+    zoomRef,
+  );
+  const writeTransform = useCallback(
+    (state: PreviewZoomState) => {
+      const stage = stageRef.current;
+      if (!stage) return;
+      const s = toDomPrecision(state.zoomPercent / 100);
+      const px = toDomPrecision(state.panX);
+      const py = toDomPrecision(state.panY);
+      stage.style.transform = `translate3d(${px}px, ${py}px, 0) scale(${s})`;
+      drawNavigator(state);
+    },
+    [drawNavigator],
+  );
+
+  const zoomProjectRef = useRef(projectId);
+  // Before paint, so the next project never shows a frame at the previous one's zoom.
+  useLayoutEffect(() => {
+    if (zoomProjectRef.current === projectId) return;
+    zoomProjectRef.current = projectId;
+    zoomRef.current = DEFAULT_PREVIEW_ZOOM;
+    writeTransform(DEFAULT_PREVIEW_ZOOM);
+    setSettledZoom(DEFAULT_PREVIEW_ZOOM);
+  }, [projectId, writeTransform]);
 
   const applyTransform = useCallback(
     (next: PreviewZoomState, showHud: boolean) => {
@@ -267,7 +278,6 @@ export const NLEPreview = memo(function NLEPreview({
       settleTimerRef.current = setTimeout(() => {
         zoomingRef.current = false;
         const final = zoomRef.current;
-        writeStudioUiPreferences({ previewZoom: final });
         setSettledZoom((prev) =>
           prev.zoomPercent === final.zoomPercent &&
           prev.panX === final.panX &&
@@ -302,9 +312,8 @@ export const NLEPreview = memo(function NLEPreview({
 
   const applyInitialZoom = useCallback(() => {
     const z = zoomRef.current;
-    if (Math.abs(z.zoomPercent - 100) > 0.5 || Math.abs(z.panX) > 0.1 || Math.abs(z.panY) > 0.1) {
-      // A pan persisted on a large window can restore the composition mostly
-      // off-screen in a smaller one; clamp against the current viewport first.
+    if (!isPreviewAtFit(z)) {
+      // A composition reload can bring a different frame size than the pan was made on; clamp first.
       const viewport = viewportRef.current;
       const rect = viewport?.getBoundingClientRect();
       const sz = stageSizeRef.current;
@@ -522,6 +531,8 @@ export const NLEPreview = memo(function NLEPreview({
                     applyInitialZoom();
                   }}
                   onCompositionLoadingChange={onCompositionLoadingChange}
+                  onReadyToShowChange={poster.onLiveReadyToShowChange}
+                  onPreviewError={poster.onPreviewError}
                   onPainted={(details) => reportPreviewFirstFrame(slot, details)}
                   portrait={portrait}
                   suppressLoadingOverlay={suppressLoadingOverlay}
@@ -547,6 +558,16 @@ export const NLEPreview = memo(function NLEPreview({
                 />
               ),
             )}
+            {poster.mountPoster && (
+              <PreviewPoster
+                key={activeKey}
+                projectId={projectId}
+                hidden={poster.hidePoster}
+                onSize={(size) => setCompositionSize((prev) => prev ?? size)}
+                onLoaded={poster.onPosterLoaded}
+                onMissing={poster.onPosterMissing}
+              />
+            )}
           </div>
         </div>
         <div
@@ -555,17 +576,15 @@ export const NLEPreview = memo(function NLEPreview({
           style={{ opacity: 0, transition: "opacity 200ms ease-in" }}
           aria-live="polite"
         />
-        {!isPreviewAtFit(settledZoom) && (
-          <button
-            type="button"
-            className="absolute bottom-3 right-3 z-50 rounded-md px-2.5 py-1 text-xs font-medium text-white/80 bg-black/50 backdrop-blur-xs hover:bg-black/70 hover:text-white transition-colors"
-            onClick={() => applyZoom(DEFAULT_PREVIEW_ZOOM)}
-            aria-label="Reset zoom to fit"
-            data-testid="preview-reset-zoom"
-          >
-            {Math.round(settledZoom.zoomPercent)}% — Reset
-          </button>
-        )}
+        <PreviewZoomOverlay
+          zoom={settledZoom}
+          stageSize={stageSize}
+          onFit={() => {
+            applyZoom(DEFAULT_PREVIEW_ZOOM);
+            viewportRef.current?.focus();
+          }}
+          navigatorRegionRef={setNavigatorRegion}
+        />
       </div>
     </div>
   );

package/src/components/nle/PreviewPoster.tsx

@@ -0,0 +1,99 @@
+import { useCallback, useRef, useState } from "react";
+import { buildProjectApiPath } from "../../utils/projectRouting";
+import type { PreviewCompositionSize } from "../../utils/previewCompositionSize";
+
+/** Frame 0 as the thumbnail route last rendered it; `cachedOnly` never starts a render. */
+function previewPosterUrl(projectId: string, cachedOnly: boolean): string {
+  const query = `t=0&output=source${cachedOnly ? "&cached=1" : ""}`;
+  return buildProjectApiPath(projectId, `/thumbnail/index.html?${query}`);
+}
+
+const PREVIEW_POSTER_STYLE: React.CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  objectFit: "contain",
+  zIndex: 2,
+  pointerEvents: "none",
+};
+
+/** Covers the live preview with the cached frame 0; reports its size so the stage fits it. */
+export function PreviewPoster({
+  projectId,
+  hidden,
+  onSize,
+  onLoaded,
+  onMissing,
+}: {
+  projectId: string;
+  hidden: boolean;
+  onSize: (size: PreviewCompositionSize) => void;
+  onLoaded: () => void;
+  onMissing: () => void;
+}) {
+  return (
+    <img
+      src={previewPosterUrl(projectId, true)}
+      alt=""
+      aria-hidden
+      data-testid="preview-poster"
+      hidden={hidden}
+      style={PREVIEW_POSTER_STYLE}
+      onLoad={(event) => {
+        const { naturalWidth: width, naturalHeight: height } = event.currentTarget;
+        if (!hidden && width > 0 && height > 0) onSize({ width, height });
+        onLoaded();
+      }}
+      onError={onMissing}
+    />
+  );
+}
+
+/** The poster covers the live slot until its first frame is ready; a missing poster is rendered
+ * after both are known, in either order, off the open path, for the next open. */
+export function usePreviewPoster(
+  projectId: string,
+  activeKey: string,
+  directUrl: string | undefined,
+) {
+  const visit = useVisitNumber(activeKey);
+  const [coverDoneFor, setCoverDoneFor] = useState<number | null>(null);
+  const [posterSettledFor, setPosterSettledFor] = useState<number | null>(null);
+  const missingForRef = useRef<number | null>(null);
+  const liveReadyForRef = useRef<number | null>(null);
+  const renderMissingPoster = useCallback(() => {
+    if (missingForRef.current !== visit || liveReadyForRef.current !== visit) return;
+    missingForRef.current = null;
+    void fetch(previewPosterUrl(projectId, false)).catch(() => {});
+  }, [visit, projectId]);
+  const onLiveReadyToShowChange = useCallback(
+    (ready: boolean) => {
+      if (!ready) return;
+      setCoverDoneFor(visit);
+      liveReadyForRef.current = visit;
+      renderMissingPoster();
+    },
+    [visit, renderMissingPoster],
+  );
+  return {
+    mountPoster: !directUrl && (coverDoneFor !== visit || posterSettledFor !== visit),
+    hidePoster: coverDoneFor === visit,
+    onLiveReadyToShowChange,
+    onPreviewError: () => setCoverDoneFor(visit),
+    onPosterLoaded: () => setPosterSettledFor(visit),
+    onPosterMissing: () => {
+      setCoverDoneFor(visit);
+      setPosterSettledFor(visit);
+      missingForRef.current = visit;
+      renderMissingPoster();
+    },
+  };
+}
+
+function useVisitNumber(key: string): number {
+  const [seen, setSeen] = useState({ key, visit: 0 });
+  if (seen.key === key) return seen.visit;
+  setSeen({ key, visit: seen.visit + 1 });
+  return seen.visit + 1;
+}

package/src/components/nle/PreviewZoomOverlay.tsx

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+import {
+  isFitZoom,
+  isPreviewAtFit,
+  resolvePreviewVisibleRegion,
+  toDomPrecision,
+  type PreviewZoomState,
+} from "./previewZoom";
+
+const NAVIGATOR_PX = 112;
+
+function zoomChipLabel(zoomPercent: number): string {
+  return isFitZoom(zoomPercent) ? "Panned" : `Zoomed ${Math.round(zoomPercent)}%`;
+}
+
+function navigatorFrameSize(stage: { width: number; height: number }) {
+  const ratio = stage.width > 0 && stage.height > 0 ? stage.width / stage.height : 16 / 9;
+  return ratio >= 1
+    ? { width: NAVIGATOR_PX, height: toDomPrecision(NAVIGATOR_PX / ratio) }
+    : { width: toDomPrecision(NAVIGATOR_PX * ratio), height: NAVIGATOR_PX };
+}
+
+/** `draw` moves the navigator's highlight without a render, so it can follow every transform write. */
+export function usePreviewNavigator(
+  viewportRef: RefObject<HTMLDivElement | null>,
+  stageSize: { width: number; height: number },
+  zoomRef: RefObject<PreviewZoomState>,
+) {
+  const regionRef = useRef<HTMLDivElement | null>(null);
+  const stageSizeRef = useRef(stageSize);
+  stageSizeRef.current = stageSize;
+  const draw = useCallback(
+    (state: PreviewZoomState) => {
+      const region = regionRef.current;
+      const rect = viewportRef.current?.getBoundingClientRect();
+      if (!region || !rect) return;
+      const visible = resolvePreviewVisibleRegion({
+        state,
+        viewportWidth: rect.width,
+        viewportHeight: rect.height,
+        contentWidth: stageSizeRef.current.width,
+        contentHeight: stageSizeRef.current.height,
+      });
+      region.style.left = `${visible.left * 100}%`;
+      region.style.top = `${visible.top * 100}%`;
+      region.style.width = `${visible.width * 100}%`;
+      region.style.height = `${visible.height * 100}%`;
+    },
+    [viewportRef],
+  );
+  const setRegion = useCallback(
+    (node: HTMLDivElement | null) => {
+      regionRef.current = node;
+      draw(zoomRef.current);
+    },
+    [draw, zoomRef],
+  );
+  useEffect(() => draw(zoomRef.current), [stageSize, draw, zoomRef]);
+  return { draw, setRegion };
+}
+
+export function PreviewZoomOverlay({
+  zoom,
+  stageSize,
+  onFit,
+  navigatorRegionRef,
+}: {
+  zoom: PreviewZoomState;
+  stageSize: { width: number; height: number };
+  onFit: () => void;
+  navigatorRegionRef: (node: HTMLDivElement | null) => void;
+}) {
+  if (isPreviewAtFit(zoom)) return null;
+  return (
+    <>
+      <div
+        className="absolute top-3 left-1/2 -translate-x-1/2 z-50 flex items-center gap-1.5 rounded-md py-1 pl-2.5 pr-1 text-xs text-white/80 bg-black/60 backdrop-blur-xs"
+        data-testid="preview-zoom-chip"
+        // The pane clears the timeline selection on a pointerdown outside the frame.
+        onPointerDown={(event) => event.stopPropagation()}
+      >
+        <span className="tabular-nums">{zoomChipLabel(zoom.zoomPercent)}</span>
+        <span aria-hidden="true" className="text-white/30">
+          ·
+        </span>
+        <button
+          type="button"
+          className="rounded px-1.5 py-0.5 font-medium text-studio-accent hover:bg-white/10 transition-colors"
+          onClick={onFit}
+          aria-label="Fit the whole frame in view"
+          data-testid="preview-zoom-fit"
+        >
+          Fit
+        </button>
+      </div>
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute bottom-3 right-3 z-50 rounded-md p-1.5 bg-black/60 backdrop-blur-xs"
+        data-testid="preview-zoom-navigator"
+      >
+        <div className="relative overflow-hidden bg-white/10" style={navigatorFrameSize(stageSize)}>
+          <div
+            ref={navigatorRegionRef}
+            className="absolute rounded-[1px] border border-studio-accent bg-studio-accent/15"
+            data-testid="preview-zoom-navigator-region"
+          />
+        </div>
+      </div>
+    </>
+  );
+}