castle-web-cli 0.4.169 → 0.4.171

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

@@ -92,6 +92,8 @@ import {
 } from './pixelInspector';
 import { useArtboardFit, useEditorCompactLayout } from './useArtboardFit';
 import { useTwoFingerZoomPan } from '../engine/gestureZoomPan';
+import { useArtboardZoomPan } from './useArtboardZoomPan';
+import { renderSnapLattice, setupOverlayContext } from './overlayCanvas';
 import {
   clearRegion,
   fillRegion,
@@ -149,11 +151,6 @@ 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).
@@ -214,6 +211,7 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
   const canvasRef = useRef(null);
   const smoothRef = useRef(null);
   const overlayRef = useRef(null);
+  const latticeRef = useRef(null);
   const strokeRef = useRef(null);
   const refitActiveBrushStrokeRef = useRef(() => {});
   // The serialized text this editor last wrote itself. Lets us tell our own
@@ -369,14 +367,22 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
     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`.
+  // surrounding viewport scrolls (programmatically -- see useArtboardZoomPan) to
+  // pan, over half a viewport of overscroll on every side so any part of the
+  // sprite can be brought to the middle of the screen.
   const viewportRef = useRef(null);
-  const panRef = useRef(null);
-  const [zoom, setZoom] = useState(1);
-  const zoomRef = useRef(zoom);
-  zoomRef.current = zoom;
+  const {
+    zoom,
+    zoomBy,
+    resetZoom,
+    applyZoomPan,
+    beginGesture,
+    endGesture,
+    viewportHandlers,
+    viewportStyle: artboardViewportStyle,
+    contentStyle: artboardContentStyle,
+    canvasSize,
+  } = useArtboardZoomPan({ viewportRef, displaySize });
   const pathCellPull =
     displaySize?.width && sprite?.resolution?.width
       ? magneticCellPull(sprite.resolution.width, displaySize.width, zoom)
@@ -391,62 +397,6 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
     stroke: hitRadiusCells(EDGE_HIT_SCREEN_PX, pathCellPx),
     openEnd: hitRadiusCells(OPEN_END_HIT_SCREEN_PX, pathCellPx),
   };
-  // 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;
-    });
-  }, []);
-  // Two-finger gesture step. Pan SYNCHRONOUSLY by scrolling — smooth and
-  // accumulative, exactly like the middle-drag pan. (Applying the pan inside the
-  // zoom's rAF made successive moves recompute from a scroll that hadn't been
-  // written yet, dropping intermediate deltas — the "funky" pan.) Zoom about the
-  // centroid only when the pinch actually changed scale; `applyZoom` reads the
-  // just-scrolled position, so the pan is preserved. The epsilon keeps finger
-  // jitter during a pure pan from flipping the zoom on and off.
-  const applyZoomPan = useCallback(({ factor, cx, cy, dx, dy }) => {
-    const vp = viewportRef.current;
-    if (!vp) return;
-    if (dx) vp.scrollLeft -= dx;
-    if (dy) vp.scrollTop -= dy;
-    if (Math.abs(factor - 1) > 0.002) applyZoom(zoomRef.current * factor, cx, cy);
-  }, [applyZoom]);
-  // 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]);
   // Touch: one finger draws, a second finger pinch-zooms about the centroid and
   // pans (the viewport already has touch-action:none). The second finger aborts
   // the in-flight stroke so it doesn't leave a stray mark. See gestureZoomPan.
@@ -455,62 +405,21 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
   // lands entirely inside the canvas. Zoom/pan still applies to the viewport.
   useTwoFingerZoomPan({
     targetRef: editorBodyRef,
-    onGestureStart: abortStroke,
+    onGestureStart: () => {
+      abortStroke();
+      beginGesture();
+    },
     onGestureMove: applyZoomPan,
+    // Releasing a pinch near fit settles onto exactly fit.
+    onGestureEnd: endGesture,
     // Procreate convention: two-finger tap undoes, three-finger tap redoes.
     onUndo: readOnly ? undefined : () => history.undo(),
     onRedo: readOnly ? undefined : () => history.redo(),
   });
-  // 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;
+  const artboardCanvasStyle = canvasSize ?? 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
+  // panel resize). Feeding it in here is what keeps the supersampled
   // canvas's resolution in sync with that display size: without it, this
   // effect has no way to know the wrap resized (nothing about `text`,
   // `frameIndex`, or `cornerRadius` changes on a pure container resize), so
@@ -625,6 +534,12 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
     const id = setInterval(() => setAntsOffset((o) => (o + 1) % 1000), 80);
     return () => clearInterval(id);
   }, [tool, marquee]);
+  // Snap lattice for path layers. Redrawn on the artboard's CURRENT display size
+  // (`artboardCanvasStyle.width` carries the zoom), because the dots are placed
+  // per cell in screen space -- there is nothing tiled here to stretch.
+  useEffect(() => {
+    renderSnapLattice(latticeRef.current, sprite?.resolution, isPathLayer);
+  }, [isPathLayer, sprite?.resolution, artboardCanvasStyle?.width, artboardCanvasStyle?.height]);
   useEffect(() => {
     if (isPathLayer) {
       drawPathOverlay(overlayRef.current, sprite?.resolution, playing ? null : activePath, {
@@ -2314,36 +2229,32 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
                     />
                   </div>
                 </div>
-                <div
-                  ref={viewportRef}
-                  style={artboardViewportStyle}
-                  onPointerDownCapture={onViewportPointerDownCapture}
-                  onPointerMove={onViewportPointerMove}
-                  onPointerUp={onViewportPointerUp}
-                  onPointerCancel={onViewportPointerUp}
-                >
-                  <PixelArtboard
-                    canvasRef={canvasRef}
-                    smoothRef={smoothRef}
-                    overlayRef={overlayRef}
-                    smoothPreview={displayFinish(sprite).smooth}
-                    style={{
-                      ...artboardCanvasStyle,
-                      ...latticeBackground(isPathLayer, artboardCanvasStyle, width, height),
-                      cursor,
-                    }}
-                    handlers={
-                      readOnly
-                        ? {}
-                        : {
-                            onPointerDown: startTool,
-                            onPointerMove: handlePointerMove,
-                            onPointerUp: finishTool,
-                            onPointerCancel: finishTool,
-                            onPointerLeave: clearHover,
-                          }
-                    }
-                  />
+                <div ref={viewportRef} style={artboardViewportStyle} {...viewportHandlers}>
+                  <div style={artboardContentStyle}>
+                    <PixelArtboard
+                      canvasRef={canvasRef}
+                      smoothRef={smoothRef}
+                      overlayRef={overlayRef}
+                      latticeRef={latticeRef}
+                      smoothPreview={displayFinish(sprite).smooth}
+                      style={{
+                        ...artboardCanvasStyle,
+                        ...artboardBackground(isPathLayer, artboardCanvasStyle, zoom),
+                        cursor,
+                      }}
+                      handlers={
+                        readOnly
+                          ? {}
+                          : {
+                              onPointerDown: startTool,
+                              onPointerMove: handlePointerMove,
+                              onPointerUp: finishTool,
+                              onPointerCancel: finishTool,
+                              onPointerLeave: clearHover,
+                            }
+                      }
+                    />
+                  </div>
                 </div>
               </div>
             </div>
@@ -2375,12 +2286,12 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
               <IconButton
                 icon="zoom-in"
                 label="Zoom in"
-                onClick={() => applyZoom(zoomRef.current * 1.25)}
+                onClick={() => zoomBy(1.25)}
               />
               <IconButton
                 icon="zoom-out"
                 label="Zoom out"
-                onClick={() => applyZoom(zoomRef.current * 0.8)}
+                onClick={() => zoomBy(0.8)}
               />
               <IconButton icon="fit" label="Fit" onClick={resetZoom} />
             </div>
@@ -2547,7 +2458,7 @@ function useArtboardRender(canvasRef, text, sprite, previewIndex, onion, playing
 // the `sprite` object (a fresh object every render) so it only redraws on an
 // actual content/frame/radius change, not on every hover-driven re-render of
 // the tool preview — PLUS `displayWidth` (the artboard's current CSS width
-// from useArtboardFit), so a wrap resize (e.g. a dockview panel drag) also
+// from useArtboardFit), so a wrap resize (e.g. a panel drag) also
 // triggers a re-render at the new supersample scale, not just a content
 // change. The supersample factor auto-fits to the displayed size (capped
 // between 4x and 16x).
@@ -2573,21 +2484,23 @@ function useSmoothPreviewRender(smoothRef, text, sprite, frameIndex, displayWidt
   }, [text, frameIndex, smoothRef, cornerRadius, vector, displayWidth, bakePreview]);
 }
 
-// Snap-lattice dot field for path layers — always on the artboard frame so it
-// stays consistent across Pixel / ¼ / ½ / Smooth (shows through transparent
-// canvas areas; the inline background overrides the frame checkerboard).
-function latticeBackground(isPathLayer, canvasStyle, gridWidth, gridHeight) {
-  if (!isPathLayer || !canvasStyle) return {};
-  const pitchX = parseFloat(canvasStyle.width) / gridWidth;
-  const pitchY = parseFloat(canvasStyle.height) / gridHeight;
-  if (!Number.isFinite(pitchX) || !Number.isFinite(pitchY)) return {};
-  // Dots centered on cell centers (half-cell offset from the corner lattice).
-  const dots =
-    Math.min(pitchX, pitchY) >= 5
-      ? `radial-gradient(circle, rgba(255, 255, 255, 0.28) 1px, transparent 1.6px) ` +
-        `0 0 / ${pitchX}px ${pitchY}px, `
-      : '';
-  return { background: `${dots}#121212` };
+// What the artboard frame paints UNDER the art. On a path layer that is a flat
+// ground for the snap lattice (drawn on its own canvas -- see renderSnapLattice,
+// which explains why it is not a background); everywhere else it is the
+// transparency checkerboard, scaled so it zooms with the sprite instead of
+// sitting still behind it.
+//
+// Either way it belongs to the FRAME, not to a canvas, so it shows through
+// transparent art in every finish (Pixel / ¼ / ½ / Smooth) without painting over
+// the smooth-preview canvas underneath.
+//
+// The checkerboard check at fit; `--checker-size` scales it from there, so the
+// pattern travels with a pinch instead of re-tiling underneath it.
+const CHECKER_FIT_SIZE = 16;
+function artboardBackground(isPathLayer, canvasStyle, zoom) {
+  if (!canvasStyle) return {};
+  if (isPathLayer) return { background: '#121212' };
+  return { '--checker-size': `${CHECKER_FIT_SIZE * zoom}px` };
 }
 
 // Window-scoped tool keyboard shortcuts, mounted only while the editor is.
@@ -2628,24 +2541,14 @@ function renderArtboard(canvas, sprite, frameIndex, onion, playing, preview) {
 }
 
 function setupOverlayCanvas(canvas, resolution) {
-  if (!canvas || !resolution) return null;
-  const ctx = canvas.getContext('2d');
-  if (!ctx) return null;
-  const cssW = canvas.clientWidth;
-  const cssH = canvas.clientHeight;
-  if (!cssW || !cssH) return null;
-  const dpr = window.devicePixelRatio || 1;
-  const bw = Math.round(cssW * dpr);
-  const bh = Math.round(cssH * dpr);
-  if (canvas.width !== bw) canvas.width = bw;
-  if (canvas.height !== bh) canvas.height = bh;
-  ctx.setTransform(1, 0, 0, 1, 0, 0);
-  ctx.clearRect(0, 0, bw, bh);
+  if (!resolution) return null;
+  const surface = setupOverlayContext(canvas);
+  if (!surface) return null;
   return {
-    ctx,
-    dpr,
-    sx: bw / resolution.width,
-    sy: bh / resolution.height,
+    ctx: surface.ctx,
+    dpr: surface.dpr,
+    sx: surface.bw / resolution.width,
+    sy: surface.bh / resolution.height,
   };
 }
 

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

@@ -886,6 +886,7 @@ export function SceneEditor({
                       ? undefined
                       : () => onSelectBlueprint(selectedActorBlueprint)
                   }
+                  onEditSprite={onEditSprite}
                   onBeginPick={beginPick}
                   pickActive={Boolean(pickRequest)}
                   onSelectShape={setColliderShapeSel}
@@ -2083,6 +2084,7 @@ function ActorInspector({
   onRemoveBehavior,
   onNewBlueprint,
   onEditBlueprint,
+  onEditSprite,
   onBeginPick,
   pickActive,
   onSelectShape,
@@ -2096,6 +2098,14 @@ function ActorInspector({
   readOnly = false,
 }) {
   const isInstance = Boolean(rawActor?.blueprint);
+  // Same art the thumbnail shows (blueprint face, else the actor's own Sprite).
+  const thumbBlueprint = blueprintTemplate ?? { components: selectedActor.components };
+  const spritePath = thumbBlueprint.components?.Sprite?.file;
+  const canEditSprite =
+    Boolean(spritePath) &&
+    !readOnly &&
+    !isImportedPath(spritePath) &&
+    files?.[spritePath] !== undefined;
   const presentNames = new Set(
     Object.entries(selectedActor.components)
       .filter(([, component]) => !!component)
@@ -2148,10 +2158,21 @@ function ActorInspector({
       {isInstance ? (
         <div className={styles.instanceHeader}>
           <div className={styles.instanceHeaderName}>
-            <BlueprintThumbnail
-              blueprint={blueprintTemplate ?? { components: selectedActor.components }}
-              sprites={sprites}
-            />
+            {canEditSprite ? (
+              <button
+                type="button"
+                className={styles.editSpriteButton}
+                title={`Edit ${spritePath}`}
+                aria-label="Edit sprite"
+                onClick={() => void onEditSprite?.(spritePath)}>
+                <BlueprintThumbnail blueprint={thumbBlueprint} sprites={sprites} />
+                <span className={styles.editSpriteHint}>
+                  <Icon name="pencil" />
+                </span>
+              </button>
+            ) : (
+              <BlueprintThumbnail blueprint={thumbBlueprint} sprites={sprites} />
+            )}
             <div className={styles.instanceHeaderNameCol}>
               <span className={styles.instanceHeaderNameText}>
                 <strong className={styles.instanceHeaderNameStrong}>{blueprintName}</strong> Actor

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

@@ -31,14 +31,18 @@ function cardClassName(selected, clickable) {
 // One card, palette or font: a head (name + meta) over whatever the type shows
 // of itself. A button when it can be picked, a plain div when it can't.
 function styleCard({ cardKey, name, meta, preview, selected, onPick }) {
+  // Inner wrapper is the flex column, not the <button>. WebKit still wraps
+  // button contents in a shrink-to-fit anonymous box, so a flex button never
+  // stretches its children on some iOS versions — the palette strip stays
+  // colorCount × min-width wide. A block button + width:100% inner avoids that.
   const body = (
-    <>
+    <div className={styles.cardBody}>
       <div className={styles.cardHead}>
         <div className={styles.cardName}>{name}</div>
         {meta ? <div className={styles.cardMeta}>{meta}</div> : null}
       </div>
       {preview}
-    </>
+    </div>
   );
   const className = cardClassName(selected, Boolean(onPick));
   if (!onPick) {

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

@@ -0,0 +1,77 @@
+// Backing store for the display-resolution overlay canvases (marching ants, path
+// chrome). They are sized from the artboard's CSS size, which grows with zoom --
+// so at 12x on a 3x screen a 460px artboard asks for a 16560 x 16560 store,
+// around 274 megapixels. WebKit refuses an allocation that large (the overlay
+// silently stops drawing) and every zoom step reallocates it, which is most of
+// what made a deep pinch stutter on a phone.
+//
+// So cap the AREA and let the effective ratio fall below the device's. Past the
+// cap the art underneath is upscaled anyway, so nothing goes soft that was still
+// sharp; at fit on any normal artboard the cap is not reached and the overlay is
+// exactly as crisp as before.
+const MAX_OVERLAY_PIXELS = 4e6;
+
+// Returns the cleared 2D context plus the ratio actually used, or null when the
+// canvas has no layout yet. `dpr` is the CSS-pixel -> backing-store scale to draw
+// with; `bw`/`bh` are the backing store, `cssW`/`cssH` the element.
+export function setupOverlayContext(canvas) {
+  if (!canvas) return null;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return null;
+  // The measured box, NOT clientWidth: the artboard is sized by a continuous
+  // zoom, so its width is fractional at nearly every zoom, and clientWidth
+  // rounds it to a whole pixel. Dividing a rounded width by the grid gives a
+  // pitch that is wrong by up to half a pixel per cell, which accumulates
+  // across the row -- the marks drift further from their cells the further
+  // right you look, and the drift resets each time the rounding flips.
+  const { width: cssW, height: cssH } = canvas.getBoundingClientRect();
+  if (!cssW || !cssH) return null;
+  const device = window.devicePixelRatio || 1;
+  const wanted = cssW * cssH * device * device;
+  const dpr = wanted > MAX_OVERLAY_PIXELS ? device * Math.sqrt(MAX_OVERLAY_PIXELS / wanted) : device;
+  const bw = Math.max(1, Math.round(cssW * dpr));
+  const bh = Math.max(1, Math.round(cssH * dpr));
+  if (canvas.width !== bw) canvas.width = bw;
+  if (canvas.height !== bh) canvas.height = bh;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, bw, bh);
+  return { ctx, dpr, cssW, cssH, bw, bh };
+}
+
+// Snap-lattice dot field for path layers: one dot at the centre of every cell.
+//
+// This used to be a repeating radial-gradient on the artboard frame, which
+// cannot do the job: the pitch is the artboard width over the grid, so it is
+// fractional at nearly every zoom, and while the browser repeats the tile at the
+// exact fractional pitch it rounds the dot's offset WITHIN the tile to whole
+// device pixels. The dots therefore sat up to a pixel off the cells they mark,
+// drifting further out and snapping back as the pitch crossed each pixel
+// boundary -- a sawtooth you could watch while pinching. Marks that say "snap
+// here" have to be where the snap actually is, so they are drawn instead.
+const LATTICE_DOT_RADIUS = 1.3;
+const LATTICE_DOT_FILL = 'rgba(255, 255, 255, 0.28)';
+// Below this the cells are too small for a dot per cell to read as anything but
+// noise, so the field is left off.
+const LATTICE_MIN_PITCH = 5;
+
+export function renderSnapLattice(canvas, resolution, enabled) {
+  const surface = setupOverlayContext(canvas);
+  if (!surface) return;
+  const { ctx, dpr, bw, bh } = surface;
+  if (!enabled || !resolution?.width || !resolution?.height) return;
+  // Placed in BACKING pixels, not CSS pixels through a transform: the store is a
+  // whole number of pixels spanning exactly the artboard, so a cell centre is
+  // exact by construction and no rounding is left to accumulate. The radius is
+  // the only thing scaled by the ratio, so the dots stay one screen size.
+  const pitchX = bw / resolution.width;
+  const pitchY = bh / resolution.height;
+  if (Math.min(pitchX, pitchY) < LATTICE_MIN_PITCH * dpr) return;
+  ctx.fillStyle = LATTICE_DOT_FILL;
+  for (let y = 0; y < resolution.height; y++) {
+    for (let x = 0; x < resolution.width; x++) {
+      ctx.beginPath();
+      ctx.arc((x + 0.5) * pitchX, (y + 0.5) * pitchY, LATTICE_DOT_RADIUS * dpr, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+}

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

@@ -1,6 +1,7 @@
 import { absoluteSegment, subpathEdgeFrom, subpathPoints } from '../engine/pxartPath.js';
 import { primitiveHandleIndices } from '../engine/pxartPath.js';
 import { anchorKey, coincidentSiteKeys, isOpenPenShape } from './pathTools';
+import { setupOverlayContext } from './overlayCanvas';
 
 // Render-only overlay for path-layer tools: selection chrome (outline + anchor
 // dots), pen rubber-band to hover, fill-tool hover preview, and shape marquee.
@@ -40,19 +41,10 @@ function toCanvas(sx, sy, x, y) {
 }
 
 export function drawPathOverlay(canvas, resolution, path, ui) {
-  if (!canvas || !resolution) return;
-  const ctx = canvas.getContext('2d');
-  if (!ctx) return;
-  const cssW = canvas.clientWidth;
-  const cssH = canvas.clientHeight;
-  if (!cssW || !cssH) return;
-  const dpr = window.devicePixelRatio || 1;
-  const bw = Math.round(cssW * dpr);
-  const bh = Math.round(cssH * dpr);
-  if (canvas.width !== bw) canvas.width = bw;
-  if (canvas.height !== bh) canvas.height = bh;
-  ctx.setTransform(1, 0, 0, 1, 0, 0);
-  ctx.clearRect(0, 0, bw, bh);
+  if (!resolution) return;
+  const surface = setupOverlayContext(canvas);
+  if (!surface) return;
+  const { ctx, dpr, cssW, cssH } = surface;
   // From here on the drawing units are CSS pixels while the backing store stays
   // at device resolution, so the chrome is both crisp and a fixed screen size.
   ctx.setTransform(dpr, 0, 0, dpr, 0, 0);

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

@@ -45,14 +45,18 @@ export function PixelEditorHeader({ title, subtitle, shell, chrome }) {
 // callbacks the editor wires for tools. `overlayRef` is a sibling canvas at
 // display resolution used for crisp overlays (marching-ants selection) that would
 // otherwise render sub-pixel on the upscaled native canvas. `smoothRef` is a
+// `latticeRef` is a sibling canvas BEHIND even that one, holding the path-layer
+// snap lattice, so the dots sit under the art exactly as the frame background
+// they replaced did. `smoothRef` is a
 // sibling canvas BEHIND the main one, holding the corner-rounded render for
 // "smooth"-mode sprites (empty/unused in "pixel" mode) so the interactive canvas
 // above it can stay at native resolution — pointer math and tool-preview overlays
 // are unaffected by the render mode.
-export function PixelArtboard({ canvasRef, smoothRef, overlayRef, style, handlers, smoothPreview = false }) {
+export function PixelArtboard({ canvasRef, smoothRef, overlayRef, latticeRef, style, handlers, smoothPreview = false }) {
   return (
     <div className={styles.drawingArtboard}>
       <div className={styles.drawingArtboardFrame} style={style}>
+        <canvas ref={latticeRef} className={styles.drawingLattice} aria-hidden="true" />
         <canvas ref={smoothRef} className={styles.drawingSmooth} aria-hidden="true" />
         <canvas
           ref={canvasRef}

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

@@ -23,7 +23,7 @@ export const PIXEL_TOOLS = [
 export const PATH_TOOLS = [
   { id: 'brush', label: 'Brush', icon: 'pencil', shortcut: 'B' },
   { id: 'fill', label: 'Fill', icon: 'fill', shortcut: 'G' },
-  { id: 'path-select', label: 'Select', icon: 'location-arrow', shortcut: 'V' },
+  { id: 'path-select', label: 'Select', icon: 'navigation-arrow', shortcut: 'V' },
   { id: 'bend', label: 'Bend', icon: 'bezier-curve', shortcut: 'N' },
 ];
 
@@ -40,7 +40,7 @@ export const SHAPE_MODES = [
 
 // Sub-modes for the path brush tool: click-to-place pen, freehand fit, drag primitives.
 export const BRUSH_MODES = [
-  { id: 'freehand', label: 'Freehand', icon: 'paintbrush' },
+  { id: 'freehand', label: 'Freehand', icon: 'scribble' },
   { id: 'pen', label: 'Pen', icon: 'pen-nib', shortcut: 'P' },
   { id: 'line', label: 'Line', icon: 'slash', shortcut: 'L' },
   { id: 'rect', label: 'Rectangle', icon: 'square', shortcut: 'R' },
@@ -58,7 +58,7 @@ export const PATH_BRUSH_MODE_BY_KEY = Object.fromEntries(
 export const MOVE_ACTIONS = [
   { id: 'flipH', label: 'Flip horizontal', icon: 'flip-h' },
   { id: 'flipV', label: 'Flip vertical', icon: 'flip-v' },
-  { id: 'rotateCW', label: 'Rotate clockwise', icon: 'redo' },
+  { id: 'rotateCW', label: 'Rotate clockwise', icon: 'rotate' },
 ];
 
 // Tools whose work is driven by the active palette color, so the palette panel
@@ -636,7 +636,7 @@ function ShapeInspectorButtons({
           aria-label="Rotate 90 degrees clockwise"
           disabled={!pathActions?.hasSelection}
           onClick={pathActions?.rotateCW}>
-          <Icon name="redo" />
+          <Icon name="rotate" />
         </button>
         <button
           type="button"