castle-web-cli 0.4.86 → 0.4.87

package/kits/basic-2d/editors/SceneEditor.jsx

@@ -58,6 +58,17 @@ const BLUEPRINT_TEMPLATE_ACTOR_ID = '__template__';
 const LONG_PRESS_MS = 500;
 const DRAG_THRESHOLD = 4;
 const DEFAULT_GRID_SIZE = 25;
+// Floating zoom/pan control cluster, tucked into the bottom-right corner of the
+// stage workspace (matches the art editor's placement).
+const ZOOM_CONTROLS_STYLE = {
+  position: 'absolute',
+  right: 8,
+  bottom: 8,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  zIndex: 5,
+};
 const EDIT_VIEWPORT = {
   width: cardSize.width * 3,
   height: cardSize.height * 3,
@@ -468,35 +479,22 @@ export function SceneEditor({
         <div className={styles.sceneWorkspace}>
           <div className={styles.sceneTools}>
             {isBlueprintFile ? null : (
-              <>
-                {/* Open (or focus) a Play panel in the shell for this scene.
-                    Lives here in the visible toolbar because the scene editor's
-                    header only renders in the combined editor, not the shell. */}
-                <IconButton
-                  icon="external"
-                  label="Open play preview"
-                  onClick={(event) => {
-                    event.currentTarget.blur();
-                    window.parent.postMessage({ type: 'castle-open-playtest', scene: path }, '*');
-                  }}
-                />
-                <BlueprintLibrary
-                  files={files}
-                  sprites={sprites}
-                  canvasRef={canvasRef}
-                  editCameraRef={editCameraRef}
-                  isPlaying={isPlaying}
-                  selectedBlueprintPath={selectedBlueprintPath}
-                  instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
-                  onSelectBlueprint={onSelectBlueprint}
-                  onAddActor={onAddActor}
-                  dragPlace={dragPlace}
-                  onDeleteBlueprint={onDeleteBlueprint}
-                />
-              </>
+              <BlueprintLibrary
+                files={files}
+                sprites={sprites}
+                canvasRef={canvasRef}
+                editCameraRef={editCameraRef}
+                isPlaying={isPlaying}
+                selectedBlueprintPath={selectedBlueprintPath}
+                instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
+                onSelectBlueprint={onSelectBlueprint}
+                onAddActor={onAddActor}
+                dragPlace={dragPlace}
+                onDeleteBlueprint={onDeleteBlueprint}
+              />
             )}
           </div>
-          <div className={styles.stageWrap} style={stageWrapStyle}>
+          <div className={styles.stageWrap} style={{ ...stageWrapStyle, position: 'relative' }}>
             <div className={styles.stageCard} data-castle-card>
               <div className={cx(styles.stageCardClip, !isPlaying && styles.stageCardEditSurface)}>
                 <canvas
@@ -511,7 +509,12 @@ export function SceneEditor({
                   onPointerDown={(event) => {
                     event.currentTarget.focus({ preventScroll: true });
                     if (isPlaying) return playPointer.onPointerDown(event);
-                    if (panGesture.isSpacePanning()) return panGesture.onPointerDown(event);
+                    if (
+                      panGesture.isSpacePanning() ||
+                      event.button === 1 ||
+                      (event.button === 0 && event.metaKey)
+                    )
+                      return panGesture.onPointerDown(event);
                     return gesture.onPointerDown(event);
                   }}
                   onPointerMove={(event) =>
@@ -555,6 +558,25 @@ export function SceneEditor({
                 />
               )}
             </div>
+            {!isPlaying && (
+              <div style={ZOOM_CONTROLS_STYLE}>
+                <IconButton
+                  icon="zoom-in"
+                  label="Zoom in"
+                  onClick={() => panGesture.zoomAtCenter(1.25)}
+                />
+                <IconButton
+                  icon="zoom-out"
+                  label="Zoom out"
+                  onClick={() => panGesture.zoomAtCenter(0.8)}
+                />
+                <IconButton
+                  icon="fit"
+                  label="Reset view"
+                  onClick={() => panGesture.resetView()}
+                />
+              </div>
+            )}
           </div>
           <aside {...inspectorSheet.rootProps}>
             <div {...inspectorSheet.grabProps}>
@@ -1036,18 +1058,19 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
     const onWheel = (event) => {
       if (isPlayingRef.current) return;
       event.preventDefault();
-      // Trackpad pinch (and Ctrl+wheel) surface as wheel events with ctrlKey set
-      // in Chromium; route those to zoom and leave plain scroll as pan.
-      if (event.ctrlKey) {
-        if (gestureActive) return;
-        zoomByFactorAtPointer(
-          event.clientX,
-          event.clientY,
-          Math.exp(-event.deltaY * ZOOM_WHEEL_SPEED)
-        );
-      } else {
-        panByScreenDelta(event.deltaX, event.deltaY);
-      }
+      // Safari fires ctrl+wheel alongside its own gesture* pinch events; skip the
+      // wheel while a pinch is mid-flight so zoom isn't applied twice.
+      if (gestureActive) return;
+      // The wheel zooms at the cursor (standard editor affordance). Trackpad
+      // pinch and Ctrl+wheel arrive here too (Chromium sets ctrlKey) and map to
+      // the same zoom. Clamp per-event delta so a chunky mouse-wheel notch
+      // (deltaY ~100) is a sane step (≤1.65x) while trackpad deltas stay smooth.
+      const clampedDeltaY = Math.max(-50, Math.min(50, event.deltaY));
+      zoomByFactorAtPointer(
+        event.clientX,
+        event.clientY,
+        Math.exp(-clampedDeltaY * ZOOM_WHEEL_SPEED)
+      );
     };
     const onGestureStart = (event) => {
       if (isPlayingRef.current) return;
@@ -1088,7 +1111,13 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
     };
   }, [canvasRef, panByScreenDelta, zoomByFactorAtPointer]);
   const onPointerDown = useCallback((event) => {
-    if (isPlaying || !spaceDownRef.current) return;
+    if (isPlaying) return;
+    // Pan when Space is held (existing modifier), on a middle-button drag, or on
+    // a ⌘+left-drag (metaKey) — matching the art editor. preventDefault also
+    // suppresses the browser's middle-click autoscroll.
+    const middle = event.button === 1;
+    const cmdDrag = event.button === 0 && event.metaKey;
+    if (!spaceDownRef.current && !middle && !cmdDrag) return;
     event.preventDefault();
     event.currentTarget.setPointerCapture(event.pointerId);
     dragRef.current = { id: event.pointerId, lastX: event.clientX, lastY: event.clientY };
@@ -1117,7 +1146,29 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
   }, []);
   const isSpacePanning = useCallback(() => spaceDownRef.current, []);
   const isActive = useCallback(() => Boolean(dragRef.current), []);
-  return { onPointerDown, onPointerMove, onPointerUp, isSpacePanning, isActive };
+  // Button-driven zoom about the canvas center, and a reset-to-fit that restores
+  // the initial camera (zoom 1 = the card exactly fills the viewport).
+  const zoomAtCenter = useCallback(
+    (factor) => {
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+      const rect = canvas.getBoundingClientRect();
+      zoomByFactorAtPointer(rect.left + rect.width / 2, rect.top + rect.height / 2, factor);
+    },
+    [canvasRef, zoomByFactorAtPointer]
+  );
+  const resetView = useCallback(() => {
+    editCameraRef.current = { x: 0, y: 0, zoom: 1 };
+  }, [editCameraRef]);
+  return {
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    isSpacePanning,
+    isActive,
+    zoomAtCenter,
+    resetView,
+  };
 }
 function handleShiftPointerDown(drag, actor, current) {
   if (actor) {

package/kits/basic-2d/editors/useArtboardFit.js

@@ -98,5 +98,8 @@ export function useArtboardFit({ wrapRef, sizeBarRef, resolution }) {
     ? { width: `${displaySize.width}px`, height: `${displaySize.height}px` }
     : undefined;
 
-  return { canvasStyle, refit: fit };
+  // `displaySize` (numeric px, or null) is the fit baseline the zoom/pan layer
+  // multiplies against; `canvasStyle` is the same value pre-formatted for the
+  // unzoomed render path.
+  return { canvasStyle, displaySize, refit: fit };
 }

package/kits/basic-2d/engine/ScenePlayer.jsx

@@ -93,7 +93,20 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
       <canvas
         ref={canvasRef}
         tabIndex={0}
-        style={{ width: '100%', height: '100%', display: 'block', outline: 'none' }}
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'block',
+          outline: 'none',
+          // Claim touches for the game: without this, a mobile WebView
+          // (castle-client) treats a drag as a scroll/pan gesture and fires
+          // `pointercancel` mid-drag, so a held Draggable/Slingshot loses its
+          // grip. Also suppress long-press text selection / callout.
+          touchAction: 'none',
+          userSelect: 'none',
+          WebkitUserSelect: 'none',
+          WebkitTouchCallout: 'none',
+        }}
       />
       <SceneUI getRuntime={getRuntime} />
       {error ? <PlayErrorOverlay error={error} onRestart={onRestart} /> : null}

package/kits/basic-2d/engine/ui.jsx

@@ -13,6 +13,7 @@ import {
   faCode,
   faCodeBranch,
   faEraser,
+  faExpand,
   faExternalLinkAlt,
   faEyeDropper,
   faFile,
@@ -27,6 +28,8 @@ import {
   faPlay,
   faPlus,
   faRedo,
+  faSearchMinus,
+  faSearchPlus,
   faShapes,
   faSlash,
   faVectorSquare,
@@ -180,6 +183,7 @@ const icons = {
   // FA5 has no faCodeFork (that's the FA6 name); faCodeBranch is the fork glyph.
   'code-fork': faCodeBranch,
   eraser: faEraser,
+  expand: faExpand,
   external: faExternalLinkAlt,
   eyedropper: faEyeDropper,
   fill: faFillDrip,
@@ -199,6 +203,9 @@ const icons = {
   plus: faPlus,
   redo: faRedo,
   rotate: faSyncAlt,
+  'zoom-in': faSearchPlus,
+  'zoom-out': faSearchMinus,
+  fit: faExpand,
   shapes: faShapes,
   slash: faSlash,
   square: faSquare,

package/kits/physics-2d/editors/PxArtEditor.jsx

@@ -1,8 +1,8 @@
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { frameCount, renderSpriteFrame, TRANSPARENT } from '../engine/pxart';
 import { renderSmoothSpriteFrame } from '../engine/pxartSmooth';
 import { basename } from '../engine/files';
-import { EditorBody, styles } from '../engine/ui';
+import { EditorBody, IconButton, styles } from '../engine/ui';
 import { eventToCell } from './pixelCanvas';
 import { forEachDab } from './pixelGeometry';
 import { PixelArtboard, PixelEditorHeader, usePixelEditorShell } from './pixelEditorChrome';
@@ -74,6 +74,24 @@ import tl from './pxArtTimeline.module.css';
 const ONION_WARM = '#ff7a3c';
 const ONION_COOL = '#3ca0ff';
 
+// Artboard zoom bounds and wheel sensitivity. zoom 1 = fit (the artboard fills
+// its region); zooming in scrolls the surrounding viewport to pan.
+const MIN_ART_ZOOM = 1;
+const MAX_ART_ZOOM = 12;
+const ART_ZOOM_WHEEL_SPEED = 0.01;
+// Floating zoom/pan control cluster, tucked into the true bottom-right corner of
+// the artboard region (over the palette column's empty lower area — the palette
+// keeps its swatches top-aligned).
+const PXART_ZOOM_CONTROLS_STYLE = {
+  position: 'absolute',
+  right: 8,
+  bottom: 8,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  zIndex: 5,
+};
+
 // Native CSS cursors over the artboard, keyed by the active tool. The transient
 // eyedropper (picker mode) overrides any of these with 'crosshair'. Tools not
 // listed fall back to the default cursor.
@@ -147,11 +165,109 @@ export function PxArtEditor({ path, text, onChange, ...chrome }) {
     eraseSize,
     activeKey,
   });
-  const { canvasStyle } = useArtboardFit({
+  const { canvasStyle, displaySize } = useArtboardFit({
     wrapRef: canvasWrapRef,
     sizeBarRef: canvasSizeBarRef,
     resolution: sprite?.resolution ?? { width: 16, height: 16 },
   });
+  // Artboard zoom + pan. `zoom` scales the canvas above its fit size; the
+  // surrounding viewport (overflow: auto) scrolls to pan. Middle-drag pans and
+  // the wheel zooms at the cursor (wired below); the button cluster drives the
+  // same via `applyZoom`.
+  const viewportRef = useRef(null);
+  const panRef = useRef(null);
+  const [zoom, setZoom] = useState(1);
+  const zoomRef = useRef(zoom);
+  zoomRef.current = zoom;
+  // Set zoom to `nextRaw` (clamped) while pinning the point under (anchorX,
+  // anchorY) client coords — defaulting to the viewport center. Scroll is fixed
+  // up on the next frame, once the resized canvas has laid out.
+  const applyZoom = useCallback((nextRaw, anchorX, anchorY) => {
+    const vp = viewportRef.current;
+    const z0 = zoomRef.current;
+    const z1 = Math.max(MIN_ART_ZOOM, Math.min(MAX_ART_ZOOM, nextRaw));
+    if (!vp || z1 === z0) return;
+    const rect = vp.getBoundingClientRect();
+    const ax = (Number.isFinite(anchorX) ? anchorX : rect.left + rect.width / 2) - rect.left;
+    const ay = (Number.isFinite(anchorY) ? anchorY : rect.top + rect.height / 2) - rect.top;
+    const contentX = vp.scrollLeft + ax;
+    const contentY = vp.scrollTop + ay;
+    const ratio = z1 / z0;
+    setZoom(z1);
+    requestAnimationFrame(() => {
+      vp.scrollLeft = contentX * ratio - ax;
+      vp.scrollTop = contentY * ratio - ay;
+    });
+  }, []);
+  const resetZoom = useCallback(() => {
+    setZoom(1);
+    const vp = viewportRef.current;
+    if (vp) requestAnimationFrame(() => {
+      vp.scrollLeft = 0;
+      vp.scrollTop = 0;
+    });
+  }, []);
+  // Wheel zoom as a NATIVE non-passive listener so preventDefault stops the
+  // page/browser zoom underneath. Delta is clamped so a chunky mouse notch is a
+  // sane step while trackpad deltas stay smooth.
+  useEffect(() => {
+    const vp = viewportRef.current;
+    if (!vp) return undefined;
+    const onWheel = (event) => {
+      event.preventDefault();
+      const clamped = Math.max(-50, Math.min(50, event.deltaY));
+      applyZoom(zoomRef.current * Math.exp(-clamped * ART_ZOOM_WHEEL_SPEED), event.clientX, event.clientY);
+    };
+    vp.addEventListener('wheel', onWheel, { passive: false });
+    return () => vp.removeEventListener('wheel', onWheel, { passive: false });
+  }, [applyZoom]);
+  // Middle-button drag pans by scrolling the viewport. Intercept in the capture
+  // phase so the press never reaches the canvas's draw handler (startTool).
+  const onViewportPointerDownCapture = (event) => {
+    // Pan on a middle-button drag or a ⌘+left-drag (metaKey). Both are caught in
+    // the capture phase so the press never reaches the canvas's draw handler.
+    const startsPan = event.button === 1 || (event.button === 0 && event.metaKey);
+    if (!startsPan) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const vp = viewportRef.current;
+    vp.setPointerCapture(event.pointerId);
+    panRef.current = { id: event.pointerId, x: event.clientX, y: event.clientY };
+  };
+  const onViewportPointerMove = (event) => {
+    const pan = panRef.current;
+    if (!pan || pan.id !== event.pointerId) return;
+    const vp = viewportRef.current;
+    vp.scrollLeft -= event.clientX - pan.x;
+    vp.scrollTop -= event.clientY - pan.y;
+    pan.x = event.clientX;
+    pan.y = event.clientY;
+  };
+  const onViewportPointerUp = (event) => {
+    const pan = panRef.current;
+    if (!pan || pan.id !== event.pointerId) return;
+    try {
+      viewportRef.current?.releasePointerCapture(event.pointerId);
+    } catch {
+      // pointer capture may already be gone
+    }
+    panRef.current = null;
+  };
+  // Viewport is sized to the fit baseline; the canvas inside scales by zoom, so
+  // zoom > 1 overflows and the viewport scrolls (= pan).
+  const artboardViewportStyle = displaySize
+    ? {
+        width: displaySize.width,
+        height: displaySize.height,
+        maxWidth: '100%',
+        maxHeight: '100%',
+        overflow: 'auto',
+        touchAction: 'none',
+      }
+    : { overflow: 'auto' };
+  const artboardCanvasStyle = displaySize
+    ? { width: displaySize.width * zoom, height: displaySize.height * zoom }
+    : canvasStyle;
   // `canvasStyle`'s width is the artboard's CURRENT display size (recomputed
   // by useArtboardFit's own ResizeObserver whenever the wrap resizes — e.g. a
   // dockview panel drag). Feeding it in here is what keeps the supersampled
@@ -437,7 +553,7 @@ export function PxArtEditor({ path, text, onChange, ...chrome }) {
     <PxArtShell path={path} subtitle={pxArtSubtitle(sprite)} shell={headerShell} chrome={chrome} editorBodyRef={editorBodyRef}>
       <div className={styles.drawingEditor}>
         <div className={tl.editorLeft}>
-          <div className={tl.artboardRegion}>
+          <div className={tl.artboardRegion} style={{ position: 'relative' }}>
             <div className={styles.artboardToolColumn}>
               <PixelToolStrip
                 tools={PIXEL_TOOLS}
@@ -464,19 +580,28 @@ export function PxArtEditor({ path, text, onChange, ...chrome }) {
                     />
                   </div>
                 </div>
-                <PixelArtboard
-                  canvasRef={canvasRef}
-                  smoothRef={smoothRef}
-                  overlayRef={overlayRef}
-                  style={{ ...canvasStyle, cursor }}
-                  handlers={{
-                    onPointerDown: startTool,
-                    onPointerMove: handlePointerMove,
-                    onPointerUp: finishTool,
-                    onPointerCancel: finishTool,
-                    onPointerLeave: clearHover,
-                  }}
-                />
+                <div
+                  ref={viewportRef}
+                  style={artboardViewportStyle}
+                  onPointerDownCapture={onViewportPointerDownCapture}
+                  onPointerMove={onViewportPointerMove}
+                  onPointerUp={onViewportPointerUp}
+                  onPointerCancel={onViewportPointerUp}
+                >
+                  <PixelArtboard
+                    canvasRef={canvasRef}
+                    smoothRef={smoothRef}
+                    overlayRef={overlayRef}
+                    style={{ ...artboardCanvasStyle, cursor }}
+                    handlers={{
+                      onPointerDown: startTool,
+                      onPointerMove: handlePointerMove,
+                      onPointerUp: finishTool,
+                      onPointerCancel: finishTool,
+                      onPointerLeave: clearHover,
+                    }}
+                  />
+                </div>
               </div>
             </div>
             <div className={styles.paintColumn}>
@@ -494,6 +619,19 @@ export function PxArtEditor({ path, text, onChange, ...chrome }) {
                 selectActions={selectActions}
               />
             </div>
+            <div style={PXART_ZOOM_CONTROLS_STYLE}>
+              <IconButton
+                icon="zoom-in"
+                label="Zoom in"
+                onClick={() => applyZoom(zoomRef.current * 1.25)}
+              />
+              <IconButton
+                icon="zoom-out"
+                label="Zoom out"
+                onClick={() => applyZoom(zoomRef.current * 0.8)}
+              />
+              <IconButton icon="fit" label="Fit" onClick={resetZoom} />
+            </div>
           </div>
           <PxArtTimeline
             sprite={sprite}

package/kits/physics-2d/editors/SceneEditor.jsx

@@ -58,6 +58,17 @@ const BLUEPRINT_TEMPLATE_ACTOR_ID = '__template__';
 const LONG_PRESS_MS = 500;
 const DRAG_THRESHOLD = 4;
 const DEFAULT_GRID_SIZE = 25;
+// Floating zoom/pan control cluster, tucked into the bottom-right corner of the
+// stage workspace (matches the art editor's placement).
+const ZOOM_CONTROLS_STYLE = {
+  position: 'absolute',
+  right: 8,
+  bottom: 8,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  zIndex: 5,
+};
 const EDIT_VIEWPORT = {
   width: cardSize.width * 3,
   height: cardSize.height * 3,
@@ -468,35 +479,22 @@ export function SceneEditor({
         <div className={styles.sceneWorkspace}>
           <div className={styles.sceneTools}>
             {isBlueprintFile ? null : (
-              <>
-                {/* Open (or focus) a Play panel in the shell for this scene.
-                    Lives here in the visible toolbar because the scene editor's
-                    header only renders in the combined editor, not the shell. */}
-                <IconButton
-                  icon="external"
-                  label="Open play preview"
-                  onClick={(event) => {
-                    event.currentTarget.blur();
-                    window.parent.postMessage({ type: 'castle-open-playtest', scene: path }, '*');
-                  }}
-                />
-                <BlueprintLibrary
-                  files={files}
-                  sprites={sprites}
-                  canvasRef={canvasRef}
-                  editCameraRef={editCameraRef}
-                  isPlaying={isPlaying}
-                  selectedBlueprintPath={selectedBlueprintPath}
-                  instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
-                  onSelectBlueprint={onSelectBlueprint}
-                  onAddActor={onAddActor}
-                  dragPlace={dragPlace}
-                  onDeleteBlueprint={onDeleteBlueprint}
-                />
-              </>
+              <BlueprintLibrary
+                files={files}
+                sprites={sprites}
+                canvasRef={canvasRef}
+                editCameraRef={editCameraRef}
+                isPlaying={isPlaying}
+                selectedBlueprintPath={selectedBlueprintPath}
+                instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
+                onSelectBlueprint={onSelectBlueprint}
+                onAddActor={onAddActor}
+                dragPlace={dragPlace}
+                onDeleteBlueprint={onDeleteBlueprint}
+              />
             )}
           </div>
-          <div className={styles.stageWrap} style={stageWrapStyle}>
+          <div className={styles.stageWrap} style={{ ...stageWrapStyle, position: 'relative' }}>
             <div className={styles.stageCard} data-castle-card>
               <div className={cx(styles.stageCardClip, !isPlaying && styles.stageCardEditSurface)}>
                 <canvas
@@ -511,7 +509,12 @@ export function SceneEditor({
                   onPointerDown={(event) => {
                     event.currentTarget.focus({ preventScroll: true });
                     if (isPlaying) return playPointer.onPointerDown(event);
-                    if (panGesture.isSpacePanning()) return panGesture.onPointerDown(event);
+                    if (
+                      panGesture.isSpacePanning() ||
+                      event.button === 1 ||
+                      (event.button === 0 && event.metaKey)
+                    )
+                      return panGesture.onPointerDown(event);
                     return gesture.onPointerDown(event);
                   }}
                   onPointerMove={(event) =>
@@ -555,6 +558,25 @@ export function SceneEditor({
                 />
               )}
             </div>
+            {!isPlaying && (
+              <div style={ZOOM_CONTROLS_STYLE}>
+                <IconButton
+                  icon="zoom-in"
+                  label="Zoom in"
+                  onClick={() => panGesture.zoomAtCenter(1.25)}
+                />
+                <IconButton
+                  icon="zoom-out"
+                  label="Zoom out"
+                  onClick={() => panGesture.zoomAtCenter(0.8)}
+                />
+                <IconButton
+                  icon="fit"
+                  label="Reset view"
+                  onClick={() => panGesture.resetView()}
+                />
+              </div>
+            )}
           </div>
           <aside {...inspectorSheet.rootProps}>
             <div {...inspectorSheet.grabProps}>
@@ -1036,18 +1058,19 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
     const onWheel = (event) => {
       if (isPlayingRef.current) return;
       event.preventDefault();
-      // Trackpad pinch (and Ctrl+wheel) surface as wheel events with ctrlKey set
-      // in Chromium; route those to zoom and leave plain scroll as pan.
-      if (event.ctrlKey) {
-        if (gestureActive) return;
-        zoomByFactorAtPointer(
-          event.clientX,
-          event.clientY,
-          Math.exp(-event.deltaY * ZOOM_WHEEL_SPEED)
-        );
-      } else {
-        panByScreenDelta(event.deltaX, event.deltaY);
-      }
+      // Safari fires ctrl+wheel alongside its own gesture* pinch events; skip the
+      // wheel while a pinch is mid-flight so zoom isn't applied twice.
+      if (gestureActive) return;
+      // The wheel zooms at the cursor (standard editor affordance). Trackpad
+      // pinch and Ctrl+wheel arrive here too (Chromium sets ctrlKey) and map to
+      // the same zoom. Clamp per-event delta so a chunky mouse-wheel notch
+      // (deltaY ~100) is a sane step (≤1.65x) while trackpad deltas stay smooth.
+      const clampedDeltaY = Math.max(-50, Math.min(50, event.deltaY));
+      zoomByFactorAtPointer(
+        event.clientX,
+        event.clientY,
+        Math.exp(-clampedDeltaY * ZOOM_WHEEL_SPEED)
+      );
     };
     const onGestureStart = (event) => {
       if (isPlayingRef.current) return;
@@ -1088,7 +1111,13 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
     };
   }, [canvasRef, panByScreenDelta, zoomByFactorAtPointer]);
   const onPointerDown = useCallback((event) => {
-    if (isPlaying || !spaceDownRef.current) return;
+    if (isPlaying) return;
+    // Pan when Space is held (existing modifier), on a middle-button drag, or on
+    // a ⌘+left-drag (metaKey) — matching the art editor. preventDefault also
+    // suppresses the browser's middle-click autoscroll.
+    const middle = event.button === 1;
+    const cmdDrag = event.button === 0 && event.metaKey;
+    if (!spaceDownRef.current && !middle && !cmdDrag) return;
     event.preventDefault();
     event.currentTarget.setPointerCapture(event.pointerId);
     dragRef.current = { id: event.pointerId, lastX: event.clientX, lastY: event.clientY };
@@ -1117,7 +1146,29 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
   }, []);
   const isSpacePanning = useCallback(() => spaceDownRef.current, []);
   const isActive = useCallback(() => Boolean(dragRef.current), []);
-  return { onPointerDown, onPointerMove, onPointerUp, isSpacePanning, isActive };
+  // Button-driven zoom about the canvas center, and a reset-to-fit that restores
+  // the initial camera (zoom 1 = the card exactly fills the viewport).
+  const zoomAtCenter = useCallback(
+    (factor) => {
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+      const rect = canvas.getBoundingClientRect();
+      zoomByFactorAtPointer(rect.left + rect.width / 2, rect.top + rect.height / 2, factor);
+    },
+    [canvasRef, zoomByFactorAtPointer]
+  );
+  const resetView = useCallback(() => {
+    editCameraRef.current = { x: 0, y: 0, zoom: 1 };
+  }, [editCameraRef]);
+  return {
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    isSpacePanning,
+    isActive,
+    zoomAtCenter,
+    resetView,
+  };
 }
 function handleShiftPointerDown(drag, actor, current) {
   if (actor) {

package/kits/physics-2d/editors/useArtboardFit.js

@@ -98,5 +98,8 @@ export function useArtboardFit({ wrapRef, sizeBarRef, resolution }) {
     ? { width: `${displaySize.width}px`, height: `${displaySize.height}px` }
     : undefined;
 
-  return { canvasStyle, refit: fit };
+  // `displaySize` (numeric px, or null) is the fit baseline the zoom/pan layer
+  // multiplies against; `canvasStyle` is the same value pre-formatted for the
+  // unzoomed render path.
+  return { canvasStyle, displaySize, refit: fit };
 }