@hyperframes/studio 0.8.76 → 0.8.78

package/package.json

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

package/src/components/editor/domEditingElement.ts

@@ -314,6 +314,19 @@ export function findElementForSelection(
   return findAll(selection.selector)[selection.selectorIndex ?? 0] ?? null;
 }
 
+// The selected node while mounted, else its copy in the selection's own file (ids repeat across files), else any copy.
+export function findPreviewNode(
+  doc: Document | null | undefined,
+  el: DomEditSelection,
+): Element | null {
+  if (!doc) return null;
+  if (el.element?.isConnected && el.element.ownerDocument === doc) return el.element;
+  return (
+    findElementForSelection(doc, el) ??
+    findElementForSelection(doc, { ...el, sourceFile: undefined })
+  );
+}
+
 // fallow-ignore-next-line complexity
 export function findElementForTimelineElement(
   doc: Document,

package/src/components/editor/gsapLivePreview.test.ts

@@ -0,0 +1,63 @@
+// @vitest-environment happy-dom
+import { expect, it, vi } from "vitest";
+import { createGsapLivePreview } from "./gsapLivePreview";
+import type { DomEditSelection } from "./domEditingTypes";
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
+import { readGsapRuntimeValuesForPanel } from "./propertyPanelHelpers";
+
+it("previews on the selected element, not an earlier same-id copy in a sub-composition", () => {
+  document.body.innerHTML =
+    '<div data-composition-id="strip"><div id="card" data-hf-id="hf-inner"></div></div>' +
+    '<div id="card" data-hf-id="hf-root"></div>';
+  const set = vi.fn();
+  const iframe = { contentWindow: { gsap: { set } }, contentDocument: document };
+  const preview = createGsapLivePreview({ current: iframe as unknown as HTMLIFrameElement });
+  preview({ id: "card", hfId: "hf-root" } as DomEditSelection, { x: 10 });
+  expect(set.mock.calls[0]?.[0]).toBe(document.querySelector('[data-hf-id="hf-root"]'));
+});
+
+it("previews on the copy in the selection's own file when a sub-composition repeats its hf-id", () => {
+  document.body.innerHTML =
+    '<div data-composition-id="strip" data-composition-src="compositions/strip.html">' +
+    '<div id="card" data-hf-id="hf-card"></div></div><div id="card" data-hf-id="hf-card" class="root"></div>';
+  const set = vi.fn();
+  const iframe = { contentWindow: { gsap: { set } }, contentDocument: document };
+  const preview = createGsapLivePreview({ current: iframe as unknown as HTMLIFrameElement });
+  preview({ id: "card", hfId: "hf-card", sourceFile: "index.html" } as DomEditSelection, { x: 10 });
+  expect(set.mock.calls[0]?.[0]).toBe(document.querySelector(".root"));
+});
+
+it("previews on the selected node while it is mounted, even in a second mount of the same sub-composition", () => {
+  document.body.innerHTML =
+    '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><div id="card" data-hf-id="hf-card"></div></div>' +
+    '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><div id="card" data-hf-id="hf-card"></div></div>';
+  const second = document.querySelectorAll<HTMLElement>("#card")[1];
+  const selection = {
+    id: "card",
+    hfId: "hf-card",
+    sourceFile: "compositions/strip.html",
+    element: second,
+  };
+  const set = vi.fn();
+  const iframe = { contentWindow: { gsap: { set } }, contentDocument: document };
+  createGsapLivePreview({ current: iframe as unknown as HTMLIFrameElement })(
+    selection as DomEditSelection,
+    { x: 10 },
+  );
+  expect(set.mock.calls[0]?.[0]).toBe(second);
+});
+
+it("the panel reads GSAP values off the node the live preview moves", () => {
+  document.body.innerHTML =
+    '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><div id="card"></div></div>' +
+    '<div id="card" class="root"></div>';
+  const root = document.querySelector<HTMLElement>(".root");
+  const getProperty = vi.fn(() => 5);
+  const iframe = { contentWindow: { gsap: { getProperty } }, contentDocument: document };
+  const selection = { id: "card", sourceFile: "index.html", element: root } as DomEditSelection;
+  const animations = [{ properties: { x: 5 } }] as unknown as GsapAnimation[];
+  readGsapRuntimeValuesForPanel("anim", animations, selection, {
+    current: iframe as unknown as HTMLIFrameElement,
+  });
+  expect(getProperty.mock.calls[0]?.[0]).toBe(root);
+});

package/src/components/editor/gsapLivePreview.ts

@@ -1,4 +1,5 @@
 import type { DomEditSelection } from "./domEditingTypes";
+import { findPreviewNode } from "./domEditingElement";
 
 /**
  * Build the "live preview" callback the 3D-transform sub-view fires while a
@@ -8,19 +9,6 @@ import type { DomEditSelection } from "./domEditingTypes";
  * Extracted so the identical closure exists once — shared by the legacy
  * PropertyPanel Layout section and the flat Layout group (PropertyPanelFlat).
  */
-// Resolve by id when unique, otherwise by selector + selectorIndex — a bare
-// querySelector(selector) always hits the FIRST match, so dragging on the
-// second of two same-selector siblings would animate the wrong element.
-function resolvePreviewNode(
-  doc: Document | null | undefined,
-  el: DomEditSelection,
-): Element | null {
-  if (!doc) return null;
-  if (el.id) return doc.querySelector(`#${el.id}`);
-  if (!el.selector) return null;
-  return doc.querySelectorAll(el.selector)[el.selectorIndex ?? 0] ?? null;
-}
-
 export function createGsapLivePreview(iframeRef: { readonly current: HTMLIFrameElement | null }) {
   return (el: DomEditSelection, props: Record<string, number>) => {
     const iframe = iframeRef.current;
@@ -28,7 +16,7 @@ export function createGsapLivePreview(iframeRef: { readonly current: HTMLIFrameE
       | { gsap?: { set: (t: Element, v: Record<string, number>) => void } }
       | null
       | undefined;
-    const node = resolvePreviewNode(iframe?.contentDocument, el);
+    const node = findPreviewNode(iframe?.contentDocument, el);
     if (win?.gsap && node) win.gsap.set(node, props);
   };
 }

package/src/components/editor/propertyPanelHelpers.ts

@@ -4,6 +4,7 @@ import type { DomEditSelection } from "./domEditing";
 import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import type { TimelineElement } from "../../player";
 import { roundToCenti } from "../../utils/rounding";
+import { findPreviewNode } from "./domEditingElement";
 
 export type {
   BackgroundRemovalProgress,
@@ -470,8 +471,6 @@ export function readGsapRuntimeValuesForPanel(
   if (!gsapAnimId || gsapAnimations.length === 0) return null;
   const iframe = previewIframeRef?.current;
   if (!iframe?.contentWindow) return null;
-  const selector = element.id ? `#${element.id}` : element.selector;
-  if (!selector) return null;
   try {
     const gsap = (
       iframe.contentWindow as unknown as {
@@ -479,7 +478,7 @@ export function readGsapRuntimeValuesForPanel(
       }
     ).gsap;
     if (!gsap?.getProperty) return null;
-    const el = iframe.contentDocument?.querySelector(selector);
+    const el = findPreviewNode(iframe.contentDocument, element);
     if (!el) return null;
     const propKeys = collectPanelPropKeys(gsapAnimations);
     const result: Record<string, number> = {};
@@ -508,10 +507,9 @@ export function readGsapBorderRadiusForPanel(
     if (!hasBRProp) return null;
   }
   const iframe = previewIframeRef?.current;
-  const selector = element.id ? `#${element.id}` : element.selector;
-  if (!iframe?.contentDocument || !selector) return null;
+  if (!iframe?.contentDocument) return null;
   try {
-    const el = iframe.contentDocument.querySelector(selector);
+    const el = findPreviewNode(iframe.contentDocument, element);
     if (!el || !iframe.contentWindow) return null;
     const cs = iframe.contentWindow.getComputedStyle(el);
     const parse = (v: string) => Number.parseFloat(v) || 0;

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

@@ -40,11 +40,6 @@ vi.mock("../../player", async () => {
   };
 });
 
-vi.mock("../../utils/studioUiPreferences", () => ({
-  readStudioUiPreferences: () => ({}),
-  writeStudioUiPreferences: () => {},
-}));
-
 let resizeCallbacks: Array<() => void> = [];
 
 class MockResizeObserver {
@@ -93,11 +88,11 @@ function renderPreview(
   document.body.append(host);
   const root = createRoot(host);
   const iframeRef = createRef<HTMLIFrameElement>();
-  const render = (directUrl?: string) =>
+  const render = (directUrl?: string, projectId = "timeline-edit-playground") =>
     act(() => {
       root.render(
         React.createElement(NLEPreview, {
-          projectId: "timeline-edit-playground",
+          projectId,
           directUrl,
           iframeRef,
           onIframeLoad: () => {},
@@ -129,6 +124,9 @@ function renderPreview(
     render,
     viewport,
     stage,
+    openProject(projectId: string) {
+      render(undefined, projectId);
+    },
     cleanup() {
       act(() => {
         root.unmount();
@@ -262,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 });

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,7 +26,7 @@ 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 {
@@ -65,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,
@@ -160,8 +150,8 @@ export const NLEPreview = memo(function NLEPreview({
   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);
@@ -232,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) => {
@@ -269,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 &&
@@ -304,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;
@@ -569,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/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>
+    </>
+  );
+}

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

@@ -13,6 +13,7 @@ import {
   ownsPreviewPanTarget,
   PREVIEW_PAN_OVERSCROLL_PX,
   PREVIEW_PAN_SURFACE_SELECTOR,
+  resolvePreviewVisibleRegion,
   resolvePreviewWheelPan,
   resolvePreviewWheelZoom,
   toDomPrecision,
@@ -321,3 +322,44 @@ describe("resolvePreviewWheelPan", () => {
     expect(next.panY).toBe(-PREVIEW_PAN_OVERSCROLL_PX);
   });
 });
+
+describe("resolvePreviewVisibleRegion", () => {
+  const frame = { viewportWidth: 1000, viewportHeight: 600, contentWidth: 800, contentHeight: 450 };
+
+  it("shows the whole frame at Fit", () => {
+    expect(resolvePreviewVisibleRegion({ state: DEFAULT_PREVIEW_ZOOM, ...frame })).toEqual({
+      left: 0,
+      top: 0,
+      width: 1,
+      height: 1,
+    });
+  });
+
+  it("shows the centre part at 200%, and the part the pan moved to", () => {
+    const zoomed = { zoomPercent: 200, panX: 0, panY: 0 };
+    const centre = resolvePreviewVisibleRegion({ state: zoomed, ...frame });
+    expect(centre.width).toBeCloseTo(1000 / 1600);
+    expect(centre.left).toBeCloseTo((1 - 1000 / 1600) / 2);
+    expect(centre.height).toBeCloseTo(600 / 900);
+
+    // Panning right by 300px brings the frame's left side into view.
+    const panned = resolvePreviewVisibleRegion({ state: { ...zoomed, panX: 300 }, ...frame });
+    expect(panned.left).toBeCloseTo(centre.left - 300 / 1600);
+    expect(panned.width).toBeCloseTo(centre.width);
+  });
+
+  it("is the whole frame below 100%, and stops at the frame's edge in an overscroll", () => {
+    const small = resolvePreviewVisibleRegion({
+      state: { zoomPercent: 50, panX: 0, panY: 0 },
+      ...frame,
+    });
+    expect(small).toEqual({ left: 0, top: 0, width: 1, height: 1 });
+
+    const past = resolvePreviewVisibleRegion({
+      state: { zoomPercent: 200, panX: 400, panY: 0 },
+      ...frame,
+    });
+    expect(past.left).toBe(0);
+    expect(past.width).toBeCloseTo((1000 / 2 - 400 + 800) / 1600);
+  });
+});