getbotons 0.0.0-stage → 0.1.0

package/payload/shared/look-critter.ts

@@ -0,0 +1,189 @@
+import { hash32, pick, seeded, weighted } from './seeded.ts';
+
+export type CritterBody = 'bun' | 'loaf' | 'round' | 'pebble';
+export type CritterEars = 'point' | 'round' | 'long' | 'floppy' | 'feelers';
+export type CritterEyes = 'dot' | 'bean' | 'arc' | 'sleepy';
+export type CritterMouth = 'smile' | 'open' | 'o' | 'w';
+export type CritterMarks = 'none' | 'belly' | 'spots' | 'cap';
+export type CritterColor = 'coral' | 'sage' | 'sky' | 'lilac' | 'peach' | 'mint' | 'rose' | 'periwinkle' | 'sand' | 'seafoam';
+export type CritterBackdrop = 'navy' | 'plum' | 'forest' | 'wine' | 'slate' | 'cocoa' | 'indigo' | 'teal';
+export interface CritterLook {
+  body: CritterBody;
+  ears: CritterEars;
+  eyes: CritterEyes;
+  mouth: CritterMouth;
+  marks: CritterMarks;
+  cheeks: boolean;
+  color: CritterColor;
+  backdrop: CritterBackdrop;
+}
+
+// The looks a database before schema version 32 holds: a Critter (version 25 on) and the capsule before it (24).
+// They are read, never drawn: shared/look-tater.ts maps each one to its closest tater look, and shared/look.ts that to
+// its closest Boton, in the schema upgrades and on import.
+// This file imports only Node-free modules: the schema upgrade (server/src/schema.ts) and the CLI-free scripts load it.
+
+export const BODIES: readonly CritterBody[] = ['bun', 'loaf', 'round', 'pebble'];
+export const EARS: readonly CritterEars[] = ['point', 'round', 'long', 'floppy', 'feelers'];
+export const EYES: readonly CritterEyes[] = ['dot', 'bean', 'arc', 'sleepy'];
+export const MOUTHS: readonly CritterMouth[] = ['smile', 'open', 'o', 'w'];
+export const MARKS: readonly CritterMarks[] = ['none', 'belly', 'spots', 'cap'];
+
+/** Mid-light body colors, none in the saturated yellow band; each keeps 3:1 against every backdrop and 4.5:1 under the face ink. */
+export const COLORS: Readonly<Record<CritterColor, string>> = {
+  coral: '#ff8c6e',
+  sage: '#a9d39f',
+  sky: '#8ec6ff',
+  lilac: '#c5a9ff',
+  peach: '#ffb48d',
+  mint: '#8fe0bf',
+  rose: '#ff9dbd',
+  periwinkle: '#a1aefc',
+  sand: '#e6c7a1',
+  seafoam: '#94dcd8',
+};
+
+/** Deep night backdrops behind the body. */
+export const BACKDROPS: Readonly<Record<CritterBackdrop, string>> = {
+  navy: '#1d2b52',
+  plum: '#35214b',
+  forest: '#1b3b31',
+  wine: '#4b1f30',
+  slate: '#253241',
+  cocoa: '#3b2a20',
+  indigo: '#272a68',
+  teal: '#123a40',
+};
+
+export const COLOR_NAMES = Object.keys(COLORS) as CritterColor[];
+export const BACKDROP_NAMES = Object.keys(BACKDROPS) as CritterBackdrop[];
+
+/**
+ * Body colors that never get spots: a blue spotted creature reads as a well-known character. The guard turns
+ * spots on them into a belly patch, and every look goes through it: random, migrated, edited and sent to the API.
+ */
+export const NO_SPOTS: readonly CritterColor[] = ['sky', 'periwinkle'];
+
+/** The look with the guardrails applied (a new object; the input is left alone). */
+export function guardCritter(look: CritterLook): CritterLook {
+  return NO_SPOTS.includes(look.color) && look.marks === 'spots' ? { ...look, marks: 'belly' } : { ...look };
+}
+
+const EYE_WEIGHTS = [['dot', 4], ['bean', 3], ['arc', 2], ['sleepy', 1]] as const;
+const MARK_WEIGHTS = [['none', 3], ['belly', 2], ['spots', 2], ['cap', 2]] as const;
+
+const oneOf = <T extends string>(xs: readonly T[], v: unknown): v is T => typeof v === 'string' && (xs as readonly string[]).includes(v);
+
+/** A stored Critter, guarded; null for anything else. Unknown extra fields are dropped. */
+export function parseCritter(v: unknown): CritterLook | null {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
+  const o = v as Record<string, unknown>;
+  if (
+    !oneOf(BODIES, o.body) ||
+    !oneOf(EARS, o.ears) ||
+    !oneOf(EYES, o.eyes) ||
+    !oneOf(MOUTHS, o.mouth) ||
+    !oneOf(MARKS, o.marks) ||
+    typeof o.cheeks !== 'boolean' ||
+    !oneOf(COLOR_NAMES, o.color) ||
+    !oneOf(BACKDROP_NAMES, o.backdrop)
+  ) {
+    return null;
+  }
+  return guardCritter({ body: o.body, ears: o.ears, eyes: o.eyes, mouth: o.mouth, marks: o.marks, cheeks: o.cheeks, color: o.color, backdrop: o.backdrop });
+}
+
+// ------------------------------------------------------------------ the look a version-24 database holds
+// { body: '#rrggbb', bg: '#rrggbb', eyes: 1 | 2, hair, mouth }: a colored capsule on a colored disc. It maps to
+// the closest Critter, field by field, so a Boton keeps what made it recognizable: its color family, its
+// backdrop's hue, what it wore on top (as ears) and its mouth. What has no counterpart (body shape, markings,
+// cheeks) is seeded from the Boton's id, so the result is the same every time and on every machine.
+
+/** Whether `v` has the version-24 shape: a capsule look. Fields need not be valid; each falls back on its own. */
+export function isLook24(v: unknown): v is Record<string, unknown> {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
+  const o = v as Record<string, unknown>;
+  return 'hair' in o || 'bg' in o || (typeof o.body === 'string' && o.body.startsWith('#'));
+}
+
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const rgb = (h: string) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16));
+
+/** [hue in degrees, saturation 0–1, lightness 0–1]. */
+export function hsl(h: string): [number, number, number] {
+  const [r, g, b] = rgb(h).map((v) => v / 255);
+  const mx = Math.max(r, g, b);
+  const mn = Math.min(r, g, b);
+  const d = mx - mn;
+  const l = (mx + mn) / 2;
+  let hue = 0;
+  if (d) {
+    hue = mx === r ? ((g - b) / d) % 6 : mx === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    hue *= 60;
+    if (hue < 0) hue += 360;
+  }
+  return [hue, d ? d / (1 - Math.abs(2 * l - 1)) : 0, l];
+}
+
+/** The saturated yellow band no body color may sit in. */
+export function isYellow(h: string): boolean {
+  const [H, S, L] = hsl(h);
+  return H >= 40 && H <= 66 && S >= 0.45 && L >= 0.3 && L <= 0.92;
+}
+
+const hueDist = (a: number, b: number) => {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+};
+
+/** The palette entry closest to `hex`: hue distance weighted by saturation, plus lightness. Ties go to the first. */
+function nearest<K extends string>(hex: string, palette: Readonly<Record<K, string>>): K {
+  const [H, S, L] = hsl(hex);
+  let best = Object.keys(palette)[0] as K;
+  let score = Infinity;
+  for (const [k, v] of Object.entries(palette) as [K, string][]) {
+    const [h2, s2, l2] = hsl(v);
+    const sc = hueDist(H, h2) * Math.min(S, s2) + Math.abs(L - l2) * 90;
+    if (sc < score) {
+      score = sc;
+      best = k;
+    }
+  }
+  return best;
+}
+
+// The swatches the capsule editor offered, mapped by hand; any other color goes to the nearest one.
+const BODY_24: Record<string, CritterColor> = { '#9b5de5': 'lilac', '#7bd389': 'sage', '#5fb3f9': 'sky', '#ff8fab': 'rose', '#ff9f43': 'peach' };
+/** Yellow has no Critter counterpart: a seeded pick of warm colors instead. */
+const FOR_YELLOW: readonly CritterColor[] = ['coral', 'peach', 'sand', 'mint'];
+const BG_24: Record<string, CritterBackdrop> = {
+  '#2f6fed': 'navy',
+  '#1fb57a': 'forest',
+  '#ef6c2f': 'cocoa',
+  '#e0457b': 'wine',
+  '#8b5cf6': 'indigo',
+  '#14b8c4': 'teal',
+  '#f2b21b': 'cocoa',
+  '#5b6170': 'slate',
+};
+const HAIR_24: Record<string, CritterEars> = { none: 'round', sprout: 'feelers', spiky: 'point', combed: 'floppy', antenna: 'long' };
+const MOUTH_24: Record<string, CritterMouth> = { smile: 'smile', grin: 'open', o: 'o', flat: 'w' };
+
+/**
+ * The closest Critter to a version-24 look, seeded by `seed` (the Boton's id, or a template's). The draws are
+ * those of the approved design preview, in its order, so a look migrates to what that preview showed for it.
+ */
+export function critterFromLook24(old: Record<string, unknown>, seed: string): CritterLook {
+  const r = seeded(hash32(seed));
+  const body = pick(r, BODIES);
+  const ears = (typeof old.hair === 'string' && Object.hasOwn(HAIR_24, old.hair) && HAIR_24[old.hair]) || 'round';
+  const eyes: CritterEyes = old.eyes === 1 ? 'arc' : pick(r, ['dot', 'bean'] as const);
+  const mouth = (typeof old.mouth === 'string' && Object.hasOwn(MOUTH_24, old.mouth) && MOUTH_24[old.mouth]) || 'smile';
+  const marks = weighted(r, MARK_WEIGHTS);
+  const cheeks = r() < 0.5;
+  const hexBody = typeof old.body === 'string' && HEX.test(old.body) ? old.body.toLowerCase() : null;
+  const color = hexBody ? BODY_24[hexBody] || (isYellow(hexBody) ? pick(r, FOR_YELLOW) : nearest(hexBody, COLORS)) : pick(r, COLOR_NAMES);
+  const hexBg = typeof old.bg === 'string' && HEX.test(old.bg) ? old.bg.toLowerCase() : null;
+  const backdrop = hexBg ? BG_24[hexBg] || nearest(hexBg, BACKDROPS) : pick(r, BACKDROP_NAMES);
+  return guardCritter({ body, ears, eyes, mouth, marks, cheeks, color, backdrop });
+}

package/payload/shared/look-tater.ts

@@ -0,0 +1,127 @@
+import { type CritterLook, critterFromLook24, isLook24, parseCritter } from './look-critter.ts';
+import { hash32, pick, type Rand, seeded, weighted } from './seeded.ts';
+
+// Tater looks: the looks a database at schema version 32 holds, a tater Boton built from fixed parts. They are read,
+// never drawn: shared/look.ts maps each one to its closest Boton, in the schema upgrade and on import. The 31-to-32
+// upgrade turns Critters and capsules into tater looks with taterLookFor, exactly as it always has, and the next
+// upgrade takes them on to Botons. This file imports only Node-free modules: the schema upgrade
+// (server/src/schema.ts) and the CLI-free scripts load it.
+
+export type TaterShape = 'classic' | 'tall' | 'chunky';
+export type TaterToast = 'raw' | 'golden' | 'toasty' | 'crispy' | 'sweet' | 'purple' | 'veggie';
+export type TaterEyes = 'dots' | 'buttons' | 'ovals' | 'happy' | 'wink' | 'lidded';
+export type TaterBrows = 'none' | 'soft' | 'straight' | 'arched' | 'bold';
+export type TaterMouth = 'smile' | 'grin' | 'smirk' | 'o' | 'calm' | 'w';
+export type TaterHat = 'none' | 'sprout' | 'beanie' | 'cap' | 'headphones' | 'bucket' | 'beret' | 'party';
+export type TaterGlasses = 'none' | 'round' | 'square' | 'shades';
+export type TaterExtra = 'none' | 'scarf' | 'bowtie' | 'pin' | 'lanyard';
+export type TaterArms = 'none' | 'nubs' | 'wave' | 'cheer';
+export type TaterWear = 'tomato' | 'sage' | 'sky' | 'plum' | 'ink' | 'cream';
+export type TaterBackdrop = 'cream' | 'butter' | 'sage' | 'sky' | 'blush' | 'lilac' | 'cocoa' | 'night';
+
+export interface TaterLook {
+  shape: TaterShape;
+  toast: TaterToast;
+  eyes: TaterEyes;
+  brows: TaterBrows;
+  mouth: TaterMouth;
+  hat: TaterHat;
+  glasses: TaterGlasses;
+  extra: TaterExtra;
+  arms: TaterArms;
+  wear: TaterWear;
+  backdrop: TaterBackdrop;
+  cheeks: boolean;
+}
+
+export const TATER_PARTS = {
+  shape: ['classic', 'tall', 'chunky'],
+  toast: ['raw', 'golden', 'toasty', 'crispy', 'sweet', 'purple', 'veggie'],
+  eyes: ['dots', 'buttons', 'ovals', 'happy', 'wink', 'lidded'],
+  brows: ['none', 'soft', 'straight', 'arched', 'bold'],
+  mouth: ['smile', 'grin', 'smirk', 'o', 'calm', 'w'],
+  hat: ['none', 'sprout', 'beanie', 'cap', 'headphones', 'bucket', 'beret', 'party'],
+  glasses: ['none', 'round', 'square', 'shades'],
+  extra: ['none', 'scarf', 'bowtie', 'pin', 'lanyard'],
+  arms: ['none', 'nubs', 'wave', 'cheer'],
+  wear: ['tomato', 'sage', 'sky', 'plum', 'ink', 'cream'],
+  backdrop: ['cream', 'butter', 'sage', 'sky', 'blush', 'lilac', 'cocoa', 'night'],
+} as const satisfies { [K in keyof Omit<TaterLook, 'cheeks'>]: readonly TaterLook[K][] };
+
+const oneOf = (xs: readonly string[], v: unknown): boolean => typeof v === 'string' && xs.includes(v);
+
+/** A tater look as a database or a file holds it; null for anything else. Unknown extra fields are dropped. */
+export function parseTater(v: unknown): TaterLook | null {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
+  const o = v as Record<string, unknown>;
+  for (const [part, values] of Object.entries(TATER_PARTS)) if (!oneOf(values, o[part])) return null;
+  if (typeof o.cheeks !== 'boolean') return null;
+  return Object.fromEntries([...Object.keys(TATER_PARTS), 'cheeks'].map((k) => [k, o[k]])) as unknown as TaterLook;
+}
+
+// A random tater look, for a stored look that couldn't be read: the 31-to-32 upgrade seeds one from the id.
+const TOAST_W = [['golden', 5], ['toasty', 3], ['raw', 2], ['crispy', 2], ['sweet', 2], ['purple', 1], ['veggie', 1]] as const;
+const EYES_W = [['dots', 5], ['buttons', 3], ['ovals', 3], ['happy', 2], ['wink', 1], ['lidded', 1]] as const;
+const BROWS_W = [['none', 5], ['soft', 2], ['straight', 1], ['arched', 1], ['bold', 1]] as const;
+const MOUTH_W = [['smile', 5], ['grin', 2], ['calm', 2], ['smirk', 1], ['o', 1], ['w', 1]] as const;
+const HAT_W = [['none', 6], ['sprout', 1], ['beanie', 1], ['cap', 1], ['headphones', 1], ['bucket', 1], ['beret', 1], ['party', 1]] as const;
+const GLASSES_W = [['none', 8], ['round', 1], ['square', 1], ['shades', 1]] as const;
+const EXTRA_W = [['none', 7], ['scarf', 1], ['bowtie', 1], ['pin', 1], ['lanyard', 1]] as const;
+const ARMS_W = [['nubs', 6], ['none', 2], ['wave', 1], ['cheer', 1]] as const;
+
+export function randomTater(r: Rand): TaterLook {
+  return {
+    shape: weighted(r, [['classic', 3], ['tall', 2], ['chunky', 2]] as const),
+    toast: weighted(r, TOAST_W),
+    eyes: weighted(r, EYES_W),
+    brows: weighted(r, BROWS_W),
+    mouth: weighted(r, MOUTH_W),
+    hat: weighted(r, HAT_W),
+    glasses: weighted(r, GLASSES_W),
+    extra: weighted(r, EXTRA_W),
+    arms: weighted(r, ARMS_W),
+    wear: pick(r, TATER_PARTS.wear),
+    backdrop: pick(r, TATER_PARTS.backdrop),
+    cheeks: r() < 0.6,
+  };
+}
+
+// A Critter maps to its closest tater look field by field, with no randomness.
+const SHAPE_C: Record<CritterLook['body'], TaterShape> = { bun: 'classic', loaf: 'tall', round: 'chunky', pebble: 'classic' };
+const TOAST_C: Record<CritterLook['color'], TaterToast> = { coral: 'sweet', peach: 'toasty', rose: 'crispy', sand: 'raw', sage: 'veggie', mint: 'veggie', seafoam: 'golden', sky: 'golden', lilac: 'purple', periwinkle: 'purple' };
+const WEAR_C: Record<CritterLook['color'], TaterWear> = { coral: 'tomato', peach: 'tomato', rose: 'plum', sand: 'cream', sage: 'sage', mint: 'sage', seafoam: 'sky', sky: 'sky', lilac: 'plum', periwinkle: 'sky' };
+const BACKDROP_C: Record<CritterLook['backdrop'], TaterBackdrop> = { navy: 'sky', plum: 'lilac', forest: 'sage', wine: 'blush', slate: 'night', cocoa: 'cocoa', indigo: 'lilac', teal: 'sage' };
+const HAT_C: Record<CritterLook['ears'], TaterHat> = { point: 'cap', round: 'none', long: 'headphones', floppy: 'beanie', feelers: 'sprout' };
+const EYES_C: Record<CritterLook['eyes'], TaterEyes> = { dot: 'dots', bean: 'ovals', arc: 'happy', sleepy: 'lidded' };
+const MOUTH_C: Record<CritterLook['mouth'], TaterMouth> = { smile: 'smile', open: 'grin', o: 'o', w: 'w' };
+const EXTRA_C: Record<CritterLook['marks'], TaterExtra> = { none: 'none', belly: 'scarf', spots: 'none', cap: 'pin' };
+
+/** The closest tater look to a Critter. */
+export function taterFromCritter(c: CritterLook): TaterLook {
+  const hat = HAT_C[c.ears] === 'none' && c.marks === 'cap' ? 'beret' : HAT_C[c.ears];
+  return {
+    shape: SHAPE_C[c.body],
+    toast: TOAST_C[c.color],
+    eyes: EYES_C[c.eyes],
+    brows: c.marks === 'spots' ? 'soft' : 'none',
+    mouth: MOUTH_C[c.mouth],
+    hat,
+    glasses: 'none',
+    extra: EXTRA_C[c.marks],
+    arms: 'nubs',
+    wear: WEAR_C[c.color],
+    backdrop: BACKDROP_C[c.backdrop],
+    cheeks: c.cheeks,
+  };
+}
+
+/**
+ * Any look a database at version 31 holds, as a tater look, never failing: a tater look as it is, a Critter mapped to
+ * its closest, a capsule through its closest Critter, and anything else one seeded from `seed`.
+ */
+export function taterLookFor(v: unknown, seed: string): TaterLook {
+  const tater = parseTater(v);
+  if (tater) return tater;
+  const critter = parseCritter(v) ?? (isLook24(v) ? critterFromLook24(v, seed) : null);
+  return critter ? taterFromCritter(critter) : randomTater(seeded(hash32(`look:${seed}`)));
+}

package/payload/shared/look.ts

@@ -0,0 +1,200 @@
+import type { BotonArms, BotonBackdrop, BotonBrows, BotonEars, BotonEyes, BotonGlow, BotonLook, BotonMouth, BotonPanel, BotonShape, BotonShell, BotonTop, BotonVisor } from './types.ts';
+import { critterFromLook24, isLook24, parseCritter } from './look-critter.ts';
+import { parseTater, type TaterLook, taterFromCritter } from './look-tater.ts';
+import { hash32, pick, type Rand, seeded, weighted } from './seeded.ts';
+
+// A Boton's look: a button-bot built from fixed parts. Every field is one of a fixed set of names, so a stored look
+// can never carry markup or an arbitrary color into the renderer (shared/boton.ts).
+// This file imports only Node-free modules: the schema upgrade (server/src/schema.ts) and the CLI-free scripts load it.
+
+export { hash32, seeded };
+
+export const SHAPES: readonly BotonShape[] = ['round', 'pill', 'key'];
+export const EYES: readonly BotonEyes[] = ['dots', 'rings', 'bars', 'happy', 'wink', 'lidded'];
+export const BROWS: readonly BotonBrows[] = ['none', 'soft', 'straight', 'arched', 'bold'];
+export const MOUTHS: readonly BotonMouth[] = ['smile', 'grin', 'smirk', 'o', 'calm', 'wave'];
+export const TOPS: readonly BotonTop[] = ['none', 'antenna', 'twin', 'dish', 'coil', 'fin', 'beacon', 'halo'];
+export const EARS: readonly BotonEars[] = ['none', 'bolts', 'pods', 'fins', 'knobs'];
+export const VISORS: readonly BotonVisor[] = ['none', 'goggles', 'monocle', 'band'];
+export const PANELS: readonly BotonPanel[] = ['none', 'holes', 'grill', 'leds', 'dial', 'switch'];
+export const ARMS: readonly BotonArms[] = ['none', 'nubs', 'wave', 'cheer'];
+
+/** Shell colors. The display carries the face, so a shell only has to stand out from its backdrop. */
+export const SHELLS: Readonly<Record<BotonShell, string>> = {
+  snow: '#eef2f7',
+  steel: '#a9b4c6',
+  graphite: '#323a4c',
+  sun: '#f4c53d',
+  signal: '#f0624d',
+  cobalt: '#3f63e0',
+  violet: '#8457e6',
+  teal: '#17a99d',
+};
+/** The light of the face and the rim. Every one is 7:1 or better on the display glass. */
+export const GLOWS: Readonly<Record<BotonGlow, string>> = { cyan: '#3ee6ff', pink: '#ff6ad5', lime: '#a8ff5c', amber: '#ffbe45', violet: '#b49bff', ice: '#e8f6ff' };
+/** The disc behind the Boton. Its skirt or its rim light keeps every shell at 3:1 or better against it. */
+export const BACKDROPS: Readonly<Record<BotonBackdrop, string>> = {
+  mist: '#e7ecf3',
+  ice: '#d4f2fa',
+  mint: '#d3f4e2',
+  lilac: '#e6defa',
+  blush: '#fbdde8',
+  night: '#121b36',
+  plum: '#2a1842',
+  grid: '#090d18',
+};
+/** Backdrops dark enough that sleep marks are drawn light. */
+export const DARK_BACKDROPS: readonly BotonBackdrop[] = ['night', 'plum', 'grid'];
+
+export const SHELL_NAMES = Object.keys(SHELLS) as BotonShell[];
+export const GLOW_NAMES = Object.keys(GLOWS) as BotonGlow[];
+export const BACKDROP_NAMES = Object.keys(BACKDROPS) as BotonBackdrop[];
+
+/** Every part and its choices, in the builder's order. */
+export const PARTS = {
+  shape: SHAPES,
+  shell: SHELL_NAMES,
+  glow: GLOW_NAMES,
+  eyes: EYES,
+  brows: BROWS,
+  mouth: MOUTHS,
+  top: TOPS,
+  ears: EARS,
+  visor: VISORS,
+  panel: PANELS,
+  arms: ARMS,
+  backdrop: BACKDROP_NAMES,
+} as const;
+export type Part = keyof typeof PARTS;
+
+/** The look a new Boton starts from before anything is chosen: the brand Boton. */
+export const DEFAULT_LOOK: BotonLook = { shape: 'round', shell: 'snow', glow: 'cyan', eyes: 'dots', brows: 'none', mouth: 'smile', top: 'antenna', ears: 'none', visor: 'none', panel: 'none', arms: 'nubs', backdrop: 'night', cheeks: true };
+
+// Weights for a random look: a friendly face on any shell, and only now and then ears, a visor or a panel, so a
+// crowd of Botons reads as a family and each still has something of its own.
+const EYES_W = [['dots', 5], ['rings', 3], ['bars', 3], ['happy', 2], ['wink', 1], ['lidded', 1]] as const;
+const BROWS_W = [['none', 5], ['soft', 2], ['straight', 1], ['arched', 1], ['bold', 1]] as const;
+const MOUTH_W = [['smile', 5], ['grin', 2], ['calm', 2], ['smirk', 1], ['o', 1], ['wave', 1]] as const;
+const TOP_W = [['antenna', 4], ['none', 3], ['twin', 1], ['dish', 1], ['coil', 1], ['fin', 1], ['beacon', 1], ['halo', 1]] as const;
+const EARS_W = [['none', 6], ['bolts', 1], ['pods', 1], ['fins', 1], ['knobs', 1]] as const;
+const VISOR_W = [['none', 8], ['goggles', 1], ['monocle', 1], ['band', 1]] as const;
+const PANEL_W = [['none', 6], ['holes', 2], ['grill', 1], ['leds', 1], ['dial', 1], ['switch', 1]] as const;
+const ARMS_W = [['nubs', 6], ['none', 2], ['wave', 1], ['cheer', 1]] as const;
+
+/** A random look; `r` may be seeded for a stable one. */
+export function randomLook(r: Rand = Math.random): BotonLook {
+  return {
+    shape: weighted(r, [['round', 3], ['pill', 2], ['key', 2]] as const),
+    shell: pick(r, SHELL_NAMES),
+    glow: pick(r, GLOW_NAMES),
+    eyes: weighted(r, EYES_W),
+    brows: weighted(r, BROWS_W),
+    mouth: weighted(r, MOUTH_W),
+    top: weighted(r, TOP_W),
+    ears: weighted(r, EARS_W),
+    visor: weighted(r, VISOR_W),
+    panel: weighted(r, PANEL_W),
+    arms: weighted(r, ARMS_W),
+    backdrop: pick(r, BACKDROP_NAMES),
+    cheeks: r() < 0.6,
+  };
+}
+
+const oneOf = <T extends string>(xs: readonly T[], v: unknown): v is T => typeof v === 'string' && (xs as readonly string[]).includes(v);
+
+/** A look as the API and the database hold it; null for anything else. Unknown extra fields are dropped. */
+export function parseLook(v: unknown): BotonLook | null {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
+  const o = v as Record<string, unknown>;
+  for (const [part, values] of Object.entries(PARTS)) if (!oneOf(values as readonly string[], o[part])) return null;
+  if (typeof o.cheeks !== 'boolean') return null;
+  const look = Object.fromEntries([...Object.keys(PARTS), 'cheeks'].map((k) => [k, o[k]]));
+  return look as unknown as BotonLook;
+}
+
+// ------------------------------------------------------------------ tater looks, which a database at 32 holds
+// A tater look maps to its closest Boton field by field, with no randomness: its shape becomes a button, its toast a
+// shell, its wear color the glow, what it wore on top an antenna or more (headphones become pod ears), its glasses a
+// visor and its extras a panel; its face, arms and cheeks carry over, and the backdrop keeps its light or dark.
+
+const SHAPE_T: Record<TaterLook['shape'], BotonShape> = { classic: 'round', tall: 'key', chunky: 'pill' };
+const SHELL_T: Record<TaterLook['toast'], BotonShell> = { raw: 'snow', golden: 'sun', toasty: 'steel', crispy: 'graphite', sweet: 'signal', purple: 'violet', veggie: 'teal' };
+const GLOW_T: Record<TaterLook['wear'], BotonGlow> = { tomato: 'pink', sage: 'lime', sky: 'cyan', plum: 'violet', ink: 'ice', cream: 'amber' };
+const EYES_T: Record<TaterLook['eyes'], BotonEyes> = { dots: 'dots', buttons: 'rings', ovals: 'bars', happy: 'happy', wink: 'wink', lidded: 'lidded' };
+const MOUTH_T: Record<TaterLook['mouth'], BotonMouth> = { smile: 'smile', grin: 'grin', smirk: 'smirk', o: 'o', calm: 'calm', w: 'wave' };
+const TOP_T: Record<TaterLook['hat'], BotonTop> = { none: 'none', sprout: 'antenna', beanie: 'beacon', cap: 'fin', headphones: 'none', bucket: 'dish', beret: 'halo', party: 'twin' };
+const VISOR_T: Record<TaterLook['glasses'], BotonVisor> = { none: 'none', round: 'goggles', square: 'monocle', shades: 'band' };
+const PANEL_T: Record<TaterLook['extra'], BotonPanel> = { none: 'none', scarf: 'grill', bowtie: 'switch', pin: 'dial', lanyard: 'leds' };
+const BACKDROP_T: Record<TaterLook['backdrop'], BotonBackdrop> = { cream: 'mist', butter: 'mist', sage: 'mint', sky: 'ice', blush: 'blush', lilac: 'lilac', cocoa: 'plum', night: 'night' };
+
+/** The closest Boton to a tater look. */
+export function lookFromTater(t: TaterLook): BotonLook {
+  return {
+    shape: SHAPE_T[t.shape],
+    shell: SHELL_T[t.toast],
+    glow: GLOW_T[t.wear],
+    eyes: EYES_T[t.eyes],
+    brows: t.brows,
+    mouth: MOUTH_T[t.mouth],
+    top: TOP_T[t.hat],
+    ears: t.hat === 'headphones' ? 'pods' : 'none',
+    visor: VISOR_T[t.glasses],
+    panel: PANEL_T[t.extra],
+    arms: t.arms,
+    backdrop: BACKDROP_T[t.backdrop],
+    cheeks: t.cheeks,
+  };
+}
+
+/** Whether a stored value is a look from before Botons (a tater look, a Critter or a capsule), which lookFor maps. */
+export function isEarlierLook(v: unknown): boolean {
+  return parseLook(v) === null && (parseTater(v) !== null || parseCritter(v) !== null || isLook24(v));
+}
+
+/**
+ * Any stored look as a Boton, never failing: a Boton look as it is, a tater look mapped to its closest Boton, a
+ * Critter (or a capsule, through its closest Critter) through its closest tater look, and anything else (missing,
+ * unreadable) a Boton seeded from `seed`.
+ */
+export function lookFor(v: unknown, seed: string): BotonLook {
+  const look = parseLook(v);
+  if (look) return look;
+  const tater = parseTater(v);
+  if (tater) return lookFromTater(tater);
+  const critter = parseCritter(v) ?? (isLook24(v) ? critterFromLook24(v, seed) : null);
+  return critter ? lookFromTater(taterFromCritter(critter)) : randomLook(seeded(hash32(`look:${seed}`)));
+}
+
+const LABELS = {
+  shape: { round: 'Round', pill: 'Pill', key: 'Key' },
+  shell: { snow: 'Snow', steel: 'Steel', graphite: 'Graphite', sun: 'Sun', signal: 'Signal', cobalt: 'Cobalt', violet: 'Violet', teal: 'Teal' },
+  glow: { cyan: 'Cyan', pink: 'Pink', lime: 'Lime', amber: 'Amber', violet: 'Violet', ice: 'Ice' },
+  eyes: { dots: 'Dots', rings: 'Rings', bars: 'Bars', happy: 'Happy', wink: 'Wink', lidded: 'Lidded' },
+  brows: { none: 'None', soft: 'Soft', straight: 'Straight', arched: 'Arched', bold: 'Bold' },
+  mouth: { smile: 'Smile', grin: 'Grin', smirk: 'Smirk', o: 'Oh', calm: 'Calm', wave: 'Wave' },
+  top: { none: 'None', antenna: 'Antenna', twin: 'Twin', dish: 'Dish', coil: 'Coil', fin: 'Fin', beacon: 'Beacon', halo: 'Halo' },
+  ears: { none: 'None', bolts: 'Bolts', pods: 'Pods', fins: 'Fins', knobs: 'Knobs' },
+  visor: { none: 'None', goggles: 'Goggles', monocle: 'Monocle', band: 'Band' },
+  panel: { none: 'None', holes: 'Button holes', grill: 'Grill', leds: 'Lights', dial: 'Dial', switch: 'Switch' },
+  arms: { none: 'None', nubs: 'Nubs', wave: 'Wave', cheer: 'Cheer' },
+  backdrop: { mist: 'Mist', ice: 'Ice', mint: 'Mint', lilac: 'Lilac', blush: 'Blush', night: 'Night', plum: 'Plum', grid: 'Grid' },
+} as const satisfies { [K in Part]: Record<BotonLook[K], string> };
+
+/** The builder's names for each choice. */
+export const LOOK_LABELS: typeof LABELS = LABELS;
+
+/** A short description of a look, for a screen reader: "Snow round Boton with a cyan glow, an antenna and goggles, on night". */
+export function describeLook(l: BotonLook): string {
+  const lower = (s: string) => s.toLowerCase();
+  const article = (s: string) => (/^[aeiou]/i.test(s) ? 'an' : 'a');
+  const named = (s: string) => `${article(s)} ${lower(s)}`;
+  const wearing = [
+    `${named(LABELS.glow[l.glow])} glow`,
+    l.top !== 'none' ? named(LABELS.top[l.top] + (l.top === 'twin' ? ' antennas' : '')).replace(/^a twin/, 'twin') : '',
+    l.ears !== 'none' ? `${lower(LABELS.ears[l.ears])} for ears` : '',
+    l.visor === 'goggles' ? 'goggles' : l.visor !== 'none' ? named(LABELS.visor[l.visor]) : '',
+    l.panel !== 'none' ? (l.panel === 'holes' ? 'button holes' : l.panel === 'leds' ? 'a row of lights' : named(LABELS.panel[l.panel])) : '',
+  ].filter(Boolean);
+  const list = wearing.length > 1 ? `${wearing.slice(0, -1).join(', ')} and ${wearing.at(-1)}` : wearing[0];
+  return `${LABELS.shell[l.shell]} ${lower(LABELS.shape[l.shape])} Boton with ${list}, on ${lower(LABELS.backdrop[l.backdrop])}`;
+}

package/payload/shared/reactions.ts

@@ -0,0 +1,43 @@
+// Emoji reactions on chat messages: what counts as one, and the defaults. The server checks every reaction with
+// reactionEmoji; the web app uses the same lists for its picker.
+
+/** The quick-pick row the app offers on a message. */
+export const QUICK_REACTIONS: readonly string[] = ['👍', '❤️', '😂', '🎉', '👀', '🙏'];
+
+/** The owner's reactions that start a short follow-up turn until they choose others: 👎 alone. */
+export const DEFAULT_REACTION_FOLLOW_UPS: readonly string[] = ['👎'];
+
+/** At most this many emoji start a follow-up turn. */
+export const REACTION_FOLLOW_UP_MAX = 12;
+
+/** At most this many different emoji of the owner's on one message. */
+export const OWNER_REACTION_MAX = 10;
+
+/** What a follow-up turn is asked to do for the reactions whose meaning is set; any other gets a general request. */
+export const REACTION_MEANINGS: Readonly<Record<string, string>> = {
+  '👎': 'that was wrong or not what they wanted: reconsider it',
+  '😕': 'something about it is off or unclear: reconsider it, or ask what was off',
+  '❓': 'they want it explained',
+};
+
+const graphemes = new Intl.Segmenter('en', { granularity: 'grapheme' });
+const PICTOGRAPHIC = /\p{Extended_Pictographic}|\p{Regional_Indicator}/u;
+const KEYCAP = /^[0-9#*]️?⃣$/u;
+const PRESENTATION = /^\p{Emoji_Presentation}$/u;
+
+/**
+ * The emoji as stored, or null when `input` isn't one: exactly one emoji (a single grapheme that is a pictograph, a
+ * flag or a keycap, with no text). A lone symbol that has a text form, such as ❤, is stored with its emoji
+ * presentation (❤️), so both spellings are one reaction.
+ */
+export function reactionEmoji(input: unknown): string | null {
+  if (typeof input !== 'string') return null;
+  const e = input.trim().normalize('NFC');
+  if (!e || e.length > 32) return null;
+  if ([...graphemes.segment(e)].length !== 1) return null;
+  if (KEYCAP.test(e)) return e.replace(/️?⃣$/u, '️⃣');
+  if (!PICTOGRAPHIC.test(e) || /[\p{L}\p{N}\p{P}\p{Cc}\p{Zs}<>]/u.test(e)) return null;
+  const bare = e.replace(/️$/u, '');
+  if ([...bare].length === 1) return PRESENTATION.test(bare) ? bare : `${bare}️`;
+  return e;
+}

package/payload/shared/seeded.ts

@@ -0,0 +1,34 @@
+// Seeded randomness for looks. This file imports nothing: the schema upgrade and the CLI-free scripts load it.
+
+// FNV-1a for strings, mulberry32 for a stream. The same seed gives the same look on every
+// machine, so a migrated Boton looks the same wherever it is drawn.
+export function hash32(s: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+export function seeded(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export type Rand = () => number;
+export const pick = <T>(r: Rand, xs: readonly T[]): T => xs[Math.min(xs.length - 1, Math.floor(r() * xs.length))];
+export function weighted<T>(r: Rand, entries: readonly (readonly [T, number])[]): T {
+  let x = r() * entries.reduce((s, e) => s + e[1], 0);
+  for (const [v, w] of entries) {
+    x -= w;
+    if (x < 0) return v;
+  }
+  return entries[entries.length - 1][0];
+}
+