lanre-ds 0.0.0-stage → 0.2.0

package/components/identity/Avatar.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+
+/**
+ * Contributor portrait with a white ring; falls back to a deterministic generated avatar (hue + pattern from seed, initials); mystery mode shows a neutral "?" and leaks nothing.
+ * @startingPoint section="Identity" subtitle="Portrait, generated fallback, mystery" viewport="700x140"
+ */
+export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  /** Display name (initials + accessible label). */
+  name?: string;
+  /** Stable id used to pick the generated look (falls back to name). Use the contributor id so the avatar never changes. */
+  seed?: string;
+  /** Portrait URL. When present, replaces the generated avatar. */
+  src?: string;
+  /** Diameter in px. Default 64. */
+  size?: number;
+  /** Neutral unknown-person avatar. Ignores name/seed/src entirely so nothing identifying can leak. */
+  mystery?: boolean;
+  /** White ring (default true). */
+  ring?: boolean;
+  alt?: string;
+  style?: React.CSSProperties;
+}
+
+export function Avatar(props: AvatarProps): React.JSX.Element;
+/** First letters of up to two words. */
+export function initials(name?: string): string;

package/components/identity/Avatar.jsx

@@ -0,0 +1,31 @@
+'use client';
+import React from 'react';
+
+function hash(s) { let h = 2166136261; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); } return h >>> 0; }
+const HUES = [25, 55, 95, 140, 175, 215, 260, 300, 335];
+const PATTERNS = ['dots', 'stripes', 'rings', 'plain'];
+// Letters only, with notes in brackets dropped, so "Bayo (work)" gives "B" rather than "B(".
+export function initials(name = '') { return String(name).replace(/\(.*?\)/g, ' ').split(/\s+/).map(w => w.replace(/[^\p{L}\p{N}]/gu, '')).filter(Boolean).slice(0, 2).map(w => [...w][0].toUpperCase()).join(''); } // [...w] keeps letters outside the BMP whole
+
+export function Avatar({ name = '', seed, src, size = 64, mystery = false, ring = true, alt, style, ...rest }) {
+  const b = Math.max(2, Math.round(size * 0.05));
+  const base = { position: 'relative', width: size, height: size, borderRadius: '50%', flex: 'none', overflow: 'hidden', boxSizing: 'border-box', border: ring ? b + 'px solid #fff' : 0,
+    boxShadow: '0 ' + b + 'px 0 oklch(0 0 0 / 0.18), 0 4px 10px oklch(0.2 0.05 60 / 0.25)', display: 'grid', placeItems: 'center', ...style };
+  if (mystery) return (
+    <span role="img" aria-label="Unknown person" style={{ ...base, background: 'radial-gradient(circle at 50% 30%, var(--stone-100), var(--stone-300) 70%)' }} {...rest}>
+      <span aria-hidden="true" style={{ fontFamily: 'var(--font-display)', fontSize: size * 0.5, color: '#fff', WebkitTextStroke: (size * 0.06) + 'px var(--stone-700)', paintOrder: 'stroke fill', lineHeight: 1 }}>?</span>
+    </span>
+  );
+  if (src) return <span style={base} {...rest}><img src={src} alt={alt || name} style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }} /></span>;
+  const h = hash(String(seed || name || 'anon')), hue = HUES[h % HUES.length], pat = PATTERNS[(h >> 4) % PATTERNS.length];
+  const light = 'oklch(0.86 0.11 ' + hue + ')', mid = 'oklch(0.68 0.16 ' + hue + ')', deep = 'oklch(0.42 0.12 ' + hue + ')';
+  const cell = Math.round(size * 0.22), band = Math.round(size * 0.08);
+  const overlay = pat === 'dots' ? 'radial-gradient(oklch(1 0 0 / 0.35) 18%, transparent 21%) 0 0 / ' + cell + 'px ' + cell + 'px'
+    : pat === 'stripes' ? 'repeating-linear-gradient(-45deg, oklch(1 0 0 / 0.22) 0 ' + band + 'px, transparent ' + band + 'px ' + (band * 2.5) + 'px)'
+    : pat === 'rings' ? 'repeating-radial-gradient(circle at 50% 120%, oklch(1 0 0 / 0.25) 0 ' + band + 'px, transparent ' + band + 'px ' + (band * 2.5) + 'px)' : '';
+  return (
+    <span role="img" aria-label={alt || name || 'Contributor'} style={{ ...base, background: (overlay ? overlay + ', ' : '') + 'linear-gradient(160deg, ' + light + ', ' + mid + ' 60%, ' + deep + ')' }} {...rest}>
+      <span aria-hidden="true" style={{ fontFamily: 'var(--font-display)', fontSize: size * 0.42, color: '#fff', WebkitTextStroke: (size * 0.05) + 'px ' + deep, paintOrder: 'stroke fill', lineHeight: 1, letterSpacing: '0.02em' }}>{initials(name) || '•'}</span>
+    </span>
+  );
+}

package/components/identity/Avatar.prompt.md

@@ -0,0 +1,11 @@
+Avatar: every person in the adventure. Portrait if provided; otherwise a generated avatar (never a grey silhouette); mystery when unrevealed.
+
+```jsx
+<Avatar name="Ada Okafor" seed="c_01" size={96} />           // generated: hue + pattern from seed, initials AO
+<Avatar name="Ada Okafor" src={portraitUrl} size={96} />     // real portrait
+<Avatar mystery size={96} />                                  // unrevealed: no name, no seed, no src
+```
+
+- Pass the contributor id as seed so the generated look is stable across screens and sessions.
+- For unrevealed people render mystery and do NOT pass name/seed/src, the component ignores them, but the payload must not contain them either.
+- Portraits are optional and never a prerequisite for guessing.

package/components/identity/AvatarButton.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * The person's own avatar as a 48px button with a small pencil badge, for opening the page where they change their name and photo.
+ * @startingPoint section="Identity" subtitle="Own avatar with a pencil badge" viewport="700x120"
+ */
+export interface AvatarButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** Display name, for the generated avatar's initials. */
+  name?: string;
+  /** Stable id for the generated look. */
+  seed?: string;
+  /** Portrait URL. */
+  src?: string;
+  /** Accessible name. Default "Edit your name and photo". */
+  label?: string;
+  onClick?: () => void;
+}
+
+export function AvatarButton(props: AvatarButtonProps): React.JSX.Element;

package/components/identity/AvatarButton.jsx

@@ -0,0 +1,13 @@
+'use client';
+import React from 'react';
+import { Avatar } from './Avatar';
+
+/* The person's own avatar as a button, with a small pencil to say it can be changed. Fixed at 48px so it sits in a HUD row. */
+export function AvatarButton({ name, seed, src, label = 'Edit your name and photo', onClick, className, ...rest }) {
+  return (
+    <button type="button" className={['mp-avatar-button', className].filter(Boolean).join(' ')} onClick={onClick} aria-label={label} {...rest}>
+      <Avatar name={name} alt="" seed={seed} src={src} size={48} />
+      <span className="mp-avatar-badge" aria-hidden="true"><i className="ph-fill ph-pencil-simple" /></span>
+    </button>
+  );
+}

package/components/identity/AvatarButton.prompt.md

@@ -0,0 +1,8 @@
+Avatar button: the person's own face, pressed to edit their profile.
+
+```jsx
+<AvatarButton name={me.displayName} seed={me.id} src={portraitUrl} onClick={() => go('you')} />
+```
+
+- Use it only for the person's own avatar, where pressing it changes something. Anyone else's portrait is a plain `Avatar`.
+- The label says what pressing does, not who it is.

package/components/identity/Gemstone.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+/**
+ * Quiz gemstone: colour + distinct cut per gem (amber hexagon, emerald octagon, amethyst kite, pearl round), tier I plain / II sparkle / III halo.
+ * @startingPoint section="Identity" subtitle="Amber / Emerald / Amethyst × tiers, Pearl keepsake" viewport="700x220"
+ */
+export interface GemstoneProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  /** amber = score 0–2, emerald = 3–5, amethyst = 6–8, pearl = quiz skipped (unranked keepsake). */
+  gem?: 'amber' | 'emerald' | 'amethyst' | 'pearl';
+  /** 1 plain · 2 sparkle · 3 halo. Ignored for pearl. */
+  tier?: 1 | 2 | 3;
+  /** Box size in px. Default 64. Halo extends ~20% beyond. */
+  size?: number;
+  /** Accessible name override (default "Emerald, tier II" / "Pearl keepsake"). */
+  label?: string;
+  /** Visual only, with no visible or accessible label. Defaults to !showTier. Use true on the recipient’s surfaces. */
+  decorative?: boolean;
+  /** Prints "Emerald II" / "Keepsake" under the stone: FRIEND-FACING ONLY; never on the recipient’s reveal card or collection. */
+  showTier?: boolean;
+  /** Sparkle/halo animation (default true; static in dense lists). */
+  animate?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function Gemstone(props: GemstoneProps): React.JSX.Element;
+/** Maps a 0–8 quiz score (or null for skipped) to { gem, tier }. */
+export function gemForScore(score: number | null | undefined): { gem: 'amber' | 'emerald' | 'amethyst' | 'pearl'; tier: 0 | 1 | 2 | 3 };
+export const GEM_NAMES: Record<'amber' | 'emerald' | 'amethyst' | 'pearl', string>;

package/components/identity/Gemstone.jsx

@@ -0,0 +1,46 @@
+'use client';
+import React from 'react';
+
+const GEMS = {
+  amber:    { name: 'Amber',    light: 'var(--gem-amber-light)',    fill: 'var(--gem-amber)',    deep: 'var(--gem-amber-deep)',    clip: 'polygon(50% 0%, 96% 24%, 96% 76%, 50% 100%, 4% 76%, 4% 24%)', shape: 'hexagon' },
+  emerald:  { name: 'Emerald',  light: 'var(--gem-emerald-light)',  fill: 'var(--gem-emerald)',  deep: 'var(--gem-emerald-deep)',  clip: 'polygon(26% 4%, 74% 4%, 96% 26%, 96% 74%, 74% 96%, 26% 96%, 4% 74%, 4% 26%)', shape: 'octagon' },
+  amethyst: { name: 'Amethyst', light: 'var(--gem-amethyst-light)', fill: 'var(--gem-amethyst)', deep: 'var(--gem-amethyst-deep)', clip: 'polygon(50% 0%, 96% 38%, 50% 100%, 4% 38%)', shape: 'kite' },
+  pearl:    { name: 'Pearl',    light: 'var(--gem-pearl-light)',    fill: 'var(--gem-pearl)',    deep: 'var(--gem-pearl-deep)',    clip: 'circle(48% at 50% 50%)', shape: 'round' },
+};
+const ROMAN = ['', 'I', 'II', 'III'];
+export const GEM_NAMES = { amber: 'Amber', emerald: 'Emerald', amethyst: 'Amethyst', pearl: 'Pearl' };
+
+// Score → gem + tier. null/undefined (quiz skipped) → pearl keepsake, tier 0 (unranked, not a zero).
+export function gemForScore(score) {
+  if (score == null) return { gem: 'pearl', tier: 0 };
+  const s = Math.max(0, Math.min(8, Math.round(score)));
+  return { gem: s < 3 ? 'amber' : s < 6 ? 'emerald' : 'amethyst', tier: (s % 3) + 1 };
+}
+
+export function Gemstone({ gem = 'amber', tier = 1, size = 64, label, showTier = false, decorative = !showTier, animate = true, style, ...rest }) {
+  const g = GEMS[gem] || GEMS.amber;
+  const pearl = gem === 'pearl';
+  const t = pearl ? 0 : Math.max(1, Math.min(3, tier));
+  const sparkle = t >= 2, halo = t === 3;
+  const inset = Math.max(2, Math.round(size * 0.07));
+  const aria = label || (pearl ? 'Pearl keepsake' : g.name + ', tier ' + ROMAN[t]);
+  const layer = (bg, extra) => <span aria-hidden="true" style={{ position: 'absolute', inset, clipPath: g.clip, background: bg, ...extra }} />;
+  return (
+    <span role={decorative ? undefined : "img"} aria-hidden={decorative || undefined} aria-label={decorative ? undefined : aria} style={{ position: 'relative', display: 'inline-grid', justifyItems: 'center', width: size, flex: 'none', ...style }} {...rest}>
+      <span style={{ position: 'relative', width: size, height: size, filter: 'drop-shadow(0 ' + Math.max(2, Math.round(size * 0.05)) + 'px 0 oklch(0 0 0 / 0.22))' }}>
+        {halo && <span aria-hidden="true" style={{ position: 'absolute', inset: '-22%', borderRadius: '50%', background: 'radial-gradient(circle, ' + g.light + ' 0%, ' + g.fill + ' 30%, transparent 70%)', opacity: 0.8, animation: animate ? 'mp-float var(--dur-idle) ease-in-out infinite' : 'none' }} />}
+        {halo && <span aria-hidden="true" style={{ position: 'absolute', inset: '-10%', borderRadius: '50%', border: Math.max(2, Math.round(size * 0.045)) + 'px solid #fff', opacity: 0.9 }} />}
+        <span aria-hidden="true" style={{ position: 'absolute', inset: 0, clipPath: g.clip, background: g.deep }} />
+        {layer('linear-gradient(155deg, ' + g.light + ' 0%, ' + g.fill + ' 48%, ' + g.deep + ' 100%)')}
+        {layer('linear-gradient(180deg, oklch(1 0 0 / 0.6), oklch(1 0 0 / 0) 60%)', { clipPath: pearl ? g.clip : 'polygon(50% 12%, 78% 34%, 50% 54%, 22% 34%)' })}
+        {!pearl && layer('linear-gradient(0deg, oklch(0 0 0 / 0.28), transparent 42%)')}
+        {pearl && <span aria-hidden="true" style={{ position: 'absolute', left: '24%', top: '18%', width: '26%', height: '15%', borderRadius: '50%', background: 'oklch(1 0 0 / 0.9)' }} />}
+        {sparkle && [[-0.1, -0.06, 0], [0.64, 0.66, 600]].map(([x, y, d], i) => (
+          <i key={i} aria-hidden="true" className="ph-fill ph-sparkle" style={{ position: 'absolute', left: x * size, top: y * size, fontSize: size * 0.36, lineHeight: 1, color: '#fff', WebkitTextStroke: (size * 0.03) + 'px ' + g.deep, paintOrder: 'stroke fill', animation: animate ? 'mp-sparkle 1.8s ease-in-out infinite ' + d + 'ms' : 'none' }} />
+        ))}
+      </span>
+      {showTier && !decorative && !pearl && <span style={{ marginTop: 6, fontFamily: 'var(--font-display)', fontSize: Math.max(11, Math.round(size * 0.2)), color: 'var(--ink-700)', letterSpacing: '0.08em' }}>{g.name + ' ' + ROMAN[t]}</span>}
+      {showTier && !decorative && pearl && <span style={{ marginTop: 6, fontFamily: 'var(--font-ui)', fontWeight: 700, fontSize: Math.max(11, Math.round(size * 0.17)), color: 'var(--ink-500)' }}>Keepsake</span>}
+    </span>
+  );
+}

package/components/identity/Gemstone.prompt.md

@@ -0,0 +1,15 @@
+Quiz gemstone: the only visual for quiz results. Colour AND cut differ per gem so it never relies on colour alone.
+
+```jsx
+const { gem, tier } = gemForScore(7);          // → amethyst II
+<Gemstone gem={gem} tier={tier} size={72} />
+<Gemstone gem="amber" tier={1} size={40} animate={false} />   // dense lists
+<Gemstone gem="pearl" size={56} />                            // quiz skipped: keepsake, unranked
+<Gemstone gem="emerald" tier={3} showTier />                  // friend-facing result / leaderboard only
+```
+
+- The recipient’s surfaces (reveal card, Your People) show the stone only, never score, rank or tier text. Friends' surfaces may add showTier and the score.
+- Tier III = halo (+ sparkle). Pearl has no tiers and is never ranked or shown as a zero.
+- Size ≥ 28 in lists, 56–72 on cards. Tap-to-explain is allowed: wrap in a button with aria-label "About this gem".
+
+Project update: The recipient’s gems use decorative={true}: no labels, including accessibility labels. Default decorative is !showTier; contributor-facing showTier still exposes labels. See PROJECT-DECISIONS.md.

package/components/identity/PersonTile.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+
+/**
+ * "Your People" collection tile: revealed (avatar + name + gem badge), mystery (neutral, nothing identifying) or new (late arrival awaiting discovery).
+ * @startingPoint section="Identity" subtitle="Revealed / mystery / new collection tiles" viewport="700x200"
+ */
+export interface PersonTileProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style'> {
+  /** mystery renders no name, portrait or gem regardless of the other props. */
+  state?: 'revealed' | 'mystery' | 'new';
+  name?: string;
+  relationship?: string;
+  portrait?: string;
+  seed?: string;
+  gem?: 'amber' | 'emerald' | 'amethyst' | 'pearl';
+  tier?: 1 | 2 | 3;
+  /** Default 116. */
+  width?: number;
+  onClick?: () => void;
+  style?: React.CSSProperties;
+}
+
+export function PersonTile(props: PersonTileProps): React.JSX.Element;

package/components/identity/PersonTile.jsx

@@ -0,0 +1,27 @@
+'use client';
+import React, { useState } from 'react';
+import { Avatar } from './Avatar';
+import { Gemstone } from './Gemstone';
+
+export function PersonTile({ state = 'mystery', name, relationship, portrait, seed, gem = 'amber', tier = 1, width = 116, onClick, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const mystery = state === 'mystery', isNew = state === 'new';
+  const Tag = onClick ? 'button' : 'div';
+  return (
+    <Tag type={onClick ? 'button' : undefined} onClick={onClick} aria-label={mystery ? 'Not yet found' : name + (isNew ? ', new surprise' : '')}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', margin: 0, position: 'relative', width, padding: '16px 8px 12px', boxSizing: 'border-box', display: 'grid', justifyItems: 'center', gap: 8, borderRadius: 'var(--radius-lg)',
+        border: '3px solid ' + (mystery ? 'oklch(1 0 0 / 0.3)' : isNew ? 'var(--gold-300)' : 'var(--cream-300)'),
+        background: mystery ? 'oklch(0.34 0.09 145 / 0.30)' : 'linear-gradient(180deg, #fff, var(--cream-100))',
+        boxShadow: mystery ? 'inset 0 2px 6px oklch(0 0 0 / 0.25)' : '0 ' + (down && onClick ? 1 : 4) + 'px 0 ' + (isNew ? 'var(--gold-500)' : 'var(--cream-300)') + ', 0 6px 10px oklch(0.2 0.05 60 / 0.2)',
+        transform: down && onClick && !mystery ? 'translateY(3px)' : 'none', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)', cursor: onClick ? 'pointer' : 'default', fontFamily: 'var(--font-ui)', textAlign: 'center', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      {isNew && <span style={{ position: 'absolute', top: -10, left: '50%', transform: 'translateX(-50%)', height: 20, padding: '0 8px', borderRadius: 6, background: 'var(--gold-500)', boxShadow: '0 2px 0 var(--gold-700)', fontFamily: 'var(--font-display)', fontSize: 11, letterSpacing: '0.06em', color: 'var(--gold-900)', display: 'grid', placeItems: 'center', whiteSpace: 'nowrap' }}>NEW</span>}
+      <span style={{ position: 'relative' }}>
+        <Avatar mystery={mystery} name={mystery ? '' : name} seed={mystery ? undefined : seed} src={mystery ? undefined : portrait} size={60} />
+        {!mystery && <Gemstone gem={gem} tier={tier} size={30} decorative animate={false} style={{ position: 'absolute', right: -12, bottom: -6 }} />}
+      </span>
+      <span style={{ fontWeight: 700, fontSize: 13, lineHeight: 1.2, color: mystery ? '#fff' : 'var(--ink-900)', textShadow: mystery ? '0 1px 0 oklch(0 0 0 / 0.4)' : 'none' }}>{mystery ? 'Not yet found' : name}</span>
+      {!mystery && relationship && <span style={{ fontWeight: 600, fontSize: 11, color: 'var(--ink-500)', marginTop: -6 }}>{relationship}</span>}
+    </Tag>
+  );
+}

package/components/identity/PersonTile.prompt.md

@@ -0,0 +1,10 @@
+Person tile: cells of the recipient’s "Your People" collection. Order ranked people by quiz result but emphasise the gem; show no score text.
+
+```jsx
+<PersonTile state="revealed" name="Ada Okafor" relationship="Sister" seed="c_01" gem="amethyst" tier={3} onClick={open} />
+<PersonTile state="mystery" />
+<PersonTile state="new" name="Tunde B." seed="c_22" gem="amber" tier={1} onClick={openDiscovery} />
+```
+
+- Grid: 3 per row on phones, 5–6 on iPad, 10px gaps, over the world background.
+- Mystery tiles get no identifying props at all. Late arrivals stay "new" until their discovery reveal.

package/components/levels/ChoiceButton.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+/**
+ * Full-width answer option for the sender guess and the friends' quiz. Letter badge + result glyph make states colour-independent.
+ * @startingPoint section="Levels" subtitle="Guess / quiz option: idle, selected, correct, wrong, dim" viewport="700x330"
+ */
+export interface ChoiceButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'style'> {
+  /** 0 → A, 1 → B, 2 → C … */
+  index?: number;
+  /** idle · selected (blue) · correct (green + check) · wrong (coral + ×, shakes once) · dim (stone, after resolution). */
+  state?: 'idle' | 'selected' | 'correct' | 'wrong' | 'dim';
+  /** md 56px (phone) · lg 64px (iPad). */
+  size?: 'md' | 'lg';
+  children?: React.ReactNode;
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  disabled?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function ChoiceButton(props: ChoiceButtonProps): React.JSX.Element;

package/components/levels/ChoiceButton.jsx

@@ -0,0 +1,31 @@
+'use client';
+import React, { useState } from 'react';
+
+const TONES = {
+  idle:     { top: '#fff', mid: 'var(--cream-100)', shade: 'var(--cream-300)', text: 'var(--ink-900)', badge: 'var(--blue-500)', badgeText: '#fff' },
+  selected: { top: 'var(--blue-300)', mid: 'var(--blue-500)', shade: 'var(--blue-700)', text: '#fff', badge: '#fff', badgeText: 'var(--blue-700)' },
+  correct:  { top: 'var(--green-300)', mid: 'var(--green-500)', shade: 'var(--green-700)', text: '#fff', badge: '#fff', badgeText: 'var(--green-700)', glyph: 'check', sr: 'Correct' },
+  wrong:    { top: 'var(--coral-300)', mid: 'var(--coral-500)', shade: 'var(--coral-700)', text: '#fff', badge: '#fff', badgeText: 'var(--coral-700)', glyph: 'x', sr: 'Not this one' },
+  dim:      { top: 'var(--stone-100)', mid: 'var(--stone-300)', shade: 'var(--stone-500)', text: 'var(--ink-700)', badge: 'var(--stone-500)', badgeText: '#fff' },
+};
+const SR = { position: 'absolute', width: 1, height: 1, overflow: 'hidden', clip: 'rect(0 0 0 0)', whiteSpace: 'nowrap' };
+
+export function ChoiceButton({ index = 0, state = 'idle', size = 'md', children, onClick, disabled = false, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const t = TONES[state] || TONES.idle;
+  const h = size === 'lg' ? 64 : 56, depth = 5;
+  const off = disabled || state === 'dim' || state === 'correct' || state === 'wrong';
+  const lift = down && !off ? 1 : depth;
+  return (
+    <button type="button" onClick={off ? undefined : onClick} disabled={disabled} aria-pressed={state === 'selected'} aria-disabled={off && !disabled ? true : undefined}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', border: 0, margin: 0, width: '100%', minHeight: h, padding: '8px 14px 8px 10px', boxSizing: 'border-box', display: 'flex', alignItems: 'center', gap: 14, borderRadius: 'var(--radius-md)', textAlign: 'left', cursor: off ? 'default' : 'pointer',
+        background: 'linear-gradient(180deg, ' + t.top + ' 0%, ' + t.mid + ' 42%)', boxShadow: '0 ' + lift + 'px 0 ' + t.shade + ', 0 ' + (lift + 5) + 'px 12px oklch(0.2 0.04 60 / 0.2), inset 0 2px 0 oklch(1 0 0 / 0.45)' + (state === 'correct' ? ', 0 0 0 4px oklch(0.92 0.14 90 / 0.65), 0 0 22px oklch(0.92 0.14 90 / 0.8)' : ''),
+        transform: 'translateY(' + (depth - lift) + 'px)', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)', fontFamily: 'var(--font-ui)', fontWeight: 700, fontSize: size === 'lg' ? 20 : 18, color: t.text,
+        textShadow: t.text === '#fff' ? '0 2px 0 ' + t.shade : 'none', opacity: state === 'dim' ? 0.7 : 1, WebkitTapHighlightColor: 'transparent', animation: state === 'wrong' ? 'mp-shake 0.4s var(--ease-out) 1' : state === 'correct' ? 'mp-pop var(--dur-slow) var(--ease-bounce) 1' : 'none', ...style }} {...rest}>
+      <span aria-hidden="true" style={{ width: 34, height: 34, borderRadius: '50%', flex: 'none', display: 'grid', placeItems: 'center', background: t.badge, color: t.badgeText, fontFamily: 'var(--font-display)', fontSize: 16, boxShadow: 'inset 0 -2px 0 oklch(0 0 0 / 0.15)' }}>{String.fromCharCode(65 + index)}</span>
+      <span style={{ flex: 1, minWidth: 0, lineHeight: 1.2 }}>{children}</span>
+      {t.glyph && <span style={{ width: 30, height: 30, borderRadius: '50%', flex: 'none', display: 'grid', placeItems: 'center', background: '#fff', color: t.badgeText, fontSize: 18 }}><i className={'ph-bold ph-' + t.glyph} aria-hidden="true" /><span style={SR}>{t.sr}</span></span>}
+    </button>
+  );
+}

package/components/levels/ChoiceButton.prompt.md

@@ -0,0 +1,10 @@
+Choice button: "Who sent this?" options (up to three real names, never invented) and quiz answers. Stack vertically, 10px gaps, one column.
+
+```jsx
+{options.map((o, i) => <ChoiceButton key={o.id} index={i} state={stateFor(o)} onClick={() => pick(o)}>{o.name}</ChoiceButton>)}
+<Button variant="ghost" typeface="ui">Just tell me</Button>          // always offered alongside the guess
+```
+
+- Wrong answers: mark that option wrong, keep the others idle for a retry, and keep "Just tell me" available. Never lock the reveal behind a correct guess.
+- After resolution set the correct one to correct and the rest to dim.
+- Use size="lg" on iPad; names are sentence case in the UI face (not display caps).

package/components/map/DiscoveryMarker.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * Optional memory beside the road: a thematic object on a wooden pedestal (mango, rice bowl, flower, dumbbell, lantern, gift, letter). States: hidden (looks like a bush with a glint), available, new (late arrival), opened.
+ * @startingPoint section="Map" subtitle="Discovery markers: hidden / available / new / opened" viewport="700x200"
+ */
+export interface DiscoveryMarkerProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'style'> {
+  kind?: 'mango' | 'rice' | 'flower' | 'dumbbell' | 'lantern' | 'gift' | 'letter' | 'star';
+  /** hidden = contributor asked for it to be tucked away (a glinting bush); available = glow + float; new = "New surprise" tag; opened = dim + tick. */
+  state?: 'hidden' | 'available' | 'new' | 'opened';
+  /** Outlined caption under the object. */
+  label?: string;
+  /** Object size in px. Default 64. */
+  size?: number;
+  onClick?: () => void;
+  style?: React.CSSProperties;
+}
+
+export function DiscoveryMarker(props: DiscoveryMarkerProps): React.JSX.Element;

package/components/map/DiscoveryMarker.jsx

@@ -0,0 +1,31 @@
+'use client';
+import React, { useState } from 'react';
+
+const KINDS = { mango: ['orange', 'gold'], rice: ['bowl-food', 'white'], flower: ['flower', 'coral'], dumbbell: ['barbell', 'blue'], lantern: ['lamp-pendant', 'coral'], gift: ['gift', 'berry'], letter: ['envelope', 'gold'], star: ['star', 'gold'] };
+const TONES = { gold: ['var(--gold-500)', 'var(--gold-900)'], white: ['#fff', 'var(--ink-900)'], coral: ['var(--coral-500)', 'var(--coral-900)'], blue: ['var(--blue-500)', 'var(--blue-900)'], berry: ['var(--berry-500)', 'var(--berry-900)'], teal: ['var(--teal-500)', 'var(--teal-900)'] };
+
+export function DiscoveryMarker({ kind = 'gift', state = 'available', label, size = 64, onClick, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const [glyph, toneKey] = KINDS[kind] || KINDS.gift;
+  const [fill, stroke] = TONES[toneKey] || TONES.gold;
+  const hidden = state === 'hidden', opened = state === 'opened', isNew = state === 'new', live = state === 'available' || isNew;
+  const ped = Math.round(size * 0.42);
+  return (
+    <button type="button" onClick={onClick} aria-label={label || (hidden ? 'Something in the bushes' : (isNew ? 'New surprise: ' : 'Discovery: ') + kind + (opened ? ', opened' : ''))}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', background: 'none', border: 0, padding: 0, margin: 0, position: 'relative', display: 'inline-grid', justifyItems: 'center', width: size + 24, cursor: 'pointer', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      {isNew && <span style={{ marginBottom: 6, height: 20, padding: '0 8px', borderRadius: 6, background: 'var(--gold-500)', boxShadow: '0 2px 0 var(--gold-700)', fontFamily: 'var(--font-display)', fontSize: 11, letterSpacing: '0.06em', color: 'var(--gold-900)', display: 'grid', placeItems: 'center', whiteSpace: 'nowrap', animation: 'mp-float 1.6s ease-in-out infinite' }}>NEW SURPRISE</span>}
+      <span style={{ position: 'relative', width: size, height: Math.round(size * 0.98), display: 'grid', placeItems: 'end center' }}>
+        <span aria-hidden="true" style={{ position: 'absolute', left: '6%', right: '6%', bottom: 0, height: ped, borderRadius: '50%',
+          background: hidden ? 'radial-gradient(ellipse at 40% 25%, var(--green-300), var(--green-500) 55%, var(--green-700))' : 'radial-gradient(ellipse at 50% 30%, var(--wood-300), var(--wood-500) 70%)',
+          boxShadow: '0 ' + (down ? 2 : 5) + 'px 0 ' + (hidden ? 'var(--green-900)' : 'var(--wood-700)') + ', 0 8px 10px oklch(0.2 0.05 60 / 0.3)' + (live ? ', 0 0 0 4px oklch(0.92 0.14 90 / 0.8), 0 0 22px oklch(0.86 0.17 85 / 0.7)' : ''),
+          transform: 'translateY(' + (down ? 3 : 0) + 'px)', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)' }} />
+        {hidden
+          ? <i aria-hidden="true" className="ph-fill ph-sparkle" style={{ position: 'absolute', right: '12%', top: '30%', fontSize: size * 0.28, color: '#fff', filter: 'drop-shadow(0 1px 0 var(--green-900))', animation: 'mp-sparkle 2s ease-in-out infinite' }} />
+          : <i aria-hidden="true" className={'ph-fill ph-' + glyph} style={{ position: 'relative', fontSize: size * 0.6, lineHeight: 1, color: fill, WebkitTextStroke: (size * 0.06) + 'px ' + stroke, paintOrder: 'stroke fill', filter: 'drop-shadow(0 3px 0 oklch(0 0 0 / 0.25))', marginBottom: Math.round(ped * 0.45), opacity: opened ? 0.75 : 1, animation: live ? 'mp-float var(--dur-idle) ease-in-out infinite' : 'none' }} />}
+        {opened && <span aria-hidden="true" style={{ position: 'absolute', right: -2, top: '10%', width: 22, height: 22, borderRadius: '50%', background: 'var(--green-500)', border: '2px solid #fff', color: '#fff', fontSize: 12, display: 'grid', placeItems: 'center', boxShadow: '0 2px 0 var(--green-700)' }}><i className="ph-bold ph-check" /></span>}
+      </span>
+      {label && <span style={{ marginTop: 4, fontFamily: 'var(--font-display)', fontSize: 12, textTransform: 'uppercase', letterSpacing: '0.04em', color: '#fff', WebkitTextStroke: '0.2em var(--ink-900)', paintOrder: 'stroke fill', textShadow: '0 2px 0 oklch(0 0 0 / 0.25)', whiteSpace: 'nowrap' }}>{label}</span>}
+    </button>
+  );
+}

package/components/map/DiscoveryMarker.prompt.md

@@ -0,0 +1,11 @@
+Discovery marker: extra packages placed beside the road in their world; never on the numbered path and never a completion requirement.
+
+```jsx
+<DiscoveryMarker kind="mango" state="available" onClick={open} />
+<DiscoveryMarker kind="gift" state="new" label="New" onClick={open} />     // arrived after the route was frozen
+<DiscoveryMarker kind="rice" state="hidden" onClick={open} />              // contributor asked to hide it
+<DiscoveryMarker kind="lantern" state="opened" />
+```
+
+- Pick the kind from the world (mango grove → mango; small chops → rice; good energy → dumbbell; japan → lantern/flower). gift for anything else.
+- Keep markers 24px+ off the road so level nodes stay the primary tap.

package/components/map/LevelNode.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * Level node on the world map: a 3D stone/blue disc with an outlined number; stars above when complete, pulse ring when current.
+ * @startingPoint section="Map" subtitle="Locked / current / complete level nodes" viewport="700x200"
+ */
+export interface LevelNodeProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'style'> {
+  number: number | string;
+  /** locked = grey stone, unplayable; current = blue with pulse ring; complete = blue with a star row. */
+  state?: 'locked' | 'current' | 'complete';
+  /** Earned stars (0–3), shown for complete. */
+  stars?: number;
+  /** Node width in px. Default 84. */
+  size?: number;
+  onClick?: () => void;
+  style?: React.CSSProperties;
+}
+
+export function LevelNode(props: LevelNodeProps): React.JSX.Element;

package/components/map/LevelNode.jsx

@@ -0,0 +1,37 @@
+'use client';
+import React, { useState } from 'react';
+
+export function LevelNode({ number, state = 'locked', stars = 0, size = 84, onClick, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const locked = state === 'locked';
+  const h = Math.round(size * 0.62), depth = Math.round(size * 0.13);
+  const top = locked ? 'radial-gradient(ellipse at 50% 30%, var(--stone-100), var(--stone-300) 80%)' : 'radial-gradient(ellipse at 50% 30%, var(--blue-300), var(--blue-500) 80%)';
+  const side = locked ? 'var(--stone-500)' : 'var(--blue-700)';
+  const rim = locked ? 'var(--stone-300)' : 'var(--blue-300)';
+  const stroke = locked ? 'var(--stone-700)' : 'var(--blue-700)';
+  const lift = down && !locked ? Math.round(depth * 0.4) : depth;
+  const starEls = [];
+  if (state === 'complete') for (let i = 0; i < 3; i++) {
+    const on = i < stars, s = Math.round(size * 0.3), mid = i === 1;
+    starEls.push(<i key={i} className="ph-fill ph-star" aria-hidden="true" style={{ fontSize: s, lineHeight: 1, color: on ? 'var(--gold-500)' : 'var(--stone-300)', WebkitTextStroke: (s * 0.1) + 'px ' + (on ? 'var(--gold-700)' : 'var(--stone-700)'), paintOrder: 'stroke fill',
+      transform: 'translateY(' + (mid ? -s * 0.3 : 0) + 'px) rotate(' + ((i - 1) * 16) + 'deg)', filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.22))' }} />);
+  }
+  return (
+    <button type="button" onClick={locked ? undefined : onClick} aria-label={'Level ' + number + (locked ? ', locked' : state === 'complete' ? ', ' + stars + ' stars' : ', current')} aria-disabled={locked}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', background: 'none', border: 0, padding: 0, margin: 0, cursor: locked ? 'default' : 'pointer', position: 'relative', display: 'inline-flex', flexDirection: 'column', alignItems: 'center', width: size + 8, WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      <span aria-hidden="true" style={{ display: 'flex', alignItems: 'flex-end', height: Math.round(size * 0.36), marginBottom: -Math.round(size * 0.02), gap: 0, zIndex: 2 }}>{starEls}</span>
+      <span style={{ position: 'relative', width: size, height: h, marginTop: 0 }}>
+        {state === 'current' && <span aria-hidden="true" style={{ position: 'absolute', inset: -2, borderRadius: '50%', animation: 'mp-pulse-ring 1.6s ease-out infinite' }} />}
+        <span aria-hidden="true" style={{ position: 'absolute', inset: 0, borderRadius: '50%', background: top, border: '3px solid ' + rim,
+          boxShadow: '0 ' + lift + 'px 0 ' + side + ', 0 ' + (lift + 6) + 'px 12px oklch(0.2 0.05 60 / 0.35), inset 0 3px 0 oklch(1 0 0 / 0.55)',
+          transform: 'translateY(' + (depth - lift) + 'px)', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)', boxSizing: 'border-box' }}>
+          <span style={{ position: 'absolute', left: '18%', top: '12%', width: '28%', height: '18%', borderRadius: '50%', background: 'oklch(1 0 0 / 0.45)' }} />
+          <span style={{ position: 'absolute', right: '20%', bottom: '22%', width: '10%', height: '8%', borderRadius: '50%', background: 'oklch(1 0 0 / 0.35)' }} />
+        </span>
+        <span style={{ position: 'absolute', inset: 0, display: 'grid', placeItems: 'center', transform: 'translateY(' + (depth - lift - depth * 0.35) + 'px)', transition: 'transform var(--dur-fast)',
+          fontFamily: 'var(--font-display)', fontSize: Math.round(size * 0.46), lineHeight: 1, color: '#fff', WebkitTextStroke: Math.round(size * 0.07) + 'px ' + stroke, paintOrder: 'stroke fill', textShadow: '0 3px 0 oklch(0 0 0 / 0.2)' }}>{number}</span>
+      </span>
+    </button>
+  );
+}

package/components/map/LevelNode.prompt.md

@@ -0,0 +1,11 @@
+Level node: the nodes along the winding path on a world map. Place them absolutely on the map; the path is drawn by the map layer.
+
+```jsx
+<LevelNode number={1} state="complete" stars={3} onClick={() => open(1)} />
+<LevelNode number={4} state="current" onClick={() => open(4)} />
+<LevelNode number={5} state="locked" />
+<LevelNode number={9} size={64} state="locked" />
+```
+
+- Only one current node per map. Locked nodes ignore taps.
+- Keep ≥ 24px of grass between nodes; alternate left/right along the path.

package/components/map/PortraitMedallion.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+/**
+ * Portrait medallion: a revealed friend on a gold pedestal, with the level number on a plate underneath. Takes the LevelNode's place once a level is complete, and stays tappable for replay.
+ * @startingPoint section="Map" subtitle="Completed levels as portrait medallions" viewport="700x220"
+ */
+export interface PortraitMedallionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style' | 'onClick'> {
+  /** The revealed friend's name. Used for the generated avatar's initials and the accessible name. */
+  name: string;
+  /** Contributor id that seeds the generated avatar, so it stays the same everywhere. */
+  seed?: string;
+  /** Portrait URL. Without one, the generated avatar is used. */
+  src?: string;
+  /** Level number on the plate underneath. Leave it out for discoveries. */
+  number?: number | string;
+  /** Medallion width in px. Default 84, the same as LevelNode. */
+  size?: number;
+  /** Play the arrival animation. Use it once, for the level that was just completed. */
+  pop?: boolean;
+  /** Makes it a button for replay, with the bevel press. */
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  /** Accessible name. Defaults to "Replay level {number}, {name}" (or "Replay surprise from {name}") when clickable, otherwise "Level {number}, {name}" or the name. */
+  label?: string;
+  style?: React.CSSProperties;
+}
+
+export function PortraitMedallion(props: PortraitMedallionProps): React.JSX.Element;

package/components/map/PortraitMedallion.jsx

@@ -0,0 +1,29 @@
+'use client';
+import React from 'react';
+import { Avatar } from '../identity/Avatar';
+
+/* A completed level on the map: the friend on a gold pedestal, with the level number on a plate underneath. Give it
+   onClick and it becomes a button that replays the level, with a press, a hover and a keyboard focus ring. The pedestal's
+   shadow and the number plate are the same at every size. */
+export function PortraitMedallion({ name = '', seed, src, number, size = 84, pop = false, onClick, label, style, ...rest }) {
+  const interactive = typeof onClick === 'function';
+  const who = name || 'a friend';
+  const accessibleName = label || (interactive
+    ? (number != null ? 'Replay level ' + number + ', ' + who : 'Replay surprise from ' + who)
+    : (number != null ? 'Level ' + number + ', ' + who : name || 'A friend'));
+  const medallion = (
+    <span className={'mp-medallion' + (pop ? ' mp-medallion-pop' : '')} style={{ '--m': size + 'px', ...(interactive ? null : style) }}
+      {...(interactive ? null : { role: 'img', 'aria-label': accessibleName, ...rest })}>
+      <span className="mp-medallion-ring">
+        <Avatar name={name} seed={seed} src={src} size={Math.round(size * 0.8)} alt="" />
+      </span>
+      {number != null && <span className="mp-medallion-number">{number}</span>}
+    </span>
+  );
+  if (!interactive) return medallion;
+  return (
+    <button type="button" className="mp-medallion-button" aria-label={accessibleName} onClick={onClick} style={style} {...rest}>
+      {medallion}
+    </button>
+  );
+}

package/components/map/PortraitMedallion.prompt.md

@@ -0,0 +1,14 @@
+Portrait medallion: what a completed level becomes on the map. The revealed friend on a gold pedestal, with the level number on a plate underneath. Tap to replay.
+
+```jsx
+<PortraitMedallion name="Ada Okafor" seed="c_01" number={4} onClick={() => replay(4)} />
+<PortraitMedallion name="Ada Okafor" src={portraitUrl} number={4} pop onClick={() => replay(4)} />   // just completed
+<PortraitMedallion name="Tunde Bello" seed="c_22" size={76} onClick={() => replay(discovery)} />     // an opened discovery: no number
+```
+
+- Only for completed levels and opened discoveries. Locked and available levels stay a `LevelNode` and never show who's behind them.
+- Use the friend's portrait when there is one, otherwise their seeded avatar.
+- Keep the replay label readable: it defaults to "Replay level 4, Ada Okafor". Pass `label` to change the wording, never to remove the name.
+- `pop` plays the arrival once. Set it only for the level that was just finished.
+- Same size as the `LevelNode` it replaces (84 by default), so the road doesn't shift.
+- The pedestal's shadow and the number plate are the same at every size, so a small medallion for a discovery has the same bevel as a big one. It is a real button when it has `onClick`, with a hover, a press and a keyboard focus ring.

package/components/map/StarRating.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+
+/**
+ * Gold/grey star row for level results; arc mode raises the middle star (level-complete crown).
+ * @startingPoint section="Map" subtitle="0–3 stars, flat or arched" viewport="700x140"
+ */
+export interface StarRatingProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  /** Earned stars. */
+  value?: number;
+  /** Default 3. */
+  max?: number;
+  /** Star size in px. Default 28. */
+  size?: number;
+  /** Middle star larger and raised, outer stars tilted. */
+  arc?: boolean;
+  /** Pop-in each earned star in sequence. */
+  animate?: boolean;
+  gap?: number;
+  style?: React.CSSProperties;
+}
+
+export function StarRating(props: StarRatingProps): React.JSX.Element;