lanre-ds 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Apata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/components/buttons/Button.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+/**
+ * Chunky bevelled game button. Solid darker bottom edge, top highlight, presses down 4px.
+ * @startingPoint section="Buttons" subtitle="Bevelled CTA in 8 tones and 3 sizes" viewport="700x260"
+ */
+export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'style'> {
+  /** Tone. primary = gold (default CTA), play = sky blue, confirm = teal OK, danger = coral, premium = berry, wood = brown frame, ghost = cream, locked = stone. */
+  variant?: 'primary' | 'play' | 'confirm' | 'danger' | 'premium' | 'wood' | 'ghost' | 'locked';
+  /** sm 36px / md 48px / lg 60px tall. */
+  size?: 'sm' | 'md' | 'lg';
+  /** display = Titan One uppercase (default); ui = Quicksand bold sentence case for longer labels. */
+  typeface?: 'display' | 'ui';
+  /** Leading icon node (e.g. <GameIcon name="play" size={20} />). */
+  icon?: React.ReactNode;
+  /** Trailing node (e.g. a price or a CurrencyPill). */
+  trailing?: React.ReactNode;
+  children?: React.ReactNode;
+  disabled?: boolean;
+  /** Stretch to container width. */
+  block?: boolean;
+  /** Fully rounded ends. */
+  pill?: boolean;
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  style?: React.CSSProperties;
+}
+
+export function Button(props: ButtonProps): React.JSX.Element;

package/components/buttons/Button.jsx

@@ -0,0 +1,50 @@
+'use client';
+import React, { useState } from 'react';
+
+const TONES = {
+  primary: ['var(--gold-300)', 'var(--gold-500)', 'var(--gold-700)', 'var(--gold-900)'],
+  play:    ['var(--blue-300)', 'var(--blue-500)', 'var(--blue-700)', '#fff'],
+  confirm: ['var(--teal-300)', 'var(--teal-500)', 'var(--teal-700)', '#fff'],
+  danger:  ['var(--coral-300)', 'var(--coral-500)', 'var(--coral-700)', '#fff'],
+  premium: ['var(--berry-300)', 'var(--berry-500)', 'var(--berry-700)', '#fff'],
+  wood:    ['var(--wood-300)', 'var(--wood-500)', 'var(--wood-700)', '#fff'],
+  ghost:   ['#fff', 'var(--cream-100)', 'var(--cream-300)', 'var(--ink-900)'],
+  locked:  ['var(--stone-300)', 'var(--stone-500)', 'var(--stone-700)', '#fff'],
+};
+// [height, padding-x, font-size, bevel depth]
+const SIZES = { sm: [36, 14, 14, 3], md: [48, 22, 18, 5], lg: [60, 30, 24, 7] };
+
+export function Button({ variant = 'primary', size = 'md', typeface = 'display', icon, trailing, children, disabled = false, block = false, pill = false, onClick, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const [hover, setHover] = useState(false);
+  const [top, mid, shade, text] = TONES[disabled ? 'locked' : variant] || TONES.primary;
+  const [h, px, fs, depth] = SIZES[size] || SIZES.md;
+  const lift = down && !disabled ? 1 : depth;
+  const display = typeface === 'display';
+  return (
+    <button type="button" disabled={disabled} onClick={onClick}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerCancel={() => setDown(false)}
+      onPointerEnter={() => setHover(true)} onPointerLeave={() => { setDown(false); setHover(false); }}
+      style={{
+        appearance: 'none', border: 0, margin: 0, cursor: disabled ? 'default' : 'pointer',
+        display: block ? 'flex' : 'inline-flex', width: block ? '100%' : undefined, boxSizing: 'border-box',
+        alignItems: 'center', justifyContent: 'center', gap: 'var(--space-2)',
+        height: h, minWidth: h, padding: '0 ' + px + 'px',
+        borderRadius: pill ? 'var(--radius-pill)' : 'var(--radius-md)',
+        background: 'linear-gradient(180deg, ' + top + ' 0%, ' + mid + ' 42%, ' + mid + ' 100%)',
+        boxShadow: '0 ' + lift + 'px 0 ' + shade + ', 0 ' + (lift + 6) + 'px 14px oklch(0.2 0.04 60 / 0.25), inset 0 2px 0 oklch(1 0 0 / 0.45)',
+        transform: 'translateY(' + (depth - lift) + 'px)',
+        filter: hover && !disabled && !down ? 'brightness(1.06)' : 'none',
+        transition: 'transform var(--dur-fast) var(--ease-out), box-shadow var(--dur-fast) var(--ease-out), filter var(--dur-fast)',
+        fontFamily: display ? 'var(--font-display)' : 'var(--font-ui)',
+        fontWeight: display ? 400 : 700,
+        fontSize: display ? fs : fs - 1, lineHeight: 1, letterSpacing: display ? '0.02em' : 0,
+        textTransform: display ? 'uppercase' : 'none',
+        color: text, textShadow: text === '#fff' ? '0 2px 0 ' + shade : 'none',
+        opacity: disabled ? 0.85 : 1, userSelect: 'none', WebkitTapHighlightColor: 'transparent', whiteSpace: 'nowrap',
+        ...style,
+      }} {...rest}>
+      {icon}{children}{trailing}
+    </button>
+  );
+}

package/components/buttons/Button.prompt.md

@@ -0,0 +1,16 @@
+Chunky bevelled game button: use for every tappable action (CTA, OK, Claim, Play, Buy); never a flat or outlined button.
+
+```jsx
+<Button variant="primary" size="lg" block>Claim</Button>
+<Button variant="play" icon={<GameIcon name="play" size={20} />}>Level 22</Button>
+<Button variant="confirm">OK</Button>
+<Button variant="danger" size="sm">Cancel</Button>
+<Button variant="premium" trailing={<span>USD 3.99</span>} typeface="ui">3,000 coins</Button>
+<Button variant="wood" pill>Shop</Button>
+<Button disabled>Locked</Button>
+```
+
+- Variants: primary (gold, dark text: the default CTA), play (blue), confirm (teal), danger (coral), premium (berry), wood, ghost (cream), locked (stone).
+- Sizes: sm 36 / md 48 / lg 60. One lg button per screen (the main action); md for panel actions; sm inside rows.
+- Labels are 1–2 words, Title Case in source; display typeface renders them uppercase.
+- Pressed state is built in (travels down, bevel collapses). Do not add your own hover styles.

package/components/buttons/IconButton.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+/**
+ * Round (or rounded-square) bevelled button holding a single glyph; optional notification badge and outlined caption.
+ * @startingPoint section="Buttons" subtitle="Round glyph button with badge + caption" viewport="700x260"
+ */
+export interface IconButtonProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style'> {
+  variant?: 'primary' | 'play' | 'confirm' | 'danger' | 'premium' | 'wood' | 'ghost' | 'locked';
+  /** sm 36px / md 48px / lg 60px. */
+  size?: 'sm' | 'md' | 'lg';
+  shape?: 'circle' | 'square';
+  /** true renders a red "!" dot; a number/string renders a count. */
+  badge?: boolean | number | string;
+  /** Outlined uppercase caption under the button (e.g. SHOP, QUESTS). Also used as aria-label. */
+  label?: string;
+  /** The glyph, e.g. <i className="ph-fill ph-gear" /> or <GameIcon name="gift" />. */
+  children?: React.ReactNode;
+  disabled?: boolean;
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  style?: React.CSSProperties;
+}
+
+export function IconButton(props: IconButtonProps): React.JSX.Element;

package/components/buttons/IconButton.jsx

@@ -0,0 +1,53 @@
+'use client';
+import React, { useState } from 'react';
+
+const TONES = {
+  primary: ['var(--gold-300)', 'var(--gold-500)', 'var(--gold-700)', 'var(--gold-900)'],
+  play:    ['var(--blue-300)', 'var(--blue-500)', 'var(--blue-700)', '#fff'],
+  confirm: ['var(--teal-300)', 'var(--teal-500)', 'var(--teal-700)', '#fff'],
+  danger:  ['var(--coral-300)', 'var(--coral-500)', 'var(--coral-700)', '#fff'],
+  premium: ['var(--berry-300)', 'var(--berry-500)', 'var(--berry-700)', '#fff'],
+  wood:    ['var(--wood-300)', 'var(--wood-500)', 'var(--wood-700)', '#fff'],
+  ghost:   ['#fff', 'var(--cream-100)', 'var(--cream-300)', 'var(--ink-900)'],
+  locked:  ['var(--stone-300)', 'var(--stone-500)', 'var(--stone-700)', '#fff'],
+};
+// [diameter, bevel depth, icon font-size]
+const SIZES = { sm: [36, 3, 18], md: [48, 5, 24], lg: [60, 7, 30] };
+
+export function IconButton({ variant = 'play', size = 'md', shape = 'circle', badge, label, children, disabled = false, onClick, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const [top, mid, shade, text] = TONES[disabled ? 'locked' : variant] || TONES.play;
+  const [d, depth, fs] = SIZES[size] || SIZES.md;
+  const lift = down && !disabled ? 1 : depth;
+  const btn = (
+    <button type="button" disabled={disabled} onClick={onClick} aria-label={label}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerCancel={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{
+        appearance: 'none', border: 0, margin: 0, padding: 0, cursor: disabled ? 'default' : 'pointer', position: 'relative',
+        display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: d, height: d, flex: 'none',
+        borderRadius: shape === 'circle' ? '50%' : 'var(--radius-md)',
+        background: 'linear-gradient(180deg, ' + top + ' 0%, ' + mid + ' 45%)',
+        boxShadow: '0 ' + lift + 'px 0 ' + shade + ', 0 ' + (lift + 5) + 'px 12px oklch(0.2 0.04 60 / 0.25), inset 0 2px 0 oklch(1 0 0 / 0.45)',
+        transform: 'translateY(' + (depth - lift) + 'px)',
+        transition: 'transform var(--dur-fast) var(--ease-out), box-shadow var(--dur-fast) var(--ease-out)',
+        color: text, fontSize: fs, lineHeight: 1, textShadow: text === '#fff' ? '0 2px 0 ' + shade : 'none',
+        opacity: disabled ? 0.85 : 1, userSelect: 'none', WebkitTapHighlightColor: 'transparent',
+        ...(label ? {} : style),
+      }} {...(label ? {} : rest)}>
+      {children}
+      {badge != null && badge !== false && (
+        <span style={{ position: 'absolute', top: -6, right: -6, minWidth: 22, height: 22, padding: '0 6px', boxSizing: 'border-box', borderRadius: 'var(--radius-pill)',
+          background: 'linear-gradient(180deg, var(--coral-300), var(--coral-500) 50%)', boxShadow: '0 2px 0 var(--coral-700), 0 3px 6px oklch(0 0 0 / 0.25)', border: '2px solid #fff',
+          color: '#fff', fontFamily: 'var(--font-display)', fontSize: 12, lineHeight: '18px', textAlign: 'center' }}>{badge === true ? '!' : badge}</span>
+      )}
+    </button>
+  );
+  if (!label) return btn;
+  return (
+    <div style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: 6, ...style }} {...rest}>
+      {btn}
+      <span style={{ fontFamily: 'var(--font-display)', fontSize: 13, letterSpacing: '0.04em', textTransform: 'uppercase', color: '#fff',
+        WebkitTextStroke: '0.2em var(--ink-900)', paintOrder: 'stroke fill', textShadow: '0 2px 0 oklch(0 0 0 / 0.25)' }}>{label}</span>
+    </div>
+  );
+}

package/components/buttons/IconButton.prompt.md

@@ -0,0 +1,12 @@
+Round bevelled glyph button: for close (×), settings, plus (+), and the captioned side-rail actions (SPIN / SHOP / QUESTS).
+
+```jsx
+<IconButton variant="danger" size="sm"><i className="ph-fill ph-x" /></IconButton>
+<IconButton variant="ghost"><i className="ph-fill ph-gear" /></IconButton>
+<IconButton variant="primary" shape="square" label="Shop" badge><i className="ph-fill ph-storefront" /></IconButton>
+<IconButton variant="play" label="Quests" badge={3}><i className="ph-fill ph-clipboard-text" /></IconButton>
+```
+
+- Close buttons sit on the panel's top-right corner, overlapping the edge: variant="danger" or "play", size="sm".
+- Captioned buttons (label) stack the outlined caption below; use in vertical side rails and bottom bars.
+- badge renders the red notification dot (true → "!", number → count).

package/components/buttons/SegmentedTabs.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+/**
+ * A pill-shaped tab switch for two or three views of the same list, such as People and Keepsakes. The chosen tab lifts onto a white pill.
+ * @startingPoint section="Buttons" subtitle="Pill tab switch" viewport="700x140"
+ */
+export interface SegmentedTab {
+  id: string;
+  label: React.ReactNode;
+}
+
+export interface SegmentedTabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  items: SegmentedTab[];
+  /** The id of the tab that is on. */
+  value: string;
+  onChange?: (id: string) => void;
+  /** Accessible name for the group, such as "Collection". */
+  label?: string;
+}
+
+export function SegmentedTabs(props: SegmentedTabsProps): React.JSX.Element;

package/components/buttons/SegmentedTabs.jsx

@@ -0,0 +1,15 @@
+'use client';
+import React from 'react';
+
+/* A pill-shaped tab switch for two or three views of the same thing. items are { id, label }; the one whose id equals value is on. */
+export function SegmentedTabs({ items = [], value, onChange, label, className, ...rest }) {
+  return (
+    <div className={['mp-seg', className].filter(Boolean).join(' ')} role="tablist" aria-label={label} {...rest}>
+      {items.map(it => (
+        <button key={it.id} type="button" role="tab" aria-selected={value === it.id} className={'mp-seg-tab' + (value === it.id ? ' mp-seg-on' : '')} onClick={() => onChange && onChange(it.id)}>
+          {it.label}
+        </button>
+      ))}
+    </div>
+  );
+}

package/components/buttons/SegmentedTabs.prompt.md

@@ -0,0 +1,10 @@
+Segmented tabs: switch between two or three views in place.
+
+```jsx
+<SegmentedTabs label="Collection" value={tab} onChange={setTab}
+  items={[{ id: 'people', label: 'People · 3 of 8' }, { id: 'keepsakes', label: 'Keepsakes · 2' }]} />
+```
+
+- Controlled: keep the chosen id in state and render the matching view yourself.
+- Keep labels short. The group is as wide as its tabs and never wider than its container.
+- For moving between steps of a flow, use `StepBar`; this is for views of one thing.

package/components/contributor/AudioRecorder.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { RecorderPanelProps } from './RecorderPanel';
+
+/** What onDone receives: the take, ready to upload. */
+export interface RecordedAudio {
+  blob: Blob;
+  kind: 'audio';
+  /** The format that was recorded, such as "audio/mp4" or "audio/webm". */
+  mimeType: string;
+  /** "voice-note.m4a", ".ogg" or ".webm", to match the format. */
+  filename: string;
+  durationSeconds: number;
+}
+
+/**
+ * A voice-note recorder: record, listen back, then use or discard. It asks for the microphone when Record is pressed, stops by itself at the limit, and keeps the take in the browser until Use this.
+ * @startingPoint section="Contributor" subtitle="Working voice-note recorder" viewport="700x300"
+ */
+export interface AudioRecorderProps extends Omit<RecorderPanelProps, 'phase' | 'supported' | 'seconds' | 'url' | 'error' | 'onRecord' | 'onStop' | 'onRedo' | 'onUse'> {
+  /** Called with the take when Use this is pressed. */
+  onDone?: (audio: RecordedAudio) => void;
+  onCancel?: () => void;
+  /** The longest take, in seconds. Default 600. */
+  maxSeconds?: number;
+}
+
+export function AudioRecorder(props: AudioRecorderProps): React.JSX.Element;

package/components/contributor/AudioRecorder.jsx

@@ -0,0 +1,79 @@
+'use client';
+import React, { useEffect, useRef, useState } from 'react';
+import { RecorderPanel } from './RecorderPanel';
+
+const MIME_TYPES = ['audio/mp4', 'audio/webm;codecs=opus', 'audio/webm', 'audio/ogg;codecs=opus'];
+
+function pickMimeType() {
+  if (typeof MediaRecorder === 'undefined') return undefined;
+  return MIME_TYPES.find(t => MediaRecorder.isTypeSupported(t));
+}
+
+const baseMimeType = mime => mime.split(';')[0].trim().toLowerCase();
+
+/* A voice-note recorder: record, listen back, then use or discard. Nothing leaves the browser until onDone is called with the take.
+   onDone gets { blob, kind: 'audio', mimeType, filename, durationSeconds }. It asks for the microphone when Record is pressed. */
+export function AudioRecorder({ onDone, onCancel, prompt, maxSeconds = 10 * 60, ...rest }) {
+  const [phase, setPhase] = useState('idle');
+  const [seconds, setSeconds] = useState(0);
+  const [error, setError] = useState(null);
+  const [result, setResult] = useState(null);
+  const recorder = useRef(null);
+  const stream = useRef(null);
+  const chunks = useRef([]);
+  const tick = useRef(null);
+
+  const supported = typeof window !== 'undefined' && typeof MediaRecorder !== 'undefined' && !!(navigator.mediaDevices && navigator.mediaDevices.getUserMedia);
+
+  useEffect(() => () => {
+    if (tick.current) clearInterval(tick.current);
+    if (stream.current) stream.current.getTracks().forEach(t => t.stop());
+  }, []);
+
+  useEffect(() => () => { if (result) URL.revokeObjectURL(result.url); }, [result]);
+
+  useEffect(() => { if (phase === 'recording' && seconds >= maxSeconds) stop(); }, [phase, seconds, maxSeconds]);
+
+  async function start() {
+    setError(null);
+    try {
+      stream.current = await navigator.mediaDevices.getUserMedia({ audio: true });
+    } catch {
+      setError('Microphone access was blocked. Allow it in your browser settings, or upload an audio file instead.');
+      return;
+    }
+    const mimeType = pickMimeType();
+    const rec = new MediaRecorder(stream.current, mimeType ? { mimeType } : undefined);
+    chunks.current = [];
+    rec.ondataavailable = e => { if (e.data.size) chunks.current.push(e.data); };
+    rec.onstop = () => {
+      if (stream.current) stream.current.getTracks().forEach(t => t.stop());
+      const mime = baseMimeType(rec.mimeType || mimeType || 'audio/webm');
+      const blob = new Blob(chunks.current, { type: mime });
+      setResult({ blob, url: URL.createObjectURL(blob), mime });
+      setPhase('review');
+    };
+    recorder.current = rec;
+    rec.start(1000);
+    setSeconds(0);
+    setPhase('recording');
+    tick.current = setInterval(() => setSeconds(n => n + 1), 1000);
+  }
+
+  function stop() {
+    if (tick.current) clearInterval(tick.current);
+    tick.current = null;
+    if (recorder.current && recorder.current.state === 'recording') recorder.current.stop();
+  }
+
+  function use() {
+    if (!result) return;
+    const ext = result.mime.includes('mp4') ? 'm4a' : result.mime.includes('ogg') ? 'ogg' : 'webm';
+    onDone && onDone({ blob: result.blob, kind: 'audio', mimeType: result.mime, filename: 'voice-note.' + ext, durationSeconds: seconds });
+  }
+
+  return (
+    <RecorderPanel phase={phase} supported={supported} prompt={prompt} seconds={seconds} maxSeconds={maxSeconds} url={result && result.url} error={error}
+      onRecord={start} onStop={stop} onRedo={() => { setResult(null); setPhase('idle'); }} onUse={use} onCancel={onCancel} {...rest} />
+  );
+}

package/components/contributor/AudioRecorder.prompt.md

@@ -0,0 +1,13 @@
+Audio recorder: record a voice note in the browser, listen back, then use or discard it.
+
+```jsx
+<AudioRecorder
+  prompt="Record a voice note. It will be played as it is."
+  onDone={file => addBlock(file)}
+  onCancel={() => setRecording(false)} />
+```
+
+- Nothing is uploaded here. `onDone` hands back the take (`blob`, `mimeType`, `filename`, `durationSeconds`) and the app decides what to do with it.
+- The microphone is only asked for when Record is pressed. If it's blocked, the panel says so and points to uploading a file instead.
+- It picks the best format the browser can record (m4a, then webm, then ogg) and stops by itself at `maxSeconds`.
+- Tell people in `prompt` anything they should know before recording, such as that their voice may be recognised.

package/components/contributor/RadioCard.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+
+/**
+ * Tall, card-sized radio option: media on top, then a title and a short description, with the radio in the top-right corner. Teal with a glow when chosen.
+ * @startingPoint section="Contributor" subtitle="Radio cards for an honest either/or" viewport="700x300"
+ */
+export interface RadioCardProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'style' | 'onChange' | 'title'> {
+  checked?: boolean;
+  onChange?: (checked: true) => void;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  /** Shown above the title, usually a 72px Avatar. */
+  media?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+
+export function RadioCard(props: RadioCardProps): React.JSX.Element;

package/components/contributor/RadioCard.jsx

@@ -0,0 +1,30 @@
+'use client';
+import React, { useState } from 'react';
+
+const DROP = '0 14px 24px oklch(0.22 0.05 60 / 0.3)';
+const GLOW = '0 0 0 4px oklch(0.76 0.13 180 / 0.5), 0 0 28px oklch(0.76 0.13 180 / 0.6)';
+
+export function RadioCard({ checked = false, onChange, onClick, onPointerDown, onPointerUp, onPointerCancel, onPointerLeave, title, description, media, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  // Your own handlers run alongside the card's, so passing one never breaks choosing or the press.
+  const press = (on, yours) => e => { setDown(on); if (yours) yours(e); };
+  return (
+    <button type="button" role="radio" aria-checked={checked} onClick={e => { if (onClick) onClick(e); if (onChange) onChange(true); }}
+      onPointerDown={press(true, onPointerDown)} onPointerUp={press(false, onPointerUp)} onPointerCancel={press(false, onPointerCancel)} onPointerLeave={press(false, onPointerLeave)}
+      style={{ appearance: 'none', position: 'relative', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 10, padding: '22px 12px 16px', boxSizing: 'border-box',
+        borderRadius: 'var(--radius-lg)', border: '4px solid ' + (checked ? 'var(--teal-500)' : 'var(--cream-300)'),
+        background: checked ? 'linear-gradient(180deg, var(--teal-100), #fff)' : 'linear-gradient(180deg, #fff, var(--cream-100))',
+        boxShadow: checked ? '0 5px 0 var(--teal-700), ' + DROP + ', ' + GLOW : '0 5px 0 var(--cream-300), ' + DROP,
+        font: 'inherit', textAlign: 'center', cursor: 'pointer', WebkitTapHighlightColor: 'transparent',
+        transition: 'transform var(--dur-fast) var(--ease-out)', transform: down ? 'translateY(3px)' : undefined, ...style }} {...rest}>
+      <span aria-hidden="true" style={{ position: 'absolute', right: 10, top: 10, width: 28, height: 28, boxSizing: 'border-box', borderRadius: '50%',
+        border: '3px solid ' + (checked ? 'var(--teal-500)' : 'var(--stone-500)'), background: checked ? 'var(--teal-500)' : '#fff', boxShadow: 'inset 0 2px 3px oklch(0 0 0 / 0.1)',
+        display: 'grid', placeItems: 'center', color: '#fff', fontSize: 14, animation: checked ? 'mp-radio-pop var(--dur-base) var(--ease-bounce) both' : undefined }}>
+        {checked && <i className="ph-bold ph-check" />}
+      </span>
+      {media}
+      <strong style={{ fontSize: 16, lineHeight: 1.2, color: 'var(--ink-900)' }}>{title}</strong>
+      {description && <span style={{ fontSize: 13, lineHeight: 1.4, fontWeight: 600, color: 'var(--ink-700)' }}>{description}</span>}
+    </button>
+  );
+}

package/components/contributor/RadioCard.prompt.md

@@ -0,0 +1,12 @@
+Radio card: a tall card for an honest either/or. Put two side by side in a radiogroup with a visible question.
+
+```jsx
+<div role="radiogroup" aria-label="Does this memory show who you are?" style={{ display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: 'var(--space-3)' }}>
+  <RadioCard checked={!reveals} onChange={() => setReveals(false)} media={<Avatar mystery size={72} aria-hidden="true" />} title="Keeps me a mystery" description="No face, name or voice in here." />
+  <RadioCard checked={reveals} onChange={() => setReveals(true)} media={<Avatar name="Ada Okafor" size={72} alt="" aria-hidden="true" />} title="Shows who I am" description="Skip the guessing for this one." />
+</div>
+```
+
+- A chosen card turns teal with a glow, and its radio pops a tick. That's the system's "selected", so there's no tone to pick.
+- Keep each description to a sentence or two, and keep the two cards about the same length.
+- Never promise automatic anonymization. The contributor's honest answer decides mystery or direct reveal.

package/components/contributor/RecorderPanel.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+
+/**
+ * The card a voice recorder lives in, drawing one step at a time: a prompt and Record, a blinking dot with the time and Stop, or the take to play back with Redo and Use this. It only shows a state; AudioRecorder does the recording.
+ * @startingPoint section="Contributor" subtitle="Voice-recorder card: idle, recording, review" viewport="700x300"
+ */
+export interface RecorderPanelProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  phase?: 'idle' | 'recording' | 'review';
+  /** False when the browser can't record, which shows a note to upload a file instead. Default true. */
+  supported?: boolean;
+  /** The line above Record. Default "Record a voice note." */
+  prompt?: React.ReactNode;
+  /** Time recorded so far, in seconds. */
+  seconds?: number;
+  /** The limit shown beside the time, in seconds. Default 600. */
+  maxSeconds?: number;
+  /** The recorded take to play back in the review step. */
+  url?: string | null;
+  /** A problem to show under the step, such as a blocked microphone. */
+  error?: string | null;
+  onRecord?: () => void;
+  onStop?: () => void;
+  onRedo?: () => void;
+  onUse?: () => void;
+  onCancel?: () => void;
+}
+
+export function RecorderPanel(props: RecorderPanelProps): React.JSX.Element;
+/** 90 gives "1:30". Returns null for a missing or non-finite number. */
+export function formatDuration(seconds?: number | null): string | null;

package/components/contributor/RecorderPanel.jsx

@@ -0,0 +1,49 @@
+'use client';
+import React from 'react';
+import { Button } from '../buttons/Button';
+
+// 90 seconds is "1:30"
+export function formatDuration(seconds) {
+  if (seconds == null || !Number.isFinite(seconds)) return null;
+  const s = Math.round(seconds);
+  return Math.floor(s / 60) + ':' + String(s % 60).padStart(2, '0');
+}
+
+/* The card a voice recorder lives in. It only draws one step at a time: unsupported, idle (a prompt and Record), recording
+   (a blinking dot, the time and Stop) or review (the take to play back, Redo and Use this). The recording itself is
+   AudioRecorder's job; this panel is for showing a state or wiring your own recorder. */
+export function RecorderPanel({ phase = 'idle', supported = true, prompt = 'Record a voice note.', seconds = 0, maxSeconds = 600, url, error, onRecord, onStop, onRedo, onUse, onCancel, className, ...rest }) {
+  return (
+    <div className={['mp-recorder', className].filter(Boolean).join(' ')} {...rest}>
+      {!supported ? (
+        <p className="mp-recorder-lede">This browser can&apos;t record audio. Upload an audio file instead.</p>
+      ) : phase === 'idle' ? (
+        <>
+          <p className="mp-recorder-lede">{prompt}</p>
+          <Button size="lg" variant="danger" onClick={onRecord} icon={<i className="ph-fill ph-microphone" aria-hidden="true" />}>Record</Button>
+        </>
+      ) : phase === 'recording' ? (
+        <>
+          <div className="mp-recorder-row" role="status" aria-live="polite">
+            <span className="mp-rec-dot" aria-hidden="true" />
+            <strong style={{ fontSize: 22, fontVariantNumeric: 'tabular-nums' }}>{formatDuration(seconds)}</strong>
+            <span className="mp-recorder-small">/ {formatDuration(maxSeconds)}</span>
+          </div>
+          <Button size="lg" onClick={onStop} icon={<i className="ph-fill ph-stop" aria-hidden="true" />}>Stop</Button>
+        </>
+      ) : (
+        url && (
+          <>
+            <audio controls src={url} style={{ width: '100%' }} />
+            <div className="mp-recorder-row">
+              <Button variant="ghost" onClick={onRedo}>Redo</Button>
+              <Button onClick={onUse}>Use this</Button>
+            </div>
+          </>
+        )
+      )}
+      {error && <p className="mp-recorder-small" style={{ color: 'var(--coral-700)', fontWeight: 700 }}>{error}</p>}
+      {phase !== 'recording' && <button type="button" className="mp-link-button" onClick={onCancel}>Cancel</button>}
+    </div>
+  );
+}

package/components/contributor/RecorderPanel.prompt.md

@@ -0,0 +1,11 @@
+Recorder panel: the card a voice recorder lives in, drawing one step at a time.
+
+```jsx
+<RecorderPanel phase="idle" prompt="Record a voice note." onRecord={start} onCancel={close} />
+<RecorderPanel phase="recording" seconds={42} onStop={stop} />
+<RecorderPanel phase="review" url={takeUrl} onRedo={redo} onUse={use} onCancel={close} />
+```
+
+- It only draws a state. For a working recorder that asks for the microphone, use `AudioRecorder`, which is this panel plus the recording.
+- Cancel shows in the idle and review steps, but not while recording, so a take isn't thrown away by a stray tap.
+- Set `supported={false}` where the browser has no recorder, to point people to uploading a file instead.

package/components/contributor/StepBar.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+
+/**
+ * Contributor-flow progress: numbered step markers on a short stretch of road that fills green as steps finish. The current marker pulses, and a step forward celebrates.
+ * @startingPoint section="Contributor" subtitle="Flow steps, with and without labels" viewport="700x200"
+ */
+export interface StepBarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style'> {
+  /** Step names, in order. Without `labels` they're only read out to screen readers. */
+  steps: string[];
+  /** 0-based current step. */
+  current?: number;
+  /** Shows each step's name under its marker, on wider 68px slots. Without it, slots are 46px. */
+  labels?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function StepBar(props: StepBarProps): React.JSX.Element;

package/components/contributor/StepBar.jsx

@@ -0,0 +1,55 @@
+'use client';
+import React, { useEffect, useLayoutEffect, useState } from 'react';
+
+// Where each trail was last seen in this tab, so only a forward step celebrates.
+const seen = {};
+// Decided in the browser, before paint. A server can't know what this tab saw, and an object shared
+// by every request would leak one visitor's steps into someone else's page.
+const useBrowserEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+export function StepBar({ steps = [], current = 0, labels = false, style, ...rest }) {
+  const slot = labels ? 68 : 46;
+  const kind = steps.join('|');
+  const [advanced, setAdvanced] = useState(false);
+  // Once per mount: did they just finish the step before this one?
+  useBrowserEffect(() => {
+    const prev = seen[kind];
+    if (prev !== undefined && current === prev + 1) setAdvanced(true);
+  }, []);
+  // Remember every step it shows, not only the first, so a bar that moved while mounted isn't misread later.
+  useBrowserEffect(() => { seen[kind] = current; }, [kind, current]);
+  const n = steps.length;
+  const filled = Math.max(0, Math.min(current, n - 1)); // all done fills the road, never past its end
+  return (
+    <nav aria-label="Progress" style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', paddingTop: 6, boxSizing: 'border-box', ...style }} {...rest}>
+      <div style={{ position: 'relative' }}>
+        <span aria-hidden="true" style={{ position: 'absolute', top: 12, left: slot / 2, right: slot / 2, height: 12, borderRadius: 999,
+          background: 'var(--world-path)', boxShadow: '0 0 0 3px var(--world-path-edge), 0 4px 0 3px oklch(0.25 0.05 60 / 0.2)' }} />
+        <span aria-hidden="true" style={{ position: 'absolute', top: 16, left: slot / 2, width: slot * filled, height: 4, borderRadius: 999,
+          background: 'var(--green-500)', transition: 'width var(--dur-slow) var(--ease-out)',
+          ...(advanced ? { '--from': slot * Math.min(current - 1, filled) + 'px', '--to': slot * filled + 'px', animation: 'mp-trail-grow var(--dur-slow) var(--ease-out) 260ms both' } : null) }} />
+        <ol style={{ position: 'relative', listStyle: 'none', margin: 0, padding: 0, display: 'flex' }}>
+          {steps.map((label, i) => {
+            const done = i < current, cur = i === current, justDone = advanced && i === current - 1;
+            return (
+              <li key={i} aria-current={cur ? 'step' : undefined} style={{ width: slot, display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6 }}>
+                <span aria-hidden="true" className={'mp-step' + (done ? ' mp-step-done' : cur ? ' mp-step-current' : '')}
+                  style={justDone ? { animation: 'mp-pop var(--dur-slow) var(--ease-bounce) 560ms both' } : undefined}>
+                  {done ? <i className="ph-bold ph-check" /> : i + 1}
+                  {cur && <span style={{ position: 'absolute', inset: -4, borderRadius: '50%', animation: 'mp-pulse-ring 1.6s ease-out infinite' }} />}
+                </span>
+                {labels ? (
+                  <span style={{ fontFamily: 'var(--font-display)', letterSpacing: '0.04em', textTransform: 'uppercase', color: '#fff', WebkitTextStroke: '0.22em var(--world-stroke)', paintOrder: 'stroke fill', whiteSpace: 'nowrap', fontSize: 11 }}>
+                    {label}{done && <span className="mp-sr">, done</span>}
+                  </span>
+                ) : (
+                  <span className="mp-sr">{'Step ' + (i + 1) + ' of ' + n + ': ' + label}{done && <span className="mp-sr">, done</span>}</span>
+                )}
+              </li>
+            );
+          })}
+        </ol>
+      </div>
+    </nav>
+  );
+}