castle-web-cli 0.4.71 → 0.4.73

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

@@ -0,0 +1,662 @@
+import { useEffect, useRef, useState } from 'react';
+import { frameCount, renderSpriteFrame, TRANSPARENT } from '../engine/pxart';
+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,
+  PaintStrip,
+  PIXEL_TOOLS,
+  PixelToolStrip,
+  PxArtInspectorDock,
+  usePixelToolState,
+} from './pixelInspector';
+import { useArtboardFit, useEditorCompactLayout } from './useArtboardFit';
+import {
+  EDITOR_KEYS,
+  EDITOR_PALETTE,
+  fillRegion,
+  paintLine,
+  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,
+  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',
+  'move-all': 'move',
+};
+
+export function PxArtEditor({ path, text, onChange, ...chrome }) {
+  const canvasRef = useRef(null);
+  const strokeRef = useRef(null);
+  const [activeKey, setActiveKey] = useState(EDITOR_KEYS[1]);
+  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);
+  const toolState = usePixelToolState();
+  const {
+    tool,
+    setTool,
+    picking,
+    setPicking,
+    eraseFillMode,
+    fillSwapMode,
+    brushSize,
+    setBrushSize,
+    eraseSize,
+    setEraseSize,
+  } = toolState;
+  const { history, headerShell } = usePixelEditorShell(text, onChange);
+  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,
+  });
+  useToolShortcuts({ tool, picking, setTool, setPicking, setBrushSize, setEraseSize });
+  const { canvasStyle } = useArtboardFit({
+    wrapRef: canvasWrapRef,
+    sizeBarRef: canvasSizeBarRef,
+    resolution: sprite?.resolution ?? { width: 16, height: 16 },
+  });
+  const isCompactLayout = useEditorCompactLayout(editorBodyRef);
+  useEffect(() => {
+    if (!isCompactLayout) setPaletteOpen(false);
+  }, [isCompactLayout]);
+
+  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 cursor = picking ? 'crosshair' : (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;
+    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) {
+    history.commit(serializeModel(withCellsAt(sprite, selection.layerIndex, selection.frameIndex, nextCells)));
+  }
+  function startTool(event) {
+    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 === '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,
+      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 === '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 === '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() {
+    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}>
+                  <CanvasSizeBar
+                    width={width}
+                    height={height}
+                    onResize={(w, h) => history.commit(serializeModel(resizeSprite(sprite, w, h)))}
+                  />
+                </div>
+                <PixelArtboard
+                  canvasRef={canvasRef}
+                  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}
+              />
+            </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}
+        />
+      </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,
+  ]);
+}
+
+// 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;
+  ctx.drawImage(frameCanvas(sprite, frameIndex), 0, 0);
+  if (preview) drawToolPreview(ctx, canvas, preview);
+}
+
+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', 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 };
+  }
+  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();
+}