lanre-ds 0.0.0-stage → 0.2.0

package/components/forms/Switch.prompt.md

@@ -0,0 +1,6 @@
+Settings toggle: Sound, Music, Vibration, Notifications. Pair it with a GameIcon + UI-type label on the left.
+
+```jsx
+<Switch checked={sound} onChange={setSound} label="Sound" />
+<Switch checked tone="blue" size="sm" />
+```

package/components/games/MatchCard.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+/**
+ * Flip card for the brief, skippable matching game: blue "?" back, cream face with a themed symbol; matched pairs get a green ring + tick.
+ * @startingPoint section="Games" subtitle="Matching cards: down / up / matched" viewport="700x180"
+ */
+export interface MatchCardProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'style'> {
+  symbol?: 'mango' | 'rice' | 'flower' | 'dumbbell' | 'lantern' | 'star' | 'heart' | 'leaf';
+  face?: 'down' | 'up' | 'matched';
+  /** Card width in px (height 1.15×). Default 84. */
+  size?: number;
+  onClick?: () => void;
+  disabled?: boolean;
+  label?: string;
+  style?: React.CSSProperties;
+}
+
+export function MatchCard(props: MatchCardProps): React.JSX.Element;

package/components/games/MatchCard.jsx

@@ -0,0 +1,27 @@
+'use client';
+import React from 'react';
+
+const SYMBOLS = { mango: ['orange', 'var(--gold-500)', 'var(--gold-900)'], rice: ['bowl-food', '#fff', 'var(--ink-900)'], flower: ['flower', 'var(--coral-500)', 'var(--coral-900)'], dumbbell: ['barbell', 'var(--blue-500)', 'var(--blue-900)'], lantern: ['lamp-pendant', 'var(--coral-500)', 'var(--coral-900)'], star: ['star', 'var(--gold-500)', 'var(--gold-900)'], heart: ['heart', 'var(--coral-500)', 'var(--coral-900)'], leaf: ['leaf', 'var(--green-500)', 'var(--green-900)'] };
+const reduce = () => typeof window !== 'undefined' && window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+export function MatchCard({ symbol = 'mango', face = 'down', size = 84, onClick, disabled = false, label, style, ...rest }) {
+  const [glyph, fill, stroke] = SYMBOLS[symbol] || SYMBOLS.star;
+  const up = face !== 'down', matched = face === 'matched';
+  const faceStyle = { position: 'absolute', inset: 0, borderRadius: 'var(--radius-md)', backfaceVisibility: 'hidden', WebkitBackfaceVisibility: 'hidden', display: 'grid', placeItems: 'center', boxSizing: 'border-box' };
+  const swap = reduce() ? 'none' : 'opacity 0s linear 225ms';
+  return (
+    <button type="button" onClick={onClick} disabled={disabled || up} aria-label={label || (up ? symbol + (matched ? ', matched' : '') : 'Face-down card')}
+      style={{ appearance: 'none', background: 'none', border: 0, padding: 0, margin: 0, width: size, height: Math.round(size * 1.15), perspective: 600, cursor: disabled || up ? 'default' : 'pointer', flex: 'none', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      <span style={{ position: 'relative', display: 'block', width: '100%', height: '100%', transformStyle: 'preserve-3d', transform: up ? 'rotateY(180deg)' : 'none', transition: reduce() ? 'none' : 'transform 450ms var(--ease-in-out)' }}>
+        <span aria-hidden="true" style={{ ...faceStyle, opacity: up ? 0 : 1, transition: swap, background: 'radial-gradient(circle at 50% 30%, var(--blue-300), var(--blue-500) 70%)', border: '3px solid var(--blue-300)', boxShadow: '0 5px 0 var(--blue-700), 0 8px 12px oklch(0.2 0.05 60 / 0.3), inset 0 2px 0 oklch(1 0 0 / 0.5)' }}>
+          <span style={{ position: 'absolute', inset: 8, borderRadius: 10, border: '2px dashed oklch(1 0 0 / 0.5)' }} />
+          <span style={{ fontFamily: 'var(--font-display)', fontSize: size * 0.42, lineHeight: 1, color: '#fff', WebkitTextStroke: (size * 0.05) + 'px var(--blue-700)', paintOrder: 'stroke fill' }}>?</span>
+        </span>
+        <span aria-hidden="true" style={{ ...faceStyle, opacity: up ? 1 : 0, transition: swap, transform: 'rotateY(180deg)', background: 'linear-gradient(180deg, #fff, var(--cream-100))', border: '3px solid ' + (matched ? 'var(--green-500)' : 'var(--cream-300)'), boxShadow: '0 5px 0 ' + (matched ? 'var(--green-700)' : 'var(--cream-300)') + ', 0 8px 12px oklch(0.2 0.05 60 / 0.2)' }}>
+          <i className={'ph-fill ph-' + glyph} style={{ fontSize: size * 0.5, lineHeight: 1, color: fill, WebkitTextStroke: (size * 0.055) + 'px ' + stroke, paintOrder: 'stroke fill', filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.2))' }} />
+          {matched && <span style={{ position: 'absolute', right: -8, top: -8, width: 24, height: 24, borderRadius: '50%', background: 'var(--green-500)', border: '2px solid #fff', color: '#fff', fontSize: 13, display: 'grid', placeItems: 'center', boxShadow: '0 2px 0 var(--green-700)' }}><i className="ph-bold ph-check" /></span>}
+        </span>
+      </span>
+    </button>
+  );
+}

package/components/games/MatchCard.prompt.md

@@ -0,0 +1,11 @@
+Match card: for levels whose media already reveals the sender: a 6-card (3 pairs) or 8-card grid, then the direct reveal. Always paired with a Skip button.
+
+```jsx
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 84px)', gap: 12 }}>
+  {cards.map(c => <MatchCard key={c.id} symbol={c.symbol} face={c.face} onClick={() => flip(c.id)} />)}
+</div>
+<Button variant="ghost" typeface="ui">Skip</Button>
+```
+
+- Choose the interaction once per level and persist it; don't re-roll on each render.
+- Symbols come from the Birthday Adventure’s world: mango, rice bowl, flower, dumbbell, lantern.

package/components/hud/Countdown.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+
+/**
+ * Live countdown that ticks every second: a wooden board with day, hour, minute and second tiles, or a ticking TimerChip for the HUD.
+ * @startingPoint section="HUD" subtitle="Live countdown: wooden board or HUD chip" viewport="700x300"
+ */
+export interface CountdownProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'title'> {
+  /** When it ends: a Date, an ISO string or a timestamp in ms. */
+  to: Date | string | number;
+  /** board = the wooden board with tiles (default). chip = a ticking DD:HH:MM:SS TimerChip. */
+  variant?: 'board' | 'chip';
+  /** What it counts down to, e.g. "your birthday". Read out as "3 days, 4 hours and 12 minutes until your birthday". */
+  label?: string;
+  /** Board only: the gold tag across the top. Defaults to "Until {label}". */
+  title?: React.ReactNode;
+  /** Board only: a line under the tiles, such as the date. */
+  caption?: React.ReactNode;
+  /** Phosphor glyph name. Defaults to gift on the board and hourglass-medium on the chip. */
+  icon?: string;
+  /** What to show once the time has passed. Default nothing. */
+  ended?: React.ReactNode;
+  /** Chip only: turns urgent (coral, floating) within this many ms of the end. Default one day. */
+  urgentWithin?: number;
+  /** Chip only: TimerChip tone. */
+  tone?: 'dark' | 'light';
+  /** Chip only: TimerChip size. */
+  size?: 'sm' | 'md';
+  /** Freeze the clock at this timestamp in ms, for fixtures and screenshots. */
+  now?: number;
+  style?: React.CSSProperties;
+}
+
+export function Countdown(props: CountdownProps): React.JSX.Element | null;

package/components/hud/Countdown.jsx

@@ -0,0 +1,74 @@
+'use client';
+import React, { useSyncExternalStore } from 'react';
+import { TimerChip } from './TimerChip';
+
+const SECOND = 1000;
+// One clock for every Countdown on the page, firing just after each whole second so they all change together.
+const listeners = new Set();
+let timer = 0;
+const schedule = () => { timer = setTimeout(() => { listeners.forEach(tick => tick()); schedule(); }, SECOND - (Date.now() % SECOND) + 5); };
+const tickEverySecond = tick => { listeners.add(tick); if (listeners.size === 1) schedule(); return () => { listeners.delete(tick); if (!listeners.size) clearTimeout(timer); }; };
+const noTicks = () => () => {};
+const clockNow = () => Math.floor(Date.now() / SECOND) * SECOND;
+const noClockOnServer = () => null; // server and browser clocks differ, so it renders after hydration
+const pad = n => String(n).padStart(2, '0');
+const plural = (n, word) => n + ' ' + word + (n === 1 ? '' : 's');
+
+export function Countdown({ to, variant = 'board', label, title, caption, icon, ended = null, urgentWithin = 86400000, tone, size, now, style, ...rest }) {
+  const frozen = now != null;
+  const ticking = useSyncExternalStore(frozen ? noTicks : tickEverySecond, clockNow, noClockOnServer);
+  const current = frozen ? now : ticking;
+  if (current == null) return null;
+  const left = new Date(to).getTime() - current;
+  if (!(left > 0)) return ended;
+  const total = Math.floor(left / SECOND);
+  const days = Math.floor(total / 86400), hours = Math.floor((total % 86400) / 3600), minutes = Math.floor((total % 3600) / 60), seconds = total % 60;
+  const said = [[days, 'day'], [hours, 'hour'], [minutes, 'minute']];
+  while (said.length && said[0][0] === 0) said.shift(); // "4 hours and 2 minutes", not "0 days, 4 hours…"
+  const words = said.map(([n, w]) => plural(n, w));
+  const spoken = (words.length > 1 ? words.slice(0, -1).join(', ') + ' and ' + words[words.length - 1] : words[0] || 'Less than a minute') + (label ? ' until ' + label : ' left');
+
+  if (variant === 'chip') {
+    return <TimerChip role="timer" aria-label={spoken} icon={icon || 'hourglass-medium'} time={pad(days) + ':' + pad(hours) + ':' + pad(minutes) + ':' + pad(seconds)}
+      urgent={left <= urgentWithin} tone={tone} size={size} style={style} {...rest} />;
+  }
+
+  const units = [[days, 'Days'], [hours, 'Hours'], [minutes, 'Mins'], [seconds, 'Secs']];
+  return (
+    <div role="timer" aria-label={spoken} style={{ width: '100%', containerType: 'inline-size', paddingTop: 22, boxSizing: 'border-box', ...style }} {...rest}>
+      <div style={{
+        position: 'relative', boxSizing: 'border-box', padding: 'clamp(34px, 7cqi, 44px) clamp(14px, 4cqi, 26px) clamp(16px, 3.5cqi, 22px)',
+        borderRadius: 'var(--radius-xl)', border: '5px solid var(--wood-900)',
+        background: 'repeating-linear-gradient(180deg, transparent 0 18px, oklch(0 0 0 / 0.06) 18px 21px), linear-gradient(180deg, var(--wood-300), var(--wood-500))',
+        boxShadow: '0 8px 0 var(--wood-900), 0 22px 36px oklch(0.25 0.05 60 / 0.35), inset 0 4px 0 oklch(1 0 0 / 0.3)',
+        display: 'grid', justifyItems: 'center', gap: 14,
+      }}>
+        <span aria-hidden="true" style={{
+          position: 'absolute', top: -22, left: '50%', transform: 'translateX(-50%)', height: 44, padding: '0 20px', boxSizing: 'border-box',
+          borderRadius: 'var(--radius-pill)', border: '4px solid #fff', background: 'linear-gradient(180deg, var(--gold-300), var(--gold-500) 60%)', boxShadow: '0 4px 0 var(--gold-700)',
+          display: 'inline-flex', alignItems: 'center', gap: 8, whiteSpace: 'nowrap',
+          fontFamily: 'var(--font-display)', fontSize: 'clamp(14px, 3cqi, 17px)', letterSpacing: '0.06em', textTransform: 'uppercase', color: 'var(--gold-900)',
+        }}>
+          <i className={'ph-fill ph-' + (icon || 'gift')} style={{ fontSize: '1.2em' }} />
+          {title || (label ? 'Until ' + label : 'Time left')}
+        </span>
+        <div aria-hidden="true" style={{ width: '100%', display: 'grid', gridTemplateColumns: 'repeat(4, minmax(0, 1fr))', gap: 'clamp(8px, 2.4cqi, 14px)' }}>
+          {units.map(([value, unit]) => (
+            <div key={unit} style={{ display: 'grid', justifyItems: 'center', gap: 8, minWidth: 0 }}>
+              <span style={{
+                position: 'relative', width: '100%', aspectRatio: '1 / 1.04', boxSizing: 'border-box', borderRadius: 'clamp(14px, 3.5cqi, 20px)', overflow: 'hidden',
+                background: 'linear-gradient(180deg, #fff 0%, var(--cream-100) 48%, var(--cream-200) 100%)', boxShadow: '0 6px 0 var(--wood-700), inset 0 3px 0 oklch(1 0 0 / 0.8)',
+                display: 'grid', placeItems: 'center',
+              }}>
+                <span style={{ fontFamily: 'var(--font-display)', fontSize: 'clamp(28px, 10cqi, 64px)', lineHeight: 1, color: 'var(--blue-900)', fontVariantNumeric: 'tabular-nums', letterSpacing: '0.02em' }}>{pad(value)}</span>
+                <span style={{ position: 'absolute', left: 0, right: 0, top: '50%', height: 2, background: 'oklch(0.4 0.08 60 / 0.12)' }} />
+              </span>
+              <span style={{ fontFamily: 'var(--font-display)', fontSize: 'clamp(11px, 2.6cqi, 14px)', letterSpacing: '0.1em', textTransform: 'uppercase', color: '#fff', WebkitTextStroke: '0.22em var(--wood-900)', paintOrder: 'stroke fill' }}>{unit}</span>
+            </div>
+          ))}
+        </div>
+        {caption && <span aria-hidden="true" style={{ fontWeight: 700, fontSize: 15, color: 'var(--cream-50)', textShadow: '0 2px 0 oklch(0.3 0.06 55 / 0.6)' }}>{caption}</span>}
+      </div>
+    </div>
+  );
+}

package/components/hud/Countdown.prompt.md

@@ -0,0 +1,15 @@
+Live countdown that ticks every second. The board is the big wooden one for a front gate or a title screen. The chip is a ticking TimerChip for the HUD.
+
+```jsx
+<Countdown to="2026-12-24T00:00:00" label="the party" caption="24 December" />
+<Countdown variant="chip" to={deadline} label="the deadline" ended={<TimerChip icon="heart" time="Late entries welcome" />} />
+<Countdown to={opensAt} title="Doors open in" icon="door-open" />
+<Countdown to="2026-12-24T00:00:00" now={Date.parse('2026-12-20T09:30:00')} />   // frozen, for fixtures
+```
+
+- Give a `label` for what it counts down to. Screen readers hear "3 days, 4 hours and 12 minutes until the party". The seconds are left out so it isn't noisy.
+- It renders nothing on the server and until the page hydrates, because the server's clock isn't the visitor's. Leave room for it if the layout would jump.
+- When the time passes it shows `ended`, which is nothing by default. Swap in a message or another component.
+- The board fills its container's width and scales its tiles to fit. One board per screen.
+- The chip turns urgent in the last day. Change that with `urgentWithin`.
+- Don't hard-code dates in components. Pass them in, so fixtures and real data stay separate.

package/components/hud/CurrencyPill.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * HUD currency readout: dark inset pill, glyph overlapping the left edge, optional "+" buy button on the right.
+ * @startingPoint section="HUD" subtitle="Coins / gems / hearts readout with + button" viewport="700x160"
+ */
+export interface CurrencyPillProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style'> {
+  /** Built-in glyph + tone. Default coin. */
+  kind?: 'coin' | 'gem' | 'ruby' | 'heart' | 'energy' | 'star' | 'key';
+  /** Formatted amount, e.g. "50,253k" or "3/3". */
+  value: React.ReactNode;
+  /** Custom glyph node replacing the built-in one (e.g. <GameIcon kind="chest" />). */
+  icon?: React.ReactNode;
+  /** When set, renders the teal "+" button and calls this on tap. */
+  onAdd?: () => void;
+  /** sm 28px / md 36px tall. */
+  size?: 'sm' | 'md';
+  /** dark = translucent brown over the world (default); light = cream, for inside panels. */
+  tone?: 'dark' | 'light';
+  minWidth?: number;
+  style?: React.CSSProperties;
+}
+
+export function CurrencyPill(props: CurrencyPillProps): React.JSX.Element;

package/components/hud/CurrencyPill.jsx

@@ -0,0 +1,34 @@
+'use client';
+import React, { useState } from 'react';
+
+const KINDS = { coin: ['coin', 'var(--gold-500)', 'var(--gold-900)'], gem: ['sketch-logo', 'var(--blue-500)', 'var(--blue-900)'], ruby: ['sketch-logo', 'var(--coral-500)', 'var(--coral-900)'],
+  heart: ['heart', 'var(--coral-500)', 'var(--coral-900)'], energy: ['lightning', 'var(--teal-500)', 'var(--teal-900)'], star: ['star', 'var(--gold-500)', 'var(--gold-900)'], key: ['key', 'var(--gold-500)', 'var(--gold-900)'] };
+const SIZES = { sm: [28, 14, 34, 22], md: [36, 18, 44, 28] }; // [pill height, font, icon, plus size]
+
+export function CurrencyPill({ kind = 'coin', value, icon, onAdd, size = 'md', tone = 'dark', minWidth, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const [glyph, fill, stroke] = KINDS[kind] || KINDS.coin;
+  const [h, fs, ic, plus] = SIZES[size] || SIZES.md;
+  const dark = tone === 'dark';
+  return (
+    <div style={{ position: 'relative', display: 'inline-flex', alignItems: 'center', height: h, minWidth: minWidth || h * 3,
+      padding: '0 ' + (onAdd ? plus * 0.7 + 6 : 12) + 'px 0 ' + (ic * 0.72) + 'px', boxSizing: 'border-box', borderRadius: 'var(--radius-pill)',
+      background: dark ? 'var(--surface-hud)' : 'var(--cream-50)', border: dark ? '2px solid oklch(0.20 0.05 55 / 0.9)' : '2px solid var(--cream-300)',
+      boxShadow: dark ? 'inset 0 2px 4px oklch(0 0 0 / 0.35), 0 2px 0 oklch(1 0 0 / 0.15)' : 'inset 0 2px 3px oklch(0 0 0 / 0.08), 0 2px 0 var(--cream-300)',
+      fontFamily: 'var(--font-display)', fontSize: fs, color: dark ? '#fff' : 'var(--ink-900)', letterSpacing: '0.02em',
+      textShadow: dark ? '0 2px 0 oklch(0 0 0 / 0.35)' : 'none', ...style }} {...rest}>
+      <span aria-hidden="true" style={{ position: 'absolute', left: -ic * 0.28, top: '50%', transform: 'translateY(-50%)', width: ic, height: ic, display: 'grid', placeItems: 'center', filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.25))' }}>
+        {icon || <i className={'ph-fill ph-' + glyph} style={{ fontSize: ic, lineHeight: 1, color: fill, WebkitTextStroke: (ic * 0.11) + 'px ' + stroke, paintOrder: 'stroke fill' }} />}
+      </span>
+      <span style={{ flex: 1, textAlign: 'center', paddingLeft: 2, whiteSpace: 'nowrap' }}>{value}</span>
+      {onAdd && (
+        <button type="button" aria-label="Add" onClick={onAdd} onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+          style={{ position: 'absolute', right: -plus * 0.3, top: '50%', transform: 'translateY(-50%) translateY(' + (down ? 2 : 0) + 'px)', width: plus, height: plus, border: '2px solid #fff', borderRadius: 'var(--radius-sm)', padding: 0, cursor: 'pointer',
+            background: 'linear-gradient(180deg, var(--teal-300), var(--teal-500) 50%)', boxShadow: '0 ' + (down ? 1 : 3) + 'px 0 var(--teal-700)', color: '#fff', fontSize: plus * 0.6, lineHeight: 1, display: 'grid', placeItems: 'center',
+            transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)' }}>
+          <i className="ph-bold ph-plus" />
+        </button>
+      )}
+    </div>
+  );
+}

package/components/hud/CurrencyPill.prompt.md

@@ -0,0 +1,12 @@
+HUD currency pill: the top-bar readout for coins, gems, hearts, energy; also used inline for a cost or a count ("3/3").
+
+```jsx
+<CurrencyPill kind="coin" value="50,253k" onAdd={() => openShop()} />
+<CurrencyPill kind="gem" value={36} onAdd={openShop} />
+<CurrencyPill kind="heart" value="5/5" size="sm" />
+<CurrencyPill kind="energy" value={32} tone="light" />
+```
+
+- Top HUD: 2–3 pills max, right-aligned, size md, tone dark. Numbers are pre-formatted strings (50,253k, 1.2M).
+- Inside panels use tone="light".
+- onAdd only on purchasable currencies.

package/components/hud/HudBar.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+/**
+ * The bar along the top of the map: chips on the left and a slot on the right, such as a sound toggle, that drops away on phones. It sits over the window and lets taps through to the map, except on what's inside it.
+ * @startingPoint section="HUD" subtitle="The map's top bar, with HudChips" viewport="700x180"
+ */
+export interface HudBarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  /** HudChips. On a narrow phone they wrap onto a second row instead of pushing the right side off screen. */
+  left?: React.ReactNode;
+  /** Hidden on phones. */
+  right?: React.ReactNode;
+  /** Hides the bar, for when something covers the map. */
+  hidden?: boolean;
+  /** Sits inside a positioned box instead of covering the window. */
+  contained?: boolean;
+}
+
+export function HudBar(props: HudBarProps): React.JSX.Element;

package/components/hud/HudBar.jsx

@@ -0,0 +1,14 @@
+'use client';
+import React from 'react';
+
+/* The bar along the top of the map: chips on the left, and a slot on the right (such as a sound toggle) that drops away on
+   phones. It sits over the window and lets taps through to the map, except on what's inside it. Set `contained` to place
+   it in a positioned box instead. Put `mp-chrome-arriving` or `mp-chrome-away` on a parent for the arrival and the climb. */
+export function HudBar({ left, right, hidden = false, contained = false, ...rest }) {
+  return (
+    <header className={'mp-hud' + (contained ? ' mp-hud-contained' : '')} hidden={hidden} {...rest}>
+      <div className="mp-hud-left">{left}</div>
+      <div className="mp-hud-right">{right}</div>
+    </header>
+  );
+}

package/components/hud/HudBar.prompt.md

@@ -0,0 +1,15 @@
+HUD bar: the strip across the top of the map.
+
+```jsx
+<HudBar
+  left={<>
+    <HudChip icon="users-three" tone="teal" value="3/5" onClick={openPeople} aria-label="3 of 5 friends found. Open Your people" />
+    <HudChip icon="sparkle" tone="berry" value="1/3" fresh onClick={findNext} aria-label="1 of 3 surprises found, a new one just arrived. Show me the next one" />
+  </>}
+  right={<SoundToggle on={sound} onChange={setSound} size="sm" />} />
+```
+
+- It covers the window and lets taps through to the map, so only the chips and the right slot take them. Set `contained` to place it in a positioned box.
+- On a phone the right slot drops away, since sound stays one tap away in the menu. Its layout follows the window, not its box.
+- Hide it with `hidden` while a sheet is open over the map.
+- For the arrival (it drops in) and the climb (it steps aside), put `mp-chrome-arriving` or `mp-chrome-away` on a parent of the HUD, the toolbar and the dock.

package/components/hud/HudChip.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+/** True for a moment each time `count` goes up, so a chip can bump as something is found. */
+export function useBump(count: number): boolean;
+
+/**
+ * A count on the HUD, such as friends or surprises found: a dark pill with a big glyph overlapping its left edge. A tap does something about it. A coral dot says something new has arrived.
+ * @startingPoint section="HUD" subtitle="Friends and surprises counts" viewport="700x140"
+ */
+export interface HudChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** A Phosphor icon name. Default "users-three". */
+  icon?: string;
+  /** teal is steady. berry glints every few seconds, for surprises. */
+  tone?: 'teal' | 'berry';
+  /** The count, such as "3/5". */
+  value: string;
+  /** Bumps the chip, once. Use `useBump(count)`. */
+  bump?: boolean;
+  /** A coral dot: something new has arrived. */
+  fresh?: boolean;
+  disabled?: boolean;
+  onClick?: () => void;
+}
+
+export function HudChip(props: HudChipProps): React.JSX.Element;

package/components/hud/HudChip.jsx

@@ -0,0 +1,30 @@
+'use client';
+import React, { useEffect, useState } from 'react';
+import { CurrencyPill } from './CurrencyPill';
+
+/* True for a moment each time `count` goes up, so a chip bumps as something is found. */
+export function useBump(count) {
+  const [seen, setSeen] = useState(count);
+  const [bump, setBump] = useState(false);
+  if (count !== seen) {
+    setSeen(count);
+    if (count > seen) setBump(true);
+  }
+  useEffect(() => {
+    if (!bump) return;
+    const t = window.setTimeout(() => setBump(false), 560);
+    return () => window.clearTimeout(t);
+  }, [bump]);
+  return bump;
+}
+
+/* A count on the HUD, such as friends found or surprises found. A tap does something about it. Give it an aria-label
+   that says the count in words and what pressing it does. */
+export function HudChip({ icon = 'users-three', tone = 'teal', value, bump = false, fresh = false, disabled = false, onClick, ...rest }) {
+  return (
+    <button type="button" className={'mp-hud-chip' + (bump ? ' mp-hud-bump' : '')} onClick={onClick} disabled={disabled} {...rest}>
+      <CurrencyPill size="md" value={value} icon={<i className={'ph-fill ph-' + icon + ' ' + (tone === 'berry' ? 'mp-hud-sparkle' : 'mp-hud-friends')} />} minWidth={86} />
+      {fresh && <span className="mp-hud-new" aria-hidden="true" />}
+    </button>
+  );
+}

package/components/hud/HudChip.prompt.md

@@ -0,0 +1,13 @@
+HUD chip: a count that's also a shortcut.
+
+```jsx
+const bump = useBump(found);
+<HudChip icon="users-three" value={`${found}/${total}`} bump={bump} onClick={openPeople} aria-label={`${found} of ${total} friends found. Open Your people`} />
+```
+
+- Always give it an `aria-label` that says the count in words and what a tap does. The visible "3/5" alone doesn't.
+- `useBump(count)` returns true for half a second each time the count goes up, so the chip bumps and glows as something is found. It stays still when the count drops or stays the same.
+- `fresh` adds a pulsing coral dot, for something that arrived after they started.
+- Use `tone="berry"` for surprises. Its glyph glints now and then. With reduced motion, nothing moves.
+- Disable it when there's nothing for a tap to do.
+- It's a `CurrencyPill` inside a button, so the two always match.

package/components/hud/ProgressBar.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+/**
+ * Striped, bevelled progress bar in a dark inset track, XP, loading, boost timers, quest progress.
+ * @startingPoint section="HUD" subtitle="Striped XP / loading bar with cap + label" viewport="700x200"
+ */
+export interface ProgressBarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style'> {
+  /** Current value; percent = value / max. */
+  value: number;
+  /** Default 1 (value is a 0–1 ratio). */
+  max?: number;
+  tone?: 'gold' | 'blue' | 'teal' | 'green' | 'coral' | 'berry';
+  /** sm 14 / md 22 / lg 30 px tall. */
+  size?: 'sm' | 'md' | 'lg';
+  /** Centered outlined label, e.g. "6/20" or "75%". */
+  label?: React.ReactNode;
+  /** Diagonal stripes on the fill (default true). */
+  striped?: boolean;
+  /** Node overlapping the left end (a level star badge, an avatar). */
+  cap?: React.ReactNode;
+  width?: number | string;
+  /** dark = brown inset over the world (default); light = cream, inside panels. */
+  track?: 'dark' | 'light';
+  style?: React.CSSProperties;
+}
+
+export function ProgressBar(props: ProgressBarProps): React.JSX.Element;

package/components/hud/ProgressBar.jsx

@@ -0,0 +1,39 @@
+'use client';
+import React from 'react';
+
+const FILLS = {
+  gold:  ['var(--gold-300)',  'var(--gold-500)',  'var(--gold-700)'],
+  blue:  ['var(--blue-300)',  'var(--blue-500)',  'var(--blue-700)'],
+  teal:  ['var(--teal-300)',  'var(--teal-500)',  'var(--teal-700)'],
+  green: ['var(--green-300)', 'var(--green-500)', 'var(--green-700)'],
+  coral: ['var(--coral-300)', 'var(--coral-500)', 'var(--coral-700)'],
+  berry: ['var(--berry-300)', 'var(--berry-500)', 'var(--berry-700)'],
+};
+const SIZES = { sm: [14, 11], md: [22, 14], lg: [30, 18] }; // [height, label size]
+
+export function ProgressBar({ value = 0, max = 1, tone = 'gold', size = 'md', label, striped = true, cap, width, track = 'dark', style, ...rest }) {
+  const pct = Math.max(0, Math.min(100, (value / (max || 1)) * 100));
+  const [top, mid, shade] = FILLS[tone] || FILLS.gold;
+  const [h, fs] = SIZES[size] || SIZES.md;
+  const dark = track === 'dark';
+  return (
+    <div role="progressbar" aria-valuenow={Math.round(pct)} aria-valuemin={0} aria-valuemax={100}
+      style={{ position: 'relative', display: 'flex', alignItems: 'center', width: width || '100%', minWidth: 80, ...style }} {...rest}>
+      {cap && <span style={{ position: 'relative', zIndex: 2, marginRight: -h * 0.5, flex: 'none', display: 'grid', placeItems: 'center' }}>{cap}</span>}
+      <div style={{ position: 'relative', flex: 1, height: h, borderRadius: 'var(--radius-pill)', overflow: 'hidden', boxSizing: 'border-box',
+        background: dark ? 'oklch(0.30 0.06 55 / 0.85)' : 'var(--cream-200)', border: '2px solid ' + (dark ? 'oklch(0.20 0.05 55 / 0.9)' : 'var(--cream-300)'),
+        boxShadow: 'inset 0 2px 4px oklch(0 0 0 / 0.35), 0 2px 0 oklch(1 0 0 / 0.15)' }}>
+        <div style={{ position: 'absolute', inset: 0, right: 'auto', width: pct + '%', minWidth: pct > 0 ? h : 0, borderRadius: 'var(--radius-pill)',
+          background: 'linear-gradient(180deg, ' + top + ' 0%, ' + mid + ' 55%, ' + shade + ' 100%)', boxShadow: 'inset 0 -3px 0 ' + shade + ', inset 0 2px 0 oklch(1 0 0 / 0.5)',
+          transition: 'width var(--dur-slow) var(--ease-out)' }}>
+          {striped && <div style={{ position: 'absolute', inset: 0, borderRadius: 'inherit', opacity: 0.35,
+            background: 'repeating-linear-gradient(-55deg, transparent 0 8px, oklch(1 0 0 / 0.55) 8px 14px)' }} />}
+        </div>
+        {label != null && (
+          <span style={{ position: 'absolute', inset: 0, display: 'grid', placeItems: 'center', fontFamily: 'var(--font-display)', fontSize: fs, color: '#fff', lineHeight: 1,
+            WebkitTextStroke: (fs * 0.18) + 'px var(--ink-900)', paintOrder: 'stroke fill', letterSpacing: '0.03em' }}>{label}</span>
+        )}
+      </div>
+    </div>
+  );
+}

package/components/hud/ProgressBar.prompt.md

@@ -0,0 +1,11 @@
+Striped progress bar: XP in the HUD, loading screens, boost/energy meters, quest and event progress.
+
+```jsx
+<ProgressBar value={0.42} label="42%" />
+<ProgressBar value={6} max={20} tone="green" label="6/20" size="lg" cap={<GameIcon kind="star" size={36} />} />
+<ProgressBar value={0.7} tone="blue" size="sm" striped={false} />
+<ProgressBar value={0.3} tone="teal" track="light" />
+```
+
+- Default gold fill on a dark track; green for quest/points, blue for water/energy-style meters, coral for hearts/health.
+- Width transitions on change (420ms ease-out): animate by updating value, nothing else.

package/components/hud/TimerChip.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * Small countdown chip (clock glyph + mm:ss) for boosts, offers, energy refills.
+ * @startingPoint section="HUD" subtitle="Countdown chip" viewport="700x120"
+ */
+export interface TimerChipProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  /** Pre-formatted time, e.g. "00:02" or "3h 12m". */
+  time: React.ReactNode;
+  /** Phosphor glyph name. Default clock. */
+  icon?: string;
+  tone?: 'dark' | 'light';
+  size?: 'sm' | 'md';
+  /** Coral text + gentle float when time is nearly up. */
+  urgent?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function TimerChip(props: TimerChipProps): React.JSX.Element;

package/components/hud/TimerChip.jsx

@@ -0,0 +1,17 @@
+'use client';
+import React from 'react';
+
+export function TimerChip({ time, icon = 'clock', tone = 'dark', size = 'md', urgent = false, style, ...rest }) {
+  const h = size === 'sm' ? 24 : 32; const fs = size === 'sm' ? 12 : 15;
+  const dark = tone === 'dark';
+  const alarm = dark ? 'var(--coral-300)' : 'var(--coral-700)'; // coral-300 is too light to read on cream
+  return (
+    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6, height: h, padding: '0 12px 0 8px', borderRadius: 'var(--radius-pill)', boxSizing: 'border-box',
+      background: dark ? 'var(--surface-hud)' : 'var(--cream-50)', border: '2px solid ' + (dark ? 'oklch(0.20 0.05 55 / 0.9)' : 'var(--cream-300)'),
+      color: urgent ? alarm : (dark ? '#fff' : 'var(--ink-900)'), fontFamily: 'var(--font-display)', fontSize: fs, letterSpacing: '0.04em', fontVariantNumeric: 'tabular-nums',
+      textShadow: dark ? '0 2px 0 oklch(0 0 0 / 0.35)' : 'none', animation: urgent ? 'mp-float var(--dur-idle) ease-in-out infinite' : 'none', ...style }} {...rest}>
+      <i className={'ph-fill ph-' + icon} style={{ fontSize: fs + 4, lineHeight: 1, color: urgent ? alarm : (dark ? '#fff' : 'var(--ink-700)') }} />
+      <span>{time}</span>
+    </span>
+  );
+}

package/components/hud/TimerChip.prompt.md

@@ -0,0 +1,7 @@
+Countdown chip: sits directly under the thing it times (a boost button, an offer card, an energy pill).
+
+```jsx
+<TimerChip time="00:02" />
+<TimerChip time="4h 12m" tone="light" size="sm" />
+<TimerChip time="00:09" urgent />
+```

package/components/icons/GameIcon.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+/**
+ * Painted-style glyph: a Phosphor FILL icon with solid tone, dark outline behind the fill and a hard 2px drop.
+ * @startingPoint section="Icons" subtitle="Currency + world glyphs with outline treatment" viewport="700x220"
+ */
+export interface GameIconProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  /** Semantic preset choosing glyph + tone: coin, coins, gem, ruby, heart, star, energy, key, gift, chest, trophy, crown, lock, clock, ticket, egg, map, compass, flag, leaf, tent, boat, mountains, footprints, play, check, x, plus, gear, shop, trash, sound, music, vibrate, bell, backpack, fire, binoculars, sparkle, quest, spin. */
+  kind?: 'coin' | 'coins' | 'gem' | 'ruby' | 'heart' | 'star' | 'energy' | 'key' | 'gift' | 'chest' | 'trophy' | 'crown' | 'lock' | 'clock' | 'ticket' | 'egg' | 'map' | 'compass' | 'flag' | 'leaf' | 'tent' | 'boat' | 'mountains' | 'footprints' | 'play' | 'check' | 'x' | 'plus' | 'gear' | 'shop' | 'trash' | 'sound' | 'music' | 'vibrate' | 'bell' | 'backpack' | 'fire' | 'binoculars' | 'sparkle' | 'quest' | 'spin';
+  /** Any Phosphor icon name (without the ph- prefix): overrides the preset glyph. */
+  name?: string;
+  /** Overrides the preset tone. */
+  tone?: 'gold' | 'coral' | 'blue' | 'teal' | 'green' | 'berry' | 'wood' | 'stone' | 'white' | 'ink';
+  /** Box size in px (glyph fills it). Default 28. */
+  size?: number;
+  /** Dark outline behind the fill. Default true. */
+  outline?: boolean;
+  /** Hard drop shadow. Default true. */
+  shadow?: boolean;
+  /** Phosphor weight. fill (default) for pictorial glyphs; bold for utility strokes (plus, x, check, carets). */
+  weight?: 'fill' | 'bold';
+  style?: React.CSSProperties;
+}
+
+export function GameIcon(props: GameIconProps): React.JSX.Element;

package/components/icons/GameIcon.jsx

@@ -0,0 +1,43 @@
+'use client';
+import React from 'react';
+
+// Phosphor FILL glyph with the painted game-icon treatment: solid fill, dark outline painted behind, 2px drop.
+const TONES = {
+  gold:  ['var(--gold-500)',  'var(--gold-900)'],
+  coral: ['var(--coral-500)', 'var(--coral-900)'],
+  blue:  ['var(--blue-500)',  'var(--blue-900)'],
+  teal:  ['var(--teal-500)',  'var(--teal-900)'],
+  green: ['var(--green-500)', 'var(--green-900)'],
+  berry: ['var(--berry-500)', 'var(--berry-900)'],
+  wood:  ['var(--wood-500)',  'var(--wood-900)'],
+  stone: ['var(--stone-300)', 'var(--stone-700)'],
+  white: ['#fff',             'var(--ink-900)'],
+  ink:   ['var(--ink-900)',   'var(--ink-900)'],
+};
+// Semantic presets: glyph + tone
+const KINDS = {
+  coin: ['coin', 'gold'], coins: ['coins', 'gold'], gem: ['sketch-logo', 'blue'], ruby: ['sketch-logo', 'coral'],
+  heart: ['heart', 'coral'], star: ['star', 'gold'], energy: ['lightning', 'teal'], key: ['key', 'gold'],
+  gift: ['gift', 'berry'], chest: ['treasure-chest', 'wood'], trophy: ['trophy', 'gold'], crown: ['crown', 'gold'],
+  lock: ['lock', 'stone'], clock: ['clock', 'white'], ticket: ['ticket', 'coral'], egg: ['egg', 'white'],
+  map: ['map-trifold', 'wood'], compass: ['compass', 'blue'], flag: ['flag', 'coral'], leaf: ['leaf', 'green'],
+  tent: ['tent', 'coral'], boat: ['boat', 'blue'], mountains: ['mountains', 'stone'], footprints: ['footprints', 'wood'],
+  play: ['play', 'white'], check: ['check', 'white', 'bold'], x: ['x', 'white', 'bold'], plus: ['plus', 'white', 'bold'], gear: ['gear', 'white'],
+  shop: ['storefront', 'coral'], trash: ['trash', 'stone'], sound: ['speaker-high', 'blue'], music: ['music-notes', 'blue'],
+  vibrate: ['vibrate', 'blue'], bell: ['bell', 'gold'], backpack: ['backpack', 'wood'], fire: ['fire', 'coral'],
+  binoculars: ['binoculars', 'wood'], sparkle: ['sparkle', 'gold'], quest: ['clipboard-text', 'coral'], spin: ['circle-half-tilt', 'berry'],
+};
+
+export function GameIcon({ kind, name, tone, size = 28, outline = true, shadow = true, weight, style, ...rest }) {
+  const preset = KINDS[kind] || KINDS.coin;
+  const glyph = name || preset[0];
+  const w = weight || (name ? 'fill' : preset[2] || 'fill');
+  const [fill, stroke] = TONES[tone || preset[1]] || TONES.gold;
+  return (
+    <span aria-hidden="true" style={{ display: 'inline-grid', placeItems: 'center', width: size, height: size, flex: 'none', lineHeight: 1,
+      filter: shadow ? 'drop-shadow(0 ' + Math.max(1, Math.round(size * 0.07)) + 'px 0 oklch(0 0 0 / 0.25))' : 'none', ...style }} {...rest}>
+      <i className={'ph-' + w + ' ph-' + glyph} style={{ fontSize: size, lineHeight: 1, color: fill, display: 'block',
+        WebkitTextStroke: outline ? Math.max(1.5, size * 0.11) + 'px ' + stroke : '0', paintOrder: 'stroke fill' }} />
+    </span>
+  );
+}

package/components/icons/GameIcon.prompt.md

@@ -0,0 +1,13 @@
+Painted game glyph (Phosphor FILL + outline + drop) for any icon that stands on its own: on the world, on a panel, on a medal or a prize. Never emoji, and never the sticker look rebuilt in CSS.
+
+```jsx
+<GameIcon kind="coin" size={32} />
+<GameIcon kind="gem" />
+<GameIcon kind="heart" size={20} />
+<GameIcon name="anchor" tone="blue" size={40} />
+<GameIcon kind="gear" outline={false} shadow={false} size={22} />   // plain white glyph inside a button
+```
+
+- Prefer a semantic kind (coin, gem, heart, star, energy, gift, lock…) so tones stay consistent across screens.
+- Inside a component's icon slot (`Button`, `IconButton`, `Tag`, a level node), pass plain Phosphor (`<i className="ph-fill ph-star" />`) or a GameIcon with outline and shadow off. The component already carries the depth.
+- Currency glyphs are always gold coin, blue gem, coral ruby/heart, teal energy.