@homie-rocks/studio 0.20.0 → 0.22.0

package/lib/codex.mjs

@@ -42,6 +42,7 @@ import { latestFeedFor, summarize } from './feed-summary.mjs';
 import { escapeHtml as esc, renderMarkdown } from './markdown.mjs';
 import { readTheme } from './site.mjs';
 import { GAME_ID, listGames, readStudio } from './studio.mjs';
+import { decisionRows, readDecisions } from './decisions.mjs';
 
 export const CODEX_FILE = 'CODEX.md';
 export const CODEX_DIR = join('.studio', 'codex');
@@ -314,6 +315,9 @@ function sectionHtml(section, emb, ctx) {
   }
   const questions = section.key === 'questions';
   let body = blocks(intro, emb, { dated: section.key === 'latest' });
+  // The Art direction tab is the style bible: the decisions (games/<id>/codex/decisions.json) drawn after the prose.
+  const decided = section.key === 'art' && ctx.decisions ? decisionsHtml(ctx.decisions, emb) : '';
+  if (decided) body += decided;
   if (questions) body = body.replace(/^<(ul|ol)>/, '<ol class="questions">').replace(/<\/(ul|ol)>$/, '</ol>');
   const empty = !body && !cards.length;
   return `<section class="tab" id="${esc(section.id)}" data-key="${esc(section.key ?? '')}">
@@ -324,6 +328,29 @@ ${cards.length ? `<div class="cards">${cards.map((c) => card(c.title, c.lines, e
 </section>`;
 }
 
+/* ------------------------------------------------------------------ the art direction decisions */
+
+const STATE_WORD = { auto: 'Auto', steered: 'Steered', pinned: 'Pinned by use', locked: 'Locked' };
+
+/**
+ * The decisions as the style bible: the board's directions (the engine's swatches, a painted mood image only as a
+ * labelled target), the golden images, then one table per phase: decision, value (with the palette's colours), why, its
+ * state and who set it. Pictures come from codex/board/ inside the game's folder, embedded like any codex picture.
+ */
+function decisionsHtml(doc, emb) {
+  const phases = decisionRows(doc);
+  if (!phases.length) return '';
+  const swatch = (c) => `<span class="sw" style="background:${esc(c)}" title="${esc(c)}"></span>`;
+  const board = (doc.board?.directions ?? []).map((d) => {
+    const pic = d.swatch ? emb.image(d.swatch) : null;
+    const mood = d.mood?.path ? emb.image(d.mood.path) : null;
+    return `<figure class="dir${doc.board.chosen === d.id ? ' chosen' : ''}">${pic ? `<img src="${pic}" alt="Direction ${esc(d.id.toUpperCase())}, drawn by the game engine">` : ''}${mood ? `<img src="${mood}" alt="A painted mood image for direction ${esc(d.id.toUpperCase())} (a target)">` : ''}<figcaption><b>${esc(d.id.toUpperCase())}</b> ${esc(d.label)}${doc.board.chosen === d.id ? ' · chosen' : ''}${mood ? ' · the painting is a target, not what the game draws' : ''}</figcaption></figure>`;
+  }).join('');
+  const golden = (doc.golden ?? []).map((g) => { const pic = emb.image(g.path); return pic ? `<img src="${pic}" alt="Golden image">` : ''; }).join('');
+  const tables = phases.map((p) => `<h3 class="phase">${esc(p.label)}</h3><div class="scroll"><table class="decisions"><thead><tr><th>Decision</th><th>Value</th><th>Why</th><th>State</th></tr></thead><tbody>${p.rows.map((r) => `<tr class="${esc(r.state)}"><td>${esc(r.name)}</td><td>${r.colours ? `<span class="sws">${r.colours.map(swatch).join('')}</span> ` : ''}${esc(r.label)}${r.steer.length ? ` <em>(“${esc(r.steer.at(-1))}”)</em>` : ''}</td><td>${esc(r.why ?? '')}</td><td><span class="st ${esc(r.state)}">${esc(STATE_WORD[r.state] ?? r.state)}</span>${r.by === 'person' ? ' <small>the person</small>' : ''}${r.at ? ` <small>${esc(String(r.at).slice(0, 10))}</small>` : ''}</td></tr>`).join('')}</tbody></table></div>`).join('');
+  return `<div class="decided"><p class="eyebrow">The decisions</p><p class="sub">Every look decision with its why. Auto: picked from the plan; steered: nudged by the person; pinned: an asset is built on it; locked: frozen by the person. Your AI changes a locked one only after you say so, and shows what would need remaking first.</p>${board ? `<div class="board">${board}</div>` : ''}${golden ? `<p class="eyebrow">Golden images</p><div class="gallery golden">${golden}</div>` : ''}${tables}${doc.derived?.prompt?.text ? `<details class="prompt"><summary>The style prompt every generated picture starts from</summary><p>${esc(doc.derived.prompt.text)}</p></details>` : ''}</div>`;
+}
+
 /* ------------------------------------------------------------------ the build status tab */
 
 const STATE_MARK = { done: '✓', pass: '✓', skipped: '–', skip: '–', running: '◌', failed: '✗', fail: '✗', stopped: '■', pending: '' };
@@ -432,6 +459,13 @@ code{font-family:var(--mono);font-size:.92em}pre{overflow-x:auto;background:var(
 .try{margin:16px 0;padding:14px 16px;border:1px solid var(--gold);border-radius:14px;background:color-mix(in srgb,var(--gold) 8%,transparent)}.try .eyebrow{color:var(--gold)}.try p{margin:0}
 .panel h3{margin-bottom:6px}.status .panel{margin-top:14px}
 footer{max-width:1080px;margin:0 auto;padding:18px 16px 40px;color:var(--dim);font-size:13px;border-top:1px solid var(--line)}
+.decided{margin-top:22px}.decided h3.phase{margin:22px 0 4px;font:600 13px/1.4 var(--mono);letter-spacing:.1em;text-transform:uppercase;color:var(--accent2)}
+table.decisions td:first-child{white-space:nowrap;font-weight:600}table.decisions td:nth-child(3){color:var(--dim);font-size:14px}
+.sws{display:inline-flex;gap:3px;vertical-align:middle}.sw{display:inline-block;width:16px;height:16px;border-radius:4px;border:1px solid var(--line)}
+.st{display:inline-block;padding:1px 8px;border-radius:999px;font:600 12px/1.6 var(--mono);border:1px solid var(--line);color:var(--dim)}
+.st.locked{color:var(--gold);border-color:var(--gold)}.st.pinned{color:var(--accent2);border-color:color-mix(in srgb,var(--accent2) 60%,transparent)}.st.steered{color:var(--ink)}
+.board{display:grid;grid-template-columns:repeat(auto-fill,minmax(min(100%,300px),1fr));gap:12px;margin:12px 0}.board figure{margin:0}.board figure.chosen img:first-child{outline:3px solid var(--accent);outline-offset:-3px}.board img+img{margin-top:6px}
+details.prompt{margin:16px 0;color:var(--dim);font-size:14px}details.prompt summary{cursor:pointer;color:var(--accent2)}
 @media (max-width:560px){.card .art{width:72px;height:72px}ol.timeline li{grid-template-columns:1fr;gap:2px}}`;
 }
 
@@ -502,10 +536,17 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
   let studio = {};
   try { studio = readStudio(root); } catch { studio = {}; }
   const emb = new Embedder(root, game.dir);
+  let decisions = null;
+  try { decisions = readDecisions(root, id); } catch { decisions = null; }
+  // A palette or fonts the person steered or locked, or an asset pinned, is the game's look: the codex wears it too.
+  const pal = decisions?.decisions?.['style.palette'];
+  const ui = decisions?.decisions?.['style.ui'];
+  if (pal && pal.state !== 'auto') meta.palette = { ...(meta.palette ?? {}), ...Object.fromEntries(['bg', 'ink', 'accent', 'accent2', 'danger', 'good', 'gold'].filter((k) => pal.value?.[k]).map((k) => [k, pal.value[k]])) };
+  if (ui && ui.state !== 'auto' && ui.value?.display) meta.fonts = { ...(meta.fonts ?? {}), display: ui.value.display, body: ui.value.body ?? meta.fonts?.body };
   const look = lookOf(root, game, meta, emb);
   const title = parsed.title ?? game.name ?? id;
   const eyebrow = typeof meta.eyebrow === 'string' && meta.eyebrow.trim() ? meta.eyebrow.trim() : `${studio.name ?? 'Studio'} · ${title}`;
-  const ctx = { eyebrow: String(eyebrow).slice(0, 80), pixel: meta.pixel === true, try: typeof meta.try === 'string' ? meta.try.slice(0, 300) : '', mode };
+  const ctx = { eyebrow: String(eyebrow).slice(0, 80), pixel: meta.pixel === true, try: typeof meta.try === 'string' ? meta.try.slice(0, 300) : '', mode, decisions };
   const s = summarize(feed === undefined ? latestFeedFor(root, id) : feed);
   const sections = parsed.sections.filter((x) => x.body.join('\n').trim() || x.key);
   const tabs = sections.map((x) => `<a href="#${esc(x.id)}">${esc(x.title)}</a>`);
@@ -519,6 +560,7 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
   const start = s?.state === 'running' ? 'build-status' : (sections[0]?.id ?? 'build-status');
   const tagline = typeof meta.tagline === 'string' ? meta.tagline : '';
   const gaps = codexGaps(parsed);
+  if (decisions) gaps.missing = gaps.missing.filter((x) => x !== 'Art direction');
   const html = `<!doctype html>
 <html lang="en">
 <head>

package/lib/colour.mjs

@@ -0,0 +1,160 @@
+/**
+ * COLOUR ARITHMETIC for art direction: hex and RGB, HSL nudges (a palette steered "warmer" or "less saturated"),
+ * CIE Lab and the CIEDE2000 difference (is an asset's albedo still in the locked palette?), and a small k-means for
+ * the dominant colours of a picture. No dependencies; numbers, never a file.
+ */
+
+const clamp = (v, lo = 0, hi = 1) => Math.min(hi, Math.max(lo, v));
+export const HEX = /^#([0-9a-f]{6}|[0-9a-f]{3})$/i;
+
+/** "#ffcf5a" (or "#fc5") as [r, g, b] in 0..255; null when it is not a hex colour. */
+export function hexToRgb(hex) {
+  const m = HEX.exec(String(hex ?? '').trim());
+  if (!m) return null;
+  const h = m[1].length === 3 ? m[1].replace(/./g, '$&$&') : m[1];
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+export function rgbToHex([r, g, b]) {
+  return `#${[r, g, b].map((v) => Math.round(clamp(v, 0, 255)).toString(16).padStart(2, '0')).join('')}`;
+}
+
+export function rgbToHsl([r, g, b]) {
+  const R = r / 255; const G = g / 255; const B = b / 255;
+  const max = Math.max(R, G, B); const min = Math.min(R, G, B);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h = max === R ? (G - B) / d + (G < B ? 6 : 0) : max === G ? (B - R) / d + 2 : (R - G) / d + 4;
+  h *= 60;
+  return [h, s, l];
+}
+
+export function hslToRgb([h, s, l]) {
+  const H = (((h % 360) + 360) % 360) / 360;
+  if (s === 0) return [l * 255, l * 255, l * 255];
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const f = (t) => { let x = t; if (x < 0) x += 1; if (x > 1) x -= 1; if (x < 1 / 6) return p + (q - p) * 6 * x; if (x < 1 / 2) return q; if (x < 2 / 3) return p + (q - p) * (2 / 3 - x) * 6; return p; };
+  return [f(H + 1 / 3) * 255, f(H) * 255, f(H - 1 / 3) * 255];
+}
+
+/** The shortest signed angle from hue a to hue b, in degrees. */
+const hueStep = (a, b) => ((((b - a) % 360) + 540) % 360) - 180;
+
+/**
+ * One colour nudged: { hue: degrees toward `toward` (or a plain rotation), sat: multiply, light: add (-1..1),
+ * warm: 0..1 (toward orange) or cool (toward blue) }. Greys stay grey.
+ */
+export function nudge(hex, { warm = 0, cool = 0, sat = 1, light = 0, hue = 0 } = {}) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return hex;
+  let [h, s, l] = rgbToHsl(rgb);
+  if (s > 0.06) {
+    if (warm) h += hueStep(h, 32) * clamp(warm);
+    if (cool) h += hueStep(h, 215) * clamp(cool);
+    h += hue;
+  }
+  s = clamp(s * sat);
+  l = clamp(l + light, 0.02, 0.98);
+  return rgbToHex(hslToRgb([h, s, l]));
+}
+
+/* ------------------------------------------------------------------ Lab and CIEDE2000 */
+
+function srgbToLinear(c) { const v = c / 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }
+
+/** sRGB [0..255] to CIE L*a*b* (D65). */
+export function rgbToLab([r, g, b]) {
+  const R = srgbToLinear(r); const G = srgbToLinear(g); const B = srgbToLinear(b);
+  const X = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047;
+  const Y = R * 0.2126 + G * 0.7152 + B * 0.0722;
+  const Z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;
+  const f = (t) => (t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116);
+  const fx = f(X); const fy = f(Y); const fz = f(Z);
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+
+/** CIEDE2000 between two Lab colours (Sharma, Wu and Dalal 2005). About 2.3 is "just noticeable". */
+export function deltaE2000([L1, a1, b1], [L2, a2, b2]) {
+  const rad = Math.PI / 180;
+  const C1 = Math.hypot(a1, b1); const C2 = Math.hypot(a2, b2);
+  const Cb = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cb ** 7 / (Cb ** 7 + 25 ** 7)));
+  const ap1 = (1 + G) * a1; const ap2 = (1 + G) * a2;
+  const Cp1 = Math.hypot(ap1, b1); const Cp2 = Math.hypot(ap2, b2);
+  const hp = (b, ap) => { if (b === 0 && ap === 0) return 0; const h = Math.atan2(b, ap) / rad; return h >= 0 ? h : h + 360; };
+  const hp1 = hp(b1, ap1); const hp2 = hp(b2, ap2);
+  const dL = L2 - L1; const dC = Cp2 - Cp1;
+  let dh = 0;
+  if (Cp1 * Cp2 !== 0) { dh = hp2 - hp1; if (dh > 180) dh -= 360; else if (dh < -180) dh += 360; }
+  const dH = 2 * Math.sqrt(Cp1 * Cp2) * Math.sin((dh / 2) * rad);
+  const Lb = (L1 + L2) / 2; const Cpb = (Cp1 + Cp2) / 2;
+  let hb = hp1 + hp2;
+  if (Cp1 * Cp2 !== 0) { hb = Math.abs(hp1 - hp2) <= 180 ? (hp1 + hp2) / 2 : hp1 + hp2 < 360 ? (hp1 + hp2 + 360) / 2 : (hp1 + hp2 - 360) / 2; }
+  const T = 1 - 0.17 * Math.cos((hb - 30) * rad) + 0.24 * Math.cos(2 * hb * rad) + 0.32 * Math.cos((3 * hb + 6) * rad) - 0.2 * Math.cos((4 * hb - 63) * rad);
+  const dTheta = 30 * Math.exp(-(((hb - 275) / 25) ** 2));
+  const Rc = 2 * Math.sqrt(Cpb ** 7 / (Cpb ** 7 + 25 ** 7));
+  const Sl = 1 + (0.015 * (Lb - 50) ** 2) / Math.sqrt(20 + (Lb - 50) ** 2);
+  const Sc = 1 + 0.045 * Cpb; const Sh = 1 + 0.015 * Cpb * T;
+  const Rt = -Math.sin(2 * dTheta * rad) * Rc;
+  return Math.sqrt((dL / Sl) ** 2 + (dC / Sc) ** 2 + (dH / Sh) ** 2 + Rt * (dC / Sc) * (dH / Sh));
+}
+
+/** ΔE2000 between two hex colours. */
+export const deltaHex = (a, b) => { const x = hexToRgb(a); const y = hexToRgb(b); return x && y ? deltaE2000(rgbToLab(x), rgbToLab(y)) : Infinity; };
+
+/** The nearest palette colour to `hex`: { hex, delta }. */
+export function nearest(hex, palette) {
+  let best = { hex: null, delta: Infinity };
+  for (const p of palette) { const d = deltaHex(hex, p); if (d < best.delta) best = { hex: p, delta: d }; }
+  return best;
+}
+
+/**
+ * Dominant colours of RGB samples ([[r,g,b], ...], or a flat Uint8Array of RGB with `weights`), by k-means in Lab:
+ * [{ hex, share }] biggest share first. Deterministic: the first centres are the most distant samples.
+ */
+export function dominant(samples, k = 5, { iterations = 12 } = {}) {
+  const pts = samples.map((s) => ({ rgb: s.rgb ?? s, w: s.w ?? 1, lab: rgbToLab(s.rgb ?? s) }));
+  if (!pts.length) return [];
+  const K = Math.min(k, pts.length);
+  // Farthest-point seeding from the heaviest sample.
+  const centres = [pts.slice().sort((a, b) => b.w - a.w)[0].lab];
+  while (centres.length < K) {
+    let far = null; let fd = -1;
+    for (const p of pts) { const d = Math.min(...centres.map((c) => (c[0] - p.lab[0]) ** 2 + (c[1] - p.lab[1]) ** 2 + (c[2] - p.lab[2]) ** 2)); if (d > fd) { fd = d; far = p; } }
+    centres.push(far.lab);
+  }
+  let assign = new Array(pts.length).fill(0);
+  for (let it = 0; it < iterations; it++) {
+    assign = pts.map((p) => { let bi = 0; let bd = Infinity; centres.forEach((c, i) => { const d = (c[0] - p.lab[0]) ** 2 + (c[1] - p.lab[1]) ** 2 + (c[2] - p.lab[2]) ** 2; if (d < bd) { bd = d; bi = i; } }); return bi; });
+    for (let i = 0; i < K; i++) {
+      let w = 0; const s = [0, 0, 0];
+      pts.forEach((p, j) => { if (assign[j] === i) { w += p.w; s[0] += p.lab[0] * p.w; s[1] += p.lab[1] * p.w; s[2] += p.lab[2] * p.w; } });
+      if (w) centres[i] = [s[0] / w, s[1] / w, s[2] / w];
+    }
+  }
+  const total = pts.reduce((n, p) => n + p.w, 0);
+  return centres.map((c, i) => {
+    let w = 0; const rgb = [0, 0, 0];
+    pts.forEach((p, j) => { if (assign[j] === i) { w += p.w; rgb[0] += p.rgb[0] * p.w; rgb[1] += p.rgb[1] * p.w; rgb[2] += p.rgb[2] * p.w; } });
+    return w ? { hex: rgbToHex(rgb.map((x) => x / w)), share: +(w / total).toFixed(3) } : null;
+  }).filter(Boolean).sort((a, b) => b.share - a.share);
+}
+
+/** Relative luminance (0..1) of a hex colour, for "is this a light palette". */
+export function luminance(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return 0;
+  const [r, g, b] = rgb.map(srgbToLinear);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** Interpolate two hex colours (t 0..1). */
+export function mix(a, b, t) {
+  const x = hexToRgb(a); const y = hexToRgb(b);
+  if (!x || !y) return a;
+  return rgbToHex(x.map((v, i) => v + (y[i] - v) * t));
+}