castle-web-cli 0.4.84 → 0.4.86

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

@@ -0,0 +1,954 @@
+import { 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 { eventToCell } from './pixelCanvas';
+import { forEachDab } from './pixelGeometry';
+import { PixelArtboard, PixelEditorHeader, usePixelEditorShell } from './pixelEditorChrome';
+import {
+  BRUSH_SIZES,
+  CanvasSizeBar,
+  CornerRadiusBar,
+  PaintStrip,
+  PIXEL_TOOLS,
+  PixelToolStrip,
+  PxArtInspectorDock,
+  usePixelToolState,
+} from './pixelInspector';
+import { useArtboardFit, useEditorCompactLayout } from './useArtboardFit';
+import {
+  DEFAULT_KEY,
+  EDITOR_KEYS,
+  EDITOR_PALETTE,
+  clearRegion,
+  fillRegion,
+  flipCellsH,
+  flipCellsV,
+  moveRegion,
+  paintLine,
+  paintShape,
+  rotateCellsCW,
+  sampleKey,
+  swapKey,
+} from './pxArtTools';
+import {
+  addFrame,
+  addLayer,
+  addTag,
+  cellOffsetAt,
+  cellsAt,
+  clampSelection,
+  deleteFrame,
+  deleteLayer,
+  deleteTag,
+  deriveSprite,
+  duplicateFrame,
+  duplicateLayer,
+  linkCell,
+  moveFrame,
+  moveLayer,
+  patchLayer,
+  patchTag,
+  resizeSprite,
+  serializeModel,
+  setCellOffset,
+  setDefaultDuration,
+  setDefaultTag,
+  setCornerRadius,
+  setFrameDuration,
+  setupSpriteCanvas,
+  unlinkCell,
+  withCellsAt,
+} from './pxArtEditorModel';
+import { frameDurations, playbackOrder, resolveActiveTag, usePreviewPlayback } from './pxArtPlayback';
+import { PxArtTimeline } from './pxArtTimeline';
+import tl from './pxArtTimeline.module.css';
+
+// Aseprite-style editor for the full .pxart sprite format: a full layers x frames
+// timeline below a compositing artboard. The artboard composites the active
+// frame's visible layers (renderSpriteFrame) so the artist sees the whole image
+// while painting targets the active layer's cell, over a FIXED Endesga-64
+// palette and power-of-two resolutions. Sprites that lose nothing in the compact
+// form serialize to compact; anything richer serializes to the full form.
+const ONION_WARM = '#ff7a3c';
+const ONION_COOL = '#3ca0ff';
+
+// 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.
+const TOOL_CURSORS = {
+  brush: 'cell',
+  erase: 'cell',
+  fill: 'crosshair',
+  shape: 'crosshair',
+  select: 'crosshair',
+  'move-all': 'move',
+};
+
+export function PxArtEditor({ path, text, onChange, ...chrome }) {
+  const canvasRef = useRef(null);
+  const smoothRef = useRef(null);
+  const overlayRef = useRef(null);
+  const strokeRef = useRef(null);
+  // The serialized text this editor last wrote itself. Lets us tell our own
+  // edits apart from external rewrites (undo/redo) so the marquee can be dropped
+  // when the art changes out from under it.
+  const lastSelfTextRef = useRef(text);
+  const [activeKey, setActiveKey] = useState(DEFAULT_KEY);
+  const [rawSelection, setRawSelection] = useState({ layerIndex: 0, frameIndex: 0 });
+  const [playing, setPlaying] = useState(false);
+  const [onion, setOnion] = useState({ enabled: false, range: 1 });
+  const [hoverCell, setHoverCell] = useState(null);
+  // The marquee selection rectangle { x, y, w, h } in canvas cells, or null. It
+  // is a MODE of the select tool: cleared when leaving the tool or changing the
+  // active cel. `antsOffset` ticks the marching-ants animation while it's shown.
+  const [marquee, setMarquee] = useState(null);
+  const [antsOffset, setAntsOffset] = useState(0);
+  const toolState = usePixelToolState();
+  const {
+    tool,
+    setTool,
+    picking,
+    setPicking,
+    eraseFillMode,
+    fillSwapMode,
+    shapeMode,
+    shapeFill,
+    brushSize,
+    setBrushSize,
+    eraseSize,
+    setEraseSize,
+  } = toolState;
+  const { history, headerShell } = usePixelEditorShell(text, onChange, path);
+  const canvasWrapRef = useRef(null);
+  const canvasSizeBarRef = useRef(null);
+  const colorButtonRef = useRef(null);
+  const editorBodyRef = useRef(null);
+  const [paletteOpen, setPaletteOpen] = useState(false);
+
+  const sprite = deriveSprite(text);
+  const selection = sprite
+    ? clampSelection(sprite, rawSelection.layerIndex, rawSelection.frameIndex)
+    : rawSelection;
+
+  const activeTag = sprite ? resolveActiveTag(sprite, sprite.defaultTag) : null;
+  const order = sprite ? playbackOrder(sprite, activeTag) : [0];
+  const durations = sprite ? frameDurations(sprite, order) : [100];
+  const repeat = activeTag ? activeTag.repeat : 0;
+  const previewIndex = usePreviewPlayback({ order, durations, repeat }, playing, selection.frameIndex);
+
+  useArtboardRender(canvasRef, text, sprite, previewIndex, onion, playing, {
+    selection,
+    hoverCell,
+    tool,
+    picking,
+    brushSize,
+    eraseSize,
+    activeKey,
+  });
+  const { canvasStyle } = useArtboardFit({
+    wrapRef: canvasWrapRef,
+    sizeBarRef: canvasSizeBarRef,
+    resolution: sprite?.resolution ?? { width: 16, height: 16 },
+  });
+  // `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
+  // 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
+  // it would keep rendering at whatever scale was last measured.
+  useSmoothPreviewRender(smoothRef, text, sprite, previewIndex, canvasStyle?.width);
+  useToolShortcuts({ tool, picking, setTool, setPicking, setBrushSize, setEraseSize });
+  const isCompactLayout = useEditorCompactLayout(editorBodyRef);
+  useEffect(() => {
+    if (!isCompactLayout) setPaletteOpen(false);
+  }, [isCompactLayout]);
+  // The marquee is a mode of the select tool: drop it when switching to another
+  // tool or when the active cel (layer/frame) changes, so it never lingers over
+  // pixels it no longer refers to.
+  useEffect(() => {
+    if (tool !== 'select') setMarquee(null);
+  }, [tool]);
+  useEffect(() => {
+    setMarquee(null);
+  }, [selection.layerIndex, selection.frameIndex]);
+  // Undo/redo (or any external rewrite) restores the art text but not the
+  // separate marquee state, which would strand the selection box over the wrong
+  // pixels. A text value this editor didn't produce means an external change, so
+  // drop the selection to keep it from ever desyncing from the art.
+  useEffect(() => {
+    if (text === lastSelfTextRef.current) return;
+    lastSelfTextRef.current = text;
+    setMarquee(null);
+  }, [text]);
+  // March the ants only while a selection is visible.
+  useEffect(() => {
+    if (tool !== 'select' || !marquee) return undefined;
+    const id = setInterval(() => setAntsOffset((o) => (o + 1) % 1000), 80);
+    return () => clearInterval(id);
+  }, [tool, marquee]);
+  // Draw the marching-ants selection on a display-resolution overlay canvas so
+  // the outline stays crisp (drawing it on the upscaled native artboard renders
+  // the thin dashes sub-pixel and washed out).
+  useEffect(() => {
+    renderMarqueeOverlay(overlayRef.current, sprite?.resolution, playing ? null : marquee, antsOffset);
+  }, [marquee, antsOffset, playing, canvasStyle, sprite?.resolution.width, sprite?.resolution.height]);
+  // Escape deselects; Delete/Backspace clears the selected pixels. Both only
+  // while the select tool is active and a marquee exists.
+  useEffect(() => {
+    if (tool !== 'select' || !marquee) return undefined;
+    function onKeyDown(event) {
+      if (event.metaKey || event.ctrlKey || event.altKey) return;
+      if (isTypingTarget(event.target || document.activeElement)) return;
+      if (event.key === 'Escape') {
+        setMarquee(null);
+        event.preventDefault();
+      } else if (event.key === 'Delete' || event.key === 'Backspace') {
+        deleteMarqueePixels();
+        event.preventDefault();
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [tool, marquee, text, selection.layerIndex, selection.frameIndex]);
+
+  if (!sprite) {
+    return (
+      <PxArtShell path={path} subtitle="invalid pixel art" shell={headerShell} chrome={chrome} editorBodyRef={editorBodyRef}>
+        <div className={styles.drawingToolHint}>This file is not valid pixel art.</div>
+      </PxArtShell>
+    );
+  }
+
+  const { width, height } = sprite.resolution;
+  const overSelection = tool === 'select' && marquee && hoverCell && pointInRect(hoverCell, marquee);
+  const cursor = picking
+    ? 'crosshair'
+    : overSelection
+      ? 'move'
+      : (TOOL_CURSORS[tool] ?? 'default');
+
+  function togglePalette(next) {
+    setPaletteOpen((previous) => (typeof next === 'boolean' ? next : !previous));
+  }
+
+  // Push a draft Sprite to the file (live, mid-stroke). Records ONE undo
+  // snapshot for the whole gesture and dedups by serialized text.
+  function liveSprite(nextSprite) {
+    const stroke = strokeRef.current;
+    if (!stroke) return;
+    const nextText = serializeModel(nextSprite);
+    if (nextText === stroke.draftText) return;
+    if (!stroke.recorded) {
+      history.recordSnapshot();
+      stroke.recorded = true;
+    }
+    stroke.draftText = nextText;
+    lastSelfTextRef.current = nextText;
+    onChange(nextText);
+  }
+  // Paint/erase strokes accumulate in a canvas-window matrix; merge it back into
+  // the (possibly larger/offset) cel so off-canvas pixels are preserved.
+  function liveStroke(nextCells) {
+    const stroke = strokeRef.current;
+    if (!stroke || nextCells === stroke.draftCells) return;
+    stroke.draftCells = nextCells;
+    liveSprite(withCellsAt(stroke.base, stroke.layerIndex, stroke.frameIndex, nextCells));
+  }
+  function commitCells(nextCells) {
+    const nextText = serializeModel(withCellsAt(sprite, selection.layerIndex, selection.frameIndex, nextCells));
+    lastSelfTextRef.current = nextText;
+    history.commit(nextText);
+  }
+  // Transform the active cel's canvas-window pixels in one history step (the
+  // move tool's flip / rotate actions). A no-op transform commits nothing.
+  function transformActiveCel(transform) {
+    const cells = cellsAt(sprite, selection.layerIndex, selection.frameIndex);
+    const next = transform(cells);
+    commitCells(next);
+  }
+  const moveActions = {
+    flipH: () => transformActiveCel(flipCellsH),
+    flipV: () => transformActiveCel(flipCellsV),
+    rotateCW: () => transformActiveCel(rotateCellsCW),
+  };
+  // Clear the marquee region's pixels to transparent (keeps the selection rect).
+  function deleteMarqueePixels() {
+    if (!marquee) return;
+    transformActiveCel((cells) => clearRegion(cells, marquee));
+  }
+  const selectActions = {
+    hasSelection: !!marquee,
+    deletePixels: deleteMarqueePixels,
+  };
+  function startTool(event) {
+    // Pull keyboard focus into this editor iframe so Cmd+Z reaches our undo
+    // handler (bound on this iframe's window) instead of falling through to the
+    // browser. Safari in particular won't keep keyboard focus in a subframe
+    // after clicking a non-focusable canvas, so we focus it explicitly. Done
+    // before the early-return so even a click outside a cell claims focus.
+    event.currentTarget.focus({ preventScroll: true });
+    const point = eventToCell(event, width, height);
+    if (!point) return;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    const cells = cellsAt(sprite, selection.layerIndex, selection.frameIndex);
+    // The eyedropper is a transient picker layered over the active tool: when
+    // engaged it intercepts the pick, leaves the underlying tool untouched, and
+    // exits picker mode so the previously selected tool resumes after one pick.
+    if (picking) {
+      setActiveKey(sampleKey(cells, point));
+      setPicking(false);
+      return;
+    }
+    if (tool === 'select') {
+      // Pointer down inside the current selection starts a move (lift & float);
+      // anywhere else begins a fresh marquee rectangle.
+      const moving = marquee && pointInRect(point, marquee);
+      strokeRef.current = {
+        tool: 'select',
+        mode: moving ? 'move' : 'new',
+        startPoint: point,
+        lastPoint: point,
+        base: sprite,
+        layerIndex: selection.layerIndex,
+        frameIndex: selection.frameIndex,
+        originCells: cells,
+        originRect: moving ? marquee : null,
+        draftCells: cells,
+        draftText: null,
+        recorded: false,
+      };
+      if (!moving) setMarquee({ x: point.x, y: point.y, w: 1, h: 1 });
+      updateStroke(point);
+      return;
+    }
+    if (tool === 'fill') {
+      const next = fillSwapMode ? swapKey(cells, point, activeKey) : fillRegion(cells, point, activeKey);
+      if (next !== cells) commitCells(next);
+      return;
+    }
+    if (tool === 'erase' && eraseFillMode) {
+      const next = fillRegion(cells, point, TRANSPARENT);
+      if (next !== cells) commitCells(next);
+      return;
+    }
+    strokeRef.current = {
+      tool,
+      startPoint: point,
+      lastPoint: point,
+      base: sprite,
+      layerIndex: selection.layerIndex,
+      frameIndex: selection.frameIndex,
+      // Offset of the cel at gesture start, so move applies an ABSOLUTE offset
+      // (start + total drag) and accumulates losslessly across gestures.
+      startOffset: cellOffsetAt(sprite, selection.layerIndex, selection.frameIndex),
+      draftCells: cells,
+      // The cells at gesture start, kept immutable so the shape tools recompute
+      // from a clean slate on each move instead of accumulating partial shapes.
+      originCells: cells,
+      draftText: null,
+      recorded: false,
+    };
+    updateStroke(point);
+  }
+  function updateTool(event) {
+    const stroke = strokeRef.current;
+    if (!stroke || event.buttons !== 1) return;
+    const point = eventToCell(event, width, height);
+    if (point) updateStroke(point);
+  }
+  // Track the hovered cell for the non-destructive tool preview overlay. While a
+  // stroke is active the preview is hidden so it never fights the live paint.
+  function handlePointerMove(event) {
+    updateTool(event);
+    if (strokeRef.current) {
+      setHoverCell(null);
+      return;
+    }
+    const point = eventToCell(event, width, height);
+    setHoverCell((prev) => (samePoint(prev, point) ? prev : point));
+  }
+  function clearHover() {
+    setHoverCell(null);
+  }
+  function updateStroke(point) {
+    const stroke = strokeRef.current;
+    if (!stroke) return;
+    if (stroke.tool === 'select') {
+      if (stroke.mode === 'new') {
+        setMarquee(rectFromPoints(stroke.startPoint, point, width, height));
+      } else {
+        const dx = point.x - stroke.startPoint.x;
+        const dy = point.y - stroke.startPoint.y;
+        liveStroke(moveRegion(stroke.originCells, stroke.originRect, dx, dy));
+        setMarquee({ ...stroke.originRect, x: stroke.originRect.x + dx, y: stroke.originRect.y + dy });
+      }
+      stroke.lastPoint = point;
+      return;
+    }
+    if (stroke.tool === 'brush') {
+      liveStroke(paintLine(stroke.draftCells, stroke.lastPoint, point, activeKey, brushSize));
+      stroke.lastPoint = point;
+    } else if (stroke.tool === 'erase') {
+      liveStroke(paintLine(stroke.draftCells, stroke.lastPoint, point, TRANSPARENT, eraseSize));
+      stroke.lastPoint = point;
+    } else if (stroke.tool === 'shape') {
+      // Recompute from the gesture-start snapshot so the shape rubber-bands to
+      // the current point rather than stacking each intermediate draft.
+      liveStroke(paintShape(stroke.originCells, stroke.startPoint, point, activeKey, shapeMode, shapeFill));
+    } else if (stroke.tool === 'move-all') {
+      // Translate the cel's OFFSET by the drag delta instead of shifting and
+      // clipping pixels — the full cel image is preserved, so pushing art off
+      // the canvas edge and back loses nothing (even across multiple gestures).
+      const x = stroke.startOffset.x + (point.x - stroke.startPoint.x);
+      const y = stroke.startOffset.y + (point.y - stroke.startPoint.y);
+      liveSprite(setCellOffset(stroke.base, stroke.layerIndex, stroke.frameIndex, x, y));
+    }
+  }
+  function finishTool() {
+    const stroke = strokeRef.current;
+    if (stroke && stroke.tool === 'select') {
+      if (stroke.mode === 'new' && samePoint(stroke.startPoint, stroke.lastPoint)) {
+        // A click with no drag deselects.
+        setMarquee(null);
+      } else if (stroke.mode === 'move') {
+        // Keep the ants box meaningful: clip the moved rect to the canvas (the
+        // pixels themselves were already clipped on commit), dropping it if it
+        // ended fully off-canvas.
+        setMarquee((rect) => clampRectToCanvas(rect, width, height));
+      }
+    }
+    strokeRef.current = null;
+  }
+
+  const actions = buildActions({
+    sprite,
+    selection,
+    history,
+    setSelection: setRawSelection,
+    setPlaying,
+    playing,
+    setOnion,
+  });
+
+  return (
+    <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={styles.artboardToolColumn}>
+              <PixelToolStrip
+                tools={PIXEL_TOOLS}
+                tool={tool}
+                onSelectTool={(id) => {
+                  setPicking(false);
+                  setTool(id);
+                }}
+                ariaLabel="Sprite tools"
+              />
+            </div>
+            <div ref={canvasWrapRef} className={styles.drawingCanvasWrap}>
+              <div className={styles.artboardStack}>
+                <div ref={canvasSizeBarRef} className={styles.canvasTopStack}>
+                  <div className={styles.canvasTopBar}>
+                    <CanvasSizeBar
+                      width={width}
+                      height={height}
+                      onResize={(w, h) => history.commit(serializeModel(resizeSprite(sprite, w, h)))}
+                    />
+                    <CornerRadiusBar
+                      radius={sprite.cornerRadius}
+                      onChange={(radius) => history.commit(serializeModel(setCornerRadius(sprite, radius)))}
+                    />
+                  </div>
+                </div>
+                <PixelArtboard
+                  canvasRef={canvasRef}
+                  smoothRef={smoothRef}
+                  overlayRef={overlayRef}
+                  style={{ ...canvasStyle, cursor }}
+                  handlers={{
+                    onPointerDown: startTool,
+                    onPointerMove: handlePointerMove,
+                    onPointerUp: finishTool,
+                    onPointerCancel: finishTool,
+                    onPointerLeave: clearHover,
+                  }}
+                />
+              </div>
+            </div>
+            <div className={styles.paintColumn}>
+              <PaintStrip
+                toolState={toolState}
+                activeKey={activeKey}
+                activeColor={EDITOR_PALETTE[activeKey]}
+                paletteOpen={paletteOpen}
+                onTogglePalette={togglePalette}
+                colorButtonRef={colorButtonRef}
+                onSelectKey={setActiveKey}
+                paletteKeys={EDITOR_KEYS}
+                palette={EDITOR_PALETTE}
+                moveActions={moveActions}
+                selectActions={selectActions}
+              />
+            </div>
+          </div>
+          <PxArtTimeline
+            sprite={sprite}
+            selection={selection}
+            playing={playing}
+            onion={onion}
+            actions={actions}
+          />
+        </div>
+        <PxArtInspectorDock
+          toolState={toolState}
+          activeKey={activeKey}
+          onSelectKey={setActiveKey}
+          paletteKeys={EDITOR_KEYS}
+          palette={EDITOR_PALETTE}
+          moveActions={moveActions}
+          selectActions={selectActions}
+        />
+      </div>
+    </PxArtShell>
+  );
+}
+
+// Build the timeline's mutation contract. Each action composes an immutable
+// model op with a history commit, updating the (layer, frame) selection where a
+// structural change moves it.
+function buildActions({ sprite, selection, history, setSelection, setPlaying, playing, setOnion }) {
+  const { layerIndex, frameIndex } = selection;
+  const commit = (next) => history.commit(serializeModel(next));
+  return {
+    selectCell: (li, fi) => setSelection({ layerIndex: li, frameIndex: fi }),
+    addLayer: (li) => {
+      commit(addLayer(sprite, li));
+      setSelection({ layerIndex: li + 1, frameIndex });
+    },
+    deleteLayer: (li) => {
+      commit(deleteLayer(sprite, li));
+      setSelection({ layerIndex: Math.max(li - 1, 0), frameIndex });
+    },
+    duplicateLayer: (li) => {
+      commit(duplicateLayer(sprite, li));
+      setSelection({ layerIndex: li + 1, frameIndex });
+    },
+    moveLayer: (li, dir) => {
+      commit(moveLayer(sprite, li, dir));
+      setSelection({ layerIndex: li + dir, frameIndex });
+    },
+    patchLayer: (li, patch) => commit(patchLayer(sprite, li, patch)),
+    addFrame: (fi) => {
+      commit(addFrame(sprite, fi));
+      setSelection({ layerIndex, frameIndex: fi + 1 });
+    },
+    deleteFrame: (fi) => {
+      commit(deleteFrame(sprite, fi));
+      setSelection({ layerIndex, frameIndex: Math.max(fi - 1, 0) });
+    },
+    duplicateFrame: (fi) => {
+      commit(duplicateFrame(sprite, fi));
+      setSelection({ layerIndex, frameIndex: fi + 1 });
+    },
+    moveFrame: (fi, dir) => {
+      commit(moveFrame(sprite, fi, dir));
+      setSelection({ layerIndex, frameIndex: fi + dir });
+    },
+    setFrameDuration: (fi, ms) => commit(setFrameDuration(sprite, fi, ms)),
+    setDefaultDuration: (ms) => commit(setDefaultDuration(sprite, ms)),
+    linkCell: (src) => commit(linkCell(sprite, layerIndex, frameIndex, src)),
+    unlinkCell: () => commit(unlinkCell(sprite, layerIndex, frameIndex)),
+    addTag: () => commit(addTag(sprite)),
+    patchTag: (i, patch) => commit(patchTag(sprite, i, patch)),
+    deleteTag: (i) => commit(deleteTag(sprite, i)),
+    setDefaultTag: (name) => commit(setDefaultTag(sprite, name)),
+    togglePlay: () => setPlaying(!playing),
+    setOnionEnabled: (enabled) => setOnion((prev) => ({ ...prev, enabled })),
+    setOnionRange: (range) => setOnion((prev) => ({ ...prev, range: Math.max(1, range || 1) })),
+  };
+}
+
+function PxArtShell({ path, subtitle, shell, chrome, editorBodyRef, children }) {
+  return (
+    <>
+      <PixelEditorHeader title={basename(path)} subtitle={subtitle} shell={shell} chrome={chrome} />
+      <EditorBody ref={editorBodyRef}>{children}</EditorBody>
+    </>
+  );
+}
+
+function pxArtSubtitle(sprite) {
+  const { width, height } = sprite.resolution;
+  const layers = sprite.layers.length;
+  const frames = frameCount(sprite);
+  return `${width} x ${height} · ${layers} layer${layers === 1 ? '' : 's'} · ${frames} frame${frames === 1 ? '' : 's'}`;
+}
+
+// ---------------------------------------------------------------------------
+// artboard rendering: composite active frame + onion skins
+// ---------------------------------------------------------------------------
+
+// Redraw the artboard whenever the sprite text or any preview input changes,
+// layering the render-only tool ghost on top of the composited frame. Gated on
+// `text` (deriveSprite returns a fresh object each render).
+function useArtboardRender(canvasRef, text, sprite, previewIndex, onion, playing, p) {
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !sprite) return;
+    renderArtboard(canvas, sprite, previewIndex, onion, playing, buildToolPreview({ sprite, playing, ...p }));
+  }, [
+    text,
+    previewIndex,
+    playing,
+    onion.enabled,
+    onion.range,
+    p.hoverCell,
+    p.tool,
+    p.picking,
+    p.brushSize,
+    p.eraseSize,
+    p.activeKey,
+    p.selection.layerIndex,
+    p.selection.frameIndex,
+  ]);
+}
+
+// Render the "smooth" preview into its own display-resolution canvas, behind
+// the interactive artboard (see .drawingSmooth). Left empty when
+// `cornerRadius` is 0 (sharp/pixel) — the interactive canvas's own unrounded
+// frame draw is what shows then. Runs off `text`/`previewIndex` rather than
+// 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
+// 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).
+function useSmoothPreviewRender(smoothRef, text, sprite, frameIndex, displayWidth) {
+  const cornerRadius = sprite?.cornerRadius ?? 0;
+  useEffect(() => {
+    const canvas = smoothRef.current;
+    if (!canvas) return;
+    if (!sprite || cornerRadius <= 0) {
+      canvas.width = 0;
+      canvas.height = 0;
+      return;
+    }
+    const cssWidth = canvas.clientWidth || sprite.resolution.width;
+    const dpr = window.devicePixelRatio || 1;
+    const autoScale = Math.min(16, Math.max(4, Math.round((cssWidth * dpr) / sprite.resolution.width)));
+    renderSmoothSpriteFrame(sprite, frameIndex, canvas, { scale: autoScale, cornerRadius });
+  }, [text, frameIndex, smoothRef, cornerRadius, displayWidth]);
+}
+
+// Window-scoped tool keyboard shortcuts, mounted only while the editor is.
+function useToolShortcuts(ctx) {
+  const { tool, picking, setTool, setPicking, setBrushSize, setEraseSize } = ctx;
+  useEffect(() => {
+    function onKeyDown(event) {
+      if (handleToolShortcut(event, ctx)) event.preventDefault();
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [tool, picking, setTool, setPicking, setBrushSize, setEraseSize]);
+}
+
+function renderArtboard(canvas, sprite, frameIndex, onion, playing, preview) {
+  const ctx = setupSpriteCanvas(canvas, sprite.resolution);
+  if (!ctx) return;
+  if (onion.enabled && !playing) {
+    for (let d = onion.range; d >= 1; d--) {
+      blitOnion(ctx, sprite, frameIndex - d, ONION_WARM, d);
+      blitOnion(ctx, sprite, frameIndex + d, ONION_COOL, d);
+    }
+  }
+  ctx.globalAlpha = 1;
+  // "Smooth" sprites are drawn by the display-resolution .drawingSmooth canvas
+  // BEHIND this one (see useSmoothPreviewRender); leaving this canvas
+  // transparent here lets that show through while pointer math, the marquee,
+  // and the tool-preview ghost below all keep working in native grid units.
+  if (sprite.cornerRadius <= 0) {
+    ctx.drawImage(frameCanvas(sprite, frameIndex), 0, 0);
+  }
+  if (preview) drawToolPreview(ctx, canvas, preview);
+}
+
+// Render-only animated marching ants for the marquee selection, drawn on a
+// display-resolution overlay canvas (1 device pixel per CSS pixel) so the dashed
+// outline is crisp and bold rather than sub-pixel on the upscaled artboard.
+// `rect` is in canvas cells; null clears the overlay.
+function renderMarqueeOverlay(canvas, resolution, rect, antsOffset) {
+  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 (!rect) return;
+
+  const sx = bw / resolution.width;
+  const sy = bh / resolution.height;
+  const lineWidth = Math.max(2, Math.round(2 * dpr));
+  const dash = Math.max(5, Math.round(5 * dpr));
+  // Advance ~2 device px per tick (not a whole dash) so the ants crawl smoothly
+  // instead of teleporting a full dash each frame.
+  const step = Math.max(1, Math.round(dpr));
+  const move = (antsOffset * step) % (dash * 2);
+  const half = lineWidth / 2;
+  const x = rect.x * sx + half;
+  const y = rect.y * sy + half;
+  const w = Math.max(lineWidth, rect.w * sx - lineWidth);
+  const h = Math.max(lineWidth, rect.h * sy - lineWidth);
+
+  ctx.lineWidth = lineWidth;
+  ctx.setLineDash([dash, dash]);
+  ctx.strokeStyle = '#000000';
+  ctx.lineDashOffset = -move;
+  ctx.strokeRect(x, y, w, h);
+  ctx.strokeStyle = '#ffffff';
+  ctx.lineDashOffset = -move + dash;
+  ctx.strokeRect(x, y, w, h);
+}
+
+// Build a marquee rect { x, y, w, h } from two cell points, normalized and
+// clamped to the canvas (min 1x1).
+function rectFromPoints(a, b, width, height) {
+  const x0 = Math.max(0, Math.min(a.x, b.x));
+  const y0 = Math.max(0, Math.min(a.y, b.y));
+  const x1 = Math.min(width - 1, Math.max(a.x, b.x));
+  const y1 = Math.min(height - 1, Math.max(a.y, b.y));
+  return { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 };
+}
+
+function pointInRect(point, rect) {
+  return (
+    point.x >= rect.x &&
+    point.x < rect.x + rect.w &&
+    point.y >= rect.y &&
+    point.y < rect.y + rect.h
+  );
+}
+
+// Intersect a marquee rect with the canvas; null when it ends up fully off it.
+function clampRectToCanvas(rect, width, height) {
+  if (!rect) return null;
+  const x0 = Math.max(0, rect.x);
+  const y0 = Math.max(0, rect.y);
+  const x1 = Math.min(width, rect.x + rect.w);
+  const y1 = Math.min(height, rect.y + rect.h);
+  if (x1 <= x0 || y1 <= y0) return null;
+  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+
+function blitOnion(ctx, sprite, idx, color, dist) {
+  if (idx < 0 || idx >= frameCount(sprite)) return;
+  ctx.globalAlpha = Math.max(0.12, 0.5 / dist);
+  ctx.drawImage(onionTint(frameCanvas(sprite, idx), color), 0, 0);
+}
+
+function frameCanvas(sprite, idx) {
+  const canvas = document.createElement('canvas');
+  renderSpriteFrame(sprite, idx, canvas);
+  return canvas;
+}
+
+// Colorize an already-rendered frame toward `color` over its own silhouette
+// (source-atop), so onion ghosts read as warm (past) / cool (future) washes.
+function onionTint(src, color) {
+  const canvas = document.createElement('canvas');
+  canvas.width = src.width;
+  canvas.height = src.height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return src;
+  ctx.imageSmoothingEnabled = false;
+  ctx.drawImage(src, 0, 0);
+  ctx.globalCompositeOperation = 'source-atop';
+  ctx.globalAlpha = 0.55;
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  return canvas;
+}
+
+// ---------------------------------------------------------------------------
+// keyboard shortcuts: tool selection + active size step
+// ---------------------------------------------------------------------------
+
+// Single-letter tool picks. The eyedropper ('i') is handled separately because
+// it toggles the transient picker rather than swapping the sidebar tool.
+const SHORTCUT_TOOLS = { b: 'brush', g: 'fill', s: 'shape', m: 'select', e: 'erase', v: 'move-all' };
+
+// True when focus is on a text-entry control, so typing there isn't hijacked.
+function isTypingTarget(node) {
+  if (!node || !node.tagName) return false;
+  const tag = node.tagName.toLowerCase();
+  return tag === 'input' || tag === 'textarea' || tag === 'select' || node.isContentEditable;
+}
+
+// Step the active size through the SAME discrete BRUSH_SIZES the slider uses,
+// clamped to its first/last entry (the size UI's min/max).
+function stepBrushSize(current, delta) {
+  const index = Math.max(0, BRUSH_SIZES.indexOf(current));
+  const next = Math.min(BRUSH_SIZES.length - 1, Math.max(0, index + delta));
+  return BRUSH_SIZES[next];
+}
+
+// Resize the active tool with [ / ]. Only brush/erase have a size; other tools
+// make this a no-op (returns false so the caller leaves the key alone).
+function adjustToolSize(delta, ctx) {
+  if (ctx.tool === 'brush') {
+    ctx.setBrushSize((prev) => stepBrushSize(prev, delta));
+    return true;
+  }
+  if (ctx.tool === 'erase') {
+    ctx.setEraseSize((prev) => stepBrushSize(prev, delta));
+    return true;
+  }
+  return false;
+}
+
+// Map a keydown to a tool action; returns true when it consumed the key. Bails
+// on modifier combos (undo/redo, alt behaviors) and while typing in a field.
+function handleToolShortcut(event, ctx) {
+  if (event.metaKey || event.ctrlKey || event.altKey) return false;
+  if (isTypingTarget(event.target || document.activeElement)) return false;
+  const key = event.key.toLowerCase();
+  const toolId = SHORTCUT_TOOLS[key];
+  if (toolId) {
+    ctx.setPicking(false);
+    ctx.setTool(toolId);
+    return true;
+  }
+  if (key === 'i') {
+    ctx.setPicking(!ctx.picking);
+    return true;
+  }
+  if (event.key === '[' || event.key === ']') {
+    return adjustToolSize(event.key === '[' ? -1 : 1, ctx);
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// tool hover preview: a render-only ghost of where the current tool would act
+// ---------------------------------------------------------------------------
+
+const PREVIEW_PAINT_ALPHA = 0.5;
+const PREVIEW_WASH_ALPHA = 0.35;
+const PREVIEW_HIGHLIGHT_ALPHA = 0.45;
+// A reserved sentinel key (not a palette key) used to flood-mark the fill region
+// for the region-accurate fill preview, via the editor's own fillRegion.
+const FILL_PREVIEW_SENTINEL = '\u0000';
+
+function samePoint(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.x === b.x && a.y === b.y;
+}
+
+// The exact set of cells a fill at `start` would recolor, computed by reusing
+// fillRegion with a sentinel key and collecting the marked cells.
+function fillPreviewCells(cells, start) {
+  const filled = fillRegion(cells, start, FILL_PREVIEW_SENTINEL);
+  if (filled === cells) return [];
+  const out = [];
+  for (let y = 0; y < filled.length; y++) {
+    const row = filled[y];
+    for (let x = 0; x < row.length; x++) {
+      if (row[x] === FILL_PREVIEW_SENTINEL) out.push({ x, y });
+    }
+  }
+  return out;
+}
+
+// Describe the overlay to draw for the hovered cell, or null when nothing should
+// show (no hover, playback, or the move-all tool which has no footprint).
+function buildToolPreview({ sprite, selection, hoverCell, tool, picking, brushSize, eraseSize, activeKey, playing }) {
+  if (!hoverCell || playing) return null;
+  const color = EDITOR_PALETTE[activeKey] || '#ffffff';
+  if (picking) return { kind: 'cell', cell: hoverCell };
+  if (tool === 'brush') return { kind: 'footprint', cell: hoverCell, size: brushSize, color };
+  if (tool === 'erase') return { kind: 'erase', cell: hoverCell, size: eraseSize };
+  if (tool === 'fill') {
+    const cells = cellsAt(sprite, selection.layerIndex, selection.frameIndex);
+    return { kind: 'region', cells: fillPreviewCells(cells, hoverCell), color };
+  }
+  // The shape tool needs two points to draw, so before a drag we just mark the
+  // hovered start cell; the live shape itself shows once the drag begins.
+  if (tool === 'shape') return { kind: 'cell', cell: hoverCell };
+  return null;
+}
+
+// One native canvas unit corresponds to (native / displayed) pixels; sizing
+// outlines to that keeps them ~1 screen pixel regardless of the artboard zoom.
+function previewLineWidth(canvas) {
+  return canvas.clientWidth ? canvas.width / canvas.clientWidth : 0.15;
+}
+
+// Translucent fill of a brush/erase dab footprint, matching how paintLine lays
+// down `size` cells around the center so the ghost lines up with real paint.
+function fillDabCells(ctx, cell, size, color, alpha) {
+  ctx.globalAlpha = alpha;
+  ctx.fillStyle = color;
+  forEachDab(size, (dx, dy) => ctx.fillRect(cell.x + dx, cell.y + dy, 1, 1));
+}
+
+// A thin "cut" outline around a dab footprint's bounds, so erase reads as a
+// removal region rather than a paint stroke.
+function strokeDabBounds(ctx, cell, size, lineWidth) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  forEachDab(size, (dx, dy) => {
+    minX = Math.min(minX, dx);
+    minY = Math.min(minY, dy);
+    maxX = Math.max(maxX, dx);
+    maxY = Math.max(maxY, dy);
+  });
+  if (minX === Infinity) return;
+  ctx.globalAlpha = 0.85;
+  ctx.strokeStyle = '#1c1c1c';
+  ctx.lineWidth = lineWidth;
+  const half = lineWidth / 2;
+  ctx.strokeRect(cell.x + minX + half, cell.y + minY + half, maxX - minX + 1 - lineWidth, maxY - minY + 1 - lineWidth);
+}
+
+function fillCellList(ctx, cells, color, alpha) {
+  ctx.globalAlpha = alpha;
+  ctx.fillStyle = color;
+  for (const cell of cells) ctx.fillRect(cell.x, cell.y, 1, 1);
+}
+
+// Render-only: paint the ghost overlay for the current tool onto the artboard
+// after the sprite. Never mutates the sprite, history, or serialized output.
+function drawToolPreview(ctx, canvas, preview) {
+  ctx.save();
+  const lineWidth = previewLineWidth(canvas);
+  if (preview.kind === 'footprint') {
+    fillDabCells(ctx, preview.cell, preview.size, preview.color, PREVIEW_PAINT_ALPHA);
+  } else if (preview.kind === 'erase') {
+    fillDabCells(ctx, preview.cell, preview.size, '#ffffff', PREVIEW_WASH_ALPHA);
+    strokeDabBounds(ctx, preview.cell, preview.size, lineWidth);
+  } else if (preview.kind === 'region') {
+    fillCellList(ctx, preview.cells, preview.color, PREVIEW_HIGHLIGHT_ALPHA);
+  } else if (preview.kind === 'cell') {
+    fillCellList(ctx, [preview.cell], '#ffffff', PREVIEW_HIGHLIGHT_ALPHA);
+    ctx.globalAlpha = 0.9;
+    ctx.strokeStyle = '#1c1c1c';
+    ctx.lineWidth = lineWidth;
+    const half = lineWidth / 2;
+    ctx.strokeRect(preview.cell.x + half, preview.cell.y + half, 1 - lineWidth, 1 - lineWidth);
+  }
+  ctx.restore();
+}