castle-web-cli 0.4.71 → 0.4.73

package/kits/basic-2d/engine/pxart.js

@@ -0,0 +1,985 @@
+// ============================================================================
+// Castle pixel-art format — COMPACT form ("flat" sprite)
+// ============================================================================
+//
+// `.pxart` files come in two COEXISTING forms (capability tiers, not temporal
+// versions). The on-disk discriminator is a string `format` field:
+// `"compact"` or `"full"`. The COMPACT form is intentionally minimal: one
+// shared palette + one grid of single-character keys.
+//
+//   {
+//     "format": "compact",
+//     "palette": { "y": "#ffe11a", "o": "#e8b800", ".": null },
+//     "grid": ["..ooyyoo..", ".oyyyyyyo.", "oyyyyyyyyo"]
+//   }
+//
+// Rules:
+//   - `palette` maps a SINGLE-CHARACTER key -> "#rrggbb" (or "#rrggbbaa"), or
+//     null for transparent.
+//   - The char "." is reserved for transparency. It is transparent whether or
+//     not it appears in `palette` (a `"." : null` entry is allowed but optional).
+//   - `grid` is an array of strings, one per row. Each character is a palette
+//     key. Width = the longest row; ragged rows are padded with "." (transparent).
+//     Height = grid.length.
+//   - On serialize we always stamp `format: "compact"`. The parser detects the
+//     form by STRUCTURE (object `palette` + `grid`), TOLERATES a missing
+//     `format` discriminator, and tolerates ragged rows.
+//
+// ---------------------------------------------------------------------------
+// The FULL form (layers + frames + tags) lives in the second half of this file.
+// A compact file is equivalent to a full sprite with a single pixel layer whose
+// single frame's cel grid === `grid`. In memory the kit ALWAYS works on the full
+// model: `parseFull` upgrades a compact file into the full model on read.
+//
+// This kit is plain JavaScript: the format is described in comments and the
+// runtime behavior below is the source of truth. Do NOT read/write
+// layers/frames/animation in compact-form code.
+// ============================================================================
+
+export const COMPACT_FORM = 'compact';
+export const FULL_FORM = 'full';
+export const TRANSPARENT = '.';
+
+/** Parse a .pxart string into a compact PxArt record, or null if it isn't the
+ *  compact shape. Detects by STRUCTURE (object `palette` + `grid`); the on-disk
+ *  `format` discriminator is optional. Tolerant of ragged rows and a `"."`
+ *  palette entry. */
+export function parseCompact(content) {
+  try {
+    const data = JSON.parse(content);
+    if (
+      data &&
+      typeof data.palette === 'object' &&
+      data.palette !== null &&
+      !Array.isArray(data.palette) &&
+      Array.isArray(data.grid) &&
+      data.grid.every((r) => typeof r === 'string')
+    ) {
+      const palette = {};
+      for (const [k, v] of Object.entries(data.palette)) {
+        // Accept string hex or explicit null; ignore other junk values.
+        if (typeof v === 'string') palette[k] = v;
+        else if (v === null) palette[k] = null;
+      }
+      return { palette, grid: data.grid };
+    }
+  } catch {
+    /* not valid pxart json */
+  }
+  return null;
+}
+
+/** Serialize a compact PxArt record to a .pxart string. Always stamps
+ *  `format: "compact"`. */
+export function serializeCompact(art) {
+  const out = {
+    format: COMPACT_FORM,
+    palette: art.palette,
+    grid: art.grid,
+  };
+  return JSON.stringify(out, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// cells <-> grid
+// ---------------------------------------------------------------------------
+
+/** Rectangularize: ragged rows pad with transparent; empty art gets 1×1. */
+export function toCells(art) {
+  const rows = Math.max(art.grid.length, 1);
+  const cols = Math.max(...art.grid.map((r) => r.length), 1);
+  const cells = [];
+  for (let y = 0; y < rows; y++) {
+    const row = art.grid[y] ?? '';
+    cells.push(Array.from({ length: cols }, (_, x) => row[x] ?? TRANSPARENT));
+  }
+  return cells;
+}
+
+/** Build a PxArt from a palette + cell matrix, dropping unused palette keys. */
+export function fromCells(palette, cells) {
+  const used = new Set();
+  for (const row of cells) for (const ch of row) used.add(ch);
+  const gc = {};
+  for (const [k, v] of Object.entries(palette)) {
+    if (used.has(k)) gc[k] = v;
+  }
+  return { palette: gc, grid: cells.map((r) => r.join('')) };
+}
+
+// ---------------------------------------------------------------------------
+// dimensions / colors
+// ---------------------------------------------------------------------------
+
+export function dimsOf(art) {
+  const cells = toCells(art);
+  const height = cells.length;
+  const width = cells[0]?.length ?? 0;
+  const used = new Set();
+  for (const row of cells) {
+    for (const ch of row) {
+      if (ch !== TRANSPARENT && colorForKey(art.palette, ch)) used.add(ch);
+    }
+  }
+  return { width, height, colors: used.size };
+}
+
+/** Resolve a grid char to a CSS color, or null when transparent. "." is always
+ *  transparent; an absent key or a null palette value is transparent too. */
+export function colorForKey(palette, key) {
+  if (key === TRANSPARENT) return null;
+  const v = palette[key];
+  return typeof v === 'string' ? v : null;
+}
+
+/** '#abc' | 'abc' | '#aabbcc' | 'aabbccdd' -> normalized lowercase '#...' , or
+ *  null if not a valid 3/6/8-digit hex color. */
+export function normalizeHex(input) {
+  let s = input.trim().toLowerCase();
+  if (s.startsWith('#')) s = s.slice(1);
+  if (/^[0-9a-f]{3}$/.test(s)) s = [...s].map((c) => c + c).join('');
+  if (!/^([0-9a-f]{6}|[0-9a-f]{8})$/.test(s)) return null;
+  return '#' + s;
+}
+
+/** Single-char keys usable in a packed grid, excluding "." (reserved for
+ *  transparency). Letters + digits give 62 slots — far more than a small sprite
+ *  ever needs — and the few trailing symbols are JSON-safe fallbacks. Used by
+ *  representation normalizers that arrive with raw hex colors (svg-rect,
+ *  index-array) and must mint keys for our packed compact grid. */
+export const KEY_ALPHABET =
+  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*+=?@';
+
+/** Mint stable single-char palette keys for a list of (possibly repeated, or
+ *  un-normalized) hex colors. Returns the deduped `palette` (key -> normalized
+ *  hex) plus `keyOf`, a map from normalized hex -> assigned key. Invalid hex and
+ *  duplicates are skipped. If colors exceed the alphabet they collapse onto the
+ *  last key (acceptable for the tiny sprites this harness deals with). */
+export function allocatePaletteKeys(colors) {
+  const keyOf = new Map();
+  const palette = {};
+  let i = 0;
+  for (const raw of colors) {
+    const hex = normalizeHex(raw);
+    if (!hex || keyOf.has(hex)) continue;
+    const key = KEY_ALPHABET[Math.min(i, KEY_ALPHABET.length - 1)];
+    i++;
+    keyOf.set(hex, key);
+    palette[key] = hex;
+  }
+  return { palette, keyOf };
+}
+
+/** lospec.com/palette-list/aap-64 — the recommended default palette. */
+export const AAP64 = [
+  '#060608', '#141013', '#3b1725', '#73172d', '#b4202a', '#df3e23', '#fa6a0a', '#f9a31b',
+  '#ffd541', '#fffc40', '#d6f264', '#9cdb43', '#59c135', '#14a02e', '#1a7a3e', '#24523b',
+  '#122020', '#143464', '#285cc4', '#249fde', '#20d6c7', '#a6fcdb', '#ffffff', '#fef3c0',
+  '#fad6b8', '#f5a097', '#e86a73', '#bc4a9b', '#793a80', '#403353', '#242234', '#221c1a',
+  '#322b28', '#71413b', '#bb7547', '#dba463', '#f4d29c', '#dae0ea', '#b3b9d1', '#8b93af',
+  '#6d758d', '#4a5462', '#333941', '#422433', '#5b3138', '#8e5252', '#ba756a', '#e9b5a3',
+  '#e3e6ff', '#b9bffb', '#849be4', '#588dbe', '#477d85', '#23674e', '#328464', '#5daf8d',
+  '#92dcba', '#cdf7e2', '#e4d2aa', '#c7b08b', '#a08662', '#796755', '#5a4e44', '#423934',
+];
+
+// ---------------------------------------------------------------------------
+// rendering
+// ---------------------------------------------------------------------------
+
+/** Draw the sprite at 1 device-pixel per cell with smoothing disabled. The
+ *  canvas is sized to the sprite's exact pixel dimensions; scale it up for
+ *  display with CSS `image-rendering: pixelated` (see PxSprite in the UI).
+ *  Transparent cells are left clear so a backdrop/checker can show through. */
+export function renderToCanvas(art, canvas) {
+  const cells = toCells(art);
+  const rows = cells.length;
+  const cols = cells[0]?.length ?? 1;
+  canvas.width = cols;
+  canvas.height = rows;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+  ctx.imageSmoothingEnabled = false;
+  ctx.clearRect(0, 0, cols, rows);
+  for (let y = 0; y < rows; y++) {
+    for (let x = 0; x < cols; x++) {
+      const color = colorForKey(art.palette, cells[y][x]);
+      if (color) {
+        ctx.fillStyle = color;
+        ctx.fillRect(x, y, 1, 1);
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Castle pixel-art format — FULL form (layered + animated "Sprite")
+// ============================================================================
+//
+// The FULL form is a SUPERSET of the compact form. Everything above
+// (parseCompact, serializeCompact, renderToCanvas, dimsOf, toCells, fromCells,
+// normalizeHex, allocatePaletteKeys, AAP64, ...) keeps its exact compact-form
+// signatures/behavior. The full surface below introduces a separate in-memory
+// model (`Sprite`) plus its own parse/serialize/render functions. A compact file
+// upgrades into a Sprite in memory (one layer, one frame).
+//
+// Canonical schema is documented in docs/pxart-format.md. The model here mirrors
+// it: one resolution per sprite, an ORDERED palette of { key, hex }, a frames[]
+// timeline, named tags, and layers (bottom->top) whose cells row is
+// dense-with-null (`{ grid }` | `{ link }` | null), Aseprite-style.
+// ============================================================================
+
+/** Default per-frame duration when none is supplied (ms). */
+export const DEFAULT_DURATION_MS = 100;
+
+/** Valid sprite resolutions: power-of-two from 16 to 512, inclusive. */
+export const RESOLUTION_MIN = 16;
+export const RESOLUTION_MAX = 512;
+
+// ---------------------------------------------------------------------------
+// resolution helpers
+// ---------------------------------------------------------------------------
+
+/** The valid resolution dimensions (powers of two, 16..512). */
+export const RESOLUTION_STEPS = (() => {
+  const out = [];
+  for (let v = RESOLUTION_MIN; v <= RESOLUTION_MAX; v *= 2) out.push(v);
+  return out;
+})();
+
+/** Snap an arbitrary dimension to the nearest valid power-of-two in 16..512
+ *  (ties round up). Non-finite/<=0 input snaps to the minimum. Used for
+ *  EXPLICIT full-form resolutions; compact-shorthand upgrade preserves native
+ *  dims. */
+export function snapResolutionDim(n) {
+  if (!Number.isFinite(n) || n <= 0) return RESOLUTION_MIN;
+  const clamped = Math.min(RESOLUTION_MAX, Math.max(RESOLUTION_MIN, n));
+  let best = RESOLUTION_STEPS[0];
+  let bestDist = Infinity;
+  for (const step of RESOLUTION_STEPS) {
+    const dist = Math.abs(step - clamped);
+    // strict `<` keeps the smaller step on an exact tie distance; to round ties
+    // UP we accept an equal distance only when the candidate is larger.
+    if (dist < bestDist || (dist === bestDist && step > best)) {
+      best = step;
+      bestDist = dist;
+    }
+  }
+  return best;
+}
+
+// ---------------------------------------------------------------------------
+// format defaults + curated palette
+// ---------------------------------------------------------------------------
+
+/** Default sprite resolution for new/generated art (16×16). */
+export const DEFAULT_RESOLUTION = { width: 16, height: 16 };
+
+// ---------------------------------------------------------------------------
+// Two-tier Endesga-64 palette system
+//
+// EDG64 is the FULL painting palette (Lospec "Endesga 64", canonical order) the
+// editor offers to USERS. AGENT_PALETTE_16 is a fixed 16-color SUBSET of EDG64
+// — the constrained set the LLM generation path is told to use and that the
+// `draw` svg-rect quantizer snaps to. Every AGENT_PALETTE_16 color is a member
+// of EDG64.
+// ---------------------------------------------------------------------------
+
+/** lospec.com/palette-list/endesga-64 — the full 64-color painting palette.
+ *  Lospec order, except the lead bright red (#ff0040) is moved down among the
+ *  other reds (4th from last) so the swatch grid opens on the grayscale ramp.
+ *  The editor exposes ALL of these as swatches. */
+export const EDG64 = [
+  '#131313', '#1b1b1b', '#272727', '#3d3d3d', '#5d5d5d', '#858585', '#b4b4b4', '#ffffff',
+  '#c7cfdd', '#92a1b9', '#657392', '#424c6e', '#2a2f4e', '#1a1932', '#0e071b', '#1c121c',
+  '#391f21', '#5d2c28', '#8a4836', '#bf6f4a', '#e69c69', '#f6ca9f', '#f9e6cf', '#edab50',
+  '#e07438', '#c64524', '#8e251d', '#ff5000', '#ed7614', '#ffa214', '#ffc825', '#ffeb57',
+  '#d3fc7e', '#99e65f', '#5ac54f', '#33984b', '#1e6f50', '#134c4c', '#0c2e44', '#00396d',
+  '#0069aa', '#0098dc', '#00cdf9', '#0cf1ff', '#94fdff', '#fdd2ed', '#f389f5', '#db3ffd',
+  '#7a09fa', '#3003d9', '#0c0293', '#03193f', '#3b1443', '#622461', '#93388f', '#ca52c9',
+  '#c85086', '#f68187', '#f5555d', '#ea323c', '#ff0040', '#c42430', '#891e2b', '#571c27',
+].map((hex) => normalizeHex(hex) ?? hex);
+
+/** A fixed 16-color SUBSET of EDG64 — the constrained palette the agent
+ *  generation path is told to use, and the target the svg-rect quantizer snaps
+ *  to. Order is the agent-facing order (warm skins → reds → warm → greens →
+ *  teals → neutrals → light → cyans → blue). Every entry is a member of EDG64. */
+export const AGENT_PALETTE_16 = [
+  '#e69c69', '#bf6f4a', '#8a4836', '#391f21',
+  '#891e2b', '#ea323c', '#ffa214', '#ffeb57',
+  '#5ac54f', '#1e6f50', '#134c4c', '#657392',
+  '#c7cfdd', '#ffffff', '#0cf1ff', '#0098dc',
+].map((hex) => normalizeHex(hex) ?? hex);
+
+// ---------------------------------------------------------------------------
+// full-form parse
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Normalize a loosely-typed palette array into ordered { key, hex } entries.
+ *  Drops "." entries, invalid hex, non-single-char keys, and duplicate keys
+ *  (first wins). Order is preserved. */
+function parsePaletteArray(raw) {
+  const out = [];
+  if (!Array.isArray(raw)) return out;
+  const seen = new Set();
+  for (const entry of raw) {
+    if (!isPlainObject(entry)) continue;
+    const key = entry.key;
+    if (typeof key !== 'string' || key.length !== 1 || key === TRANSPARENT) continue;
+    if (seen.has(key)) continue;
+    const hex = typeof entry.hex === 'string' ? normalizeHex(entry.hex) : null;
+    if (!hex) continue;
+    seen.add(key);
+    out.push({ key, hex });
+  }
+  return out;
+}
+
+function parseDirection(raw) {
+  return raw === 'reverse' || raw === 'pingpong' ? raw : 'forward';
+}
+
+/** Coerce a loosely-typed offset component to a finite integer, defaulting 0. */
+function coerceOffset(raw) {
+  return typeof raw === 'number' && Number.isFinite(raw) ? Math.trunc(raw) : 0;
+}
+
+/** Crop a grid so neither axis exceeds RESOLUTION_MAX (512). A cel image may be
+ *  larger than the canvas (off-canvas content), but it is hard-capped at the
+ *  same 512/axis ceiling as the canvas resolution. Returns the input untouched
+ *  when already within the cap. */
+function capGridDims(grid) {
+  const tooTall = grid.length > RESOLUTION_MAX;
+  const tooWide = grid.some((r) => r.length > RESOLUTION_MAX);
+  if (!tooTall && !tooWide) return grid;
+  const rows = tooTall ? grid.slice(0, RESOLUTION_MAX) : grid;
+  return rows.map((r) => (r.length > RESOLUTION_MAX ? r.slice(0, RESOLUTION_MAX) : r));
+}
+
+/** Build a { grid } cell, attaching x/y only when nonzero (additive: a zero
+ *  offset serializes as a bare { grid }, identical to pre-offset files). */
+function makeGridCell(grid, rawX, rawY) {
+  const capped = capGridDims(grid);
+  const x = coerceOffset(rawX);
+  const y = coerceOffset(rawY);
+  return x || y ? { grid: capped, x, y } : { grid: capped };
+}
+
+/** Coerce a loosely-typed cell into a SpriteCell. Reads an optional integer
+ *  (x, y) offset on grid cells (default 0,0) and caps grid dims at 512/axis. */
+function parseCell(raw) {
+  if (raw == null) return null;
+  if (isPlainObject(raw)) {
+    if (Array.isArray(raw.grid) && raw.grid.every((r) => typeof r === 'string')) {
+      return makeGridCell(raw.grid, raw.x, raw.y);
+    }
+    if (typeof raw.link === 'number' && Number.isInteger(raw.link)) {
+      return { link: raw.link };
+    }
+  }
+  // Tolerate a bare frame-index number as a link, or a bare row array as a grid.
+  if (typeof raw === 'number' && Number.isInteger(raw)) return { link: raw };
+  if (Array.isArray(raw) && raw.every((r) => typeof r === 'string')) {
+    return makeGridCell(raw, undefined, undefined);
+  }
+  return null;
+}
+
+/** Infer canvas dimensions from a set of layers, used ONLY as a fallback when a
+ *  full file omits an explicit `resolution`. The canvas is independent of cel
+ *  image size, so an oversized cel grid (off-canvas content) must NOT inflate
+ *  the canvas past the 512 ceiling — clamp each axis to RESOLUTION_MAX. */
+function inferDimsFromLayers(layers) {
+  let width = 0;
+  let height = 0;
+  for (const layer of layers) {
+    for (const cell of layer.cells) {
+      if (cell && 'grid' in cell) {
+        height = Math.max(height, cell.grid.length);
+        for (const row of cell.grid) width = Math.max(width, row.length);
+      }
+    }
+  }
+  return {
+    width: Math.min(Math.max(width, 1), RESOLUTION_MAX),
+    height: Math.min(Math.max(height, 1), RESOLUTION_MAX),
+  };
+}
+
+/** Decide whether a parsed JSON object is the COMPACT form. Detection is by
+ *  STRUCTURE — full = layered/animated shape (layers / array palette / frames /
+ *  resolution); compact = flat `grid` over an object palette. The optional
+ *  `format` discriminator only breaks a tie when structure is ambiguous, so a
+ *  missing or mislabeled field never causes a silent mis-detection. */
+function detectCompactForm(data) {
+  const looksFull =
+    Array.isArray(data.layers) ||
+    Array.isArray(data.palette) ||
+    Array.isArray(data.frames) ||
+    isPlainObject(data.resolution);
+  const looksCompact = isPlainObject(data.palette) && Array.isArray(data.grid);
+  if (looksCompact && !looksFull) return true;
+  if (looksFull && !looksCompact) return false;
+  const declared = typeof data.format === 'string' ? data.format : null;
+  if (declared === COMPACT_FORM) return true;
+  if (declared === FULL_FORM) return false;
+  return looksCompact; // last resort: a bare grid upgrades
+}
+
+/**
+ * Parse a .pxart string into the full Sprite model, or null if it isn't valid
+ * pixel art. Handles BOTH on-disk forms, detecting by STRUCTURE:
+ *   - the FULL form (resolution / array palette / frames / layers), parsed
+ *     natively, and
+ *   - the COMPACT shorthand ({ palette: {...}, grid: [...] }), upgraded in
+ *     memory.
+ *
+ * The optional `format` discriminator ("compact" | "full") is used as a hint to
+ * disambiguate genuinely ambiguous shapes, but clear structure always wins so a
+ * mislabeled or undiscriminated file still parses without silent mis-detection.
+ *
+ * Tolerant: missing `format`, missing/short cells arrays, ragged rows, null
+ * cells, bare link numbers, and out-of-range explicit resolutions (snapped).
+ */
+export function parseFull(content) {
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(data)) return null;
+
+  if (detectCompactForm(data)) {
+    // Compact shorthand path: reuse the compact parser then upgrade.
+    const compact = parseCompact(content);
+    return compact ? upgradeCompactToFull(compact) : null;
+  }
+
+  const palette = parsePaletteArray(data.palette);
+
+  // Layers (tolerant). A full file with no layers but a top-level grid still
+  // works via the compact path above; here we require a layers array to proceed.
+  const rawLayers = Array.isArray(data.layers) ? data.layers : [];
+  const layers = rawLayers.filter(isPlainObject).map((l, i) => {
+    const rawCells = Array.isArray(l.cells) ? l.cells : [];
+    return {
+      id: typeof l.id === 'string' && l.id ? l.id : `layer-${i}`,
+      name: typeof l.name === 'string' && l.name ? l.name : `Layer ${i + 1}`,
+      visible: l.visible !== false,
+      opacity:
+        typeof l.opacity === 'number' && Number.isFinite(l.opacity)
+          ? Math.min(1, Math.max(0, l.opacity))
+          : 1,
+      blendMode: 'normal',
+      kind: 'pixel',
+      cells: rawCells.map(parseCell),
+    };
+  });
+
+  // Frame count: max of explicit frames[] and the longest cells row.
+  const rawFrames = Array.isArray(data.frames) ? data.frames : [];
+  let frameCount = rawFrames.length;
+  for (const layer of layers) frameCount = Math.max(frameCount, layer.cells.length);
+  frameCount = Math.max(frameCount, 1);
+
+  const defaultDurationMs =
+    typeof data.defaultDurationMs === 'number' && Number.isFinite(data.defaultDurationMs)
+      ? data.defaultDurationMs
+      : DEFAULT_DURATION_MS;
+
+  // A frame's `durationMs` is an OPTIONAL override: keep it only when the raw
+  // frame supplies a finite value, otherwise leave it undefined so the frame
+  // inherits the global `defaultDurationMs`. Padded frames (beyond rawFrames)
+  // inherit too.
+  const frames = [];
+  for (let f = 0; f < frameCount; f++) {
+    const raw = rawFrames[f];
+    if (
+      isPlainObject(raw) &&
+      typeof raw.durationMs === 'number' &&
+      Number.isFinite(raw.durationMs)
+    ) {
+      frames.push({ durationMs: raw.durationMs });
+    } else {
+      frames.push({});
+    }
+  }
+
+  // Pad/truncate every layer's cells to exactly frameCount (dense-with-null).
+  for (const layer of layers) {
+    if (layer.cells.length < frameCount) {
+      while (layer.cells.length < frameCount) layer.cells.push(null);
+    } else if (layer.cells.length > frameCount) {
+      layer.cells.length = frameCount;
+    }
+  }
+
+  // Resolution: snap an explicit value; otherwise infer from the largest grid.
+  let resolution;
+  if (isPlainObject(data.resolution)) {
+    resolution = {
+      width: snapResolutionDim(Number(data.resolution.width)),
+      height: snapResolutionDim(Number(data.resolution.height)),
+    };
+  } else {
+    resolution = inferDimsFromLayers(layers);
+  }
+
+  const tags = (Array.isArray(data.tags) ? data.tags : [])
+    .filter(isPlainObject)
+    .map((t) => ({
+      name: typeof t.name === 'string' ? t.name : '',
+      from: typeof t.from === 'number' && Number.isInteger(t.from) ? t.from : 0,
+      to: typeof t.to === 'number' && Number.isInteger(t.to) ? t.to : 0,
+      direction: parseDirection(t.direction),
+      repeat: typeof t.repeat === 'number' && Number.isInteger(t.repeat) ? t.repeat : 0,
+    }));
+
+  const defaultTag = typeof data.defaultTag === 'string' ? data.defaultTag : undefined;
+
+  return {
+    resolution,
+    palette,
+    frames,
+    defaultDurationMs,
+    tags,
+    defaultTag,
+    layers,
+  };
+}
+
+/** Upgrade a compact PxArt record (flat palette+grid) into the full Sprite
+ *  model: one pixel layer, one frame, resolution = the grid's NATIVE dims (not
+ *  snapped). */
+export function upgradeCompactToFull(art) {
+  const cells = toCells(art);
+  const height = cells.length;
+  const width = cells[0]?.length ?? 1;
+
+  // Ordered palette from the compact record, in insertion order, dropping
+  // transparent/null/invalid entries and "." (reserved).
+  const palette = [];
+  const seen = new Set();
+  for (const [key, value] of Object.entries(art.palette)) {
+    if (key.length !== 1 || key === TRANSPARENT || seen.has(key)) continue;
+    if (typeof value !== 'string') continue;
+    const hex = normalizeHex(value);
+    if (!hex) continue;
+    seen.add(key);
+    palette.push({ key, hex });
+  }
+
+  return {
+    resolution: { width, height },
+    palette,
+    // The single upgraded frame INHERITS the global (no override).
+    frames: [{}],
+    defaultDurationMs: DEFAULT_DURATION_MS,
+    tags: [],
+    defaultTag: undefined,
+    layers: [
+      {
+        id: 'layer-0',
+        name: 'Layer 1',
+        visible: true,
+        opacity: 1,
+        blendMode: 'normal',
+        kind: 'pixel',
+        cells: [{ grid: [...art.grid] }],
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// full-form serialize
+// ---------------------------------------------------------------------------
+
+/** Collect the set of palette keys actually used by any { grid } cell. */
+function usedKeysOf(sprite) {
+  const used = new Set();
+  for (const layer of sprite.layers) {
+    for (const cell of layer.cells) {
+      if (cell && 'grid' in cell) {
+        for (const row of cell.grid) for (const ch of row) used.add(ch);
+      }
+    }
+  }
+  return used;
+}
+
+/** Serialize a Sprite to a canonical .pxart string. Always stamps
+ *  `format: "full"`, drops unused palette entries, and emits packed-string
+ *  grids. Palette order is preserved for the entries that survive. */
+export function serializeFull(sprite) {
+  const used = usedKeysOf(sprite);
+  const palette = sprite.palette
+    .filter((e) => used.has(e.key))
+    .map((e) => ({ key: e.key, hex: e.hex }));
+
+  const out = {
+    format: FULL_FORM,
+    resolution: { width: sprite.resolution.width, height: sprite.resolution.height },
+    palette,
+    // Write `durationMs` only for OVERRIDDEN frames; inherited frames (undefined)
+    // serialize as a bare `{}` and re-parse as inheriting the global.
+    frames: sprite.frames.map((f) =>
+      typeof f.durationMs === 'number' && Number.isFinite(f.durationMs)
+        ? { durationMs: f.durationMs }
+        : {},
+    ),
+    defaultDurationMs: sprite.defaultDurationMs,
+    tags: sprite.tags.map((t) => ({
+      name: t.name,
+      from: t.from,
+      to: t.to,
+      direction: t.direction,
+      repeat: t.repeat,
+    })),
+    ...(sprite.defaultTag !== undefined ? { defaultTag: sprite.defaultTag } : {}),
+    layers: sprite.layers.map((l) => ({
+      id: l.id,
+      name: l.name,
+      visible: l.visible,
+      opacity: l.opacity,
+      blendMode: l.blendMode,
+      kind: l.kind,
+      cells: l.cells.map((c) => {
+        if (c == null) return null;
+        if ('grid' in c) {
+          // Emit x/y only when nonzero so a zero-offset cel round-trips to the
+          // exact pre-offset shape (forward/backward compatible).
+          const cell = { grid: c.grid };
+          if (c.x) cell.x = c.x;
+          if (c.y) cell.y = c.y;
+          return cell;
+        }
+        return { link: c.link };
+      }),
+    })),
+  };
+  return JSON.stringify(out, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// linked-cell resolution & helpers
+// ---------------------------------------------------------------------------
+
+/** Number of frames in the sprite. */
+export function frameCount(sprite) {
+  return sprite.frames.length;
+}
+
+/** Effective pixel dimensions of the sprite (its resolution). */
+export function spriteDims(sprite) {
+  return { width: sprite.resolution.width, height: sprite.resolution.height };
+}
+
+/** Build a key -> hex lookup from the ordered palette (first key wins). */
+export function paletteLookup(palette) {
+  const map = new Map();
+  for (const { key, hex } of palette) if (!map.has(key)) map.set(key, hex);
+  return map;
+}
+
+/** Resolve a grid char to a CSS color using an ordered palette, or null when
+ *  transparent. "." and unknown keys are transparent. */
+export function colorForKeyV2(lookup, key) {
+  if (key === TRANSPARENT) return null;
+  return lookup.get(key) ?? null;
+}
+
+/**
+ * Resolve the effective cel (image grid + offset) for a (layer, frameIndex)
+ * cell, following same-layer `link` references to the underlying `{ grid }`.
+ * A link shares the SOURCE cel's image AND offset (a fully shared cel). Returns
+ * null if the cell is empty / unresolvable. Guards against cycles and invalid
+ * indices (returns null rather than looping).
+ */
+export function resolveCell(layer, frameIndex) {
+  const visited = new Set();
+  let idx = frameIndex;
+  // Bound the walk by cells.length as a hard backstop in addition to `visited`.
+  for (let steps = 0; steps <= layer.cells.length; steps++) {
+    if (idx < 0 || idx >= layer.cells.length) return null;
+    if (visited.has(idx)) return null;
+    visited.add(idx);
+    const cell = layer.cells[idx];
+    if (cell == null) return null;
+    if ('grid' in cell) return { grid: cell.grid, x: cell.x ?? 0, y: cell.y ?? 0 };
+    idx = cell.link;
+  }
+  return null;
+}
+
+/**
+ * Resolve just the effective image grid for a (layer, frameIndex) cell (offset
+ * dropped). Thin wrapper over `resolveCell` kept for call sites that only need
+ * the pixels (e.g. linkability checks, timeline thumbnails).
+ */
+export function resolveCellGrid(layer, frameIndex) {
+  return resolveCell(layer, frameIndex)?.grid ?? null;
+}
+
+/**
+ * Visit each pixel of a resolved cel (image grid + x/y offset) that lands inside
+ * the [0,width) x [0,height) canvas window. `visit(cx, cy, key)` receives the
+ * canvas coordinates and the grid char at that cel pixel. The single home for
+ * the cel-offset clip math, shared by the frame renderer and the editor's
+ * canvas-window readback so the two never drift.
+ */
+export function forEachCelPixel(resolved, width, height, visit) {
+  const { grid, x: ox, y: oy } = resolved;
+  for (let gy = 0; gy < grid.length; gy++) {
+    const cy = gy + oy;
+    if (cy < 0 || cy >= height) continue;
+    const row = grid[gy];
+    for (let gx = 0; gx < row.length; gx++) {
+      const cx = gx + ox;
+      if (cx < 0 || cx >= width) continue;
+      visit(cx, cy, row[gx]);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// full-form rendering — composite a single frame
+// ---------------------------------------------------------------------------
+
+/**
+ * Render ONE frame of a Sprite to a canvas, compositing layers bottom->top.
+ * Sizes the canvas to the sprite resolution, respects per-layer `visible` and
+ * `opacity`, treats blendMode "normal", resolves linked cells, and leaves
+ * `null` cells / transparent keys clear. Uses the same 1px-per-cell,
+ * imageSmoothingEnabled=false approach as the compact renderer; scale up with CSS
+ * `image-rendering: pixelated` for display.
+ */
+export function renderSpriteFrame(sprite, frameIndex, canvas) {
+  const { width, height } = sprite.resolution;
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+  ctx.imageSmoothingEnabled = false;
+  ctx.clearRect(0, 0, width, height);
+
+  const lookup = paletteLookup(sprite.palette);
+  const prevAlpha = ctx.globalAlpha;
+  for (const layer of sprite.layers) {
+    if (!layer.visible || layer.opacity <= 0) continue;
+    const resolved = resolveCell(layer, frameIndex);
+    if (!resolved) continue;
+    ctx.globalAlpha = Math.min(1, Math.max(0, layer.opacity));
+    // Blit the cel image at its (x, y) offset, CLIPPING to the canvas window.
+    // The cel image may be larger than / offset outside the canvas; only the
+    // portion that lands inside [0,width) x [0,height) is drawn.
+    forEachCelPixel(resolved, width, height, (cx, cy, key) => {
+      const color = colorForKeyV2(lookup, key);
+      if (color) {
+        ctx.fillStyle = color;
+        ctx.fillRect(cx, cy, 1, 1);
+      }
+    });
+  }
+  ctx.globalAlpha = prevAlpha;
+}
+
+// ===========================================================================
+// svg-rect decode (generation path)
+// ===========================================================================
+//
+// The CLI generation worker prompts an LLM to emit pixel art as a tiny <svg>
+// with one <rect> per pixel. We snap those rects onto a cell grid by (x,y) and
+// cell size, mint a palette from the distinct fills, and emit PxArt. Direct
+// rect->cell mapping; if the rects don't land on a clean grid we still snap
+// (round) onto the inferred grid, which degrades gracefully without pulling in a
+// rasterizer. Ported verbatim from castle-px-eval/src/representations.ts.
+// ===========================================================================
+
+function parseRects(svg) {
+  const rects = [];
+  const rectRe = /<rect\b([^>]*?)\/?>/gi;
+  const attrRe = /([\w:-]+)\s*=\s*"([^"]*)"|([\w:-]+)\s*=\s*'([^']*)'/g;
+  let m;
+  while ((m = rectRe.exec(svg))) {
+    const attrs = {};
+    let a;
+    attrRe.lastIndex = 0;
+    while ((a = attrRe.exec(m[1]))) {
+      const key = (a[1] ?? a[3]).toLowerCase();
+      attrs[key] = a[2] ?? a[4];
+    }
+    const x = Number(attrs.x ?? '0');
+    const y = Number(attrs.y ?? '0');
+    const w = Number(attrs.width ?? '1');
+    const h = Number(attrs.height ?? '1');
+    let fill = null;
+    const rawFill = attrs.fill ?? styleFill(attrs.style);
+    if (rawFill && rawFill !== 'none' && rawFill !== 'transparent') fill = normalizeHex(rawFill);
+    if (![x, y, w, h].every(Number.isFinite)) continue;
+    rects.push({ x, y, w, h, fill });
+  }
+
+  // Canvas size: prefer viewBox, then width/height attrs on <svg>.
+  let canvas = null;
+  const vb = svg.match(/viewBox\s*=\s*["']\s*([\d.+-]+)\s+([\d.+-]+)\s+([\d.+-]+)\s+([\d.+-]+)\s*["']/i);
+  if (vb) {
+    const w = Number(vb[3]);
+    const h = Number(vb[4]);
+    if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) canvas = { w, h };
+  }
+  if (!canvas) {
+    const svgTag = svg.match(/<svg\b[^>]*>/i)?.[0] ?? '';
+    const w = Number(svgTag.match(/\bwidth\s*=\s*["']?([\d.]+)/i)?.[1]);
+    const h = Number(svgTag.match(/\bheight\s*=\s*["']?([\d.]+)/i)?.[1]);
+    if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) canvas = { w, h };
+  }
+  return { rects, canvas };
+}
+
+function styleFill(style) {
+  if (!style) return undefined;
+  return style.match(/fill\s*:\s*([^;]+)/i)?.[1]?.trim();
+}
+
+function normalizeSvgRect(raw, ctx) {
+  const svgStart = raw.indexOf('<svg');
+  const src = svgStart >= 0 ? raw.slice(svgStart) : raw;
+  const { rects, canvas } = parseRects(src);
+  const filled = rects.filter((r) => r.fill && r.w > 0 && r.h > 0);
+  if (!filled.length) return null;
+
+  // Infer cell size: the smallest rect side is one cell (rects are per-pixel, so
+  // this is almost always 1, but models sometimes scale up, e.g. 10px cells).
+  let cell = Infinity;
+  for (const r of filled) cell = Math.min(cell, r.w, r.h);
+  if (!Number.isFinite(cell) || cell <= 0) cell = 1;
+
+  // Grid extent: from canvas if given, else from the rects' bounding box.
+  let cols;
+  let rows;
+  if (canvas) {
+    cols = Math.max(1, Math.round(canvas.w / cell));
+    rows = Math.max(1, Math.round(canvas.h / cell));
+  } else {
+    let maxX = 0;
+    let maxY = 0;
+    for (const r of filled) {
+      maxX = Math.max(maxX, r.x + r.w);
+      maxY = Math.max(maxY, r.y + r.h);
+    }
+    cols = Math.max(1, Math.round(maxX / cell));
+    rows = Math.max(1, Math.round(maxY / cell));
+  }
+  // Guard against absurd canvases (typos like width="1000"); fall back to the
+  // target size when available, else clamp.
+  const MAX = 256;
+  if (cols > MAX || rows > MAX) {
+    if (ctx.targetSize) {
+      cols = ctx.targetSize.width;
+      rows = ctx.targetSize.height;
+    } else {
+      cols = Math.min(cols, MAX);
+      rows = Math.min(rows, MAX);
+    }
+  }
+
+  const { palette, keyOf } = allocatePaletteKeys(filled.map((r) => r.fill));
+  const cells = Array.from({ length: rows }, () =>
+    Array.from({ length: cols }, () => TRANSPARENT),
+  );
+  for (const r of filled) {
+    const hex = normalizeHex(r.fill);
+    const key = hex ? keyOf.get(hex) : undefined;
+    if (!key) continue;
+    const c0 = Math.round(r.x / cell);
+    const r0 = Math.round(r.y / cell);
+    const cspan = Math.max(1, Math.round(r.w / cell));
+    const rspan = Math.max(1, Math.round(r.h / cell));
+    for (let dy = 0; dy < rspan; dy++) {
+      for (let dx = 0; dx < cspan; dx++) {
+        const cx = c0 + dx;
+        const cy = r0 + dy;
+        if (cy >= 0 && cy < rows && cx >= 0 && cx < cols) cells[cy][cx] = key;
+      }
+    }
+  }
+  return fromCells(palette, cells);
+}
+
+// ---------------------------------------------------------------------------
+// svg-rect -> palette-quantized PxArt (higher-level generation helper)
+// ---------------------------------------------------------------------------
+
+/** Quantize a single hex color to the nearest entry in `palette` by RGB
+ *  Euclidean distance. Alpha is ignored for distance. Returns the chosen
+ *  "#rrggbb" (lowercase), or null when the input is invalid or fully
+ *  transparent (alpha === 00). */
+function quantizeToPalette(hex, palette) {
+  const norm = normalizeHex(hex);
+  if (!norm) return null;
+  const body = norm.slice(1);
+  // Preserve full transparency: an 8-digit color with alpha 00 stays transparent.
+  if (body.length === 8 && body.slice(6, 8) === '00') return null;
+  const r = parseInt(body.slice(0, 2), 16);
+  const g = parseInt(body.slice(2, 4), 16);
+  const b = parseInt(body.slice(4, 6), 16);
+  let best = null;
+  let bestDist = Infinity;
+  for (const entry of palette) {
+    const pn = normalizeHex(entry);
+    if (!pn) continue;
+    const pr = parseInt(pn.slice(1, 3), 16);
+    const pg = parseInt(pn.slice(3, 5), 16);
+    const pb = parseInt(pn.slice(5, 7), 16);
+    const dist = (r - pr) ** 2 + (g - pg) ** 2 + (b - pb) ** 2;
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = '#' + pn.slice(1, 7);
+    }
+  }
+  return best;
+}
+
+/**
+ * Decode a terse svg-rect emission into a compact PxArt, quantized onto a fixed
+ * palette. Runs the svg-rect decode at the target resolution (default
+ * DEFAULT_RESOLUTION, 16×16), then maps every resulting color to the nearest
+ * color in `palette` (default AGENT_PALETTE_16, the 16-color agent subset) via
+ * RGB Euclidean distance. The returned palette contains only the quantized
+ * colors actually used; transparent cells stay transparent ("."). Returns null
+ * if the svg has no usable rects.
+ */
+export function svgRectToPxArt(svg, opts) {
+  const resolution = opts?.resolution ?? DEFAULT_RESOLUTION;
+  const palette = opts?.palette ?? AGENT_PALETTE_16;
+
+  const decoded = normalizeSvgRect(svg, { targetSize: resolution });
+  if (!decoded) return null;
+
+  // Map each original palette key to its quantized "#rrggbb" (or drop it).
+  const quantHexByKey = new Map();
+  for (const [key, hex] of Object.entries(decoded.palette)) {
+    if (typeof hex !== 'string') continue;
+    const q = quantizeToPalette(hex, palette);
+    if (q) quantHexByKey.set(key, q);
+  }
+
+  // Allocate fresh single-char keys for the distinct quantized colors used.
+  const { palette: outPalette, keyOf } = allocatePaletteKeys(quantHexByKey.values());
+
+  const cells = toCells(decoded).map((row) =>
+    row.map((ch) => {
+      if (ch === TRANSPARENT) return TRANSPARENT;
+      const q = quantHexByKey.get(ch);
+      if (!q) return TRANSPARENT;
+      return keyOf.get(q) ?? TRANSPARENT;
+    }),
+  );
+
+  return fromCells(outPalette, cells);
+}