@hyperframes/studio 0.6.2 → 0.6.4

package/src/components/editor/propertyPanelPrimitives.tsx

@@ -334,24 +334,43 @@ export function Section({
   icon,
   children,
   accessory,
+  defaultCollapsed = false,
 }: {
   title: string;
   icon: ReactNode;
   children: ReactNode;
   accessory?: ReactNode;
+  defaultCollapsed?: boolean;
 }) {
+  const [collapsed, setCollapsed] = useState(defaultCollapsed);
+
   return (
-    <section className="min-w-0 border-t border-neutral-800/80 px-4 py-4">
-      <div className="mb-3 flex min-w-0 flex-wrap items-center justify-between gap-2">
+    <section className="min-w-0 border-t border-neutral-800/80">
+      <button
+        type="button"
+        onClick={() => setCollapsed((v) => !v)}
+        className="flex w-full items-center justify-between gap-2 px-4 py-3"
+      >
         <div className="flex min-w-0 items-center gap-2.5">
           <span className="flex-shrink-0 text-neutral-500">{icon}</span>
           <h3 className="text-[11px] font-semibold uppercase tracking-[0.12em] text-neutral-300">
             {title}
           </h3>
         </div>
-        {accessory}
-      </div>
-      {children}
+        <div className="flex items-center gap-2">
+          {accessory}
+          <svg
+            width="10"
+            height="10"
+            viewBox="0 0 10 10"
+            fill="currentColor"
+            className={`flex-shrink-0 text-neutral-500 transition-transform ${collapsed ? "-rotate-90" : ""}`}
+          >
+            <path d="M2 3l3 4 3-4z" />
+          </svg>
+        </div>
+      </button>
+      {!collapsed && <div className="px-4 pb-4">{children}</div>}
     </section>
   );
 }

package/src/components/editor/propertyPanelStyleSections.tsx

@@ -109,7 +109,7 @@ export function StyleSections({
   return (
     <>
       {isFlex && (
-        <Section title="Flex" icon={<Layers size={15} />}>
+        <Section title="Flex" icon={<Layers size={15} />} defaultCollapsed>
           <div className="space-y-4">
             <SegmentedControl
               disabled={styleEditingDisabled}
@@ -154,7 +154,7 @@ export function StyleSections({
       )}
 
       {hasVisualBackground && (
-        <Section title="Radius" icon={<Settings size={15} />}>
+        <Section title="Radius" icon={<Settings size={15} />} defaultCollapsed>
           <SliderControl
             value={radiusValue}
             min={0}
@@ -168,7 +168,7 @@ export function StyleSections({
         </Section>
       )}
 
-      <Section title="Stroke" icon={<Square size={15} />}>
+      <Section title="Stroke" icon={<Square size={15} />} defaultCollapsed>
         <div className="space-y-4">
           <div className={RESPONSIVE_GRID}>
             <MetricField
@@ -226,7 +226,7 @@ export function StyleSections({
         </div>
       </Section>
 
-      <Section title="Effects" icon={<Zap size={15} />}>
+      <Section title="Effects" icon={<Zap size={15} />} defaultCollapsed>
         <div className="space-y-4">
           <SelectField
             label="Shadow"
@@ -279,7 +279,7 @@ export function StyleSections({
         </div>
       </Section>
 
-      <Section title="Clip" icon={<Layers size={15} />}>
+      <Section title="Clip" icon={<Layers size={15} />} defaultCollapsed>
         <div className="space-y-4">
           <div className={RESPONSIVE_GRID}>
             <SelectField
@@ -325,7 +325,7 @@ export function StyleSections({
         </div>
       </Section>
 
-      <Section title="Transparency" icon={<Eye size={15} />}>
+      <Section title="Transparency" icon={<Eye size={15} />} defaultCollapsed>
         <div className="space-y-4">
           <SliderControl
             value={opacityValue}

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -23,12 +23,7 @@ import {
   restoreStudioPathOffset,
   restoreStudioRotation,
 } from "./manualEdits";
-import {
-  type GroupOverlayItem,
-  type OverlayRect,
-  groupOverlayItemsEqual,
-  rectsEqual,
-} from "./domEditOverlayGeometry";
+import { type GroupOverlayItem, type OverlayRect } from "./domEditOverlayGeometry";
 import {
   BLOCKED_MOVE_THRESHOLD_PX,
   type BlockedMoveState,
@@ -87,8 +82,6 @@ export type UseDomEditOverlayGesturesOptions = {
 
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
-    if (rectsEqual(opts.overlayRectRef.current, next)) return;
-    opts.overlayRectRef.current = next;
     opts.setOverlayRect(next);
   };
   const restoreGestureOverlayRect = (g: GestureState) => {
@@ -102,8 +95,6 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     });
   };
   const setDraftGroupOverlayItems = (next: GroupOverlayItem[]) => {
-    if (groupOverlayItemsEqual(opts.groupOverlayItemsRef.current, next)) return;
-    opts.groupOverlayItemsRef.current = next;
     opts.setGroupOverlayItems(next);
   };
 

package/src/components/nle/NLELayout.tsx

@@ -247,9 +247,11 @@ export const NLELayout = memo(function NLELayout({
   const currentLevel = compositionStack[compositionStack.length - 1];
   const directUrl = compositionStack.length > 1 ? currentLevel.previewUrl : undefined;
 
+  const onIframeRefStable = useRef(onIframeRef);
+  onIframeRefStable.current = onIframeRef;
   useEffect(() => {
-    onIframeRef?.(iframeRef.current);
-  }, [compositionStack.length, onIframeRef, refreshKey, iframeRef]);
+    onIframeRefStable.current?.(iframeRef.current);
+  }, [compositionStack.length, refreshKey, iframeRef]);
 
   // Resize divider handlers
   const handleDividerPointerDown = useCallback(

package/src/components/nle/NLEPreview.tsx

@@ -1,5 +1,14 @@
-import { memo, useRef, useState, type Ref } from "react";
+import { memo, useCallback, useEffect, useRef, useState, type Ref } from "react";
 import { Player } from "../../player";
+import {
+  DEFAULT_PREVIEW_ZOOM,
+  clampPreviewPan,
+  clampPreviewZoomPercent,
+  resolvePreviewWheelZoom,
+  toDomPrecision,
+  type PreviewZoomState,
+} from "./previewZoom";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 
 interface NLEPreviewProps {
   projectId: string;
@@ -23,17 +32,20 @@ export function getPreviewPlayerKey({
   return directUrl ?? projectId;
 }
 
-/**
- * Manages the composition preview with crossfade on reload.
- *
- * When refreshKey changes, a new Player is mounted alongside the old one.
- * The old Player stays visible (opacity 1) until the new one fires onLoad,
- * at which point the old is removed. This avoids the flash that a simple
- * key-swap remount would cause.
- *
- * Uses the render-time state adjustment pattern (React-sanctioned) to detect
- * refreshKey changes — no useEffect needed.
- */
+const ZOOM_HUD_TIMEOUT_MS = 1200;
+const ZOOM_SETTLE_MS = 200;
+
+function loadInitialZoom(): PreviewZoomState {
+  const stored = readStudioUiPreferences().previewZoom;
+  return stored
+    ? {
+        zoomPercent: clampPreviewZoomPercent(stored.zoomPercent),
+        panX: stored.panX,
+        panY: stored.panY,
+      }
+    : DEFAULT_PREVIEW_ZOOM;
+}
+
 export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
@@ -46,12 +58,78 @@ export const NLEPreview = memo(function NLEPreview({
 }: NLEPreviewProps) {
   const baseKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
   const prevRefreshKeyRef = useRef(refreshKey);
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const stageRef = useRef<HTMLDivElement>(null);
   const [retiringKey, setRetiringKey] = useState<string | null>(null);
   const retiringTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // Detect refreshKey change during render (React-sanctioned derived state pattern).
-  // When the key changes, the current active player becomes the retiring player
-  // and a new active player is mounted alongside it.
+  const zoomRef = useRef<PreviewZoomState>(loadInitialZoom());
+  const hudRef = useRef<HTMLDivElement>(null);
+  const hudTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const settleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const zoomingRef = useRef(false);
+  const dragRef = useRef<{
+    pointerId: number;
+    startX: number;
+    startY: number;
+    originX: number;
+    originY: number;
+  } | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (settleTimerRef.current) clearTimeout(settleTimerRef.current);
+      if (hudTimerRef.current) clearTimeout(hudTimerRef.current);
+      if (retiringTimerRef.current) clearTimeout(retiringTimerRef.current);
+    };
+  }, []);
+
+  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.zoom = String(s);
+    stage.style.transform = `translate(${px}px, ${py}px)`;
+  }, []);
+
+  const applyZoom = useCallback(
+    (next: PreviewZoomState) => {
+      const clamped: PreviewZoomState = {
+        zoomPercent: clampPreviewZoomPercent(next.zoomPercent),
+        panX: Number.isFinite(next.panX) ? next.panX : 0,
+        panY: Number.isFinite(next.panY) ? next.panY : 0,
+      };
+      zoomRef.current = clamped;
+
+      if (!zoomingRef.current) {
+        zoomingRef.current = true;
+        const hud = hudRef.current;
+        if (hud) hud.style.opacity = "1";
+      }
+
+      writeTransform(clamped);
+
+      if (settleTimerRef.current) clearTimeout(settleTimerRef.current);
+      settleTimerRef.current = setTimeout(() => {
+        zoomingRef.current = false;
+        const final = zoomRef.current;
+        writeStudioUiPreferences({ previewZoom: final });
+        const hud = hudRef.current;
+        if (hud) {
+          const zoomed = Math.abs(final.zoomPercent - 100) > 0.5;
+          hud.textContent = zoomed ? `${Math.round(final.zoomPercent)}%` : "Fit";
+          if (hudTimerRef.current) clearTimeout(hudTimerRef.current);
+          hudTimerRef.current = setTimeout(() => {
+            if (hudRef.current) hudRef.current.style.opacity = "0";
+          }, ZOOM_HUD_TIMEOUT_MS);
+        }
+      }, ZOOM_SETTLE_MS);
+    },
+    [writeTransform],
+  );
+
   if (refreshKey !== prevRefreshKeyRef.current) {
     const oldKey = `${baseKey}:${prevRefreshKeyRef.current ?? 0}`;
     prevRefreshKeyRef.current = refreshKey;
@@ -60,8 +138,16 @@ export const NLEPreview = memo(function NLEPreview({
 
   const activeKey = `${baseKey}:${refreshKey ?? 0}`;
 
+  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) {
+      writeTransform(z);
+    }
+  }, [writeTransform]);
+
   const handleNewPlayerLoad = () => {
     onIframeLoad();
+    applyInitialZoom();
     if (retiringTimerRef.current) clearTimeout(retiringTimerRef.current);
     retiringTimerRef.current = setTimeout(() => {
       setRetiringKey(null);
@@ -69,33 +155,167 @@ export const NLEPreview = memo(function NLEPreview({
     }, 160);
   };
 
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+
+    let lastZoomTime = 0;
+
+    const handleWheel = (event: WheelEvent) => {
+      const rect = viewport.getBoundingClientRect();
+      if (
+        event.clientX < rect.left ||
+        event.clientX > rect.right ||
+        event.clientY < rect.top ||
+        event.clientY > rect.bottom
+      ) {
+        return;
+      }
+
+      const isZoomGesture = event.ctrlKey || event.metaKey;
+
+      if (isZoomGesture) {
+        lastZoomTime = Date.now();
+        event.preventDefault();
+        event.stopPropagation();
+
+        const next = resolvePreviewWheelZoom({
+          state: zoomRef.current,
+          deltaY: event.deltaY,
+          viewportWidth: rect.width,
+          viewportHeight: rect.height,
+        });
+        applyZoom(next);
+        return;
+      }
+
+      if (Date.now() - lastZoomTime < 400) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+    };
+
+    document.addEventListener("wheel", handleWheel, { passive: false, capture: true });
+    return () => document.removeEventListener("wheel", handleWheel, { capture: true });
+  }, [applyZoom]);
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+
+    const handleDblClick = (event: MouseEvent) => {
+      if (Math.abs(zoomRef.current.zoomPercent - 100) < 0.5) return;
+      const rect = viewport.getBoundingClientRect();
+      if (
+        event.clientX < rect.left ||
+        event.clientX > rect.right ||
+        event.clientY < rect.top ||
+        event.clientY > rect.bottom
+      ) {
+        return;
+      }
+      applyZoom(DEFAULT_PREVIEW_ZOOM);
+    };
+
+    document.addEventListener("dblclick", handleDblClick, { capture: true });
+    return () => document.removeEventListener("dblclick", handleDblClick, { capture: true });
+  }, [applyZoom]);
+
+  const handlePointerDown = useCallback((event: React.PointerEvent<HTMLDivElement>) => {
+    if (zoomRef.current.zoomPercent <= 100 || event.button !== 0) return;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    dragRef.current = {
+      pointerId: event.pointerId,
+      startX: event.clientX,
+      startY: event.clientY,
+      originX: zoomRef.current.panX,
+      originY: zoomRef.current.panY,
+    };
+  }, []);
+
+  const handlePointerMove = useCallback(
+    (event: React.PointerEvent<HTMLDivElement>) => {
+      const drag = dragRef.current;
+      const viewport = viewportRef.current;
+      if (!drag || !viewport || drag.pointerId !== event.pointerId) return;
+      event.preventDefault();
+      const rect = viewport.getBoundingClientRect();
+      const pan = clampPreviewPan({
+        panX: drag.originX + event.clientX - drag.startX,
+        panY: drag.originY + event.clientY - drag.startY,
+        zoomPercent: zoomRef.current.zoomPercent,
+        viewportWidth: rect.width,
+        viewportHeight: rect.height,
+      });
+      applyZoom({ ...zoomRef.current, ...pan });
+    },
+    [applyZoom],
+  );
+
+  const finishDrag = useCallback((event: React.PointerEvent<HTMLDivElement>) => {
+    if (dragRef.current?.pointerId === event.pointerId) {
+      dragRef.current = null;
+    }
+  }, []);
+
+  const initial = zoomRef.current;
+
   return (
     <div className="flex flex-col h-full min-h-0">
       <div
+        ref={viewportRef}
         className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
         tabIndex={0}
         aria-label="Composition preview"
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={finishDrag}
+        onPointerCancel={finishDrag}
       >
-        {retiringKey && (
+        <div
+          ref={stageRef}
+          className="absolute inset-2"
+          style={{
+            zoom: toDomPrecision(initial.zoomPercent / 100),
+            transform: `translate(${toDomPrecision(initial.panX)}px, ${toDomPrecision(initial.panY)}px)`,
+            transformOrigin: "0 0",
+          }}
+          data-testid="preview-zoom-stage"
+        >
+          {retiringKey && (
+            <Player
+              key={retiringKey}
+              projectId={directUrl ? undefined : projectId}
+              directUrl={directUrl}
+              onLoad={() => {}}
+              portrait={portrait}
+              style={{ position: "absolute", inset: 0, zIndex: 0, opacity: 1 }}
+            />
+          )}
           <Player
-            key={retiringKey}
+            key={activeKey}
+            ref={iframeRef}
             projectId={directUrl ? undefined : projectId}
             directUrl={directUrl}
-            onLoad={() => {}}
+            onLoad={
+              retiringKey
+                ? handleNewPlayerLoad
+                : () => {
+                    onIframeLoad();
+                    applyInitialZoom();
+                  }
+            }
+            onCompositionLoadingChange={onCompositionLoadingChange}
             portrait={portrait}
-            style={{ position: "absolute", inset: 0, zIndex: 0, opacity: 1 }}
+            style={retiringKey ? { position: "absolute", inset: 0, zIndex: 1 } : undefined}
+            suppressLoadingOverlay={suppressLoadingOverlay}
           />
-        )}
-        <Player
-          key={activeKey}
-          ref={iframeRef}
-          projectId={directUrl ? undefined : projectId}
-          directUrl={directUrl}
-          onLoad={retiringKey ? handleNewPlayerLoad : onIframeLoad}
-          onCompositionLoadingChange={onCompositionLoadingChange}
-          portrait={portrait}
-          style={retiringKey ? { position: "absolute", inset: 0, zIndex: 1 } : undefined}
-          suppressLoadingOverlay={suppressLoadingOverlay}
+        </div>
+        <div
+          ref={hudRef}
+          className="pointer-events-none absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 z-50 rounded-lg px-4 py-2 text-sm font-mono tabular-nums text-white/90 bg-black/60 backdrop-blur-sm shadow-lg"
+          style={{ opacity: 0, transition: "opacity 300ms ease-out" }}
+          aria-live="polite"
         />
       </div>
     </div>

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

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_PREVIEW_ZOOM,
+  MAX_PREVIEW_ZOOM_PERCENT,
+  MIN_PREVIEW_ZOOM_PERCENT,
+  clampPreviewPan,
+  clampPreviewZoomPercent,
+  getNextPreviewZoomPercent,
+  getPreviewWheelZoomPercent,
+  resolvePreviewWheelZoom,
+  toDomPrecision,
+} from "./previewZoom";
+
+describe("toDomPrecision", () => {
+  it("rounds to 4 decimal places", () => {
+    expect(toDomPrecision(1.23456789)).toBe(1.2346);
+  });
+
+  it("preserves zero", () => {
+    expect(toDomPrecision(0)).toBe(0);
+  });
+
+  it("handles negative values", () => {
+    expect(toDomPrecision(-3.14159)).toBe(-3.1416);
+  });
+});
+
+describe("clampPreviewZoomPercent", () => {
+  it("falls back to fit zoom for invalid input", () => {
+    expect(clampPreviewZoomPercent(Number.NaN)).toBe(100);
+  });
+
+  it("clamps to supported preview zoom bounds", () => {
+    expect(clampPreviewZoomPercent(1)).toBe(MIN_PREVIEW_ZOOM_PERCENT);
+    expect(clampPreviewZoomPercent(5000)).toBe(MAX_PREVIEW_ZOOM_PERCENT);
+  });
+});
+
+describe("getPreviewWheelZoomPercent", () => {
+  it("zooms in on negative deltaY (scroll up / pinch out)", () => {
+    expect(getPreviewWheelZoomPercent(-5, 100)).toBeGreaterThan(100);
+  });
+
+  it("zooms out on positive deltaY (scroll down / pinch in)", () => {
+    expect(getPreviewWheelZoomPercent(5, 200)).toBeLessThan(200);
+  });
+
+  it("clamps large deltas to prevent overshoot", () => {
+    const small = getPreviewWheelZoomPercent(-5, 100);
+    const large = getPreviewWheelZoomPercent(-50, 100);
+    expect(large).toBeLessThan(small * 2);
+  });
+
+  it("preserves the current zoom for invalid input", () => {
+    expect(getPreviewWheelZoomPercent(Number.NaN, 180)).toBe(180);
+  });
+});
+
+describe("getNextPreviewZoomPercent", () => {
+  it("steps preview zoom in and out", () => {
+    expect(getNextPreviewZoomPercent("in", 100)).toBe(125);
+    expect(getNextPreviewZoomPercent("out", 125)).toBe(100);
+  });
+});
+
+describe("clampPreviewPan", () => {
+  it("centers the preview when fit or zoomed out", () => {
+    expect(
+      clampPreviewPan({
+        panX: 120,
+        panY: -90,
+        zoomPercent: 100,
+        viewportWidth: 800,
+        viewportHeight: 600,
+      }),
+    ).toEqual({ panX: 0, panY: 0 });
+  });
+
+  it("keeps pan within the zoomed preview bounds", () => {
+    expect(
+      clampPreviewPan({
+        panX: 900,
+        panY: -900,
+        zoomPercent: 200,
+        viewportWidth: 800,
+        viewportHeight: 600,
+      }),
+    ).toEqual({ panX: 400, panY: -300 });
+  });
+});
+
+describe("resolvePreviewWheelZoom", () => {
+  it("zooms in from center without shifting pan", () => {
+    const next = resolvePreviewWheelZoom({
+      state: DEFAULT_PREVIEW_ZOOM,
+      deltaY: -5,
+      viewportWidth: 800,
+      viewportHeight: 600,
+    });
+
+    expect(next.zoomPercent).toBeGreaterThan(100);
+    expect(next.panX).toBe(0);
+    expect(next.panY).toBe(0);
+  });
+
+  it("clamps pan when zooming out past minimum", () => {
+    const next = resolvePreviewWheelZoom({
+      state: { zoomPercent: 26, panX: 20, panY: 20 },
+      deltaY: 500,
+      viewportWidth: 800,
+      viewportHeight: 600,
+    });
+
+    expect(next.zoomPercent).toBeCloseTo(MIN_PREVIEW_ZOOM_PERCENT, 0);
+    expect(next.panX).toBe(0);
+    expect(next.panY).toBe(0);
+  });
+});

package/src/components/nle/previewZoom.ts

@@ -0,0 +1,84 @@
+export interface PreviewZoomState {
+  zoomPercent: number;
+  panX: number;
+  panY: number;
+}
+
+export const MIN_PREVIEW_ZOOM_PERCENT = 25;
+export const MAX_PREVIEW_ZOOM_PERCENT = 400;
+export const DEFAULT_PREVIEW_ZOOM: PreviewZoomState = {
+  zoomPercent: 100,
+  panX: 0,
+  panY: 0,
+};
+
+const ZOOM_SENSITIVITY = 0.007;
+const MAX_DELTA = 10;
+
+export function toDomPrecision(value: number): number {
+  return Math.round(value * 10000) / 10000;
+}
+
+export function clampPreviewZoomPercent(percent: number): number {
+  if (!Number.isFinite(percent)) return 100;
+  return Math.min(MAX_PREVIEW_ZOOM_PERCENT, Math.max(MIN_PREVIEW_ZOOM_PERCENT, percent));
+}
+
+export function getPreviewWheelZoomPercent(deltaY: number, currentZoomPercent: number): number {
+  if (!Number.isFinite(deltaY)) return clampPreviewZoomPercent(currentZoomPercent);
+  const clamped = Math.abs(deltaY) > MAX_DELTA ? MAX_DELTA * Math.sign(deltaY) : deltaY;
+  const step = -clamped * ZOOM_SENSITIVITY;
+  const current = clampPreviewZoomPercent(currentZoomPercent);
+  return clampPreviewZoomPercent(current * Math.exp(step));
+}
+
+export function getNextPreviewZoomPercent(
+  direction: "in" | "out",
+  currentZoomPercent: number,
+): number {
+  const current = clampPreviewZoomPercent(currentZoomPercent);
+  const multiplier = direction === "in" ? 1.25 : 0.8;
+  return clampPreviewZoomPercent(current * multiplier);
+}
+
+export function clampPreviewPan(input: {
+  panX: number;
+  panY: number;
+  zoomPercent: number;
+  viewportWidth: number;
+  viewportHeight: number;
+}): Pick<PreviewZoomState, "panX" | "panY"> {
+  const scale = clampPreviewZoomPercent(input.zoomPercent) / 100;
+  if (scale <= 1) return { panX: 0, panY: 0 };
+
+  const maxPanX = ((scale - 1) * input.viewportWidth) / 2;
+  const maxPanY = ((scale - 1) * input.viewportHeight) / 2;
+  return {
+    panX: Math.min(maxPanX, Math.max(-maxPanX, input.panX)),
+    panY: Math.min(maxPanY, Math.max(-maxPanY, input.panY)),
+  };
+}
+
+export function resolvePreviewWheelZoom(input: {
+  state: PreviewZoomState;
+  deltaY: number;
+  viewportWidth: number;
+  viewportHeight: number;
+}): PreviewZoomState {
+  const nextZoomPercent = getPreviewWheelZoomPercent(
+    input.deltaY,
+    clampPreviewZoomPercent(input.state.zoomPercent),
+  );
+  const pan = clampPreviewPan({
+    panX: input.state.panX,
+    panY: input.state.panY,
+    zoomPercent: nextZoomPercent,
+    viewportWidth: input.viewportWidth,
+    viewportHeight: input.viewportHeight,
+  });
+
+  return {
+    zoomPercent: nextZoomPercent,
+    ...pan,
+  };
+}