@homie-rocks/studio 0.21.0 → 0.23.0

package/lib/chat-cli.mjs

@@ -0,0 +1,89 @@
+/**
+ * `homie-studio chat` — a studio's room chat from the studio folder (worker/chat.mjs says what it is; NETPLAY.md
+ * section 19 the rules and the wire). The office key it uses is the same as `office`'s: minted with the studio's own
+ * Cloudflare login, ten minutes long, dropped as soon as the answer is in.
+ *
+ *   homie-studio chat [--game <id>]                    each game's chat rules, every live room's last minutes, the
+ *                                                      reports, and the review's day (neurons used of its budget)
+ *   homie-studio chat rules <game> [--server <id>] [--mode off|emoji|lines|text] [--who anyone|signed-in|members]
+ *                          [--react …] [--slow <s>] [--max <n>] [--links block|allow] [--swears block|allow]
+ *                          [--ai on|off] [--bubbles on|off] [--watchers on|off] [--hub on|off] [--block "a,b"] [--reset]
+ *   homie-studio chat remove <game> <room> <line id>|--all
+ *   homie-studio chat budget <neurons>                  the review's day for the whole studio (default 2,000)
+ *   homie-studio chat words                             the built-in word list the floor holds (worker/chat-words.mjs)
+ *
+ * A change that opens chat up (a wider mode or audience, less slow mode, links or swears allowed, the review off) or
+ * a bigger budget is only ASKED for here: the answer is the owner's one-tap link, as `office kick` gives.
+ */
+import { builtinWords } from '../worker/chat.mjs';
+import { askedFor, withKey } from './office.mjs';
+
+const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const onOff = (v) => (v === undefined ? undefined : v === true || v === 'on' || v === 'true' || v === 'yes');
+
+/** The flags `chat rules` reads, as the office API's fields. */
+export function chatFields(flags) {
+  const f = {};
+  const get = (k) => (flags.has(k) ? flags.get(k) : undefined);
+  for (const k of ['mode', 'who', 'react', 'links', 'swears']) if (get(k) !== undefined) f[k] = String(get(k));
+  for (const k of ['slow', 'max']) if (get(k) !== undefined) f[k] = Number(get(k));
+  for (const k of ['ai', 'bubbles', 'watchers', 'hub']) if (get(k) !== undefined) f[k] = onOff(get(k));
+  if (get('block') !== undefined) f.block = String(get('block')).split(',').map((w) => w.trim()).filter(Boolean);
+  if (get('allow') !== undefined) f.allow = String(get('allow')).split(',').map((w) => w.trim()).filter(Boolean);
+  return f;
+}
+
+export async function chatShow(root, { url, game } = {}) {
+  const r = await withKey(root, url, (call) => call(`/_studio/api/chat${game ? `?game=${encodeURIComponent(game)}` : ''}`));
+  if (!r.ok) return { ok: false, command: 'chat', why: r.why ?? r.message ?? 'the office did not answer' };
+  return { command: 'chat', ...r, ok: true };
+}
+
+export async function chatRulesSet(root, game, flags, { url } = {}) {
+  if (!GAME.test(String(game ?? ''))) return { ok: false, command: 'chat rules', why: 'usage: homie-studio chat rules <game> [--server <id>] --mode off|emoji|lines|text [--who …] [--slow <s>] … | --reset' };
+  const server = flags.get('server') ?? '';
+  const body = flags.has('reset') ? { game, server, reset: true } : { game, server, ...chatFields(flags) };
+  if (!body.reset && Object.keys(body).length <= 2) return { ok: false, command: 'chat rules', why: 'say what to change: --mode, --who, --react, --slow, --max, --links, --swears, --ai, --bubbles, --watchers, --hub, --block, --allow; or --reset' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/chat/rules', body));
+  return askedFor(root, url, r, 'chat rules');
+}
+
+export async function chatRemove(root, game, room, id, { url, all = false } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room || (!id && !all)) return { ok: false, command: 'chat remove', why: 'usage: homie-studio chat remove <game> <room> <line id> | --all (the ids are in `homie-studio chat`)' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/chat/remove', { game, room, ...(all ? { all: true } : { id }) }));
+  return r.ok ? { ok: true, command: 'chat remove', removed: r.removed ?? 0, message: `Took ${r.removed ?? 0} message${r.removed === 1 ? '' : 's'} down in ${room}, on every screen.` } : { ok: false, command: 'chat remove', why: r.message ?? r.why };
+}
+
+export async function chatBudget(root, neurons, { url } = {}) {
+  const n = Math.floor(Number(neurons));
+  if (!(n >= 0 && n <= 1e7)) return { ok: false, command: 'chat budget', why: 'usage: homie-studio chat budget <neurons a day> (default 2000; Workers AI gives an account 10,000 a day free)' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/chat/budget', { neurons: n }));
+  return askedFor(root, url, r, 'chat budget');
+}
+
+/** The built-in list, by group: what the floor always holds (swears only while a game holds swears). */
+export function chatWords() {
+  const w = builtinWords();
+  return {
+    ok: true, command: 'chat words',
+    groups: {
+      slurs: [...w.slurs], slursInsideWords: w.slursAnywhere, sexual: [...w.sexual], sexualInsideWords: w.sexualAnywhere,
+      swears: [...w.swears], swearsInsideWords: w.swearsAnywhere, harm: w.harm, contact: w.contact,
+    },
+    note: 'Whole words unless "inside words". Shown as the floor reads them (lower case, letters only). A studio adds its own with chat rules --block, and lets one through with --allow.',
+  };
+}
+
+export function chatLines(r) {
+  const out = [];
+  const d = r.day;
+  if (d) out.push(`Review today: ${d.ai ? `${Math.round(d.used.neurons)} of ${d.budget.neurons} neurons, ${d.used.reviews} reviewed, ${d.used.held} held${d.used.errors ? `, ${d.used.errors} unanswered (the word list decided)` : ''}` : 'no Workers AI binding yet (npm run deploy binds it); the word list decides'}.`);
+  for (const g of r.games ?? []) {
+    const c = g.chat?.rules;
+    out.push(`${g.name} (${g.id}): ${c ? `${c.mode}${c.mode === 'text' ? `, typing ${c.who}` : ''}, emoji ${c.react}, slow ${c.slow} s${c.ai ? ', reviewed' : ''}${c.capped ? ` (capped: ${c.capped})` : ''}` : 'no rules read'} · from ${g.chat?.from ?? 'default'}`);
+    for (const sv of g.chat?.servers ?? []) if (sv.office) out.push(`  server ${sv.id}: ${sv.rules.mode}, typing ${sv.rules.who}`);
+    for (const rm of g.rooms ?? []) for (const l of (rm.chat?.lines ?? []).slice(-8)) out.push(`  ${rm.room} ${l.id}  ${l.by === 'studio' ? 'Studio' : l.name}: ${l.kind === 'react' ? l.glyph : l.text}`);
+    for (const p of g.chat?.reports ?? []) out.push(`  report ${p.id}: "${p.text}" by ${p.name} (${p.reasonText}), ${p.room}`);
+  }
+  return out;
+}

package/lib/cloudflare.mjs

@@ -218,7 +218,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   // Workers AI (0.17.0): bound only when a server's AI guides think with it.
   if (needsWorkersAi(root, w, cf.d1)) {
     writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true }));
-    step('Workers AI bound (AI): a server\'s AI guides think with it, within the day\'s budget (free allocation: 10,000 neurons a day)');
+    step('Workers AI bound (AI): a server\'s AI guides think with it and typed room chat is reviewed with it, each within its day\'s budget (free allocation: 10,000 neurons a day)');
   }
 
   const started = Date.now();
@@ -271,6 +271,9 @@ export function needsWorkersAi(root, w, db) {
   try {
     const cat = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8'));
     if ((cat.games ?? []).some((g) => (g.servers ?? []).some((s) => s.brain === 'workers-ai'))) return true;
+    // Room chat (0.23.0): a game whose players may type has its messages reviewed by the studio's own Workers AI
+    // (Cloudflare's Clef decision model, within a day's budget of the free allocation) unless its game.json says no.
+    if ((cat.games ?? []).some((g) => g.chat !== false && (g.chat?.mode ?? 'text') === 'text' && g.chat?.ai !== false)) return true;
   } catch { /* not built */ }
   const r = w(['d1', 'execute', db, '--remote', '--json', '--command', "SELECT COUNT(*) AS n FROM servers WHERE brain = 'workers-ai' AND state = 'open'"]);
   if (r.code !== 0) return false;
@@ -343,7 +346,7 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
     try {
       const json = JSON.parse(readFileSync(configPath(root), 'utf8').replace(/^\s*\/\/.*$/gm, ''));
       if (!json.ai) { json.ai = { binding: 'AI' }; writeFileSync(configPath(root), `${JSON.stringify(json, null, 2)}\n`); }
-      step('Workers AI bound (AI) for the AI guides');
+      step('Workers AI bound (AI): the AI guides and the review of typed room chat');
     } catch { step('could not add the Workers AI binding to wrangler.jsonc: the guides answer from the game\'s script'); }
   }
   const started = Date.now();

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));
+}