castle-web-cli 0.4.123 → 0.4.124

package/kits/physics-2d/engine/palettes.js

@@ -0,0 +1,636 @@
+// Deck palette resolution + the agent generation subset.
+//
+// A deck may declare a palette in `theme.style`. The editor uses that palette
+// as a picker (the sprite's own palette stays truth). Generation (`draw` /
+// `import-svg`) quantizes to a derived subset so the model stays coherent.
+//
+// Derivation (validated by castle-px-eval): the default Endesga-64 deck keeps
+// the hand-curated AGENT_PALETTE_16; a custom palette larger than 16 is cut
+// by greedy farthest-point in Oklab; 16 or fewer colors are used as-is.
+
+import { AGENT_PALETTE_16, EDG64, KEY_ALPHABET, normalizeHex } from './pxart.js';
+
+export const THEME_STYLE_PATH = 'theme.style';
+export const OFFICIAL_ENDESGA_64 = 'endesga-64';
+export const PALETTE_KEY_CAP = 64;
+
+// Endesga-64 stays first (the default). AAP-64-Castle is the classic Castle
+// editor default (castle-client Palettes.js `default`, not in the GraphQL
+// list). The rest are Castle's published palettes (ghost-server palettes.ts),
+// minus the three already registered from the pixel-art eval (Mushroom /
+// SOBEACHY8 / Grape Soda — those keep the eval hex lists).
+export const OFFICIAL_PALETTES = {
+  [OFFICIAL_ENDESGA_64]: {
+    id: OFFICIAL_ENDESGA_64,
+    name: 'Endesga 64',
+    colors: EDG64,
+  },
+  'aap-64-castle': {
+    id: 'aap-64-castle',
+    name: 'AAP-64-Castle',
+    colors: [
+      '#3b1725',
+      '#73172d',
+      '#b4202a',
+      '#df3e23',
+      '#fa6a0a',
+      '#f9a31b',
+      '#ffd541',
+      '#fffc40',
+      '#fffd98',
+      '#d6f264',
+      '#9cdb43',
+      '#59c135',
+      '#14a02e',
+      '#1a7a3e',
+      '#24523b',
+      '#122020',
+      '#143464',
+      '#285cc4',
+      '#249fde',
+      '#20d6c7',
+      '#a6fcdb',
+      '#fff9db',
+      '#fef3c0',
+      '#fad6b8',
+      '#f5a097',
+      '#f2838b',
+      '#e86a73',
+      '#bc4a9b',
+      '#793a80',
+      '#403353',
+      '#242234',
+      '#322b28',
+      '#71413b',
+      '#bb7547',
+      '#dba463',
+      '#f4d29c',
+      '#edeff2',
+      '#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',
+    ],
+  },
+  mushroom: {
+    id: 'mushroom',
+    name: 'Mushroom',
+    colors: [
+      '#2e222f',
+      '#45293f',
+      '#7a3045',
+      '#993d41',
+      '#cd683d',
+      '#fbb954',
+      '#f2ec8b',
+      '#b0a987',
+      '#997f73',
+      '#665964',
+      '#443846',
+      '#576069',
+      '#788a87',
+      '#a9b2a2',
+    ],
+  },
+  sobeachy8: {
+    id: 'sobeachy8',
+    name: 'SOBEACHY8',
+    colors: [
+      '#e55388',
+      '#e57d88',
+      '#e59f88',
+      '#e5d988',
+      '#e3d5cc',
+      '#bad5cc',
+      '#6dd5cc',
+      '#5ac5cc',
+    ],
+  },
+  'grape-soda': {
+    id: 'grape-soda',
+    name: 'Grape Soda',
+    colors: [
+      '#aa81ff',
+      '#b837ea',
+      '#aa11bb',
+      '#90006c',
+      '#56002a',
+      '#25000d',
+      '#000000',
+      '#15021e',
+      '#47054f',
+      '#c9298c',
+      '#ee699e',
+      '#ffbac0',
+      '#fff6f6',
+    ],
+  },
+  'chocomilk-8': {
+    id: 'chocomilk-8',
+    name: 'Chocomilk-8',
+    colors: [
+      '#d6f5e4',
+      '#f7ffc5',
+      '#b4c788',
+      '#8a8969',
+      '#8b6a44',
+      '#62554c',
+      '#463c3c',
+      '#312629',
+    ],
+  },
+  'deep-maze': {
+    id: 'deep-maze',
+    name: 'Deep Maze',
+    colors: ['#f2ff66', '#9af089', '#38d88e', '#00be91', '#009a98', '#085562', '#001d2a'],
+  },
+  'fantasy-24': {
+    id: 'fantasy-24',
+    name: 'Fantasy 24',
+    colors: [
+      '#3c9f9c',
+      '#276468',
+      '#183f39',
+      '#1f240a',
+      '#39571c',
+      '#a58c27',
+      '#efac28',
+      '#efd8a1',
+      '#300f0a',
+      '#550f0a',
+      '#9b1a0a',
+      '#ef3a0c',
+      '#ef692f',
+      '#efb775',
+      '#9c6549',
+      '#6f3826',
+      '#36170c',
+      '#45230d',
+      '#724113',
+      '#ab5c1c',
+      '#2a1d0d',
+      '#392a1c',
+      '#684c3c',
+      '#927e6a',
+    ],
+  },
+  chasm: {
+    id: 'chasm',
+    name: 'Chasm',
+    colors: [
+      '#85daeb',
+      '#5fc9e7',
+      '#5fa1e7',
+      '#5f6ee7',
+      '#4c60aa',
+      '#444774',
+      '#32313b',
+      '#463c5e',
+      '#5d4776',
+      '#855395',
+      '#ab58a8',
+      '#ca60ae',
+      '#f3a787',
+      '#f5daa7',
+      '#8dd894',
+      '#5dc190',
+      '#4ab9a3',
+      '#4593a5',
+      '#ffffff',
+      '#5efdf7',
+      '#ff5dcc',
+      '#fdfe89',
+    ],
+  },
+  'db-32': {
+    id: 'db-32',
+    name: 'DB-32',
+    colors: [
+      '#000000',
+      '#222034',
+      '#45283c',
+      '#663931',
+      '#8f563b',
+      '#df7126',
+      '#d9a066',
+      '#eec39a',
+      '#fbf236',
+      '#99e550',
+      '#6abe30',
+      '#37946e',
+      '#4b692f',
+      '#524b24',
+      '#323c39',
+      '#3f3f74',
+      '#306082',
+      '#5b6ee1',
+      '#639bff',
+      '#5fcde4',
+      '#cbdbfc',
+      '#ffffff',
+      '#9badb7',
+      '#847e87',
+      '#696a6a',
+      '#595652',
+      '#76428a',
+      '#ac3232',
+      '#d95763',
+      '#d77bba',
+      '#8f974a',
+      '#8a6f30',
+    ],
+  },
+  indecision: {
+    id: 'indecision',
+    name: 'Indecision',
+    colors: [
+      '#fff4e0',
+      '#8fcccb',
+      '#449489',
+      '#285763',
+      '#2f2b5c',
+      '#4b3b9c',
+      '#457cd6',
+      '#f2b63d',
+      '#d46e33',
+      '#e34262',
+      '#94353d',
+      '#57253b',
+      '#9c656c',
+      '#d1b48c',
+      '#b4ba47',
+      '#6d8c32',
+      '#2c1b2e',
+    ],
+  },
+  'devil-food': {
+    id: 'devil-food',
+    name: 'Devil Food',
+    colors: [
+      '#160d10',
+      '#503146',
+      '#6a3c58',
+      '#934f65',
+      '#7f3265',
+      '#6a2249',
+      '#912749',
+      '#a6333c',
+      '#b54846',
+      '#bf5e4d',
+      '#a13f2f',
+      '#7b2c32',
+      '#58232f',
+      '#351d32',
+      '#3e2544',
+      '#4a3360',
+      '#674268',
+      '#b97884',
+      '#4b5e7d',
+      '#34377e',
+      '#2b2948',
+      '#1e1c32',
+      '#221425',
+      '#471f2f',
+      '#652c39',
+      '#773a40',
+      '#8e524c',
+      '#5d4143',
+      '#3a363c',
+      '#37272a',
+      '#4b3233',
+    ],
+  },
+  logcabin: {
+    id: 'logcabin',
+    name: 'Logcabin',
+    colors: [
+      '#73383e',
+      '#ad5845',
+      '#cf784c',
+      '#e8ad80',
+      '#f5e5bf',
+      '#f7ffed',
+      '#b5f5ec',
+      '#5bace3',
+      '#636ab8',
+      '#574175',
+      '#2f2338',
+    ],
+  },
+  wisteric: {
+    id: 'wisteric',
+    name: 'Wisteric',
+    colors: [
+      '#c9dab8',
+      '#86c1a3',
+      '#569082',
+      '#2d535b',
+      '#162841',
+      '#100b27',
+      '#331541',
+      '#732d72',
+      '#a75b80',
+      '#cd7a87',
+      '#f3b5a8',
+      '#ffddcb',
+      '#e6c9c3',
+      '#cea3ad',
+      '#b37fa1',
+      '#8d5489',
+      '#53315a',
+    ],
+  },
+  'interstate-28': {
+    id: 'interstate-28',
+    name: 'Interstate 28',
+    colors: [
+      '#fefedf',
+      '#f4eaa3',
+      '#f4d565',
+      '#edb048',
+      '#bb5e25',
+      '#903a25',
+      '#6f1519',
+      '#a11920',
+      '#da453c',
+      '#f2846c',
+      '#e8676a',
+      '#c14166',
+      '#942a5e',
+      '#631649',
+      '#23192d',
+      '#342e4c',
+      '#465374',
+      '#5a8090',
+      '#78ccb9',
+      '#57a386',
+      '#3a716c',
+      '#27424b',
+      '#1f2a2c',
+      '#474214',
+      '#55632e',
+      '#89954c',
+      '#a1b974',
+      '#b6e3b3',
+    ],
+  },
+};
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  return [
+    parseInt(h.slice(0, 2), 16) / 255,
+    parseInt(h.slice(2, 4), 16) / 255,
+    parseInt(h.slice(4, 6), 16) / 255,
+  ];
+}
+
+function linearize(c) {
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+function toOklab(hex) {
+  const [r, g, b] = hexToRgb(hex).map(linearize);
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+  return [
+    0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,
+    1.9779984951 * l_ - 2.357995934 * m_ + 0.1802819701 * s_,
+    0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_,
+  ];
+}
+
+function oklabDist(a, b) {
+  const [L1, A1, B1] = toOklab(a);
+  const [L2, A2, B2] = toOklab(b);
+  return Math.hypot(L1 - L2, A1 - A2, B1 - B2);
+}
+
+/** Greedy farthest-point subset: seed with the two most-distant hexes, then add
+ *  the hex maximizing min-distance to the chosen set. Deterministic. */
+export function maxDistinctSubset(hexes, n) {
+  if (n >= hexes.length) return [...hexes];
+  if (n <= 0) return [];
+  if (n === 1) return [hexes[0]];
+
+  let bestI = 0;
+  let bestJ = 1;
+  let bestD = -1;
+  for (let i = 0; i < hexes.length; i++) {
+    for (let j = i + 1; j < hexes.length; j++) {
+      const d = oklabDist(hexes[i], hexes[j]);
+      if (d > bestD) {
+        bestD = d;
+        bestI = i;
+        bestJ = j;
+      }
+    }
+  }
+
+  const chosen = [hexes[bestI], hexes[bestJ]];
+  const remaining = hexes.filter((_, idx) => idx !== bestI && idx !== bestJ);
+
+  while (chosen.length < n && remaining.length) {
+    let bestIdx = 0;
+    let bestMin = -1;
+    for (let i = 0; i < remaining.length; i++) {
+      const minD = Math.min(...chosen.map((c) => oklabDist(remaining[i], c)));
+      if (minD > bestMin) {
+        bestMin = minD;
+        bestIdx = i;
+      }
+    }
+    chosen.push(remaining.splice(bestIdx, 1)[0]);
+  }
+  return chosen;
+}
+
+function normalizeColors(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const entry of raw) {
+    let hex = normalizeHex(typeof entry === 'string' ? entry : '');
+    if (!hex) continue;
+    // A palette entry is a color choice only — opacity is a separate choice in
+    // the UX, so #rrggbbaa collapses to its opaque color rather than becoming
+    // a distinct swatch. (Sprite files may still carry alpha palette entries.)
+    if (hex.length === 9) hex = hex.slice(0, 7);
+    if (seen.has(hex)) continue;
+    seen.add(hex);
+    out.push(hex);
+  }
+  return out;
+}
+
+function hexSetsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const other = new Set(b);
+  return a.every((hex) => other.has(hex));
+}
+
+export function defaultDeckPalette() {
+  return { ...OFFICIAL_PALETTES[OFFICIAL_ENDESGA_64] };
+}
+
+/** Parse theme.style JSON text. Returns the object or null when empty/invalid. */
+export function parseThemeData(text) {
+  if (typeof text !== 'string' || !text.trim()) return null;
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve a theme.style object to `{ id, name, colors }`. Missing/malformed
+ *  data falls back to Endesga-64 so default decks stay byte-identical. */
+export function resolveDeckPalette(themeData) {
+  const fallback = defaultDeckPalette();
+  if (!themeData || typeof themeData !== 'object') return fallback;
+  const raw = themeData.palette;
+  if (typeof raw === 'string') {
+    return OFFICIAL_PALETTES[raw] ? { ...OFFICIAL_PALETTES[raw] } : fallback;
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return fallback;
+  if (typeof raw.id === 'string' && OFFICIAL_PALETTES[raw.id] && !Array.isArray(raw.colors)) {
+    return { ...OFFICIAL_PALETTES[raw.id] };
+  }
+  const colors = normalizeColors(raw.colors);
+  if (!colors.length) return fallback;
+  const name = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : 'custom';
+  return { id: null, name, colors };
+}
+
+export function isDefaultDeckPalette(palette) {
+  return palette?.id === OFFICIAL_ENDESGA_64 || hexSetsEqual(palette?.colors ?? [], EDG64);
+}
+
+/** Generation-path subset. Default EDG64 keeps the curated 16; larger custom
+ *  palettes are cut mechanically; small palettes are used as-is. */
+export function agentPaletteFor(colors, n = 16) {
+  const hexes = normalizeColors(colors);
+  if (hexSetsEqual(hexes, EDG64)) return [...AGENT_PALETTE_16];
+  if (hexes.length > n) return maxDistinctSubset(hexes, n);
+  return hexes;
+}
+
+/** Swatches the editor's deck-palette picker shows. Caps at KEY_ALPHABET's
+ *  first 64 so a huge uploaded list still fits the key budget. */
+export function pickerColorsFor(colors) {
+  const hexes = normalizeColors(colors);
+  return hexes.length > PALETTE_KEY_CAP ? maxDistinctSubset(hexes, PALETTE_KEY_CAP) : hexes;
+}
+
+const OFFICIAL_PICKER_PAGES = Object.values(OFFICIAL_PALETTES).map((palette) => ({
+  id: palette.id,
+  name: palette.name,
+  colors: pickerColorsFor(palette.colors),
+}));
+
+/** Named pages the sprite/art picker browses. Official palettes first (Endesga
+ *  leading), then a custom `{ name, colors }` deck page when theme.style isn't
+ *  an official id. Paging these does not write theme.style. */
+export function pickerPagesFor(deckPalette) {
+  if (deckPalette?.id == null && deckPalette?.colors?.length) {
+    return [
+      ...OFFICIAL_PICKER_PAGES,
+      {
+        id: 'custom',
+        name: deckPalette.name || 'custom',
+        colors: pickerColorsFor(deckPalette.colors),
+      },
+    ];
+  }
+  return OFFICIAL_PICKER_PAGES;
+}
+
+/** Index of the deck's current palette in `pickerPagesFor` output. */
+export function pickerPageIndexFor(pages, deckPalette) {
+  const id = deckPalette?.id ?? 'custom';
+  const index = pages.findIndex((page) => page.id === id);
+  return index >= 0 ? index : 0;
+}
+
+export function themeDataFromFiles(files) {
+  return parseThemeData(files?.[THEME_STYLE_PATH]);
+}
+
+export function deckPaletteFromFiles(files) {
+  return resolveDeckPalette(themeDataFromFiles(files));
+}
+
+/** key -> hex record from an ordered `{ key, hex }[]` palette. */
+export function paletteRecord(palette) {
+  const rec = {};
+  for (const entry of palette ?? []) {
+    if (entry?.key && entry.hex) rec[entry.key] = entry.hex;
+  }
+  return rec;
+}
+
+export function hexForPaletteKey(palette, key) {
+  if (!key) return null;
+  const entry = (palette ?? []).find((item) => item.key === key);
+  return entry?.hex ?? null;
+}
+
+export function keyForPaletteHex(palette, hex) {
+  const norm = normalizeHex(hex ?? '');
+  if (!norm) return null;
+  const entry = (palette ?? []).find((item) => normalizeHex(item.hex) === norm);
+  return entry?.key ?? null;
+}
+
+/** Find or allocate a sprite-palette key for `hex`. Does not remap existing
+ *  pixels. Returns `{ sprite, key }` or `{ sprite, key: null, error }`. */
+export function allocateSpriteColor(sprite, hex) {
+  const norm = normalizeHex(typeof hex === 'string' ? hex : '');
+  if (!norm || !sprite) return { sprite, key: null };
+  const existing = keyForPaletteHex(sprite.palette, norm);
+  if (existing) return { sprite, key: existing };
+  if ((sprite.palette?.length ?? 0) >= PALETTE_KEY_CAP) {
+    return { sprite, key: null, error: 'palette-full' };
+  }
+  const used = new Set((sprite.palette ?? []).map((entry) => entry.key));
+  let key = null;
+  for (const ch of KEY_ALPHABET) {
+    if (!used.has(ch)) {
+      key = ch;
+      break;
+    }
+  }
+  if (!key) return { sprite, key: null, error: 'palette-full' };
+  return {
+    sprite: { ...sprite, palette: [...(sprite.palette ?? []), { key, hex: norm }] },
+    key,
+  };
+}

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

@@ -395,13 +395,13 @@ export function snapResolutionDim(n) {
 export const DEFAULT_RESOLUTION = { width: 16, height: 16 };
 
 // ---------------------------------------------------------------------------
-// Two-tier Endesga-64 palette system
+// Default deck palette (Endesga-64) + curated agent subset
 //
-// 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.
+// EDG64 is the default deck palette (Lospec "Endesga 64"). A deck may override
+// it in theme.style — see engine/palettes.js. AGENT_PALETTE_16 is the curated
+// 16-color subset used when the deck palette is EDG64; custom palettes derive
+// their generation subset via agentPaletteFor. Every AGENT_PALETTE_16 color is
+// a member of EDG64.
 // ---------------------------------------------------------------------------
 
 /** lospec.com/palette-list/endesga-64 — the full 64-color painting palette.