castle-web-cli 0.4.71 → 0.4.73

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

@@ -0,0 +1,718 @@
+import {
+  colorForKeyV2,
+  DEFAULT_DURATION_MS,
+  DEFAULT_RESOLUTION,
+  forEachCelPixel,
+  fromCells,
+  frameCount,
+  paletteLookup,
+  parseFull,
+  RESOLUTION_MAX,
+  resolveCell,
+  resolveCellGrid,
+  serializeCompact,
+  serializeFull,
+  snapResolutionDim,
+  TRANSPARENT,
+} from '../engine/pxart';
+import {
+  blankCells,
+  EDITOR_KEYS,
+  EDITOR_PALETTE,
+  editorKeyForHex,
+} from './pxArtTools';
+
+// ============================================================================
+// Working-state helpers for the full Sprite the PxArt editor edits in memory.
+//
+// The editor always works on a Sprite normalized onto the FIXED Endesga-64
+// palette, so painting + serialization stay consistent no matter what palette
+// an externally-authored file arrived with. Every mutation is immutable
+// (returns a fresh Sprite) so it flows straight into the text undo/redo history.
+// ============================================================================
+
+// The Endesga-64 palette as an ordered { key, hex } list (the full palette shape).
+export const EDITOR_ORDERED = EDITOR_KEYS.map((key) => ({ key, hex: EDITOR_PALETTE[key] }));
+
+// Size a canvas to a sprite resolution, disable smoothing, and clear it.
+// Returns the 2D context (or null). Shared by the artboard + thumbnail renders.
+export function setupSpriteCanvas(canvas, resolution) {
+  const { width, height } = resolution;
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return null;
+  ctx.imageSmoothingEnabled = false;
+  ctx.clearRect(0, 0, width, height);
+  return ctx;
+}
+
+// Visit each in-bounds cell of a packed grid (rows of palette-key chars),
+// clipped to width/height. `visit(x, y, key)` receives the char at that cell.
+export function forEachGridCell(grid, width, height, visit) {
+  const rows = Math.min(grid.length, height);
+  for (let y = 0; y < rows; y++) {
+    const row = grid[y];
+    const cols = Math.min(row.length, width);
+    for (let x = 0; x < cols; x++) visit(x, y, row[x]);
+  }
+}
+
+// Parse file text into a palette-normalized working Sprite. Empty text yields a
+// blank single-layer / single-frame sprite. Returns null when the text is not
+// valid pixel art (so the caller can show an error state).
+export function deriveSprite(text) {
+  if (!(text ?? '').trim()) return blankSprite();
+  const parsed = parseFull(text);
+  return parsed ? normalizeToPalette(parsed) : null;
+}
+
+function blankSprite() {
+  const { width, height } = DEFAULT_RESOLUTION;
+  return {
+    resolution: { width, height },
+    palette: EDITOR_ORDERED,
+    // The lone frame inherits the global duration (no per-frame override).
+    frames: [{}],
+    defaultDurationMs: DEFAULT_DURATION_MS,
+    tags: [],
+    defaultTag: undefined,
+    layers: [makeLayer('layer-0', 'Layer 1', [null])],
+  };
+}
+
+function makeLayer(id, name, cells) {
+  return { id, name, visible: true, opacity: 1, blendMode: 'normal', kind: 'pixel', cells };
+}
+
+// Build a { grid } cell, attaching the offset only when nonzero so a cel that
+// sits flush at the canvas origin keeps the compact { grid } shape (and still
+// serializes to the compact form when it's the only cel). x/y may be negative
+// (off-canvas to the left/top). Mirrors the SDK's makeGridCell.
+function gridCell(grid, x, y) {
+  return x || y ? { grid, x, y } : { grid };
+}
+
+// Remap every grid char onto the nearest Endesga-64 key and swap in the full
+// palette, leaving links / null cells / structure untouched. Idempotent for an
+// already-normalized sprite.
+function normalizeToPalette(sprite) {
+  const lookup = paletteLookup(sprite.palette);
+  const layers = sprite.layers.map((layer) => ({
+    ...layer,
+    cells: layer.cells.map((cell) => remapCell(cell, lookup)),
+  }));
+  return { ...sprite, palette: EDITOR_ORDERED, layers };
+}
+
+function remapCell(cell, lookup) {
+  if (cell == null) return null;
+  if ('link' in cell) return { link: cell.link };
+  // Preserve the cel's offset while remapping its palette keys.
+  return gridCell(cell.grid.map((row) => remapRow(row, lookup)), cell.x ?? 0, cell.y ?? 0);
+}
+
+function remapRow(row, lookup) {
+  let out = '';
+  for (const ch of row) {
+    if (ch === TRANSPARENT) {
+      out += TRANSPARENT;
+      continue;
+    }
+    const hex = colorForKeyV2(lookup, ch);
+    out += hex ? editorKeyForHex(hex) : TRANSPARENT;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// cells <-> (layer, frame)
+// ---------------------------------------------------------------------------
+
+// The CANVAS-WINDOW view of the cel at (layerIndex, frameIndex): the cel image
+// composited at its (x, y) offset into a resolution-sized matrix, CLIPPED to the
+// canvas. Follows same-layer links (shared image + offset). Pixels of the cel
+// that lie outside the canvas window are not represented here (they live only in
+// the stored cel grid); the paint tools edit this window and withCellsAt merges
+// the result back without disturbing those off-window pixels.
+export function cellsAt(sprite, layerIndex, frameIndex) {
+  const { width, height } = sprite.resolution;
+  const layer = sprite.layers[layerIndex];
+  const resolved = layer ? resolveCell(layer, frameIndex) : null;
+  const cells = blankCells(width, height);
+  if (resolved) {
+    forEachCelPixel(resolved, width, height, (cx, cy, key) => {
+      cells[cy][cx] = key || TRANSPARENT;
+    });
+  }
+  return cells;
+}
+
+// Merge a painted canvas-window matrix back into the cel at (layerIndex,
+// frameIndex), following links so editing a linked cell edits the shared source.
+// The window region [0,width) x [0,height) is AUTHORITATIVE (it carries the
+// edit, including erases); cel pixels OUTSIDE that window are preserved verbatim.
+// The merged cel covers the union of the canvas window and the prior cel rect,
+// so off-canvas content is never dropped. Result is capped at 512/axis.
+export function withCellsAt(sprite, layerIndex, frameIndex, cells) {
+  const layer = sprite.layers[layerIndex];
+  const target = writeTargetIndex(layer, frameIndex);
+  const prev = layer ? resolveCell(layer, target) : null;
+  const merged = mergeWindowIntoCell(prev, cells, sprite.resolution);
+  return updateLayerCell(sprite, layerIndex, target, merged);
+}
+
+// Composite the edited window matrix over the existing cel, in canvas space.
+// Returns a { grid, x, y } cell (offset omitted when zero) sized to the union of
+// the canvas window and the prior cel rect — never shrinking below the window,
+// so a flush-at-origin cel keeps a resolution-sized grid (and stays
+// compact-eligible) while off-canvas overhang is retained. All-transparent merges still keep the
+// window-sized grid (matches the pre-offset "write the whole window" behavior).
+function mergeWindowIntoCell(prev, cells, resolution) {
+  const { width: resW, height: resH } = resolution;
+  const px = prev ? prev.x : 0;
+  const py = prev ? prev.y : 0;
+  const pGrid = prev ? prev.grid : [];
+  const ph = pGrid.length;
+  const pw = ph ? Math.max(...pGrid.map((row) => row.length)) : 0;
+
+  let minX = 0;
+  let minY = 0;
+  let maxX = resW;
+  let maxY = resH;
+  if (ph) {
+    minX = Math.min(minX, px);
+    minY = Math.min(minY, py);
+    maxX = Math.max(maxX, px + pw);
+    maxY = Math.max(maxY, py + ph);
+  }
+
+  // The canvas window is authoritative within [0,resW) x [0,resH); elsewhere the
+  // prior cel pixel (off-canvas content) stands.
+  const sample = (cx, cy) => {
+    if (cx >= 0 && cx < resW && cy >= 0 && cy < resH) return cells[cy][cx];
+    const gx = cx - px;
+    const gy = cy - py;
+    if (gy >= 0 && gy < ph) return pGrid[gy][gx] ?? TRANSPARENT;
+    return TRANSPARENT;
+  };
+
+  // Cap the union to 512/axis, keeping the band that contains the canvas window.
+  [minX, maxX] = capAxisToCanvas(minX, maxX, resW);
+  [minY, maxY] = capAxisToCanvas(minY, maxY, resH);
+
+  const grid = [];
+  for (let cy = minY; cy < maxY; cy++) {
+    let row = '';
+    for (let cx = minX; cx < maxX; cx++) row += sample(cx, cy);
+    grid.push(row);
+  }
+  return gridCell(grid, minX, minY);
+}
+
+// Clamp a canvas-space axis range [lo, hi) so its span never exceeds 512, always
+// keeping the canvas window [0, win) fully covered. When it must crop, it drops
+// the band farthest from the canvas (the most off-canvas pixels) — the single
+// place the "never discard off-canvas pixels" invariant can yield, and only for
+// content spanning >512 on one axis (well beyond the move-off-and-back path).
+function capAxisToCanvas(lo, hi, win) {
+  if (hi - lo <= RESOLUTION_MAX) return [lo, hi];
+  const slack = RESOLUTION_MAX - win; // win <= 512, so slack >= 0
+  let newLo = Math.max(lo, -Math.floor(slack / 2));
+  let newHi = newLo + RESOLUTION_MAX;
+  if (newHi > hi) {
+    newHi = hi;
+    newLo = hi - RESOLUTION_MAX;
+  }
+  // Guarantee the canvas window stays covered.
+  if (newLo > 0) newLo = 0;
+  if (newHi < win) newHi = win;
+  return [newLo, newHi];
+}
+
+// The cel's resolved offset at (layerIndex, frameIndex) — (0,0) when empty.
+export function cellOffsetAt(sprite, layerIndex, frameIndex) {
+  const layer = sprite.layers[layerIndex];
+  const resolved = layer ? resolveCell(layer, frameIndex) : null;
+  return { x: resolved?.x ?? 0, y: resolved?.y ?? 0 };
+}
+
+// Set the ABSOLUTE offset of the cel at (layerIndex, frameIndex), following
+// links to the shared source so all linked frames move together (shared offset).
+// This is the move-all primitive: it translates the whole cel image without
+// touching its pixels, so pushing art off the canvas edge and back is lossless.
+// A no-op on an empty cell (nothing to move).
+export function setCellOffset(sprite, layerIndex, frameIndex, x, y) {
+  const layer = sprite.layers[layerIndex];
+  if (!layer) return sprite;
+  const target = writeTargetIndex(layer, frameIndex);
+  const cell = layer.cells[target];
+  if (cell == null || 'link' in cell) return sprite;
+  if ((cell.x ?? 0) === x && (cell.y ?? 0) === y) return sprite;
+  return updateLayerCell(sprite, layerIndex, target, gridCell(cell.grid, x, y));
+}
+
+// Resolve the cell index a paint should write to: follow links to the cell that
+// actually holds the { grid }; an empty / broken chain writes the active cell.
+function writeTargetIndex(layer, frameIndex) {
+  if (!layer) return frameIndex;
+  const visited = new Set();
+  let idx = frameIndex;
+  while (idx >= 0 && idx < layer.cells.length && !visited.has(idx)) {
+    visited.add(idx);
+    const cell = layer.cells[idx];
+    if (cell == null || 'grid' in cell) return idx;
+    idx = cell.link;
+  }
+  return frameIndex;
+}
+
+function updateLayerCell(sprite, layerIndex, cellIndex, cell) {
+  const layers = sprite.layers.map((layer, i) => {
+    if (i !== layerIndex) return layer;
+    const cells = layer.cells.slice();
+    cells[cellIndex] = cell;
+    return { ...layer, cells };
+  });
+  return { ...sprite, layers };
+}
+
+// The display kind of a (layer, frame) cell: 'empty' | 'link' | 'grid'.
+export function cellKind(layer, frameIndex) {
+  const cell = layer?.cells[frameIndex];
+  if (cell == null) return 'empty';
+  if ('link' in cell) return 'link';
+  return 'grid';
+}
+
+// ---------------------------------------------------------------------------
+// linked cells
+// ---------------------------------------------------------------------------
+
+// A cell is either LINKED or UNLINKED — a single bit. "Linked" means it shares
+// its image with the PREVIOUS frame's cell in the same layer, so a linked cell's
+// `link` ALWAYS points at `frameIndex - 1`. If that previous cell is itself a
+// link, resolution (resolveCellGrid) chains transitively back to the nearest
+// { grid } — the run's source — so a run of consecutive linked cells all share
+// one image and editing any of them edits the whole run.
+//
+// Unavailable on frame 0 (no previous to link to), and a no-op when the previous
+// frame resolves to nothing (linking to an empty cell would only blank this one,
+// which is never what the menu offers). The 4th arg of the old arbitrary-source
+// API is accepted-and-ignored so existing wiring keeps working.
+export function linkCell(sprite, layerIndex, frameIndex) {
+  const layer = sprite.layers[layerIndex];
+  if (!layer || frameIndex <= 0) return sprite;
+  if (!resolveCellGrid(layer, frameIndex - 1)) return sprite;
+  return updateLayerCell(sprite, layerIndex, frameIndex, { link: frameIndex - 1 });
+}
+
+// Detach a linked cell into an INDEPENDENT copy of whatever it currently shows:
+// resolve the chain to the source pixels and write them as this cell's own
+// { grid } (or null when nothing resolves). It looks identical immediately, but
+// edits no longer propagate to or from the rest of the run.
+export function unlinkCell(sprite, layerIndex, frameIndex) {
+  const layer = sprite.layers[layerIndex];
+  const resolved = layer ? resolveCell(layer, frameIndex) : null;
+  // Copy the shared image AND its offset so the detached cel looks identical.
+  const cell = resolved ? gridCell(resolved.grid.slice(), resolved.x, resolved.y) : null;
+  return updateLayerCell(sprite, layerIndex, frameIndex, cell);
+}
+
+// ---------------------------------------------------------------------------
+// layer ops
+// ---------------------------------------------------------------------------
+
+function uniqueLayerId(sprite) {
+  const ids = new Set(sprite.layers.map((layer) => layer.id));
+  let n = sprite.layers.length;
+  let id = `layer-${n}`;
+  while (ids.has(id)) id = `layer-${++n}`;
+  return id;
+}
+
+// Insert a fresh empty layer directly ABOVE the active one (Aseprite stacks new
+// layers on top; layer 0 is the bottom of the stack).
+export function addLayer(sprite, layerIndex) {
+  const cells = sprite.frames.map(() => null);
+  const layer = makeLayer(uniqueLayerId(sprite), `Layer ${sprite.layers.length + 1}`, cells);
+  const layers = sprite.layers.slice();
+  layers.splice(layerIndex + 1, 0, layer);
+  return { ...sprite, layers };
+}
+
+export function deleteLayer(sprite, layerIndex) {
+  if (sprite.layers.length <= 1) return sprite;
+  const layers = sprite.layers.filter((_, i) => i !== layerIndex);
+  return { ...sprite, layers };
+}
+
+export function duplicateLayer(sprite, layerIndex) {
+  const src = sprite.layers[layerIndex];
+  if (!src) return sprite;
+  const copy = makeLayer(uniqueLayerId(sprite), `${src.name} copy`, src.cells.map(cloneCell));
+  copy.visible = src.visible;
+  copy.opacity = src.opacity;
+  const layers = sprite.layers.slice();
+  layers.splice(layerIndex + 1, 0, copy);
+  return { ...sprite, layers };
+}
+
+// Move a layer up (toward the top of the stack, higher index) or down.
+export function moveLayer(sprite, layerIndex, dir) {
+  const target = layerIndex + dir;
+  if (target < 0 || target >= sprite.layers.length) return sprite;
+  const layers = sprite.layers.slice();
+  [layers[layerIndex], layers[target]] = [layers[target], layers[layerIndex]];
+  return { ...sprite, layers };
+}
+
+export function patchLayer(sprite, layerIndex, patch) {
+  const layers = sprite.layers.map((layer, i) => (i === layerIndex ? { ...layer, ...patch } : layer));
+  return { ...sprite, layers };
+}
+
+function cloneCell(cell) {
+  if (cell == null) return null;
+  if ('link' in cell) return { link: cell.link };
+  return gridCell(cell.grid.slice(), cell.x ?? 0, cell.y ?? 0);
+}
+
+// ---------------------------------------------------------------------------
+// frame ops
+// ---------------------------------------------------------------------------
+
+// Structural frame edits (insert/duplicate/delete/move) operate on per-cell
+// SNAPSHOTS rather than raw links, then rebuild coherent links. Each snapshot is
+// a slot's RESOLVED image (chain followed on the PRE-edit layer) plus whether it
+// was a link. After reordering the snapshots, relinkSlots rebuilds cells so that
+// (a) every slot keeps the exact pixels it showed before the edit, and (b) the
+// only links that survive point at the immediate previous frame (link === i-1).
+// This makes "linked = same as previous frame" hold after any reshuffle, with no
+// forward or frame-skipping links left behind.
+
+// Snapshot every cell of a layer as { image, x, y, wasLink }. The offset travels
+// with the image so reordered/relinked frames keep their cel placement.
+function layerSlots(layer) {
+  return layer.cells.map((cell, i) => {
+    const resolved = resolveCell(layer, i);
+    return {
+      image: resolved?.grid ?? null,
+      x: resolved?.x ?? 0,
+      y: resolved?.y ?? 0,
+      wasLink: cell != null && 'link' in cell,
+    };
+  });
+}
+
+// Value-compare two packed grids (decides whether a slot may re-link to its new
+// previous neighbour or must materialize to preserve its appearance).
+function gridsEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+// Rebuild a cells row from (reordered) snapshots. A slot stays a link to i-1 only
+// when it WAS a link and the previous slot now shows an identical image AND the
+// same offset (a link shares both); empty slots stay null; everything else
+// materializes into its own { grid } copy, preserving its offset.
+function relinkSlots(slots) {
+  return slots.map((slot, i) => {
+    if (slot.image == null) return null;
+    if (
+      i > 0 &&
+      slot.wasLink &&
+      gridsEqual(slots[i - 1].image, slot.image) &&
+      slots[i - 1].x === slot.x &&
+      slots[i - 1].y === slot.y
+    ) {
+      return { link: i - 1 };
+    }
+    return gridCell(slot.image.slice(), slot.x, slot.y);
+  });
+}
+
+// Snapshot each layer, let `transform(slots, layer)` reshuffle them, then rebuild
+// coherent cells. Returns the new layers array.
+function mapLayerSlots(sprite, transform) {
+  return sprite.layers.map((layer) => ({
+    ...layer,
+    cells: relinkSlots(transform(layerSlots(layer), layer)),
+  }));
+}
+
+function clampTag(tag, count) {
+  let from = clampIndex(tag.from, count);
+  let to = clampIndex(tag.to, count);
+  if (from > to) [from, to] = [to, from];
+  return { ...tag, from, to };
+}
+
+function clampIndex(value, count) {
+  if (!Number.isInteger(value)) return 0;
+  return Math.min(Math.max(value, 0), Math.max(count - 1, 0));
+}
+
+// Insert a frame column at `pos`, building each layer's new SLOT via makeSlot
+// ({ image, wasLink }). `frame` is the new frame's timing record ({} = inherit
+// the global duration, { durationMs } = explicit override). relinkSlots keeps a
+// linked cell that now sits right after the inserted column pointed at its real
+// previous neighbour (or materializes it when the insert changed what precedes
+// it), so links never silently skip the new column.
+function insertFrameAt(sprite, pos, frame, makeSlot) {
+  const frames = sprite.frames.slice();
+  frames.splice(pos, 0, frame);
+  const layers = mapLayerSlots(sprite, (slots, layer) => {
+    slots.splice(pos, 0, makeSlot(layer));
+    return slots;
+  });
+  // Tag ranges shift with a column insert too.
+  const tags = sprite.tags.map((tag) => ({
+    ...tag,
+    from: tag.from >= pos ? tag.from + 1 : tag.from,
+    to: tag.to >= pos ? tag.to + 1 : tag.to,
+  }));
+  return { ...sprite, frames, layers, tags };
+}
+
+// Add a frame directly AFTER the active one, inheriting the global duration (no
+// override). The new frame starts LINKED to the previous frame: its snapshot
+// mirrors the previous cel's resolved image + offset and is flagged wasLink, so
+// relinkSlots links it to its immediate previous neighbour (link === i-1, chain
+// aware). When the previous frame's cell resolves to nothing (same condition
+// that disables "Link to previous frame"), the snapshot image is null and the
+// new cell stays empty.
+export function addFrame(sprite, frameIndex) {
+  return insertFrameAt(sprite, frameIndex + 1, {}, (layer) => {
+    const resolved = resolveCell(layer, frameIndex);
+    return {
+      image: resolved?.grid ?? null,
+      x: resolved?.x ?? 0,
+      y: resolved?.y ?? 0,
+      wasLink: resolved != null,
+    };
+  });
+}
+
+// Duplicate the active frame as an independent column right after it, preserving
+// the source frame's override state: copy an explicit duration, otherwise keep
+// inheriting the global (don't coalesce to the default). The new column is an
+// independent { grid } copy of the source's resolved image.
+export function duplicateFrame(sprite, frameIndex) {
+  const src = sprite.frames[frameIndex];
+  const frame = src && Number.isFinite(src.durationMs) ? { durationMs: src.durationMs } : {};
+  return insertFrameAt(sprite, frameIndex + 1, frame, (layer) => {
+    const resolved = resolveCell(layer, frameIndex);
+    return {
+      image: resolved ? resolved.grid.slice() : null,
+      x: resolved?.x ?? 0,
+      y: resolved?.y ?? 0,
+      wasLink: false,
+    };
+  });
+}
+
+// Remove a frame column. Snapshots are taken on the pre-delete layer, so any
+// cell that linked (transitively) to the removed column keeps its pixels — it
+// materializes when its source disappears, and otherwise re-links to its new
+// immediate previous frame. Tags clamp into the shorter range.
+export function deleteFrame(sprite, frameIndex) {
+  if (frameCount(sprite) <= 1) return sprite;
+  const layers = mapLayerSlots(sprite, (slots) => {
+    slots.splice(frameIndex, 1);
+    return slots;
+  });
+  const frames = sprite.frames.filter((_, i) => i !== frameIndex);
+  const tags = sprite.tags.map((tag) => clampTag(tag, frames.length));
+  return { ...sprite, frames, layers, tags };
+}
+
+// Swap the active frame with its neighbor (dir -1 / +1). Each frame's image
+// travels with it (snapshots swap together); relinkSlots then re-derives links
+// so neither frame ends up pointing forward or skipping — any link broken by the
+// swap materializes to preserve appearance.
+export function moveFrame(sprite, frameIndex, dir) {
+  const target = frameIndex + dir;
+  if (target < 0 || target >= frameCount(sprite)) return sprite;
+  const frames = sprite.frames.slice();
+  [frames[frameIndex], frames[target]] = [frames[target], frames[frameIndex]];
+  const layers = mapLayerSlots(sprite, (slots) => {
+    [slots[frameIndex], slots[target]] = [slots[target], slots[frameIndex]];
+    return slots;
+  });
+  return { ...sprite, frames, layers };
+}
+
+// Set or CLEAR a frame's duration override. A finite, positive `durationMs`
+// sets an explicit override; null/undefined (or any non-positive/NaN value,
+// e.g. an emptied input) clears the override so the frame inherits the global.
+export function setFrameDuration(sprite, frameIndex, durationMs) {
+  const override = Number.isFinite(durationMs) && durationMs > 0;
+  const frames = sprite.frames.map((frame, i) =>
+    i === frameIndex ? (override ? { durationMs } : {}) : frame
+  );
+  return { ...sprite, frames };
+}
+
+// Set the sprite's GLOBAL frame duration (the value inherited by every frame
+// without its own override). Ignores non-finite / non-positive input.
+export function setDefaultDuration(sprite, durationMs) {
+  if (!(Number.isFinite(durationMs) && durationMs > 0)) return sprite;
+  return { ...sprite, defaultDurationMs: durationMs };
+}
+
+// ---------------------------------------------------------------------------
+// tags
+// ---------------------------------------------------------------------------
+
+export function addTag(sprite) {
+  const tag = {
+    name: `tag ${sprite.tags.length + 1}`,
+    from: 0,
+    to: Math.max(frameCount(sprite) - 1, 0),
+    direction: 'forward',
+    repeat: 0,
+  };
+  return { ...sprite, tags: [...sprite.tags, tag] };
+}
+
+export function patchTag(sprite, tagIndex, patch) {
+  const tags = sprite.tags.map((tag, i) =>
+    i === tagIndex ? clampTag({ ...tag, ...patch }, frameCount(sprite)) : tag
+  );
+  return { ...sprite, tags };
+}
+
+export function deleteTag(sprite, tagIndex) {
+  const removed = sprite.tags[tagIndex];
+  const tags = sprite.tags.filter((_, i) => i !== tagIndex);
+  const defaultTag = removed && sprite.defaultTag === removed.name ? undefined : sprite.defaultTag;
+  return { ...sprite, tags, defaultTag };
+}
+
+export function setDefaultTag(sprite, name) {
+  return { ...sprite, defaultTag: name || undefined };
+}
+
+// ---------------------------------------------------------------------------
+// resize (whole sprite) + serialization
+// ---------------------------------------------------------------------------
+
+// Resize the canvas resolution (snapped pow2 16..512). This REFRAMES, never
+// crops: the canvas window changes and every cel's offset shifts by the centered
+// delta (floor((new-old)/2) per axis) so existing art stays centered. Cel images
+// are left fully intact — content that ends up outside the new (or old) canvas
+// window is retained, not destroyed.
+export function resizeSprite(sprite, width, height) {
+  const w = snapResolutionDim(width);
+  const h = snapResolutionDim(height);
+  if (w === sprite.resolution.width && h === sprite.resolution.height) return sprite;
+  const dx = Math.floor((w - sprite.resolution.width) / 2);
+  const dy = Math.floor((h - sprite.resolution.height) / 2);
+  const layers = sprite.layers.map((layer) => ({
+    ...layer,
+    cells: layer.cells.map((cell) => shiftCellOffset(cell, dx, dy)),
+  }));
+  return { ...sprite, resolution: { width: w, height: h }, layers };
+}
+
+function shiftCellOffset(cell, dx, dy) {
+  if (cell == null || 'link' in cell) return cell;
+  return gridCell(cell.grid, (cell.x ?? 0) + dx, (cell.y ?? 0) + dy);
+}
+
+// Serialize the working sprite to a `.pxart` string, choosing the SMALLEST form
+// that loses nothing. The choice is STRUCTURAL, not a hand-maintained checklist:
+// build the candidate compact form, RE-PARSE it back into a full model, and keep
+// it only when that round-trip reproduces the sprite exactly. Any feature the
+// compact form can't carry — extra layers/frames/tags, per-layer opacity or
+// visibility, cel offsets, or off-canvas content — makes the round-trip differ,
+// so the sprite falls through to the full form. Adding a new full-form feature
+// later needs no change here: if it survives the round-trip it was already
+// representable; if not, it correctly forces the full form.
+export function serializeModel(sprite) {
+  const compact = serializeCompact(fromCells(EDITOR_PALETTE, cellsAt(sprite, 0, 0)));
+  const roundTripped = parseFull(compact);
+  if (roundTripped && losslesslyCompact(sprite, roundTripped)) return compact;
+  return serializeFull(sprite);
+}
+
+// True when `roundTripped` (the full model re-parsed from the candidate compact
+// form) is EQUIVALENT to the original `sprite` — i.e. the compact form lost
+// nothing. The compact form always re-parses to exactly one fully-opaque visible
+// layer, one inheriting frame, and no tags, so any richer original differs here.
+// Comparison is by RESOLVED CONTENT, normalizing representationally-irrelevant
+// differences (palette ordering/unused keys, transparent padding, offset
+// encoding) while catching every real one (pixels, opacity, visibility, frames,
+// tags, off-canvas content).
+function losslesslyCompact(sprite, roundTripped) {
+  if (
+    sprite.resolution.width !== roundTripped.resolution.width ||
+    sprite.resolution.height !== roundTripped.resolution.height
+  ) {
+    return false;
+  }
+  if (frameCount(sprite) !== frameCount(roundTripped)) return false;
+  if (sprite.tags.length !== roundTripped.tags.length) return false;
+  if ((sprite.defaultTag ?? null) !== (roundTripped.defaultTag ?? null)) return false;
+  if (sprite.layers.length !== roundTripped.layers.length) return false;
+
+  const lookupA = paletteLookup(sprite.palette);
+  const lookupB = paletteLookup(roundTripped.palette);
+  const frames = frameCount(sprite);
+  return sprite.layers.every((a, li) =>
+    layersEquivalent(a, roundTripped.layers[li], frames, lookupA, lookupB)
+  );
+}
+
+// True when two layers are equivalent for compact-eligibility: same visibility,
+// opacity, blend/kind, and identical resolved cel content across every frame.
+function layersEquivalent(a, b, frames, lookupA, lookupB) {
+  if (a.visible !== b.visible || a.opacity !== b.opacity) return false;
+  if (a.blendMode !== b.blendMode || a.kind !== b.kind) return false;
+  for (let f = 0; f < frames; f++) {
+    if (!celContentEqual(celColorMap(a, f, lookupA), celColorMap(b, f, lookupB))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// Map a (layer, frame) cel to its non-transparent pixels keyed by CANVAS
+// coordinate ("x,y") -> resolved hex color. Built from the cel's grid plus its
+// (x, y) offset, INCLUDING off-canvas pixels (negative / out-of-bounds coords),
+// so off-canvas content the compact form would drop shows up as a difference.
+function celColorMap(layer, frameIndex, lookup) {
+  const map = new Map();
+  const resolved = resolveCell(layer, frameIndex);
+  if (!resolved) return map;
+  const { grid, x: ox, y: oy } = resolved;
+  for (let gy = 0; gy < grid.length; gy++) {
+    const row = grid[gy];
+    for (let gx = 0; gx < row.length; gx++) {
+      const color = colorForKeyV2(lookup, row[gx]);
+      if (color) map.set(`${gx + ox},${gy + oy}`, color);
+    }
+  }
+  return map;
+}
+
+function celContentEqual(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [key, color] of a) {
+    if (b.get(key) !== color) return false;
+  }
+  return true;
+}
+
+// Clamp a (layer, frame) selection into the sprite's current bounds.
+export function clampSelection(sprite, layerIndex, frameIndex) {
+  return {
+    layerIndex: clampIndex(layerIndex, sprite.layers.length),
+    frameIndex: clampIndex(frameIndex, frameCount(sprite)),
+  };
+}