lanre-ds 0.0.0-stage → 0.2.0

package/components/rewards/RewardCard.prompt.md

@@ -0,0 +1,8 @@
+Reward card: cells of a daily/streak calendar or a prize track. Grid of 3 per row inside a wood Panel; the last day is featured.
+
+```jsx
+<RewardCard title="Day 1" icon={<GameIcon kind="coin" size={40} />} amount="+1M" state="claimed" />
+<RewardCard title="Day 3" icon={<GameIcon kind="gift" size={40} />} state="available" onClick={claim} />
+<RewardCard title="Day 5" icon={<GameIcon kind="gem" size={40} />} amount="+10" state="locked" />
+<RewardCard title="Day 7" featured icon={<GameIcon kind="heart" size={44} />} amount="+50" state="locked" />
+```

package/components/rewards/ShopRow.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+/**
+ * Shop line item: prize glyph, title/subtitle, price button; optional corner Tag; featured tone for the hero offer.
+ * @startingPoint section="Rewards" subtitle="Shop rows with price buttons + tags" viewport="700x300"
+ */
+export interface ShopRowProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'title'> {
+  icon?: React.ReactNode;
+  title: React.ReactNode;
+  subtitle?: React.ReactNode;
+  /** Price label for the built-in buy button, e.g. "USD 0.99" or a CurrencyPill. */
+  price?: React.ReactNode;
+  /** Corner label, e.g. <Tag>Most popular</Tag>. */
+  tag?: React.ReactNode;
+  /** featured = teal gradient hero row with a gold price button. */
+  tone?: 'default' | 'featured';
+  onBuy?: () => void;
+  /** Replaces the built-in price button. */
+  action?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+
+export function ShopRow(props: ShopRowProps): React.JSX.Element;

package/components/rewards/ShopRow.jsx

@@ -0,0 +1,26 @@
+'use client';
+import React, { useState } from 'react';
+
+export function ShopRow({ icon, title, subtitle, price, tag, tone = 'default', onBuy, action, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const featured = tone === 'featured';
+  return (
+    <div style={{ position: 'relative', display: 'flex', alignItems: 'center', gap: 12, minHeight: 76, padding: '10px 10px 10px 12px', boxSizing: 'border-box', borderRadius: 'var(--radius-lg)',
+      background: featured ? 'linear-gradient(135deg, var(--teal-500), var(--teal-700))' : 'linear-gradient(180deg, #fff, var(--cream-100))',
+      border: '3px solid ' + (featured ? 'var(--teal-300)' : 'var(--cream-300)'), boxShadow: '0 3px 0 ' + (featured ? 'var(--teal-900)' : 'var(--cream-300)') + ', 0 4px 8px oklch(0.2 0.05 60 / 0.12)', ...style }} {...rest}>
+      {tag && <span style={{ position: 'absolute', top: -12, right: 12 }}>{tag}</span>}
+      <span style={{ display: 'grid', placeItems: 'center', width: 50, height: 50, flex: 'none' }}>{icon}</span>
+      <div style={{ flex: 1, minWidth: 0, display: 'flex', flexDirection: 'column', gap: 2 }}>
+        <span style={{ fontFamily: 'var(--font-display)', fontSize: 16, lineHeight: 1.1, color: featured ? '#fff' : 'var(--ink-900)', textShadow: featured ? '0 2px 0 var(--teal-900)' : 'none', letterSpacing: '0.01em' }}>{title}</span>
+        {subtitle && <span style={{ fontFamily: 'var(--font-ui)', fontWeight: 700, fontSize: 12, color: featured ? 'var(--teal-100)' : 'var(--ink-500)', lineHeight: 1.25 }}>{subtitle}</span>}
+      </div>
+      {action || (price != null && (
+        <button type="button" onClick={onBuy} onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+          style={{ appearance: 'none', border: 0, flex: 'none', height: 40, padding: '0 14px', borderRadius: 'var(--radius-md)', cursor: 'pointer',
+            background: featured ? 'linear-gradient(180deg, var(--gold-300), var(--gold-500) 45%)' : 'linear-gradient(180deg, var(--teal-300), var(--teal-500) 45%)',
+            boxShadow: '0 ' + (down ? 1 : 4) + 'px 0 ' + (featured ? 'var(--gold-700)' : 'var(--teal-700)') + ', inset 0 2px 0 oklch(1 0 0 / 0.45)', transform: 'translateY(' + (down ? 3 : 0) + 'px)', transition: 'transform var(--dur-fast), box-shadow var(--dur-fast)',
+            fontFamily: 'var(--font-display)', fontSize: 14, letterSpacing: '0.02em', color: featured ? 'var(--gold-900)' : '#fff', textShadow: featured ? 'none' : '0 2px 0 var(--teal-700)', whiteSpace: 'nowrap' }}>{price}</button>
+      ))}
+    </div>
+  );
+}

package/components/rewards/ShopRow.prompt.md

@@ -0,0 +1,7 @@
+Shop row: one purchasable per row inside the Shop panel; the first row is the featured hero offer.
+
+```jsx
+<ShopRow tone="featured" icon={<GameIcon kind="coins" size={48} />} title="3,000 coins" subtitle="One-time offer" price="USD 3.99" tag={<Tag tone="gold">3x the value</Tag>} onBuy={buy} />
+<ShopRow icon={<GameIcon name="prohibit" tone="berry" size={44} />} title="No ads" subtitle="Rewarded videos still available" price="USD 0.99" />
+<ShopRow icon={<GameIcon kind="coin" size={44} />} title="2,720 coins" price="USD 0.99" tag={<Tag>Most popular</Tag>} />
+```

package/components/text/Heading.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * A screen heading: a small wood tag, a big outlined title in the world's colour, and a cream plate with one line of explanation.
+ * @startingPoint section="Text" subtitle="Eyebrow, outlined title and cream plate" viewport="700x300"
+ */
+export interface HeadingProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  /** A short label above the title. */
+  eyebrow?: string;
+  title: string;
+  /** One or two sentences on a cream plate under the title. */
+  lede?: React.ReactNode;
+  /** Title size in px. Default 34. */
+  size?: number;
+  /** The title's element. Default h1. */
+  as?: 'h1' | 'h2' | 'h3';
+}
+
+export function Heading(props: HeadingProps): React.JSX.Element;

package/components/text/Heading.jsx

@@ -0,0 +1,15 @@
+'use client';
+import React from 'react';
+import { Tag } from '../feedback/Tag';
+
+/* A screen heading: an optional small tag above, an outlined title, and an optional lede on a cream plate. The outline takes
+   the colour of the world it's in (--world-stroke). */
+export function Heading({ eyebrow, title, lede, size, as: Title = 'h1', className, ...rest }) {
+  return (
+    <header className={['mp-heading', className].filter(Boolean).join(' ')} {...rest}>
+      {eyebrow && <Tag tone="wood">{eyebrow}</Tag>}
+      <Title className="mp-heading-title" style={size ? { fontSize: size } : undefined}>{title}</Title>
+      {lede && <p className="mp-plate">{lede}</p>}
+    </header>
+  );
+}

package/components/text/Heading.prompt.md

@@ -0,0 +1,10 @@
+Heading: the top of a screen.
+
+```jsx
+<Heading eyebrow="Step 2 of 4" title="Pick a spot on the road" lede="Choose where your memory should live." />
+<Heading title="All done" size={42} />
+```
+
+- Titles are uppercase, so keep them to a few words. Long ones wrap evenly; lower `size` for the longest.
+- The outline follows the surrounding `data-world`, so the same heading suits every world.
+- One `h1` per screen. Use `as="h2"` for headings inside a panel.

package/components/text/OutlineText.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * Display text with a dark stroke painted behind the fill, level numbers, panel titles, captions over the world.
+ * @startingPoint section="Text" subtitle="Outlined display type in 5 sizes" viewport="700x200"
+ */
+export interface OutlineTextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style' | 'color'> {
+  /** Element tag. Default span. */
+  as?: 'span' | 'div' | 'h1' | 'h2' | 'h3' | 'p';
+  /** Preset (xl 44 / lg 32 / md 24 / sm 18 / xs 14) or a px number. */
+  size?: 'xl' | 'lg' | 'md' | 'sm' | 'xs' | number;
+  /** Fill: white (default), gold, cream, blue, green, or any CSS color. */
+  color?: 'white' | 'gold' | 'cream' | 'blue' | 'green' | string;
+  /** Stroke tone: ink (default), stone (locked), blue (current level), gold, green, coral, berry, wood, or any CSS color. */
+  stroke?: 'ink' | 'stone' | 'blue' | 'gold' | 'green' | 'coral' | 'berry' | 'wood' | string;
+  /** Uppercase (default true). */
+  uppercase?: boolean;
+  /** Hard drop shadow under the text (default true). */
+  shadow?: boolean;
+  children?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+
+export function OutlineText(props: OutlineTextProps): React.JSX.Element;

package/components/text/OutlineText.jsx

@@ -0,0 +1,20 @@
+'use client';
+import React from 'react';
+
+const SIZES = { xl: 44, lg: 32, md: 24, sm: 18, xs: 14 };
+const STROKES = { ink: 'var(--ink-900)', stone: 'var(--stone-700)', blue: 'var(--blue-700)', gold: 'var(--gold-700)', green: 'var(--green-900)', coral: 'var(--coral-900)', berry: 'var(--berry-900)', wood: 'var(--wood-900)' };
+const FILLS = { white: '#fff', gold: 'var(--gold-300)', cream: 'var(--cream-100)', blue: 'var(--blue-300)', green: 'var(--green-300)' };
+
+export function OutlineText({ as = 'span', size = 'md', color = 'white', stroke = 'ink', weight, uppercase = true, shadow = true, children, style, ...rest }) {
+  const px = typeof size === 'number' ? size : (SIZES[size] || SIZES.md);
+  const sw = px < 20 ? 0.2 : 0.16;
+  return React.createElement(as, {
+    style: {
+      fontFamily: 'var(--font-display)', fontWeight: 400, fontSize: px, lineHeight: 1.05, letterSpacing: '0.02em',
+      textTransform: uppercase ? 'uppercase' : 'none', color: FILLS[color] || color,
+      WebkitTextStroke: (sw * px).toFixed(1) + 'px ' + (STROKES[stroke] || stroke), paintOrder: 'stroke fill',
+      textShadow: shadow ? '0 ' + Math.max(2, Math.round(px * 0.1)) + 'px 0 oklch(0 0 0 / 0.22)' : 'none',
+      display: 'inline-block', ...style,
+    }, ...rest,
+  }, children);
+}

package/components/text/OutlineText.prompt.md

@@ -0,0 +1,11 @@
+Outlined display text: every title, level number or caption that sits directly on the world (grass, sky, wood) uses this; plain text goes only inside panels.
+
+```jsx
+<OutlineText size="xl">Daily Reward</OutlineText>
+<OutlineText size={40} stroke="blue">7</OutlineText>          // number on a blue level node
+<OutlineText size="xs" stroke="stone">Locked</OutlineText>
+<OutlineText size="lg" color="gold" stroke="gold">x2 Boost</OutlineText>
+```
+
+- Stroke matches the surface it sits on: ink over grass/wood, blue on blue level nodes, stone on locked ones.
+- Keep to 1–3 words; it is a label face, not a paragraph face.

package/components/toolbar/FastTravelDock.d.ts

@@ -0,0 +1,50 @@
+import * as React from 'react';
+
+export interface DockStop {
+  id: string;
+  /** The stop's name, used for its accessible label unless `ariaLabel` is set. */
+  name: string;
+  /** The short name under the stop. Defaults to `name`. */
+  label?: string;
+  /** A Phosphor icon name. */
+  glyph: string;
+  /** done is lit gold, here is blue with a ring, ahead is stone. */
+  state: 'done' | 'here' | 'ahead';
+  /** How many surprises are still hidden there. */
+  hidden?: number;
+  /** A full accessible label, such as "Mango Grove, you are here, 2 surprises still hidden". */
+  ariaLabel?: string;
+}
+
+/**
+ * The dock down the side of the map: a compass that jumps to what's next, then one stop for each place on the road, from the top. Done stops are lit, the one you're at is ringed, and a count says how many surprises are still hidden. On phones it folds into the compass until it's tapped.
+ * @startingPoint section="Toolbar" subtitle="Fast travel down the side" viewport="700x560"
+ */
+export interface FastTravelDockProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** In order from the top of the dock. */
+  stops: DockStop[];
+  /** Folds into the compass until opened. */
+  phone?: boolean;
+  /** On a phone, whether it's open. */
+  open?: boolean;
+  /** The count on the folded compass: the surprises still hidden, in all. */
+  hiddenTotal?: number;
+  /** The word under the compass. Default "Next". */
+  nextLabel?: string;
+  /** The group's accessible name. Default "Fast travel". */
+  label?: string;
+  compassLabel?: string;
+  openLabel?: string;
+  closeLabel?: string;
+  /** Sits inside a positioned box instead of covering the window. */
+  contained?: boolean;
+  /** The compass was pressed. On a phone it opens or closes the dock. */
+  onCompass?: () => void;
+  /** The "next" stop on an open phone dock was pressed. */
+  onNext?: () => void;
+  onTravel?: (id: string) => void;
+  /** The dim area behind an open phone dock was pressed. */
+  onClose?: () => void;
+}
+
+export function FastTravelDock(props: FastTravelDockProps): React.JSX.Element;

package/components/toolbar/FastTravelDock.jsx

@@ -0,0 +1,36 @@
+'use client';
+import React from 'react';
+
+/* The dock down the side of the map: one stop for each place on the road, from the top, with the one you're at marked and
+   the ones you've finished lit. A compass jumps to what's next. On phones it folds into the compass until it's tapped.
+   Set `contained` to place it in a positioned box instead. */
+export function FastTravelDock({ stops = [], phone = false, open = false, hiddenTotal = 0, nextLabel = 'Next', label = 'Fast travel', compassLabel = 'Take me to the next level',
+  closeLabel = 'Close fast travel', openLabel = 'Open fast travel', contained = false, onCompass, onNext, onTravel, onClose, ...rest }) {
+  return (
+    <>
+      <div className={'mp-dock' + (phone ? ' mp-dock-phone' : '') + (open ? ' mp-dock-open' : '') + (contained ? ' mp-dock-contained' : '')} role="group" aria-label={label} {...rest}>
+        <button type="button" className="mp-stop mp-stop-compass" onClick={onCompass} aria-label={phone ? (open ? closeLabel : openLabel) : compassLabel} aria-expanded={phone ? open : undefined}>
+          <i className={'ph-bold ' + (phone ? 'ph-compass' : 'ph-arrow-up')} aria-hidden="true" />
+          {phone && hiddenTotal > 0 && !open && <span className="mp-stop-count">{hiddenTotal}</span>}
+        </button>
+        <span className="mp-dock-label" aria-hidden="true">{nextLabel}</span>
+        <span className="mp-dock-rule" aria-hidden="true" />
+        {phone && (
+          <button type="button" className="mp-stop mp-stop-here mp-stop-next" onClick={onNext} aria-label={compassLabel}>
+            <i className="ph-bold ph-arrow-up" aria-hidden="true" />
+          </button>
+        )}
+        {stops.map(st => (
+          <div key={st.id} className="mp-stop-wrap">
+            <button type="button" className={'mp-stop ' + (st.state === 'done' ? 'mp-stop-done' : st.state === 'here' ? 'mp-stop-here' : 'mp-stop-ahead')} onClick={onTravel ? () => onTravel(st.id) : undefined} aria-label={st.ariaLabel || st.name}>
+              <i className={'ph-fill ph-' + st.glyph} aria-hidden="true" />
+              {st.hidden > 0 && <span className="mp-stop-count" aria-hidden="true">{st.hidden}</span>}
+            </button>
+            <span className="mp-dock-label" aria-hidden="true">{st.label || st.name}</span>
+          </div>
+        ))}
+      </div>
+      {phone && open && <button type="button" className={'mp-dock-scrim' + (contained ? ' mp-dock-scrim-contained' : '')} aria-label={closeLabel} onClick={onClose} />}
+    </>
+  );
+}

package/components/toolbar/FastTravelDock.prompt.md

@@ -0,0 +1,12 @@
+Fast travel dock: a way to jump along the road without scrolling.
+
+```jsx
+<FastTravelDock stops={stops} onCompass={goToNext} onTravel={travelTo} />
+<FastTravelDock stops={stops} phone open={open} hiddenTotal={total} onCompass={() => setOpen(o => !o)} onNext={goToNext} onTravel={travelTo} onClose={() => setOpen(false)} />
+```
+
+- List the stops in the order the dock reads: the summit at the top and the first world at the bottom, the way the map reads.
+- Each stop is `done`, `here` or `ahead`, and can show how many surprises are still hidden there. Give each a full `ariaLabel`, since the visible label is only a short word.
+- The compass at the top jumps to what's next.
+- On a phone, pass `phone`. The dock folds into the compass, with a count of the hidden surprises, and opens when it's tapped. Keep `open` in your state, and close it from `onClose`.
+- It sits against the right side of the window, centred, and its layout follows the window. Set `contained` to place it in a positioned box.

package/components/toolbar/Toolbar.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+/**
+ * The bar along the bottom of the map: two tabs with the big Next button between them, floating over the window, centred.
+ * @startingPoint section="Toolbar" subtitle="Two tabs and a big Next button" viewport="700x260"
+ */
+export interface ToolbarProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  /** The accessible name. Default "Adventure tools". */
+  label?: string;
+  /** Sits inside a positioned box instead of covering the window. */
+  contained?: boolean;
+  /** ToolbarTabs on either side of a ToolbarNext. */
+  children?: React.ReactNode;
+}
+
+export function Toolbar(props: ToolbarProps): React.JSX.Element;

package/components/toolbar/Toolbar.jsx

@@ -0,0 +1,8 @@
+'use client';
+import React from 'react';
+
+/* The bar along the bottom of the map: two tabs with a big Next button between them. It floats over the window, centred.
+   Set `contained` to place it in a positioned box instead. */
+export function Toolbar({ label = 'Adventure tools', contained = false, children, ...rest }) {
+  return <nav className={'mp-toolbar' + (contained ? ' mp-toolbar-contained' : '')} aria-label={label} {...rest}>{children}</nav>;
+}

package/components/toolbar/Toolbar.prompt.md

@@ -0,0 +1,14 @@
+Toolbar: the three things always within reach on the map.
+
+```jsx
+<Toolbar>
+  <ToolbarTab icon="users-three" label="Your people" onClick={openPeople} />
+  <ToolbarNext aria-label="Next, level 7" onClick={openNext}>7</ToolbarNext>
+  <ToolbarTab icon="list" weight="bold" label="Menu" onClick={openMenu} />
+</Toolbar>
+```
+
+- Two `ToolbarTab`s and one `ToolbarNext` in the middle. The Next button rises above the bar.
+- It floats at the bottom of the window, centred, and gets smaller on phones. Its layout follows the window, not its box.
+- Set `contained` to place it in a positioned box.
+- The fast-travel dock is separate: see `FastTravelDock`.

package/components/toolbar/ToolbarNext.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+/**
+ * The big round button in the middle of the toolbar. It shows what's next, such as a level number, a padlock or an envelope. While the road rearranges itself it's busy and can't be pressed, and once the letter is ready it turns gold.
+ * @startingPoint section="Toolbar" subtitle="The big Next button, in each of its moods" viewport="700x200"
+ */
+export interface ToolbarNextProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** The small word above the value. Default "Next". */
+  caption?: string;
+  /** Gold, with a glow, for the letter. */
+  gold?: boolean;
+  /** Cream, for while the road rearranges itself. Not a button then, and hidden from screen readers. */
+  busy?: boolean;
+  /** Stone, for when there's nothing to open. */
+  disabled?: boolean;
+  onClick?: () => void;
+  /** The value: a number, or an icon such as a padlock, an envelope or an hourglass. */
+  children?: React.ReactNode;
+}
+
+export function ToolbarNext(props: ToolbarNextProps): React.JSX.Element;

package/components/toolbar/ToolbarNext.jsx

@@ -0,0 +1,21 @@
+'use client';
+import React from 'react';
+
+/* The big round button in the middle of the toolbar. It shows what's next, such as a level number, a padlock or an envelope.
+   While the road rearranges itself it's `busy` and can't be pressed. Once the letter is ready it turns `gold`. */
+export function ToolbarNext({ caption = 'Next', gold = false, busy = false, disabled = false, onClick, children, ...rest }) {
+  if (busy) {
+    return (
+      <span className="mp-next mp-next-busy" aria-hidden="true" {...rest}>
+        <small>{caption}</small>
+        <b>{children}</b>
+      </span>
+    );
+  }
+  return (
+    <button type="button" className={'mp-next' + (gold ? ' mp-next-gold' : '')} onClick={onClick} disabled={disabled} {...rest}>
+      <small>{caption}</small>
+      <b>{children}</b>
+    </button>
+  );
+}

package/components/toolbar/ToolbarNext.prompt.md

@@ -0,0 +1,13 @@
+Toolbar next: the one big button, so the next thing is always obvious.
+
+```jsx
+<ToolbarNext aria-label="Next, level 7" onClick={openNext}>7</ToolbarNext>
+<ToolbarNext caption="Your" gold aria-label="Your letter" onClick={openLetter}><i className="ph-fill ph-envelope-simple" /></ToolbarNext>
+<ToolbarNext busy><i className="ph-fill ph-hourglass" /></ToolbarNext>
+<ToolbarNext disabled aria-label="Nothing to open yet"><i className="ph-fill ph-lock-simple" /></ToolbarNext>
+```
+
+- Give it an `aria-label` that says what it opens. The visible number alone doesn't.
+- It nudges every few seconds to say "this one". The nudge stops when it's pressed, disabled or busy, and with reduced motion.
+- `busy` is for the moments the road rearranges itself, when there's nothing to press. It isn't a button then.
+- `gold` is for the summit letter, once it's ready.

package/components/toolbar/ToolbarTab.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/**
+ * A tab on the toolbar: a round icon and a short label.
+ * @startingPoint section="Toolbar" subtitle="A toolbar tab" viewport="700x140"
+ */
+export interface ToolbarTabProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** A Phosphor icon name, such as "users-three". */
+  icon: string;
+  weight?: 'fill' | 'bold';
+  label: string;
+  onClick?: () => void;
+}
+
+export function ToolbarTab(props: ToolbarTabProps): React.JSX.Element;

package/components/toolbar/ToolbarTab.jsx

@@ -0,0 +1,12 @@
+'use client';
+import React from 'react';
+
+/* A tab on the toolbar: a round icon and a short label. */
+export function ToolbarTab({ icon, weight = 'fill', label, onClick, ...rest }) {
+  return (
+    <button type="button" className="mp-toolbar-tab" onClick={onClick} {...rest}>
+      <span className="mp-toolbar-tab-icon"><i className={'ph-' + weight + ' ph-' + icon} aria-hidden="true" /></span>
+      <span>{label}</span>
+    </button>
+  );
+}

package/components/toolbar/ToolbarTab.prompt.md

@@ -0,0 +1,9 @@
+Toolbar tab: a quiet button for something the player may want any time.
+
+```jsx
+<ToolbarTab icon="users-three" label="Your people" onClick={openPeople} />
+<ToolbarTab icon="list" weight="bold" label="Menu" onClick={openMenu} />
+```
+
+- Keep labels to one or two words. Use a shorter one on phones, such as "People".
+- Pressing it dips it down and tints it, the same way every other pressable moves.

package/components/viewer/ClueCard.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+/**
+ * The contributor's clue as a taped note over the screen. Pressing it puts it back.
+ * @startingPoint section="Viewer" subtitle="The clue as a taped note" viewport="700x200"
+ */
+export interface ClueCardProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  clue: string;
+  /** Small line above the clue. Default "Their clue". */
+  label?: string;
+  /** Line under the clue. Default "Tap to put it back". */
+  hint?: string;
+  /** Plays the leaving animation. */
+  leaving?: boolean;
+  onClick?: () => void;
+}
+
+export function ClueCard(props: ClueCardProps): React.JSX.Element;

package/components/viewer/ClueCard.jsx

@@ -0,0 +1,14 @@
+'use client';
+import React from 'react';
+
+/* The clue as a taped note over the screen. Pressing it puts it back. */
+export function ClueCard({ clue, label = 'Their clue', hint = 'Tap to put it back', leaving = false, onClick, ...rest }) {
+  return (
+    <button type="button" className={'mp-clue-card' + (leaving ? ' mp-clue-card-leaving' : '')} onClick={onClick} {...rest}>
+      <span className="mp-clue-tape" aria-hidden="true" />
+      <span className="mp-viewer-label">{label}</span>
+      <strong>{clue}</strong>
+      <em>{hint}</em>
+    </button>
+  );
+}

package/components/viewer/ClueCard.prompt.md

@@ -0,0 +1,9 @@
+Clue card: the clue, taped over the screen.
+
+```jsx
+{clueOpen && <ClueCard clue={clue} leaving={clueLeaving} onClick={hideClue} />}
+```
+
+- Place it in the viewer's `clueCard` slot, so it sits over the screen.
+- Set `leaving` for a moment before you remove it, so it fades instead of vanishing.
+- The clue is the contributor's own words. Show them as written.

package/components/viewer/ClueTab.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+/**
+ * The contributor's clue, parked as a tab on the cabinet. Pressing it calls the clue over the screen as a ClueCard. On narrow phones the tab just says "clue".
+ * @startingPoint section="Viewer" subtitle="The clue tab" viewport="700x120"
+ */
+export interface ClueTabProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** True while the clue card is out. */
+  open?: boolean;
+  /** The part that drops away on narrow phones. Default "Their ". */
+  prefix?: string;
+  label?: string;
+  onClick?: () => void;
+}
+
+export function ClueTab(props: ClueTabProps): React.JSX.Element;

package/components/viewer/ClueTab.jsx

@@ -0,0 +1,12 @@
+'use client';
+import React from 'react';
+
+/* The contributor's clue, parked as a tab on the cabinet. Pressing it calls the clue over the screen. */
+export function ClueTab({ open = false, prefix = 'Their ', label = 'clue', onClick, ...rest }) {
+  return (
+    <button type="button" className={'mp-clue-tab' + (open ? ' mp-clue-tab-on' : '')} aria-expanded={open} onClick={onClick} {...rest}>
+      <i className="ph-fill ph-push-pin" aria-hidden="true" />
+      <span><span className="mp-clue-tab-their">{prefix}</span>{label}</span>
+    </button>
+  );
+}

package/components/viewer/ClueTab.prompt.md

@@ -0,0 +1,8 @@
+Clue tab: where the contributor's clue waits until it's wanted.
+
+```jsx
+{clue && <ClueTab open={clueOpen} onClick={toggleClue} />}
+```
+
+- Only show it when the contributor wrote a clue.
+- It reports `aria-expanded`, so it works as a disclosure for the `ClueCard`.

package/components/viewer/RevealTray.d.ts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+
+export interface RevealIdentity {
+  name: string;
+  /** e.g. "Sister", "Friend from uni". */
+  relationship?: string;
+  /** Portrait URL. The avatar is generated when there's none. */
+  portrait?: string | null;
+  /** Stable id for the generated avatar. */
+  seed?: string;
+  gem: 'amber' | 'emerald' | 'amethyst' | 'pearl';
+  tier?: 1 | 2 | 3;
+}
+
+/**
+ * The guess tray, centred over the viewer: a mystery face that flips to the friend and their gem. Before the reveal the body is yours (a prompt, choices, a way out). After it, the tray shows who it was from, a line, and your actions, arriving one after the other.
+ * @startingPoint section="Viewer" subtitle="The guess tray, and the reveal" viewport="700x620"
+ */
+export interface RevealTrayProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  /** blue for a level, berry for a surprise beside the road, gold once it has been met. */
+  tone?: 'blue' | 'berry' | 'gold';
+  /** Flips the face to the friend and swaps the body. */
+  revealed?: boolean;
+  identity?: RevealIdentity;
+  /** Shakes the tray once, for a wrong guess. */
+  wobble?: boolean;
+  /** No flip, no confetti, no "You found them!": everything sits still, for a memory already opened. */
+  settled?: boolean;
+  /** Fades the tray out before you remove it. */
+  leaving?: boolean;
+  /** Celebration over the tray, such as confetti. */
+  celebrate?: React.ReactNode;
+  /** Accessible name. Defaults to "Who sent this?" and, once revealed, "Who it was from". */
+  label?: string;
+  /** The line after the name, such as "You found them!". Hidden when settled. */
+  message?: string;
+  /** Buttons shown after the reveal. */
+  actions?: React.ReactNode;
+  /** An error shown at the bottom of the tray. */
+  error?: string;
+  /** Called when the dim area around the tray is pressed. */
+  onBackdrop?: () => void;
+  innerRef?: React.Ref<HTMLElement>;
+  /** The body before the reveal. */
+  children?: React.ReactNode;
+}
+
+export function RevealTray(props: RevealTrayProps): React.JSX.Element;
+
+export function TrayPrompt(props: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
+export function TrayHint(props: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
+export function TrayChoices(props: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export function TrayClue(props: React.HTMLAttributes<HTMLDivElement> & { label?: string }): React.JSX.Element;
+export function TrayLink(props: React.ButtonHTMLAttributes<HTMLButtonElement> & { back?: boolean }): React.JSX.Element;

package/components/viewer/RevealTray.jsx

@@ -0,0 +1,58 @@
+'use client';
+import React from 'react';
+import { Avatar } from '../identity/Avatar';
+import { Gemstone } from '../identity/Gemstone';
+
+/* Small pieces for the tray's body, before the reveal. */
+export const TrayPrompt = ({ children, ...rest }) => <p className="mp-tray-prompt" {...rest}>{children}</p>;
+export const TrayHint = ({ children, ...rest }) => <p className="mp-tray-hint" {...rest}>{children}</p>;
+export const TrayChoices = ({ children, ...rest }) => <div className="mp-tray-choices" {...rest}>{children}</div>;
+export const TrayClue = ({ label = 'Their clue', children, ...rest }) => (
+  <div className="mp-tray-clue" {...rest}><span className="mp-clue-tape" aria-hidden="true" /><span className="mp-viewer-label">{label}</span>{children}</div>
+);
+export const TrayLink = ({ back = false, children, ...rest }) => <button type="button" className={'mp-tray-link' + (back ? ' mp-tray-back' : '')} {...rest}>{children}</button>;
+
+/* The guess tray, centred over the viewer. A mystery face on top flips over to the friend and their gem. Before the
+   reveal the body is yours (a prompt, choices, a way out). After it, the tray shows who it was from, then a line and
+   your actions, one after the other. Render it only while it's open; set `leaving` to fade it out before you remove it. */
+export function RevealTray({ tone = 'blue', revealed = false, identity, wobble = false, settled = false, leaving = false, celebrate, label, message, actions, error, onBackdrop, innerRef, children, ...rest }) {
+  return (
+    <div className={'mp-tray-layer' + (leaving ? ' mp-tray-layer-leaving' : '')} onClick={e => { if (onBackdrop && e.target === e.currentTarget) onBackdrop(); }}>
+      {/* The entrance lives on this wrapper, so a wrong-guess wobble on the tray never replays it. */}
+      <div className={'mp-tray-in' + (leaving ? ' mp-tray-in-leaving' : '')}>
+        <aside ref={innerRef} tabIndex={-1} className={'mp-tray mp-tray-' + tone + (wobble ? ' mp-tray-wobble' : '') + (settled ? ' mp-tray-settled' : '')} aria-live="polite"
+          aria-label={label || (revealed ? 'Who it was from' : 'Who sent this?')} {...rest}>
+          <div className="mp-tray-face">
+            <span className={'mp-tray-flip' + (revealed ? ' mp-tray-flipped' : '')}>
+              <span className="mp-tray-face-front"><Avatar mystery size={104} /></span>
+              <span className="mp-tray-face-back">
+                {revealed && identity && (
+                  <>
+                    <Avatar name={identity.name} seed={identity.seed} src={identity.portrait || undefined} size={104} alt="" />
+                    <Gemstone gem={identity.gem} tier={identity.tier ?? 1} size={44} decorative className="mp-tray-gem" />
+                  </>
+                )}
+              </span>
+            </span>
+          </div>
+          {celebrate}
+          <div className="mp-tray-body">
+            {!revealed && children}
+            {revealed && identity && (
+              <>
+                <div className="mp-tray-whowas">
+                  <span className="mp-viewer-label mp-beat-1">From</span>
+                  <span className="mp-tray-name mp-beat-1">{identity.name}</span>
+                  {identity.relationship && <span className="mp-tray-relationship mp-beat-2">{identity.relationship}</span>}
+                </div>
+                {message && !settled && <p className="mp-tray-prompt mp-beat-3">{message}</p>}
+                {actions && <div className="mp-tray-actions mp-beat-4">{actions}</div>}
+              </>
+            )}
+            {error && <p role="alert" className="mp-viewer-error">{error}</p>}
+          </div>
+        </aside>
+      </div>
+    </div>
+  );
+}