lanre-ds 0.0.0-stage → 0.2.0

package/components/map/StarRating.jsx

@@ -0,0 +1,21 @@
+'use client';
+import React from 'react';
+
+export function StarRating({ value = 0, max = 3, size = 28, arc = false, animate = false, gap, style, ...rest }) {
+  const stars = [];
+  for (let i = 0; i < max; i++) {
+    const on = i < value;
+    const mid = arc && max % 2 === 1 && i === Math.floor(max / 2);
+    const side = arc && !mid ? (i < max / 2 ? -1 : 1) : 0;
+    const s = mid ? size * 1.35 : size;
+    stars.push(
+      <span key={i} aria-hidden="true" style={{ display: 'grid', placeItems: 'center', width: s, height: s, lineHeight: 1,
+        transform: arc ? 'translateY(' + (mid ? -size * 0.35 : 0) + 'px) rotate(' + (side * 14) + 'deg)' : 'none',
+        filter: 'drop-shadow(0 2px 0 oklch(0 0 0 / 0.22))', animation: animate && on ? 'mp-pop var(--dur-slow) var(--ease-bounce) both ' + (i * 140) + 'ms' : 'none' }}>
+        <i className="ph-fill ph-star" style={{ fontSize: s, lineHeight: 1, color: on ? 'var(--gold-500)' : 'var(--stone-300)',
+          WebkitTextStroke: (s * 0.1) + 'px ' + (on ? 'var(--gold-700)' : 'var(--stone-700)'), paintOrder: 'stroke fill' }} />
+      </span>
+    );
+  }
+  return <span role="img" aria-label={value + ' of ' + max + ' stars'} style={{ display: 'inline-flex', alignItems: 'flex-end', gap: gap == null ? Math.round(size * 0.05) : gap, ...style }} {...rest}>{stars}</span>;
+}

package/components/map/StarRating.prompt.md

@@ -0,0 +1,6 @@
+Star rating: level results on the map, on the level-complete ribbon, in progress lists. Always out of 3.
+
+```jsx
+<StarRating value={2} size={22} />
+<StarRating value={3} size={44} arc animate />
+```

package/components/map/Tile.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+
+/**
+ * 3D board tile (rounded square with a solid side) for grid/path boards; variants tint the tile by terrain or purpose.
+ * @startingPoint section="Map" subtitle="Terrain tiles: grass, sand, stone, water, reward, hazard, start" viewport="700x180"
+ */
+export interface TileProps extends Omit<React.HTMLAttributes<HTMLElement>, 'style' | 'content'> {
+  variant?: 'grass' | 'sand' | 'stone' | 'water' | 'reward' | 'hazard' | 'start';
+  /** Tile width in px. Default 64. */
+  size?: number;
+  /** Centered content: a GameIcon, a number, a piece. Text renders outlined in display type. */
+  content?: React.ReactNode;
+  /** Gold glow ring: reachable / selected tile. */
+  active?: boolean;
+  /** Makes the tile a button. */
+  onClick?: () => void;
+  /** Accessible name when clickable. */
+  label?: string;
+  style?: React.CSSProperties;
+}
+
+export function Tile(props: TileProps): React.JSX.Element;

package/components/map/Tile.jsx

@@ -0,0 +1,32 @@
+'use client';
+import React, { useState } from 'react';
+
+const VARIANTS = {
+  // [top, face, side, text stroke]
+  grass:  ['var(--green-300)', 'var(--green-500)', 'var(--green-700)', 'var(--green-900)'],
+  sand:   ['var(--cream-50)',  'var(--cream-200)', 'var(--wood-300)',  'var(--wood-700)'],
+  stone:  ['var(--stone-100)', 'var(--stone-300)', 'var(--stone-500)', 'var(--stone-700)'],
+  water:  ['var(--blue-100)',  'var(--blue-300)',  'var(--blue-500)',  'var(--blue-700)'],
+  reward: ['var(--gold-300)',  'var(--gold-500)',  'var(--gold-700)',  'var(--gold-900)'],
+  hazard: ['var(--berry-300)', 'var(--berry-500)', 'var(--berry-700)', 'var(--berry-900)'],
+  start:  ['var(--teal-300)',  'var(--teal-500)',  'var(--teal-700)',  'var(--teal-900)'],
+};
+
+export function Tile({ variant = 'grass', size = 64, content, active = false, onClick, label, style, ...rest }) {
+  const [down, setDown] = useState(false);
+  const [top, mid, side, stroke] = VARIANTS[variant] || VARIANTS.grass;
+  const depth = Math.round(size * 0.16);
+  const lift = down && onClick ? Math.round(depth * 0.4) : depth;
+  const Tag = onClick ? 'button' : 'div';
+  return (
+    <Tag type={onClick ? 'button' : undefined} onClick={onClick} aria-label={label} onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', border: 0, margin: 0, padding: 0, background: 'none', cursor: onClick ? 'pointer' : 'default', position: 'relative', display: 'inline-block', width: size, height: Math.round(size * 0.82) + depth, flex: 'none', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      <span aria-hidden="true" style={{ position: 'absolute', left: 0, right: 0, top: depth - lift, height: Math.round(size * 0.82), borderRadius: Math.round(size * 0.28), boxSizing: 'border-box',
+        background: 'linear-gradient(180deg, ' + top + ', ' + mid + ' 70%)', border: '3px solid ' + top,
+        boxShadow: '0 ' + lift + 'px 0 ' + side + ', 0 ' + (lift + 4) + 'px 10px oklch(0.2 0.05 60 / 0.3)' + (active ? ', 0 0 0 4px oklch(0.92 0.14 90 / 0.9), 0 0 24px oklch(0.86 0.17 85 / 0.8)' : ''),
+        transition: 'top var(--dur-fast), box-shadow var(--dur-fast)', display: 'grid', placeItems: 'center' }}>
+        <span style={{ display: 'grid', placeItems: 'center', fontFamily: 'var(--font-display)', color: '#fff', fontSize: Math.round(size * 0.36), lineHeight: 1, WebkitTextStroke: Math.round(size * 0.05) + 'px ' + stroke, paintOrder: 'stroke fill' }}>{content}</span>
+      </span>
+    </Tag>
+  );
+}

package/components/map/Tile.prompt.md

@@ -0,0 +1,8 @@
+Board tile: for dice/board expeditions and grid puzzles. Lay tiles in a CSS grid; leave 6–8px gaps so the sides read.
+
+```jsx
+<Tile variant="sand" content="?" />
+<Tile variant="reward" content={<GameIcon kind="coin" size={30} />} active onClick={pick} label="Coin tile" />
+<Tile variant="hazard" content={<GameIcon name="skull" tone="white" size={28} />} />
+<Tile variant="water" size={56} />
+```

package/components/map/WorldGate.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+/**
+ * The sign that marks where a world starts on the map: a plank on two posts, tinted with the world's accent, with its glyph, its name and a count. An optional button underneath opens the author's note for that world.
+ * @startingPoint section="Map" subtitle="The sign at the start of a world" viewport="700x380"
+ */
+export interface WorldGateProps extends React.HTMLAttributes<HTMLDivElement> {
+  world?: 'mango_grove' | 'small_chops' | 'good_energy' | 'japan' | 'summit';
+  /** Overrides the world's display name. */
+  name?: string;
+  /** Overrides the world's glyph, a Phosphor icon name. */
+  glyph?: string;
+  /** The line under the name, such as "4 memories" or "Surprises only". Leave it out for none. */
+  detail?: string;
+  /** Shows a "note" button under the sign. Called when it's pressed. */
+  onNote?: () => void;
+  /** Label on the note button. Default "A note from the author". */
+  noteLabel?: string;
+}
+
+export function WorldGate(props: WorldGateProps): React.JSX.Element;

package/components/map/WorldGate.jsx

@@ -0,0 +1,27 @@
+'use client';
+import React from 'react';
+import { WORLDS } from './worlds.js';
+
+/* The sign that marks where a world starts on the map: a plank on two posts, the world's name and a count. Place it
+   absolutely on the map (it centres itself on `left` and stands on `top`), and set its `width` from the caller. */
+export function WorldGate({ world = 'mango_grove', name, glyph, detail, onNote, noteLabel = 'A note from the author', ...rest }) {
+  const W = WORLDS[world] || WORLDS.mango_grove;
+  return (
+    <div className="mp-gate" {...rest}>
+      <div className="mp-gate-sign" data-world={world}>
+        <span className="mp-gate-post" aria-hidden="true" />
+        <span className="mp-gate-post" aria-hidden="true" />
+        <h2 className="mp-gate-title">
+          <i className={'ph-fill ph-' + (glyph || W.glyph)} aria-hidden="true" />
+          {name || W.name}
+        </h2>
+        {detail && <span className="mp-gate-count">{detail}</span>}
+      </div>
+      {onNote && (
+        <button type="button" className="mp-gate-note" onClick={onNote}>
+          <i className="ph-fill ph-envelope-simple" aria-hidden="true" /> {noteLabel}
+        </button>
+      )}
+    </div>
+  );
+}

package/components/map/WorldGate.prompt.md

@@ -0,0 +1,13 @@
+World gate: the sign where the road enters a world. Place one at each world's boundary on the map.
+
+```jsx
+<div style={{ position: 'relative', height: 360 }}>
+  <WorldGate world="small_chops" detail="4 memories" onNote={() => openNote('small_chops')} style={{ left: 190, top: 220, width: 300 }} />
+</div>
+```
+
+- Position it from the caller. It sits at `left` and `top` of its box, centres itself on `left`, and stands on `top`, so the posts reach the ground. Set `width` from the caller as well. Around 230 to 340 works.
+- The sign sets `data-world`, so the plank takes that world's accent, and its own outline colour.
+- The count under the name is your call. A world with nothing in it can say "Surprises only".
+- Pass `onNote` only when the author has written a note for that world. If there's no note, there's no button.
+- The container ignores pointer events so it never blocks the map. Only the note button takes taps.

package/components/map/worlds.d.ts

@@ -0,0 +1,18 @@
+export type WorldId = 'mango_grove' | 'small_chops' | 'good_energy' | 'japan' | 'summit';
+
+export interface WorldInfo {
+  id: WorldId;
+  /** The display name. */
+  name: string;
+  /** A Phosphor icon name without the prefix. */
+  glyph: string;
+  /** One line on what belongs in this world. */
+  blurb: string;
+  /** A short note on the scenery, for people drawing it. */
+  scenery: string;
+}
+
+/** Every world by id. The ids match the data contract. */
+export const WORLDS: Record<WorldId, WorldInfo>;
+/** The order the worlds appear along the road. */
+export const WORLD_ORDER: WorldId[];

package/components/map/worlds.js

@@ -0,0 +1,9 @@
+// Shared world metadata for the Birthday Adventure (ids match the data contract). Glyphs are Phosphor names.
+export const WORLDS = {
+  mango_grove: { id: 'mango_grove', name: 'Mango Grove', glyph: 'orange', blurb: 'First impressions, meeting, early memories', scenery: 'Sunny mango orchard' },
+  small_chops: { id: 'small_chops', name: 'Small Chops, Big Gist', glyph: 'bowl-food', blurb: 'Funny stories, inside jokes, outings', scenery: 'Restaurants, rice, lively stalls' },
+  good_energy: { id: 'good_energy', name: 'The Good Energy Hills', glyph: 'barbell', blurb: 'Appreciation, support, showing up', scenery: 'Green hills with gentle workout details' },
+  japan: { id: 'japan', name: 'Someday in Japan', glyph: 'lamp-pendant', blurb: 'Wishes, future adventures, hopes', scenery: 'Lanterns, gardens, distant mountain' },
+  summit: { id: 'summit', name: 'The Summit', glyph: 'envelope', blurb: 'The author’s letter', scenery: 'Golden hour above the clouds' },
+};
+export const WORLD_ORDER = ['mango_grove', 'small_chops', 'good_energy', 'japan', 'summit'];

package/components/media/Album.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+
+export interface AlbumPhoto {
+  src?: string;
+  /** Alt text. Falls back to "Photo n". */
+  alt?: string;
+  caption?: string;
+  /** The photo's own size in px. Used for its shape until it loads, then the file's own size wins. */
+  width?: number;
+  height?: number;
+  /** Stable key. Defaults to `src`. */
+  id?: string;
+}
+
+/**
+ * Photos in a box, one at a time on a tilted polaroid, at their own shape. A strip of thumbnails jumps around, arrows and swipes page through, and tapping a photo opens it full screen in a lightbox.
+ * @startingPoint section="Media" subtitle="Photos, a strip and a lightbox" viewport="700x520"
+ */
+export interface AlbumProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Photos without a `src` are skipped. If none have one, the album shows an Unavailable card. */
+  photos: AlbumPhoto[];
+  /** The photo on show. Leave it out and the album keeps its own place. */
+  index?: number;
+  onIndex?: (index: number) => void;
+  /** A photo failed to load, or Try again was pressed on the Unavailable card. */
+  onError?: () => void;
+  /** Called with "tick" when paging and "tap" when opening a photo, so you can play a sound. */
+  onSound?: (name: 'tick' | 'tap') => void;
+  /** Where the lightbox is drawn. Default `document.body`. Pass an element inside a themed wrapper if your tokens are scoped. */
+  lightboxRoot?: HTMLElement | null;
+}
+
+export function Album(props: AlbumProps): React.JSX.Element;

package/components/media/Album.jsx

@@ -0,0 +1,157 @@
+'use client';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { reduceMotion, useLoaded } from './shared.js';
+import { Unavailable } from './Unavailable';
+
+const shapeOf = p => (p.width && p.height ? { w: p.width, h: p.height } : null);
+const shapeVars = (s, caption) => ({ '--w': s ? s.w : 4, '--h': s ? s.h : 3, '--cap': caption ? '34px' : '0px' });
+const keyOf = p => p.id ?? p.src;
+
+function Lightbox({ photos, index, onIndex, onClose, root }) {
+  const b = photos[index];
+  const close = useRef(null);
+  const [leaving, setLeaving] = useState(false);
+  const step = useCallback(d => onIndex(Math.max(0, Math.min(photos.length - 1, index + d))), [index, onIndex, photos.length]);
+  // Fade out before going, like every other sheet.
+  const leave = useCallback(() => {
+    if (reduceMotion()) return onClose();
+    setLeaving(true);
+    window.setTimeout(onClose, 180);
+  }, [onClose]);
+  useEffect(() => { if (close.current) close.current.focus(); }, []);
+  useEffect(() => {
+    // Capture phase, so Escape closes the photo and not whatever sheet is behind it. Every key it handles stops here:
+    // the lightbox sits inside the album in the React tree, so the album's own arrow keys would step a second time.
+    const onKey = e => {
+      if (e.key === 'Escape') { e.stopImmediatePropagation(); leave(); }
+      else if (e.key === 'ArrowLeft') { e.stopImmediatePropagation(); step(-1); }
+      else if (e.key === 'ArrowRight') { e.stopImmediatePropagation(); step(1); }
+    };
+    window.addEventListener('keydown', onKey, true);
+    return () => window.removeEventListener('keydown', onKey, true);
+  }, [leave, step]);
+  return createPortal(
+    <div className={'mp-lightbox' + (leaving ? ' mp-lightbox-leaving' : '')} role="dialog" aria-modal="true" aria-label={'Photo ' + (index + 1) + ' of ' + photos.length} onClick={leave}>
+      <img key={keyOf(b)} src={b.src} alt={b.alt || 'Photo ' + (index + 1)} />
+      {b.caption && <p className="mp-light-caption">{b.caption}</p>}
+      <button ref={close} type="button" className="mp-light-close" onClick={e => { e.stopPropagation(); leave(); }} aria-label="Close the photo">
+        <i className="ph-bold ph-x" aria-hidden="true" />
+      </button>
+      {photos.length > 1 && (
+        <>
+          <button type="button" className="mp-album-arrow mp-album-arrow-prev" disabled={index === 0} onClick={e => { e.stopPropagation(); step(-1); }} aria-label="Previous photo">
+            <i className="ph-bold ph-caret-left" aria-hidden="true" />
+          </button>
+          <button type="button" className="mp-album-arrow mp-album-arrow-next" disabled={index === photos.length - 1} onClick={e => { e.stopPropagation(); step(1); }} aria-label="Next photo">
+            <i className="ph-bold ph-caret-right" aria-hidden="true" />
+          </button>
+        </>
+      )}
+    </div>,
+    root || document.body,
+  );
+}
+
+/* One photo at a time, at its own shape, with a strip to jump around. Tap the photo to see it full screen.
+   Fills the box it sits in (position: absolute; inset: 0), so put it in a positioned box with a size. */
+export function Album({ photos: all = [], index: controlled, onIndex, onError, onSound, lightboxRoot, ...rest }) {
+  const photos = useMemo(() => all.filter(p => p.src), [all]);
+  const [own, setOwn] = useState(0);
+  const index = controlled === undefined ? own : controlled;
+  const at = Math.min(index, Math.max(0, photos.length - 1));
+  const [natural, setNatural] = useState({});
+  const [zoomed, setZoomed] = useState(false);
+  const strip = useRef(null);
+  const touch = useRef(null);
+  const many = photos.length > 1;
+  const { loaded: photoLoaded, done: photoDone, checkImage } = useLoaded(photos[at] && photos[at].src);
+  // A server-rendered photo can arrive before React is listening for its load, so read its size from the element too.
+  const photoRef = useCallback(el => {
+    checkImage(el);
+    if (el && el.complete && el.naturalWidth > 0) {
+      const w = el.naturalWidth, h = el.naturalHeight, k = keyOf(photos[at]);
+      setNatural(n => (n[k] && n[k].w === w && n[k].h === h ? n : { ...n, [k]: { w, h } }));
+    }
+  }, [checkImage, photos, at]);
+
+  const go = useCallback(i => {
+    const to = Math.max(0, Math.min(photos.length - 1, i));
+    if (to === Math.min(index, photos.length - 1)) return;
+    if (onSound) onSound('tick');
+    setOwn(to);
+    if (onIndex) onIndex(to);
+  }, [index, onIndex, onSound, photos.length]);
+
+  useEffect(() => {
+    const el = strip.current;
+    const thumb = el && el.children[at];
+    if (!el || !thumb) return;
+    el.scrollTo({ left: thumb.offsetLeft - el.clientWidth / 2 + thumb.clientWidth / 2, behavior: reduceMotion() ? 'auto' : 'smooth' });
+  }, [at]);
+
+  // Fetch the neighbours ahead so the next photo is there when it's tapped.
+  useEffect(() => {
+    for (const n of [photos[at + 1], photos[at - 1]]) { if (n && n.src) new window.Image().src = n.src; }
+  }, [at, photos]);
+
+  if (!photos.length) return <Unavailable what={all.length > 1 ? 'set of photos' : 'photo'} onRetry={onError} />;
+  const b = photos[at];
+  // The file's own size wins once it has loaded: it knows about phone photos saved on their side.
+  const shape = natural[keyOf(b)] || shapeOf(b);
+
+  const arrows = [
+    <button key="prev" type="button" className="mp-album-arrow mp-album-arrow-prev" disabled={at === 0} onClick={() => go(at - 1)} aria-label="Previous photo">
+      <i className="ph-bold ph-caret-left" aria-hidden="true" />
+    </button>,
+    <button key="next" type="button" className="mp-album-arrow mp-album-arrow-next" disabled={at === photos.length - 1} onClick={() => go(at + 1)} aria-label="Next photo">
+      <i className="ph-bold ph-caret-right" aria-hidden="true" />
+    </button>,
+  ];
+
+  return (
+    <div className="mp-album" onKeyDown={e => { if (e.key === 'ArrowLeft') go(at - 1); else if (e.key === 'ArrowRight') go(at + 1); }} {...rest}>
+      <div className="mp-album-frame"
+        onTouchStart={e => { touch.current = e.touches[0].clientX; }}
+        onTouchEnd={e => {
+          const from = touch.current;
+          touch.current = null;
+          if (from === null || !many) return;
+          const dx = e.changedTouches[0].clientX - from;
+          if (Math.abs(dx) > 40) go(at + (dx < 0 ? 1 : -1));
+        }}>
+        <figure key={keyOf(b)} className="mp-polaroid" style={{ ...shapeVars(shape, Boolean(b.caption)), '--tilt': (at % 2 ? 1.5 : -1.5) + 'deg' }}>
+          <button type="button" className="mp-photo-button mp-media" data-loaded={photoLoaded} onClick={() => { if (onSound) onSound('tap'); setZoomed(true); }} aria-label="See this photo full screen">
+            <span className="mp-shimmer mp-on-cream" aria-hidden="true" />
+            <img ref={photoRef} src={b.src} alt={b.alt || (many ? 'Photo ' + (at + 1) : 'A photo from this memory')}
+              onLoad={e => {
+                photoDone();
+                const { naturalWidth: w, naturalHeight: h } = e.currentTarget;
+                const k = keyOf(b);
+                if (w && h) setNatural(n => (n[k] && n[k].w === w && n[k].h === h ? n : { ...n, [k]: { w, h } }));
+              }}
+              onError={onError} />
+            <span className="mp-photo-zoom" aria-hidden="true"><i className="ph-bold ph-arrows-out-simple" /></span>
+          </button>
+          {b.caption && <figcaption>{b.caption}</figcaption>}
+        </figure>
+        {many && <>{arrows}</>}
+      </div>
+      {many && (
+        <div className="mp-strip-row">
+          {/* On a phone the arrows live down here, clear of the photo. */}
+          {arrows}
+          <div ref={strip} className="mp-album-strip">
+            {photos.map((p, i) => (
+              <button key={keyOf(p)} type="button" className={'mp-album-thumb' + (i === at ? ' mp-album-thumb-on' : '')} onClick={() => go(i)} aria-label={'Photo ' + (i + 1)} aria-current={i === at ? 'true' : undefined}>
+                <img src={p.src} alt="" loading="lazy" />
+              </button>
+            ))}
+          </div>
+          <span className="mp-album-count">{at + 1} / {photos.length}</span>
+        </div>
+      )}
+      {zoomed && <Lightbox photos={photos} index={at} onIndex={go} onClose={() => setZoomed(false)} root={lightboxRoot} />}
+    </div>
+  );
+}

package/components/media/Album.prompt.md

@@ -0,0 +1,16 @@
+Album: photos in a box, one at a time. Give it a positioned box with a size. It fills that box.
+
+```jsx
+<div style={{ position: 'relative', height: 520, containerType: 'size' }}>
+  <Album photos={photos} index={at} onIndex={setAt} onError={refresh} onSound={play} />
+</div>
+```
+
+- Each photo sits on a slightly tilted polaroid at its own shape, so tall screenshots and square pictures don't get cropped. Pass `width` and `height` when you know them. The file's own size wins once it loads.
+- With more than one photo, a strip of thumbnails sits underneath. Arrows, the arrow keys and a swipe all page through. The next and previous photos load ahead of time.
+- Tapping a photo opens it full screen in a lightbox. Escape closes the photo and not the sheet behind it.
+- A photo shows a shimmer until it arrives, then fades in.
+- Photos without a `src` are skipped. If none are left, an `Unavailable` card shows, and `onError` is its Try again.
+- The lightbox is drawn on `document.body`. If your tokens are scoped to a wrapper, pass `lightboxRoot` so it gets them.
+- Never auto-play or auto-advance. Paging is always the viewer's call.
+- Use neutral captions, never the sender.

package/components/media/Cassette.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+/**
+ * A voice note as a cassette: two reels that spin while it plays, a wave, a play button, a seek bar and the time. Never plays by itself, and it stays put when it ends.
+ * @startingPoint section="Media" subtitle="Voice note on a cassette" viewport="700x340"
+ */
+export interface CassetteProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** Audio URL. Without one, an Unavailable card shows. */
+  src?: string;
+  /** Label on the tape. Default "Voice note". Keep it neutral during a mystery, never the sender's name. */
+  title?: string;
+  /** Length in seconds, shown until the file reports its own. Recordings often report nothing until played through. */
+  duration?: number;
+  /** A line under the cassette. */
+  heading?: string;
+  /** A smaller line under the heading. */
+  hint?: string;
+  onError?: () => void;
+  /** Called with "tap" when the play button is pressed, so you can play a sound. */
+  onSound?: (name: 'tap') => void;
+}
+
+export function Cassette(props: CassetteProps): React.JSX.Element;

package/components/media/Cassette.jsx

@@ -0,0 +1,64 @@
+'use client';
+import React, { useEffect, useRef, useState } from 'react';
+import { clock, finite } from './shared.js';
+import { Unavailable } from './Unavailable';
+
+/* A voice note as a cassette: two reels that spin while it plays, a wave, a play button and a seek bar. */
+export function Cassette({ src, title = 'Voice note', duration = 0, heading, hint, onError, onSound, ...rest }) {
+  const audio = useRef(null);
+  const [playing, setPlaying] = useState(false);
+  const [t, setT] = useState(0);
+  const [dur, setDur] = useState(duration);
+  // A server-rendered audio element can know its length before React is listening.
+  useEffect(() => {
+    const a = audio.current;
+    if (a && a.readyState >= 1) setDur(finite(a.duration) || duration);
+  }, [src, duration]);
+  if (!src) return <Unavailable what="voice note" onRetry={onError} />;
+
+  const known = e => setDur(finite(e.currentTarget.duration) || duration);
+  const toggle = () => {
+    const a = audio.current;
+    if (!a) return;
+    if (onSound) onSound('tap');
+    if (a.paused) a.play().catch(() => setPlaying(false));
+    else a.pause();
+  };
+  const pct = dur ? Math.min(100, (t / dur) * 100) : 0;
+
+  return (
+    <div className={'mp-tape-deck' + (playing ? ' mp-playing' : '')} {...rest}>
+      <audio ref={audio} src={src} preload="metadata" onLoadedMetadata={known} onDurationChange={known}
+        onTimeUpdate={e => setT(e.currentTarget.currentTime)} onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onEnded={() => setPlaying(false)} onError={onError} />
+      <div className="mp-cassette">
+        <div className="mp-cassette-label">
+          <span>{title}</span>
+          <span>{dur ? clock(dur) : ''}</span>
+        </div>
+        <div className="mp-reels" aria-hidden="true">
+          <span className="mp-reel" />
+          <span className="mp-wave">
+            {Array.from({ length: 22 }, (_, i) => (
+              <i key={i} style={{ '--bar': Math.round(10 + Math.abs(Math.sin(i * 1.7)) * 30) + 'px', '--delay': (i % 7) * -120 + 'ms' }} />
+            ))}
+          </span>
+          <span className="mp-reel" />
+        </div>
+        <div className="mp-transport">
+          <button type="button" className="mp-cassette-play" onClick={toggle} aria-label={playing ? 'Pause' : 'Play'}>
+            <i className={'ph-fill ph-' + (playing ? 'pause' : 'play')} aria-hidden="true" />
+          </button>
+          <span className="mp-seek">
+            <span className="mp-seek-bar"><b style={{ width: pct + '%' }} /></span>
+            <input type="range" min={0} max={dur || 1} step={0.1} value={t}
+              onChange={e => { const to = Number(e.target.value); setT(to); if (audio.current) audio.current.currentTime = to; }}
+              aria-label="Seek the voice note" />
+          </span>
+          <span className="mp-cassette-time">{clock(t)}</span>
+        </div>
+      </div>
+      {heading && <h4 className="mp-tape-heading">{heading}</h4>}
+      {hint && <p className="mp-tape-hint">{hint}</p>}
+    </div>
+  );
+}

package/components/media/Cassette.prompt.md

@@ -0,0 +1,13 @@
+Cassette: a voice note. Give it an audio URL and it does the rest.
+
+```jsx
+<Cassette src={note.url} duration={note.seconds} heading="A voice note" hint="Tap play when you're ready" onError={refresh} onSound={play} />
+<Cassette src={song.url} title="Song for you" heading="Listen" />
+```
+
+- Nothing plays until the play button is pressed. When it ends, it stays at the end, paused. The viewer taps Continue themselves.
+- The reels and the wave move only while it plays. With reduced motion they stay still.
+- `duration` shows until the file reports its own. Recordings made in a browser often report no length until they've been played through, and the seek bar waits for one.
+- The seek bar is a real slider, so it works with a keyboard and a screen reader.
+- Keep `title` neutral during a mystery, never the sender's name. A spoken name in the recording itself is the contributor's call.
+- With no `src`, an `Unavailable` card shows instead.

package/components/media/Film.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+/**
+ * A video on a strip of film, with sprocket holes down the sides. It keeps its own shape, upright ones included, loads with a shimmer, and uses the browser's controls so full screen works on a phone.
+ * @startingPoint section="Media" subtitle="Video on a film strip" viewport="700x420"
+ */
+export interface FilmProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  /** Video URL. Without one, an Unavailable card shows. */
+  src?: string;
+  /** A neutral line under the film, never the sender. */
+  caption?: string;
+  /** The video's own size in px, used for its shape until it loads. Default 16 by 9. */
+  width?: number;
+  height?: number;
+  /** Pauses the video when it turns true, for when something else opens on top. */
+  paused?: boolean;
+  onError?: () => void;
+}
+
+export function Film(props: FilmProps): React.JSX.Element;

package/components/media/Film.jsx

@@ -0,0 +1,39 @@
+'use client';
+import React, { useEffect, useRef, useState } from 'react';
+import { useLoaded } from './shared.js';
+import { Unavailable } from './Unavailable';
+
+/* A video on a strip of film. It keeps its own shape, upright ones included, and uses the browser's own controls,
+   so full screen works on a phone. Fills the width of the box it sits in, which is a size container. */
+export function Film({ src, caption, width, height, paused = false, onError, ...rest }) {
+  const video = useRef(null);
+  const [natural, setNatural] = useState(null);
+  const { loaded, done } = useLoaded(src);
+  useEffect(() => { if (paused && video.current) video.current.pause(); }, [paused]);
+  // A server-rendered video can have its metadata before React is listening, and React doesn't replay that event.
+  useEffect(() => {
+    const el = video.current;
+    if (!el || el.readyState < 1) return;
+    done();
+    if (el.videoWidth && el.videoHeight) setNatural({ w: el.videoWidth, h: el.videoHeight });
+  }, [src, done]);
+  if (!src) return <Unavailable what="video" onRetry={onError} />;
+  const shape = natural || (width && height ? { w: width, h: height } : { w: 16, h: 9 });
+  return (
+    <figure className="mp-film" style={{ '--w': shape.w, '--h': shape.h, '--cap': caption ? '34px' : '0px' }} {...rest}>
+      <div className="mp-film-strip mp-media" data-loaded={loaded}>
+        <span className="mp-shimmer mp-on-dark mp-inset" aria-hidden="true" />
+        <video ref={video}
+          // The fragment asks the browser to paint the first frame instead of a black box.
+          src={src + '#t=0.001'} controls playsInline preload="metadata"
+          onLoadedMetadata={e => {
+            done();
+            const { videoWidth: w, videoHeight: h } = e.currentTarget;
+            if (w && h) setNatural({ w, h });
+          }}
+          onError={onError} />
+      </div>
+      {caption && <figcaption>{caption}</figcaption>}
+    </figure>
+  );
+}

package/components/media/Film.prompt.md

@@ -0,0 +1,14 @@
+Film: a video on a strip of film. It fits the width of its box, which should be a size container, and keeps the video's own shape.
+
+```jsx
+<div style={{ position: 'relative', height: 480, containerType: 'size', display: 'grid', placeItems: 'center' }}>
+  <Film src={clip.url} caption="The party" width={clip.width} height={clip.height} paused={sheetOpen} onError={refresh} />
+</div>
+```
+
+- It uses the browser's own controls, so full screen, captions and the volume work the way people expect on their phone.
+- It never autoplays and never loops. Pass `paused` when something opens on top of it.
+- Until it loads, a shimmer holds its place. The first frame is painted instead of a black box.
+- Pass `width` and `height` when you know them, so the film has the right shape before it loads. The video's own size wins once it has.
+- Use a neutral caption, never the sender.
+- With no `src`, an `Unavailable` card shows instead.

package/components/media/MemoryText.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+/**
+ * Readable card for a contributor's written memory (or the author’s letter): warm parchment, 20px UI type at 1.6 leading, ≤ 640px column.
+ * @startingPoint section="Media" subtitle="Written memory card" viewport="700x260"
+ */
+export interface MemoryTextProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style'> {
+  /** Paragraphs (use <p> elements). */
+  children?: React.ReactNode;
+  /** lg 20px (iPad) · md 17px (phone) · sm 15px. */
+  size?: 'lg' | 'md' | 'sm';
+  /** Gold quote-mark ornament (default true). */
+  ornament?: boolean;
+  width?: number | string;
+  /** Default var(--layout-reading-max) = 640px. */
+  maxWidth?: number | string;
+  style?: React.CSSProperties;
+}
+
+export function MemoryText(props: MemoryTextProps): React.JSX.Element;

package/components/media/MemoryText.jsx

@@ -0,0 +1,14 @@
+'use client';
+import React from 'react';
+
+export function MemoryText({ children, size = 'lg', ornament = true, width = '100%', maxWidth = 'var(--layout-reading-max)', style, ...rest }) {
+  const fs = size === 'lg' ? 20 : size === 'md' ? 17 : 15;
+  return (
+    <div style={{ position: 'relative', width, maxWidth, boxSizing: 'border-box', padding: ornament ? '30px 26px 24px' : '22px 24px', borderRadius: 'var(--radius-xl)',
+      background: 'linear-gradient(180deg, #fff, var(--cream-100))', border: '3px solid var(--cream-300)', boxShadow: 'inset 0 3px 0 oklch(1 0 0 / 0.7), 0 6px 0 var(--cream-300), 0 10px 20px oklch(0.22 0.05 60 / 0.18)',
+      fontFamily: 'var(--font-ui)', fontWeight: 600, fontSize: fs, lineHeight: 1.6, color: 'var(--ink-900)', textWrap: 'pretty', ...style }} {...rest}>
+      {ornament && <span aria-hidden="true" style={{ position: 'absolute', left: 18, top: -8, fontFamily: 'var(--font-display)', fontSize: 64, lineHeight: 1, color: 'var(--gold-300)', textShadow: '0 2px 0 var(--gold-700)' }}>“</span>}
+      <div style={{ display: 'grid', gap: '0.8em' }}>{children}</div>
+    </div>
+  );
+}

package/components/media/MemoryText.prompt.md

@@ -0,0 +1,9 @@
+Memory text: any written contribution, and the summit letter (size lg, ornament off, letter tokens). Text is shown exactly as written; no truncation, no "read more".
+
+```jsx
+<MemoryText size="lg"><p>{memory.text}</p></MemoryText>
+<MemoryText ornament={false} style={{ fontSize: 'var(--text-letter)', lineHeight: 1.65 }}>{letterParagraphs}</MemoryText>
+```
+
+- Never render the author's name inside or near it while the level is a mystery.
+- On phones use size="md". Long texts scroll inside the level; the Continue button stays reachable.