castle-web-cli 0.4.129 → 0.4.131

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

@@ -1,732 +0,0 @@
-import {
-  clampCornerRadius,
-  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,
-    cornerRadius: 0,
-    layers: [makeLayer('layer-0', 'Layer 1', [null])],
-  };
-}
-
-// Set the file-level corner-rounding radius (0 = sharp/pixel). A no-op if
-// it's already that value (keeps identical sprites from producing spurious
-// history entries).
-export function setCornerRadius(sprite, radius) {
-  const clamped = clampCornerRadius(radius);
-  return sprite.cornerRadius === clamped ? sprite : { ...sprite, cornerRadius: clamped };
-}
-
-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)),
-    cornerRadius: sprite.cornerRadius,
-  });
-  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.cornerRadius !== roundTripped.cornerRadius) 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)),
-  };
-}