lanre-ds 0.0.0-stage → 0.2.0

package/components/media/Unavailable.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+/**
+ * The card that stands in when a photo, video or voice note didn't load, with a Try again button.
+ * @startingPoint section="Media" subtitle="When media didn't load" viewport="700x140"
+ */
+export interface UnavailableProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** What failed, in a word or two: "photo", "video", "voice note", "set of photos". Reads "This photo didn't load." */
+  what?: string;
+  onRetry?: () => void;
+}
+
+export function Unavailable(props: UnavailableProps): React.JSX.Element;

package/components/media/Unavailable.jsx

@@ -0,0 +1,13 @@
+'use client';
+import React from 'react';
+import { Button } from '../buttons/Button';
+
+export function Unavailable({ what = 'photo', onRetry, ...rest }) {
+  return (
+    <div className="mp-unavailable" {...rest}>
+      <i className="ph-fill ph-cloud-warning" aria-hidden="true" />
+      <span>This {what} didn&apos;t load.</span>
+      <Button variant="ghost" size="sm" onClick={onRetry}>Try again</Button>
+    </div>
+  );
+}

package/components/media/Unavailable.prompt.md

@@ -0,0 +1,10 @@
+Unavailable card: what shows when a photo, video or voice note didn't load. The media components use it on their own when they have no source, and you can use it anywhere media can fail.
+
+```jsx
+<Unavailable what="photo" onRetry={refresh} />
+<Unavailable what="set of photos" onRetry={refresh} />
+```
+
+- Say what failed in a word or two. It reads "This photo didn't load." with a Try again button.
+- `onRetry` is where you fetch a fresh link. Links to private media often expire.
+- It's a flat cream card, not an error. Nothing here has gone wrong for the player, so keep the wording calm.

package/components/media/Words.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+/** Messages shorter than this sit big in the middle and type themselves in. Longer ones read like a letter. */
+export const SHORT_CHARS: number;
+
+/**
+ * A written memory, filling its box. A few words sit big in the middle and type themselves in once. Longer text lays out as paragraphs that scroll, with a "Scroll to keep reading" hint.
+ * @startingPoint section="Media" subtitle="A written memory in a screen" viewport="700x420"
+ */
+export interface WordsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** The text. A blank line starts a new paragraph. */
+  text: string;
+  /** True once it has typed in, so it doesn't type again. Short messages only. */
+  typed?: boolean;
+  /** Called when the last character is in, or straight away for long text. */
+  onTyped?: () => void;
+  /** Accessible name for the scrolling text. Default "Message". */
+  label?: string;
+}
+
+export function Words(props: WordsProps): React.JSX.Element;

package/components/media/Words.jsx

@@ -0,0 +1,57 @@
+'use client';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { reduceMotion } from './shared.js';
+
+/* A few words sit big in the middle of the box; anything longer reads like a letter. */
+export const SHORT_CHARS = 180;
+
+export function Words({ text = '', typed = false, onTyped, label = 'Message', ...rest }) {
+  const clean = text.trim();
+  const short = clean.length < SHORT_CHARS;
+  const [shown, setShown] = useState(() => (short && !typed && !reduceMotion() ? 0 : clean.length));
+  const [more, setMore] = useState(false);
+  const box = useRef(null);
+  const done = useRef(onTyped);
+  useEffect(() => { done.current = onTyped; });
+
+  // Short messages type themselves in, once. The rest of the text is already laid out, so nothing jumps.
+  useEffect(() => {
+    if (shown >= clean.length) { if (done.current) done.current(); return; }
+    const id = window.setTimeout(() => setShown(n => Math.min(clean.length, n + 2)), 28);
+    return () => window.clearTimeout(id);
+  }, [shown, clean.length]);
+
+  const measure = useCallback(() => {
+    const el = box.current;
+    if (el) setMore(el.scrollHeight - el.scrollTop - el.clientHeight > 24);
+  }, []);
+  useEffect(() => {
+    const id = window.requestAnimationFrame(measure);
+    window.addEventListener('resize', measure);
+    return () => { window.cancelAnimationFrame(id); window.removeEventListener('resize', measure); };
+  }, [measure]);
+
+  const paragraphs = clean.split(/\n{2,}/).map(p => p.trim()).filter(Boolean);
+  return (
+    <>
+      <div ref={box} className={'mp-words' + (short ? ' mp-words-short' : '')} onScroll={measure} tabIndex={0} role="group" aria-label={label} {...rest}>
+        <div className="mp-words-inner">
+          {short ? (
+            <p>
+              <span>{clean.slice(0, shown)}</span>
+              {shown < clean.length && (
+                <>
+                  <span className="mp-words-cursor" aria-hidden="true" />
+                  <span className="mp-words-unwritten">{clean.slice(shown)}</span>
+                </>
+              )}
+            </p>
+          ) : (
+            paragraphs.map((p, i) => <p key={i}>{p}</p>)
+          )}
+        </div>
+      </div>
+      {more && <div className="mp-words-more" aria-hidden="true">Scroll to keep reading</div>}
+    </>
+  );
+}

package/components/media/Words.prompt.md

@@ -0,0 +1,12 @@
+Words: a written memory filling its box. Put it in a box with a height, such as a screen or a sheet.
+
+```jsx
+<div style={{ position: 'relative', height: 480 }}>
+  <Words text={memory.text} typed={seen} onTyped={() => setSeen(true)} label="Their message" />
+</div>
+```
+
+- Under 180 characters it sits big in the middle and types itself in, once. Pass `typed` once it has, so coming back to it doesn't type again. With reduced motion it's already there.
+- Anything longer lays out as paragraphs at a reading size, and scrolls. A "Scroll to keep reading" hint shows until you reach the end. A blank line in `text` starts a new paragraph.
+- The box is focusable, so keyboard users can scroll it. Give it a `label` that names the message neutrally, never the sender.
+- For a written letter on a parchment card, use `MemoryText`.

package/components/media/shared.js

@@ -0,0 +1,19 @@
+'use client';
+import { useCallback, useState } from 'react';
+
+/* Helpers shared by the media components. */
+
+export const reduceMotion = () => typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+export const clock = s => Math.floor(s / 60) + ':' + String(Math.floor(s % 60)).padStart(2, '0');
+// Browser recordings (webm) often report an Infinity duration until played through; treat that as unknown.
+export const finite = d => (Number.isFinite(d) && d > 0 ? d : 0);
+
+/* Whether a photo or video has arrived, for a skeleton while it is on its way. Keyed by the URL, so a fresh link
+   (or the next photo) starts loading again. A photo already in the cache counts as arrived straight away. */
+export function useLoaded(src) {
+  const [arrived, setArrived] = useState(null);
+  const loaded = !!src && arrived === src;
+  const done = useCallback(() => setArrived(src ?? null), [src]);
+  const checkImage = useCallback(el => { if (el && el.complete && el.naturalWidth > 0) setArrived(src ?? null); }, [src]);
+  return { loaded, done, checkImage };
+}

package/components/panels/Modal.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+/**
+ * Modal shell: puts a Panel over the scrim, closes on Escape, locks page scroll, keeps keyboard focus inside and hands it back on close, and leaves with a short fade.
+ * @startingPoint section="Panels" subtitle="Modal shell for panels over the scrim" viewport="700x420"
+ */
+export interface ModalProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'children'> {
+  /** Accessible name for the dialog, usually the panel title. */
+  label: string;
+  /** Called once the exit fade has finished. Unmount the modal here. */
+  onClose: () => void;
+  /** dim = the scrim over the world, blurred by --scrim-blur (default), dusk = the evening ground, world = the ground of `world`. */
+  tone?: 'dim' | 'dusk' | 'world';
+  /** World id for data-world, so the panel and a world tone pick up that world's colours. */
+  world?: 'mango_grove' | 'small_chops' | 'good_energy' | 'japan' | 'summit';
+  /** Close when the scrim around the panel is tapped. Default false. */
+  closeOnScrim?: boolean;
+  /** Stacking order. Default 45. */
+  zIndex?: number;
+  /** The panel. Pass a function to get `close`, which plays the exit fade before calling onClose. */
+  children?: React.ReactNode | ((close: () => void) => React.ReactNode);
+  style?: React.CSSProperties;
+}
+
+export function Modal(props: ModalProps): React.JSX.Element;

package/components/panels/Modal.jsx

@@ -0,0 +1,68 @@
+'use client';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+const GROUND = { dim: 'var(--bg-scrim)', dusk: 'var(--bg-dusk)', world: 'var(--world-bg)' };
+const FOCUSABLE = 'a[href], area[href], button, input, select, textarea, summary, iframe, audio[controls], video[controls], [contenteditable]:not([contenteditable="false"]), [tabindex]';
+const tabbable = el => !el.disabled && el.getAttribute('tabindex') !== '-1' && !el.closest('[inert]') && el.getClientRects().length > 0;
+const open = []; // stack of open modals: only the top one answers Escape and Tab
+let locks = 0, savedOverflow = ''; // one scroll lock shared by every open modal, so the order they close in doesn't matter
+
+export function Modal({ label, onClose, tone = 'dim', world, closeOnScrim = false, zIndex = 45, children, style, ...rest }) {
+  const box = useRef(null), timer = useRef(0), pressedScrim = useRef(false);
+  const [closing, setClosing] = useState(false);
+  const close = useCallback(() => {
+    if (closing) return;
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return onClose && onClose();
+    setClosing(true);
+    timer.current = setTimeout(() => onClose && onClose(), 240);
+  }, [onClose, closing]);
+  const closeRef = useRef(close);
+  useEffect(() => { closeRef.current = close; });
+
+  useEffect(() => {
+    const id = {}, opener = document.activeElement, root = document.documentElement;
+    open.push(id);
+    if (locks++ === 0) { savedOverflow = root.style.overflow; root.style.overflow = 'hidden'; }
+    if (box.current) box.current.focus();
+    const onKey = e => {
+      if (open[open.length - 1] !== id) return;
+      if (e.key === 'Escape') { e.preventDefault(); closeRef.current(); return; }
+      if (e.key !== 'Tab' || !box.current) return;
+      const items = Array.from(box.current.querySelectorAll(FOCUSABLE)).filter(tabbable);
+      if (!items.length) { e.preventDefault(); return; }
+      const first = items[0], last = items[items.length - 1], at = document.activeElement;
+      if (e.shiftKey && (at === first || !items.includes(at))) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && (at === last || !items.includes(at))) { e.preventDefault(); first.focus(); }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => {
+      clearTimeout(timer.current); // a fade still running must not call onClose after we're gone
+      document.removeEventListener('keydown', onKey);
+      open.splice(open.indexOf(id), 1);
+      if (--locks === 0) root.style.overflow = savedOverflow;
+      if (opener && typeof opener.focus === 'function' && document.contains(opener)) opener.focus();
+    };
+  }, []);
+
+  // Only a tap that both starts and ends on the scrim closes it, so a text selection that ends there doesn't.
+  const onScrim = e => e.target === e.currentTarget || e.target === box.current;
+  // Only the see-through scrim blurs the world behind it. The dusk and world grounds are opaque.
+  const blur = GROUND[tone] && tone !== 'dim' ? undefined : 'blur(var(--scrim-blur))';
+  return (
+    <div role="dialog" aria-modal="true" aria-label={label} data-world={world}
+      onPointerDown={closeOnScrim ? e => { pressedScrim.current = onScrim(e); } : undefined}
+      onClick={closeOnScrim ? e => { if (pressedScrim.current && onScrim(e)) close(); pressedScrim.current = false; } : undefined}
+      style={{
+        position: 'fixed', inset: 0, zIndex, overflowY: 'auto', background: GROUND[tone] || GROUND.dim, backdropFilter: blur, WebkitBackdropFilter: blur,
+        animation: closing ? 'mp-sheet-out 240ms var(--ease-in-out) both' : 'mp-sheet-in 260ms var(--ease-out) both',
+        pointerEvents: closing ? 'none' : undefined, ...style,
+      }} {...rest}>
+      <div ref={box} tabIndex={-1} style={{
+        minHeight: '100%', boxSizing: 'border-box', display: 'grid', gridTemplateColumns: 'minmax(0, 1fr)', placeItems: 'center',
+        padding: 'max(64px, env(safe-area-inset-top)) 16px max(40px, env(safe-area-inset-bottom))', outline: 'none',
+      }}>
+        {typeof children === 'function' ? children(close) : children}
+      </div>
+    </div>
+  );
+}

package/components/panels/Modal.prompt.md

@@ -0,0 +1,20 @@
+Modal shell: the behaviour around a Panel. It puts the panel over the scrim, closes on Escape, locks page scroll, keeps keyboard focus inside, gives focus back to whatever opened it, and fades out.
+
+```jsx
+{open && (
+  <Modal label="Settings" onClose={() => setOpen(false)}>
+    {close => <Panel title="Settings" onClose={close}>…rows…</Panel>}
+  </Modal>
+)}
+<Modal label="A note from the author" world="small_chops" tone="world" onClose={closeNote}>
+  {close => <Panel title="A Note" accent="teal" footer={<Button variant="confirm" onClick={close}>OK</Button>}>…</Panel>}
+</Modal>
+<Modal label="The summit" world="summit" tone="dusk" onClose={closeSummit}>…</Modal>
+```
+
+- Pass a function as the child and wire its `close` to the panel's close and footer buttons. `close` plays the exit fade, then calls `onClose`. Calling `onClose` yourself skips the fade.
+- Always give a `label`. It's what screen readers announce.
+- One panel per modal. Panels stay centred and never go edge to edge.
+- The scrim is `--bg-scrim`, and it blurs the world behind it by `--scrim-blur`. Only the scrim blurs, never the panel. Use `tone="world"` with a `world` for world notes, and `tone="dusk"` for the summit. Both grounds are opaque, so they don't blur.
+- Tapping the scrim does nothing unless you set `closeOnScrim`. The recipient’s sheets leave it off, so a stray tap on the iPad doesn't close a memory.
+- Reduced motion closes straight away, with no fade.

package/components/panels/Panel.d.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+
+/**
+ * Modal card with a chunky game header straddling its top edge, banner plate, celebration ribbon (tails + stars) or wooden sign (nails + leaves): bevelled body, optional close button + footer.
+ * @startingPoint section="Panels" subtitle="Dialog card with banner, ribbon or sign header" viewport="700x440"
+ */
+export interface PanelProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'title'> {
+  title?: React.ReactNode;
+  /** Small cream pill sitting on top of the plate, e.g. "Level 23". */
+  eyebrow?: React.ReactNode;
+  /** banner = tinted plate (settings, shop, level, reveal); ribbon = gold plate with folded tails + stars (level complete); sign = wooden plank with leaves (daily reward, world events); none. 'tab' and 'bush' are accepted as aliases. */
+  header?: 'banner' | 'ribbon' | 'sign' | 'none' | 'tab' | 'bush';
+  /** Banner colour. Default blue (gold for ribbon). Use teal for the recipient’s continue/confirm dialogs. */
+  accent?: 'blue' | 'gold' | 'teal' | 'green' | 'berry' | 'coral';
+  /** cream (default parchment), wood (plank body, thick brown border), sky (white → pale blue). */
+  tone?: 'cream' | 'wood' | 'sky';
+  /** Renders the coral × button on the top-right corner. */
+  onClose?: () => void;
+  /** Default 340 (mobile panel). */
+  width?: number | string;
+  /** Body padding. Default 20. */
+  padding?: number;
+  children?: React.ReactNode;
+  /** Centered button row at the bottom. */
+  footer?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+
+export function Panel(props: PanelProps): React.JSX.Element;

package/components/panels/Panel.jsx

@@ -0,0 +1,109 @@
+'use client';
+import React, { useState } from 'react';
+
+const BODY = {
+  cream: { bg: 'linear-gradient(180deg, var(--cream-50), var(--cream-100))', border: 'var(--cream-300)', bw: 4 },
+  wood:  { bg: 'var(--wood-100)', border: 'var(--wood-500)', bw: 6 },
+  sky:   { bg: 'linear-gradient(180deg, #fff, var(--blue-100))', border: 'var(--blue-300)', bw: 4 },
+};
+// banner accents: [highlight, face, edge, outline]
+const ACCENTS = {
+  blue:  ['var(--blue-300)',  'var(--blue-500)',  'var(--blue-700)',  'var(--blue-900)'],
+  gold:  ['var(--gold-300)',  'var(--gold-500)',  'var(--gold-700)',  'var(--gold-900)'],
+  teal:  ['var(--teal-300)',  'var(--teal-500)',  'var(--teal-700)',  'var(--teal-900)'],
+  green: ['var(--green-300)', 'var(--green-500)', 'var(--green-700)', 'var(--green-900)'],
+  berry: ['var(--berry-300)', 'var(--berry-500)', 'var(--berry-700)', 'var(--berry-900)'],
+  coral: ['var(--coral-300)', 'var(--coral-500)', 'var(--coral-700)', 'var(--coral-900)'],
+};
+const ALIAS = { tab: 'banner', bush: 'sign' }; // older names still work
+const H = 62; // header plate height
+
+function titleStyle(title, stroke, fill, scale = 1) {
+  const len = typeof title === 'string' ? title.length : 10;
+  const fs = len > 18 ? 18 : len > 12 ? 22 : 26;
+  const cq = (len > 18 ? 6 : len > 12 ? 7.5 : 9.5) * scale;
+  return { position: 'relative', fontFamily: 'var(--font-display)', fontSize: 'min(' + fs + 'px, ' + cq + 'cqw)', lineHeight: 1.05, letterSpacing: '0.04em', textTransform: 'uppercase', color: fill, WebkitTextStroke: '0.16em ' + stroke, paintOrder: 'stroke fill', textShadow: '0 3px 0 oklch(0 0 0 / 0.28)', textAlign: 'center', whiteSpace: 'nowrap' };
+}
+const Eyebrow = ({ children, outline }) => (
+  <span style={{ position: 'absolute', top: -13, left: '50%', transform: 'translateX(-50%)', zIndex: 3, height: 26, padding: '0 12px', borderRadius: 999, boxSizing: 'border-box', background: 'var(--cream-50)', border: '3px solid ' + outline, boxShadow: '0 2px 0 ' + outline, display: 'grid', placeItems: 'center', fontFamily: 'var(--font-display)', fontSize: 12, letterSpacing: '0.08em', textTransform: 'uppercase', color: 'var(--ink-900)', whiteSpace: 'nowrap' }}>{children}</span>
+);
+// The wrap shrinks to the plate's width, so tails and leaves hang off the plate's real edges. Title size follows panel width (cqw) so plates never outgrow narrow panels.
+const wrap = { position: 'absolute', top: 0, left: '50%', transform: 'translateX(-50%)', zIndex: 2, minWidth: '56%', height: H, display: 'inline-grid', alignItems: 'center', justifyItems: 'stretch' };
+
+// Banner: chunky plate straddling the panel's top edge. ribbon adds folded tails + stars.
+function Banner({ title, eyebrow, accent, ribbon, room }) {
+  const [hi, face, edge, deep] = ACCENTS[accent] || ACCENTS.blue;
+  const clip = side => side === 'left' ? 'polygon(0 0, 100% 0, 100% 100%, 0 100%, 26% 50%)' : 'polygon(0 0, 100% 0, 74% 50%, 100% 100%, 0 100%)';
+  const Tail = ({ side }) => (
+    <span aria-hidden="true" style={{ position: 'absolute', top: 22, left: side === 'left' ? -30 : 'auto', right: side === 'right' ? -30 : 'auto', width: 66, height: H - 28, transform: 'rotate(' + (side === 'left' ? -6 : 6) + 'deg)', filter: 'drop-shadow(0 5px 0 ' + deep + ')', zIndex: 0 }}>
+      <span style={{ position: 'absolute', inset: 0, clipPath: clip(side), background: deep }} />
+      <span style={{ position: 'absolute', inset: 4, clipPath: clip(side), background: 'linear-gradient(' + (side === 'left' ? '90deg' : '270deg') + ', ' + edge + ' 0%, ' + face + ' 80%)' }} />
+    </span>
+  );
+  return (
+    <div style={wrap}>
+      {ribbon && <Tail side="left" />}
+      {ribbon && <Tail side="right" />}
+      <div style={{ position: 'relative', height: H, padding: '0 26px', boxSizing: 'border-box', borderRadius: 20, border: '4px solid ' + deep,
+        background: 'linear-gradient(180deg, ' + hi + ' 0%, ' + face + ' 48%)', boxShadow: '0 6px 0 ' + edge + ', 0 12px 20px oklch(0.2 0.05 60 / 0.35), inset 0 3px 0 oklch(1 0 0 / 0.5)', display: 'grid', placeItems: 'center' }}>
+        <span aria-hidden="true" style={{ position: 'absolute', top: 6, left: 14, right: 14, height: 9, borderRadius: 999, background: 'oklch(1 0 0 / 0.35)' }} />
+        <span style={titleStyle(title, deep, '#fff', room)}>{title}</span>
+        {ribbon && ['left', 'right'].map(s => (
+          <i key={s} aria-hidden="true" className="ph-fill ph-star" style={{ position: 'absolute', top: -18, left: s === 'left' ? -8 : 'auto', right: s === 'right' ? -8 : 'auto', fontSize: 32, lineHeight: 1, color: 'var(--gold-300)', WebkitTextStroke: '3px var(--gold-900)', paintOrder: 'stroke fill', filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.25))', transform: 'rotate(' + (s === 'left' ? -18 : 18) + 'deg)' }} />
+        ))}
+      </div>
+      {eyebrow && <Eyebrow outline={deep}>{eyebrow}</Eyebrow>}
+    </div>
+  );
+}
+
+// Sign: wooden plank with nails and leaves, world events, daily reward.
+function Sign({ title, eyebrow, room }) {
+  const leaf = (side, rot, top, size, key) => (
+    <i key={key} aria-hidden="true" className="ph-fill ph-leaf" style={{ position: 'absolute', top, left: side === 'left' ? -12 : 'auto', right: side === 'right' ? -12 : 'auto', fontSize: size, lineHeight: 1, color: 'var(--green-500)', WebkitTextStroke: '3px var(--green-900)', paintOrder: 'stroke fill', transform: 'rotate(' + rot + 'deg)', filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.25))', zIndex: 0 }} />
+  );
+  return (
+    <div style={{ ...wrap, minWidth: '62%' }}>
+      {leaf('left', -35, -14, 36, 'a')}{leaf('right', 35, -14, 36, 'b')}{leaf('left', -115, 28, 28, 'c')}{leaf('right', 115, 28, 28, 'd')}
+      <div style={{ position: 'relative', height: H, padding: '0 30px', boxSizing: 'border-box', borderRadius: 14, border: '4px solid var(--wood-700)',
+        background: 'repeating-linear-gradient(180deg, transparent 0 9px, oklch(0 0 0 / 0.06) 9px 11px), linear-gradient(180deg, var(--wood-300), var(--wood-500))',
+        boxShadow: '0 6px 0 var(--wood-900), 0 12px 20px oklch(0.2 0.05 60 / 0.35), inset 0 3px 0 oklch(1 0 0 / 0.3)', display: 'grid', placeItems: 'center' }}>
+        {['left', 'right'].map(s => <span key={s} aria-hidden="true" style={{ position: 'absolute', top: 7, left: s === 'left' ? 8 : 'auto', right: s === 'right' ? 8 : 'auto', width: 9, height: 9, borderRadius: '50%', background: 'radial-gradient(circle at 35% 30%, var(--stone-100), var(--stone-500))', boxShadow: '0 1px 0 var(--wood-900)' }} />)}
+        <span style={titleStyle(title, 'var(--wood-900)', 'var(--cream-100)', room)}>{title}</span>
+      </div>
+      {eyebrow && <Eyebrow outline="var(--wood-900)">{eyebrow}</Eyebrow>}
+    </div>
+  );
+}
+
+function CloseButton({ onClick }) {
+  const [down, setDown] = useState(false);
+  return (
+    <button type="button" aria-label="Close" onClick={onClick} onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ position: 'absolute', top: -10, right: -10, width: 40, height: 40, borderRadius: '50%', border: '3px solid #fff', padding: 0, cursor: 'pointer', zIndex: 3,
+        background: 'linear-gradient(180deg, var(--coral-300), var(--coral-500) 50%)', boxShadow: '0 ' + (down ? 1 : 4) + 'px 0 var(--coral-700), 0 6px 10px oklch(0 0 0 / 0.25)',
+        transform: 'translateY(' + (down ? 3 : 0) + 'px)', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)', color: '#fff', fontSize: 20, display: 'grid', placeItems: 'center', lineHeight: 1 }}>
+      <i className="ph-bold ph-x" />
+    </button>
+  );
+}
+
+export function Panel({ title, eyebrow, header = 'banner', accent, tone = 'cream', onClose, width = 340, padding = 20, children, footer, style, ...rest }) {
+  const kind = ALIAS[header] || header;
+  const room = onClose ? 0.84 : 1; // shrink the title a little so the plate never runs under the × button
+  const t = BODY[tone] || BODY.cream;
+  const has = kind !== 'none' && title != null;
+  const overlap = has ? Math.round(H * 0.55) : 0; // part of the plate rises above the panel edge
+  const acc = accent || (kind === 'ribbon' ? 'gold' : 'blue');
+  return (
+    <div style={{ position: 'relative', width, maxWidth: '100%', boxSizing: 'border-box', paddingTop: overlap, containerType: 'inline-size', filter: 'drop-shadow(0 18px 28px oklch(0.22 0.05 60 / 0.35))', ...style }} {...rest}>
+      {has && (kind === 'sign' ? <Sign title={title} eyebrow={eyebrow} room={room} /> : <Banner title={title} eyebrow={eyebrow} accent={acc} ribbon={kind === 'ribbon'} room={room} />)}
+      <div style={{ position: 'relative', background: t.bg, border: t.bw + 'px solid ' + t.border, borderRadius: 'var(--radius-xl)', boxSizing: 'border-box',
+        boxShadow: 'inset 0 3px 0 oklch(1 0 0 / 0.7), inset 0 -4px 0 oklch(0 0 0 / 0.06)', paddingTop: has ? H - overlap : 0 }}>
+        {onClose && <CloseButton onClick={onClose} />}
+        <div style={{ padding, paddingTop: has ? padding - 4 : padding }}>{children}</div>
+        {footer && <div style={{ padding: '0 ' + padding + 'px ' + padding + 'px', display: 'flex', justifyContent: 'center', gap: 12 }}>{footer}</div>}
+      </div>
+    </div>
+  );
+}

package/components/panels/Panel.prompt.md

@@ -0,0 +1,13 @@
+Dialog panel: every modal (settings, shop, level complete, daily reward, offers) is a Panel over a scrim; one panel per screen.
+
+```jsx
+<Panel title="Settings" onClose={close}>…rows…</Panel>
+<Panel title="Complete" eyebrow="Level 23" header="ribbon" footer={<Button variant="confirm" size="lg">OK</Button>}>…</Panel>
+<Panel title="Daily Reward" header="sign" tone="wood" footer={<Button size="lg">Claim</Button>}>…</Panel>
+<Panel title="Who sent this?" accent="teal" footer={<Button variant="confirm" size="lg">Continue</Button>}>…</Panel>
+<Panel header="none" tone="sky" width={300}>…</Panel>
+```
+
+- Header choice by mood: banner = utility and level dialogs (blue; teal accent in the recipient’s flow), ribbon = celebration, sign = world / event / daily reward. The plate straddles the top edge, leave ~34px above the panel free.
+- Put the primary action in footer (one lg button, max two).
+- Place inside a fixed scrim: background var(--bg-scrim), centered.

package/components/quiz/LeaderboardRow.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+
+/**
+ * Friend-facing leaderboard row: rank (ties share, shown as "=3"), avatar, name, gem + tier text, score. Skipped quiz = pearl, unranked, no score.
+ * @startingPoint section="Quiz" subtitle="Ranked rows, ties, you, skipped" viewport="700x300"
+ */
+export interface LeaderboardRowProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style'> {
+  rank?: number;
+  /** Shares rank with neighbours → renders "=N". */
+  tied?: boolean;
+  name: string;
+  seed?: string;
+  portrait?: string;
+  gem?: 'amber' | 'emerald' | 'amethyst' | 'pearl';
+  tier?: 1 | 2 | 3;
+  score?: number;
+  /** Default 8. */
+  total?: number;
+  /** Highlights the viewer's own row. */
+  me?: boolean;
+  /** Quiz skipped: pearl keepsake, "-" rank, no score. */
+  skipped?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function LeaderboardRow(props: LeaderboardRowProps): React.JSX.Element;

package/components/quiz/LeaderboardRow.jsx

@@ -0,0 +1,24 @@
+'use client';
+import React from 'react';
+import { Avatar } from '../identity/Avatar';
+import { Gemstone, GEM_NAMES } from '../identity/Gemstone';
+
+const ROMAN = ['', 'I', 'II', 'III'];
+
+export function LeaderboardRow({ rank, tied = false, name, seed, portrait, gem = 'amber', tier = 1, score, total = 8, me = false, skipped = false, style, ...rest }) {
+  const g = skipped ? 'pearl' : gem;
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12, minHeight: 64, padding: '8px 14px 8px 10px', borderRadius: 'var(--radius-lg)', boxSizing: 'border-box',
+      background: me ? 'linear-gradient(180deg, var(--teal-100), #fff)' : 'linear-gradient(180deg, #fff, var(--cream-100))',
+      border: '3px solid ' + (me ? 'var(--teal-300)' : 'var(--cream-300)'), boxShadow: '0 3px 0 ' + (me ? 'var(--teal-500)' : 'var(--cream-300)'), fontFamily: 'var(--font-ui)', ...style }} {...rest}>
+      <span aria-label={skipped ? 'Unranked' : 'Rank ' + rank + (tied ? ', tied' : '')} style={{ width: 40, textAlign: 'center', fontFamily: 'var(--font-display)', fontSize: skipped ? 16 : 20, color: skipped ? 'var(--ink-500)' : 'var(--ink-900)', flex: 'none' }}>{skipped ? '-' : (tied ? '=' : '') + rank}</span>
+      <Avatar name={name} seed={seed} src={portrait} size={40} />
+      <span style={{ flex: 1, minWidth: 0, display: 'grid', gap: 1 }}>
+        <span style={{ fontWeight: 700, fontSize: 16, color: 'var(--ink-900)', whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{name}{me && <span style={{ marginLeft: 8, fontFamily: 'var(--font-display)', fontSize: 11, color: 'var(--teal-700)', letterSpacing: '0.08em' }}>YOU</span>}</span>
+        <span style={{ fontWeight: 600, fontSize: 12, color: 'var(--ink-500)' }}>{skipped ? 'Pearl keepsake · unranked' : GEM_NAMES[gem] + ' ' + ROMAN[tier]}</span>
+      </span>
+      <Gemstone gem={g} tier={tier} size={34} animate={false} />
+      <span style={{ width: 44, textAlign: 'right', fontFamily: 'var(--font-display)', fontSize: 18, color: 'var(--ink-900)', fontVariantNumeric: 'tabular-nums', flex: 'none' }}>{skipped ? '' : score + '/' + total}</span>
+    </div>
+  );
+}

package/components/quiz/LeaderboardRow.prompt.md

@@ -0,0 +1,10 @@
+Leaderboard row: FRIENDS ONLY (after their quiz). The recipient never sees this list.
+
+```jsx
+<LeaderboardRow rank={1} name="Ada Okafor" seed="c_01" gem="amethyst" tier={3} score={8} />
+<LeaderboardRow rank={3} tied name="Tunde B." seed="c_22" gem="emerald" tier={2} score={4} me />
+<LeaderboardRow name="Kemi A." seed="c_07" skipped />
+```
+
+- Ties share rank (=3, =3). Skipped players sit at the bottom, unranked, never as 0/8.
+- Tone celebrates participation: no "winner" language, no crowns.

package/components/rewards/ItemCell.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * Inventory / merge-grid cell: translucent dark square over the world with filled, empty, locked and add states; selected glows teal.
+ * @startingPoint section="Rewards" subtitle="Inventory grid cells with counts + selection" viewport="700x200"
+ */
+export interface ItemCellProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style' | 'content'> {
+  state?: 'empty' | 'filled' | 'locked' | 'add';
+  /** The item glyph/illustration shown when filled. */
+  content?: React.ReactNode;
+  /** Level / quantity shown bottom-right when filled. */
+  count?: number | string;
+  /** Teal border + glow. */
+  selected?: boolean;
+  /** Ghosted silhouette (undiscovered item). */
+  dim?: boolean;
+  /** Default 72. */
+  size?: number;
+  onClick?: () => void;
+  label?: string;
+  style?: React.CSSProperties;
+}
+
+export function ItemCell(props: ItemCellProps): React.JSX.Element;

package/components/rewards/ItemCell.jsx

@@ -0,0 +1,24 @@
+'use client';
+import React, { useState } from 'react';
+
+export function ItemCell({ state = 'empty', content, count, selected = false, dim = false, size = 72, onClick, label, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const clickable = !!onClick && state !== 'locked';
+  const Tag = clickable ? 'button' : 'div';
+  return (
+    <Tag type={clickable ? 'button' : undefined} onClick={clickable ? onClick : undefined} aria-label={label} onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', margin: 0, padding: 0, position: 'relative', display: 'grid', placeItems: 'center', width: size, height: size, flex: 'none', boxSizing: 'border-box', cursor: clickable ? 'pointer' : 'default',
+        borderRadius: 'var(--radius-md)', background: selected ? 'var(--surface-cell-active)' : 'var(--surface-cell)',
+        border: '3px solid ' + (selected ? 'var(--teal-300)' : 'oklch(1 0 0 / 0.08)'),
+        boxShadow: selected ? '0 0 0 3px oklch(0.88 0.09 184 / 0.5), 0 0 18px oklch(0.76 0.13 180 / 0.8), inset 0 2px 6px oklch(0 0 0 / 0.25)' : 'inset 0 2px 6px oklch(0 0 0 / 0.25)',
+        transform: down && clickable ? 'scale(0.96)' : 'scale(1)', transition: 'transform var(--dur-fast), box-shadow var(--dur-base)', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      {state === 'filled' && <span style={{ display: 'grid', placeItems: 'center', opacity: dim ? 0.45 : 1, filter: dim ? 'grayscale(0.6)' : 'none' }}>{content}</span>}
+      {state === 'locked' && <i aria-hidden="true" className="ph-fill ph-lock" style={{ fontSize: size * 0.4, color: 'oklch(1 0 0 / 0.35)', lineHeight: 1 }} />}
+      {state === 'add' && <i aria-hidden="true" className="ph-bold ph-plus" style={{ fontSize: size * 0.5, color: 'var(--gold-500)', WebkitTextStroke: (size * 0.05) + 'px var(--gold-900)', paintOrder: 'stroke fill', lineHeight: 1, filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.25))' }} />}
+      {count != null && state === 'filled' && (
+        <span style={{ position: 'absolute', right: 6, bottom: 4, fontFamily: 'var(--font-display)', fontSize: Math.round(size * 0.2), lineHeight: 1, color: '#fff',
+          WebkitTextStroke: (size * 0.035) + 'px var(--ink-900)', paintOrder: 'stroke fill', opacity: dim ? 0.6 : 1 }}>{count}</span>
+      )}
+    </Tag>
+  );
+}

package/components/rewards/ItemCell.prompt.md

@@ -0,0 +1,9 @@
+Inventory cell: grids of collectibles, merge items, party slots. 4 columns on mobile, 6px gaps, laid over grass.
+
+```jsx
+<ItemCell state="filled" content={<GameIcon kind="egg" size={44} />} count={1} selected onClick={select} />
+<ItemCell state="filled" content={<GameIcon kind="leaf" size={44} />} count={4} dim />
+<ItemCell state="empty" />
+<ItemCell state="locked" />
+<ItemCell state="add" onClick={buySlot} label="Buy slot" />
+```

package/components/rewards/RewardCard.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * Reward calendar cell (Day N + prize) with claimed / available / locked states; featured renders a wide blue banner card.
+ * @startingPoint section="Rewards" subtitle="Daily reward cells + featured day" viewport="700x260"
+ */
+export interface RewardCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'title'> {
+  /** Strip label, e.g. "Day 3". */
+  title: React.ReactNode;
+  /** Prize glyph, e.g. <GameIcon kind="gem" size={40} />. */
+  icon?: React.ReactNode;
+  /** Prize amount text, e.g. "+50". */
+  amount?: React.ReactNode;
+  /** claimed = green overlay + check; available = gold glow, floating icon, tappable; locked = desaturated + lock. */
+  state?: 'claimed' | 'available' | 'locked';
+  /** Wide blue banner (the grand prize row). */
+  featured?: boolean;
+  /** Called when an available card is tapped. */
+  onClick?: () => void;
+  width?: number | string;
+  style?: React.CSSProperties;
+}
+
+export function RewardCard(props: RewardCardProps): React.JSX.Element;

package/components/rewards/RewardCard.jsx

@@ -0,0 +1,34 @@
+'use client';
+import React, { useState } from 'react';
+
+export function RewardCard({ title, icon, amount, state = 'available', featured = false, onClick, width, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const claimed = state === 'claimed', locked = state === 'locked', avail = state === 'available';
+  const clickable = avail && onClick;
+  const border = featured ? 'var(--blue-500)' : 'var(--wood-500)';
+  const strip = featured ? 'var(--blue-700)' : 'var(--wood-700)';
+  const body = featured ? 'linear-gradient(180deg, var(--blue-100), var(--blue-300))' : 'linear-gradient(180deg, var(--cream-50), var(--wood-100))';
+  return (
+    <div role={clickable ? 'button' : undefined} tabIndex={clickable ? 0 : undefined} onClick={clickable ? onClick : undefined}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ position: 'relative', display: 'flex', flexDirection: featured ? 'row' : 'column', alignItems: 'center', width: width || (featured ? '100%' : 96), boxSizing: 'border-box',
+        borderRadius: 'var(--radius-md)', border: '3px solid ' + border, background: body, overflow: 'hidden', cursor: clickable ? 'pointer' : 'default',
+        boxShadow: '0 ' + (down && clickable ? 1 : 4) + 'px 0 ' + strip + ', 0 6px 10px oklch(0.2 0.05 60 / 0.2)' + (avail ? ', 0 0 0 3px oklch(0.92 0.14 90 / 0.9), 0 0 18px oklch(0.86 0.17 85 / 0.7)' : ''),
+        transform: 'translateY(' + (down && clickable ? 3 : 0) + 'px)', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)',
+        filter: locked ? 'saturate(0.35) brightness(0.92)' : 'none', ...style }} {...rest}>
+      <div style={{ alignSelf: 'stretch', flex: featured ? '0 0 auto' : undefined, display: 'grid', placeItems: 'center', padding: featured ? '0 14px' : '5px 6px', minWidth: featured ? 72 : undefined,
+        background: strip, color: '#fff', fontFamily: 'var(--font-display)', fontSize: 13, letterSpacing: '0.06em', textTransform: 'uppercase', textShadow: '0 1px 0 oklch(0 0 0 / 0.3)', whiteSpace: 'nowrap' }}>{title}</div>
+      <div style={{ display: 'flex', flexDirection: featured ? 'row' : 'column', alignItems: 'center', justifyContent: 'center', gap: featured ? 12 : 4, padding: featured ? '10px 14px' : '10px 8px 10px', flex: 1 }}>
+        <span style={{ display: 'grid', placeItems: 'center', animation: avail ? 'mp-float var(--dur-idle) ease-in-out infinite' : 'none' }}>{icon}</span>
+        {amount != null && <span style={{ fontFamily: 'var(--font-display)', fontSize: featured ? 22 : 16, lineHeight: 1, color: featured ? '#fff' : 'var(--ink-900)',
+          WebkitTextStroke: featured ? '3px var(--blue-700)' : '0', paintOrder: 'stroke fill', letterSpacing: '0.02em' }}>{amount}</span>}
+      </div>
+      {claimed && (
+        <div aria-label="Claimed" style={{ position: 'absolute', inset: 0, background: 'oklch(0.58 0.16 140 / 0.45)', display: 'grid', placeItems: 'center' }}>
+          <i className="ph-bold ph-check" style={{ fontSize: 40, color: '#fff', WebkitTextStroke: '3px var(--green-700)', paintOrder: 'stroke fill', filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.25))' }} />
+        </div>
+      )}
+      {locked && <i aria-hidden="true" className="ph-fill ph-lock" style={{ position: 'absolute', top: 30, right: 6, fontSize: 18, color: 'var(--stone-300)', WebkitTextStroke: '2px var(--stone-700)', paintOrder: 'stroke fill' }} />}
+    </div>
+  );
+}