lanre-ds 0.0.0-stage → 0.2.0

package/components/contributor/StepBar.prompt.md

@@ -0,0 +1,12 @@
+Step bar: the top of every contributor screen, in the HUD between the back button and the right-hand slot. It reads like the map, with step markers on a short stretch of road that fills green as steps finish.
+
+```jsx
+<StepBar steps={['You', 'Memories', 'Preview', 'Submit']} current={1} />
+<StepBar steps={['Where', 'Who', 'Write', 'Details']} current={2} labels />
+```
+
+- Use the plain bar for the main road, and `labels` for the steps inside one memory.
+- Without `labels`, each step is still read out, as "Step 2 of 4: Memories".
+- A step forward celebrates. The green grows to the new marker and the finished one pops. It only happens when the bar mounts one step further on than it was last seen on that page load, so going back or reloading stays calm.
+- The markers aren't buttons. Going back is the back button's job.
+- It takes its road colours from the world, so put it inside a `data-world`.

package/components/contributor/TextField.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+/**
+ * Labelled text input / textarea in the parchment style: 52px tall, inset well, blue focus, coral error with a warning glyph, optional counter.
+ * @startingPoint section="Contributor" subtitle="Input + textarea with helper, error, counter" viewport="700x260"
+ */
+export interface TextFieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
+  label?: React.ReactNode;
+  value?: string;
+  onChange?: (value: string) => void;
+  placeholder?: string;
+  helper?: React.ReactNode;
+  /** Error message; sets aria-invalid. */
+  error?: React.ReactNode;
+  multiline?: boolean;
+  rows?: number;
+  maxLength?: number;
+  /** Appends "· optional" to the label. */
+  optional?: boolean;
+  id?: string;
+  style?: React.CSSProperties;
+  inputStyle?: React.CSSProperties;
+}
+
+export function TextField(props: TextFieldProps): React.JSX.Element;

package/components/contributor/TextField.jsx

@@ -0,0 +1,29 @@
+'use client';
+import React, { useId, useState } from 'react';
+
+export function TextField({ label, value = '', onChange, placeholder, helper, error, multiline = false, rows = 4, maxLength, optional = false, id, style, inputStyle, ...rest }) {
+  const auto = 'mp-field-' + useId().replace(/:/g, '');
+  const fid = id || auto;
+  const [focus, setFocus] = useState(false);
+  const border = error ? 'var(--coral-500)' : focus ? 'var(--blue-300)' : 'var(--cream-300)';
+  const Tag = multiline ? 'textarea' : 'input';
+  return (
+    <div style={{ display: 'grid', gap: 6, fontFamily: 'var(--font-ui)', ...style }} {...rest}>
+      {label && (
+        <label htmlFor={fid} style={{ fontWeight: 700, fontSize: 14, color: 'var(--ink-700)', display: 'flex', justifyContent: 'space-between', gap: 8 }}>
+          <span>{label}{optional && <span style={{ fontWeight: 600, color: 'var(--ink-500)' }}> · optional</span>}</span>
+          {maxLength != null && <span style={{ fontWeight: 600, fontSize: 12, color: String(value).length > maxLength ? 'var(--coral-700)' : 'var(--ink-500)', fontVariantNumeric: 'tabular-nums' }}>{String(value).length + '/' + maxLength}</span>}
+        </label>
+      )}
+      <Tag id={fid} value={value} onChange={e => onChange && onChange(e.target.value)} placeholder={placeholder} rows={multiline ? rows : undefined} maxLength={maxLength} aria-invalid={!!error || undefined} aria-describedby={helper || error ? fid + '-help' : undefined}
+        onFocus={() => setFocus(true)} onBlur={() => setFocus(false)}
+        style={{ width: '100%', boxSizing: 'border-box', minHeight: 52, padding: multiline ? '14px 16px' : '0 16px', borderRadius: 'var(--radius-md)', border: '3px solid ' + border, background: 'var(--cream-50)', boxShadow: 'inset 0 2px 4px oklch(0 0 0 / 0.06)',
+          fontFamily: 'var(--font-ui)', fontWeight: 600, fontSize: 16, lineHeight: 1.4, color: 'var(--ink-900)', outline: 'none', resize: multiline ? 'vertical' : 'none', transition: 'border-color var(--dur-fast)', ...inputStyle }} />
+      {(error || helper) && (
+        <div id={fid + '-help'} style={{ display: 'flex', alignItems: 'center', gap: 6, fontWeight: 600, fontSize: 13, color: error ? 'var(--coral-700)' : 'var(--ink-500)' }}>
+          {error && <i className="ph-fill ph-warning" aria-hidden="true" />}{error || helper}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/contributor/TextField.prompt.md

@@ -0,0 +1,7 @@
+Text field: contributor onboarding and the memory composer. Always a visible label; helper text explains what the recipient will see.
+
+```jsx
+<TextField label="The name the recipient knows you by" value={name} onChange={setName} helper="Shown only after the reveal." />
+<TextField label="Your memory" multiline rows={6} value={text} onChange={setText} maxLength={2000} />
+<TextField label="Relationship" value={rel} onChange={setRel} error="Please add how you know them." />
+```

package/components/contributor/UploadTile.d.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+
+/**
+ * One block of a memory: a numbered step marker, its kind, and keys to move or remove it. Photo, video and voice note blocks add a thumbnail and the upload's state. The caption or the text field goes in as children.
+ * @startingPoint section="Contributor" subtitle="Memory blocks: text, and every upload state" viewport="700x620"
+ */
+export interface UploadTileProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style'> {
+  type?: 'text' | 'photo' | 'video' | 'audio';
+  /** 0-based place in the memory. Every block after the first gets a stretch of road up to the one above. */
+  index?: number;
+  /** How many blocks the memory has, so the last one can't move down. */
+  count?: number;
+  /** Upload state for photo, video and audio blocks. stalled = it stopped before finishing; missing = the file is gone. */
+  state?: 'uploading' | 'done' | 'error' | 'stalled' | 'missing';
+  /** 0–1 while uploading. */
+  progress?: number;
+  /** Filename, for the contributor only. */
+  name?: string;
+  /** Duration and size, e.g. "0:42 · 12.6 MB". */
+  details?: React.ReactNode;
+  /** Thumbnail URL for photos. */
+  thumb?: string;
+  /** Why the upload failed. Shown after "Upload failed". */
+  reason?: string;
+  /** A message under the upload's state, such as a retry that failed too. */
+  error?: React.ReactNode;
+  onMoveUp?: () => void;
+  onMoveDown?: () => void;
+  onRemove?: () => void;
+  /** Shows Retry on failed and stalled uploads. */
+  onRetry?: () => void;
+  /** Shows Cancel while uploading. */
+  onCancel?: () => void;
+  /** The caption field, or the text field of a text block. */
+  children?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+
+export function UploadTile(props: UploadTileProps): React.JSX.Element;

package/components/contributor/UploadTile.jsx

@@ -0,0 +1,116 @@
+'use client';
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Button } from '../buttons/Button';
+
+const useBrowserEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+const TYPE = { text: ['article', 'Text'], photo: ['image', 'Photo'], video: ['video-camera', 'Video'], audio: ['microphone', 'Voice note'] };
+const DROP = '0 12px 20px oklch(0.22 0.05 60 / 0.25)';
+const WARN = { color: 'var(--coral-700)' };
+const LINE = { display: 'inline-flex', alignItems: 'center', gap: 4 };
+const FONT = { fontFamily: 'inherit', fontStyle: 'inherit', lineHeight: 'inherit' };
+
+// Square cream key for moving and removing a block. One that can't act is aria-disabled rather than disabled,
+// so it keeps focus when its block reaches the top or the bottom.
+function Key({ label, disabled, onClick, buttonRef, children }) {
+  const [down, setDown] = useState(false);
+  const pressed = down && !disabled;
+  return (
+    <button type="button" ref={buttonRef} aria-label={label} aria-disabled={disabled || undefined} onClick={disabled ? undefined : onClick}
+      onPointerDown={() => setDown(true)} onPointerUp={() => setDown(false)} onPointerCancel={() => setDown(false)} onPointerLeave={() => setDown(false)}
+      style={{ appearance: 'none', boxSizing: 'border-box', border: '2px solid var(--cream-300)', background: 'linear-gradient(180deg, #fff, var(--cream-100))',
+        boxShadow: pressed ? '0 1px 0 var(--cream-300)' : '0 3px 0 var(--cream-300), inset 0 2px 0 oklch(1 0 0 / 0.45)', width: 44, height: 44, borderRadius: 12,
+        display: 'grid', placeItems: 'center', ...FONT, fontWeight: 'inherit', fontSize: 18, color: 'var(--ink-700)', cursor: disabled ? 'default' : 'pointer', flex: 'none',
+        opacity: disabled ? 0.4 : undefined, transform: pressed ? 'translateY(2px)' : undefined,
+        transition: 'transform var(--dur-fast) var(--ease-out), box-shadow var(--dur-fast) var(--ease-out)' }}>
+      {children}
+    </button>
+  );
+}
+
+function Status({ state, pct, reason }) {
+  if (state === 'missing') return <span style={WARN}>File missing. Remove this and add it again.</span>;
+  if (state === 'done') return <span style={{ color: 'var(--green-700)', ...LINE, animation: 'mp-pop var(--dur-base) var(--ease-bounce) both' }}><i className="ph-fill ph-check-circle" aria-hidden="true" /> Uploaded</span>;
+  if (state === 'error') return <span style={{ ...WARN, ...LINE }}><i className="ph-fill ph-warning-circle" aria-hidden="true" /> Upload failed{reason ? ': ' + reason : ''}</span>;
+  // The percentage is hidden from the live region, so it announces "Uploading" once, not every tick. The progress bar carries the number.
+  if (state === 'uploading') return <span>Uploading <span aria-hidden="true">{pct}%</span></span>;
+  return <span style={WARN}>Upload didn&apos;t finish</span>;
+}
+
+export function UploadTile({ type = 'photo', index = 0, count, state = 'done', progress = 0, name, details, thumb, reason, error,
+  onMoveUp, onMoveDown, onRemove, onRetry, onCancel, children, style, ...rest }) {
+  const [glyph, kind] = TYPE[type] || TYPE.photo;
+  const media = type !== 'text';
+  const failed = media && (state === 'error' || state === 'missing');
+  const pct = Math.round(Math.max(0, Math.min(1, progress)) * 100);
+  const label = kind + ' ' + (index + 1);
+  // Moving a block can move it in the page, which drops focus. So when a move key had focus, it gets it back
+  // once the block lands somewhere new.
+  const upKey = useRef(null), downKey = useRef(null), moved = useRef(null);
+  const move = (key, handler) => e => {
+    moved.current = key.current && key.current === document.activeElement ? { key, from: index } : null;
+    handler(e);
+    // Clear it once the event is over, so a move that never lands can't pull focus back on a later render.
+    setTimeout(() => { moved.current = null; });
+  };
+  useBrowserEffect(() => {
+    const m = moved.current;
+    if (!m || m.from === index) return;
+    moved.current = null;
+    if (m.key.current && m.key.current !== document.activeElement) m.key.current.focus();
+  });
+  return (
+    <div style={{ position: 'relative', ...style }} {...rest}>
+      {/* From the second block on, a short stretch of road joins it to the one above. Stack blocks 22px apart. */}
+      {index > 0 && <span aria-hidden="true" style={{ position: 'absolute', left: 28, top: -26, width: 12, height: 30, borderRadius: 999, background: 'var(--world-path)', boxShadow: '0 0 0 3px var(--world-path-edge)' }} />}
+      <div style={{ position: 'relative', boxSizing: 'border-box', background: failed ? 'var(--coral-100)' : 'linear-gradient(180deg, var(--cream-50), var(--cream-100))',
+        border: 'var(--border-panel) solid ' + (failed ? 'var(--coral-500)' : 'var(--cream-300)'), borderRadius: 'var(--radius-lg)',
+        boxShadow: '0 5px 0 ' + (failed ? 'var(--coral-700)' : 'var(--cream-300)') + ', ' + DROP, padding: 'var(--space-3)', display: 'grid', gap: 'var(--space-3)', minWidth: 0 }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)', fontWeight: 700, fontSize: 14, color: 'var(--ink-700)' }}>
+          <span className="mp-step mp-step-current mp-step-lg" aria-hidden="true" style={{ minWidth: 0 }}>{index + 1}</span>
+          <span style={{ flex: 1, minWidth: 0, display: 'inline-flex', alignItems: 'center', gap: 6 }}>
+            <i className={'ph-fill ph-' + glyph} aria-hidden="true" style={{ fontSize: 20 }} />
+            {kind}
+          </span>
+          {onMoveUp && <Key label={'Move ' + label + ' up'} disabled={index === 0} onClick={move(upKey, onMoveUp)} buttonRef={upKey}><i className="ph-bold ph-arrow-up" aria-hidden="true" /></Key>}
+          {onMoveDown && <Key label={'Move ' + label + ' down'} disabled={count !== undefined && index >= count - 1} onClick={move(downKey, onMoveDown)} buttonRef={downKey}><i className="ph-bold ph-arrow-down" aria-hidden="true" /></Key>}
+          {onRemove && <Key label={'Remove ' + label} onClick={onRemove}><i className="ph-bold ph-trash" aria-hidden="true" style={{ color: 'var(--coral-700)' }} /></Key>}
+        </div>
+        {media && (
+          <div style={{ display: 'grid', gridTemplateColumns: '88px minmax(0, 1fr)', gap: 'var(--space-3)', alignItems: 'center' }}>
+            <div style={{ width: 88, height: 88, borderRadius: 'var(--radius-sm)', background: 'var(--cream-200)', display: 'grid', placeItems: 'center', overflow: 'hidden', fontSize: 32, color: 'var(--stone-500)', position: 'relative' }}>
+              {thumb
+                ? <img src={thumb} alt="" style={{ width: '100%', height: '100%', objectFit: 'cover', animation: 'mp-pop var(--dur-base) var(--ease-bounce) both' }} />
+                : <i className={'ph-fill ph-' + glyph} aria-hidden="true" />}
+            </div>
+            <div style={{ display: 'grid', gap: 4, minWidth: 0, fontSize: 13, color: 'var(--ink-500)' }}>
+              {name && <span title="Only you see filenames" style={{ fontWeight: 700, color: 'var(--ink-700)', whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{name}</span>}
+              <span>{details}</span>
+              <span role="status" style={{ fontWeight: 700 }}><Status state={state} pct={pct} reason={reason} /></span>
+              {state === 'uploading' && (
+                <>
+                  <div role="progressbar" aria-label="Upload progress" aria-valuenow={pct} aria-valuemin={0} aria-valuemax={100}
+                    style={{ height: 12, borderRadius: 999, background: 'var(--cream-300)', boxShadow: 'inset 0 2px 3px oklch(0 0 0 / 0.12)', overflow: 'hidden' }}>
+                    <span style={{ display: 'block', width: pct + '%', height: '100%', borderRadius: 999, transition: 'width var(--dur-base) var(--ease-out)',
+                      background: 'repeating-linear-gradient(-45deg, oklch(1 0 0 / 0.28) 0 6px, transparent 6px 12px), linear-gradient(180deg, var(--teal-300), var(--teal-500))' }} />
+                  </div>
+                  {onCancel && (
+                    <button type="button" onClick={onCancel} style={{ appearance: 'none', border: 0, background: 'none', padding: 0, minHeight: 32, justifySelf: 'start', ...FONT,
+                      fontWeight: 700, fontSize: 15, color: 'var(--blue-700)', textDecoration: 'underline', textUnderlineOffset: 3, cursor: 'pointer' }}>Cancel</button>
+                  )}
+                </>
+              )}
+              {(state === 'error' || state === 'stalled') && onRetry && (
+                <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-3)' }}>
+                  <Button size="sm" variant="danger" onClick={onRetry}>Retry</Button>
+                </div>
+              )}
+              {error && <span style={WARN}>{error}</span>}
+            </div>
+          </div>
+        )}
+        {children}
+      </div>
+    </div>
+  );
+}

package/components/contributor/UploadTile.prompt.md

@@ -0,0 +1,21 @@
+Upload tile: one block of a memory in the composer. Blocks stack in the contributor's order, and that's the order the recipient sees them in.
+
+```jsx
+<ol style={{ listStyle: 'none', margin: 0, padding: 0, display: 'grid', gap: 22 }}>
+  <li><UploadTile type="text" index={0} count={3} onMoveUp={up} onMoveDown={down} onRemove={remove}>
+    <TextField label={<span className="mp-sr">Text 1</span>} multiline rows={6} value={text} onChange={setText} />
+  </UploadTile></li>
+  <li><UploadTile type="photo" index={1} count={3} state="done" name="beach.jpg" details="2.4 MB" thumb={url} onMoveUp={up} onMoveDown={down} onRemove={remove}>
+    <TextField label="Caption" optional value={caption} onChange={setCaption} />
+  </UploadTile></li>
+  <li><UploadTile type="video" index={2} count={3} state="uploading" progress={0.42} details="0:42 · 12.6 MB" onCancel={cancel} onMoveUp={up} onMoveDown={down} onRemove={remove} /></li>
+</ol>
+```
+
+- Stack blocks 22px apart. Every block after the first draws a short stretch of road up to the one above.
+- Key each list item by the block's id, not its place. When a block moves, focus stays on the key that moved it, even once that key can't go any further. Keys that can't act are `aria-disabled`, so they stay focusable.
+- `state` covers every upload. `uploading` shows `progress`, and Cancel when you pass `onCancel`. Then `done`, `error` (pass the `reason` when there is one), `stalled` when it stopped before finishing, and `missing` when the file is gone.
+- `error` and `missing` turn the block coral. Retry shows on `error` and `stalled` when you pass `onRetry`.
+- A memory with a failed or missing upload can't be sent. Keep the block on screen until it's fixed or removed.
+- Filenames only ever show to the contributor. Strip them from what the recipient receives, since they can carry names.
+- Add blocks with a row of square `IconButton`s under the list, one per kind.

package/components/contributor/WorldChip.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+/**
+ * A pill that shows the world a memory is in, with its glyph on a round medal, and changes it when pressed. Filled with the world's accent, with a small caret to say it can be changed.
+ * @startingPoint section="Contributor" subtitle="The world a memory is in, as a pill" viewport="700x160"
+ */
+export interface WorldChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  world?: 'mango_grove' | 'small_chops' | 'good_energy' | 'japan';
+  /** Overrides the world's display name. */
+  name?: string;
+  /** Overrides the world's glyph. */
+  glyph?: string;
+  /** The little caret that says "tap to change". Default true. */
+  caret?: boolean;
+  onClick?: () => void;
+}
+
+export function WorldChip(props: WorldChipProps): React.JSX.Element;

package/components/contributor/WorldChip.jsx

@@ -0,0 +1,16 @@
+'use client';
+import React from 'react';
+import { WORLDS } from '../map/worlds.js';
+
+/* A pill that shows the world a memory is in, and changes it when pressed. Give it an aria-label that says so,
+   such as "Where on the road: Mango Grove. Tap to change." */
+export function WorldChip({ world = 'mango_grove', name, glyph, caret = true, onClick, ...rest }) {
+  const W = WORLDS[world] || WORLDS.mango_grove;
+  return (
+    <button type="button" className="mp-world-pill" data-world={world} onClick={onClick} {...rest}>
+      <span className="mp-world-medal" aria-hidden="true"><i className={'ph-fill ph-' + (glyph || W.glyph)} /></span>
+      <span className="mp-world-pill-name">{name || W.name}</span>
+      {caret && <span className="mp-pill-mark" aria-hidden="true"><i className="ph-bold ph-caret-down" /></span>}
+    </button>
+  );
+}

package/components/contributor/WorldChip.prompt.md

@@ -0,0 +1,9 @@
+World chip: shows which world a memory is in, and opens a way to change it.
+
+```jsx
+<WorldChip world={memory.world} onClick={() => setPicking(true)} aria-label={`Where on the road: ${worldName}. Tap to change.`} />
+```
+
+- Always filled with the world's accent, because it shows a choice that's already made. To choose a world in the first place, use `WorldSign`s or a list of `WorldOption`s.
+- Give it an `aria-label` that says what it is and that pressing it changes the world. The visible name alone doesn't.
+- The name is cut off with an ellipsis before it pushes anything else out of the row, so it gives way first on narrow phones.

package/components/contributor/WorldOption.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * One world in a list to choose from: its glyph on a round medal, its name and a line about it, with a radio on the right. The chosen row turns teal.
+ * @startingPoint section="Contributor" subtitle="A list of worlds to pick from" viewport="700x420"
+ */
+export interface WorldOptionProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'onChange' | 'children'> {
+  world?: 'mango_grove' | 'small_chops' | 'good_energy' | 'japan';
+  /** Overrides the world's display name. */
+  name?: string;
+  /** Overrides the world's glyph. */
+  glyph?: string;
+  /** The line under the name. Defaults to the world's own. */
+  blurb?: string;
+  checked?: boolean;
+  onChange?: (checked: true) => void;
+}
+
+export function WorldOption(props: WorldOptionProps): React.JSX.Element;

package/components/contributor/WorldOption.jsx

@@ -0,0 +1,19 @@
+'use client';
+import React from 'react';
+import { WORLDS } from '../map/worlds.js';
+
+/* One world in a list to pick from: its medal, name and a line about it, with a radio on the right.
+   Put a group of them in role="radiogroup". */
+export function WorldOption({ world = 'mango_grove', name, glyph, blurb, checked = false, onChange, ...rest }) {
+  const W = WORLDS[world] || WORLDS.mango_grove;
+  return (
+    <button type="button" role="radio" aria-checked={checked} className="mp-world-option" data-world={world} onClick={() => onChange && onChange(true)} {...rest}>
+      <span className="mp-world-medal" aria-hidden="true"><i className={'ph-fill ph-' + (glyph || W.glyph)} /></span>
+      <span className="mp-world-option-text">
+        <strong>{name || W.name}</strong>
+        <span>{blurb === undefined ? W.blurb : blurb}</span>
+      </span>
+      <span className="mp-world-radio" aria-hidden="true">{checked && <i className="ph-bold ph-check" />}</span>
+    </button>
+  );
+}

package/components/contributor/WorldOption.prompt.md

@@ -0,0 +1,11 @@
+World option: a row in a list of worlds, for a picker that opens over the screen.
+
+```jsx
+<div role="radiogroup" aria-label="Where on the road?" style={{ display: 'grid', gap: 10 }}>
+  {worlds.map(w => <WorldOption key={w} world={w} checked={chosen === w} onChange={() => setChosen(w)} />)}
+</div>
+```
+
+- Put the rows in a `role="radiogroup"` with a label. Each one is a radio button.
+- The chosen row turns teal and its radio pops a tick.
+- Use `WorldSign`s when there's room to make the choice a moment, and `WorldOption`s when it's a quick change in a sheet.

package/components/contributor/WorldSign.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+/**
+ * A sign for choosing a world: a plank on two posts with the world's glyph, name and a line about it. A chosen sign glows and gets a tick. A locked sign, like the summit, is a stone plank that does nothing.
+ * @startingPoint section="Contributor" subtitle="Choose a world, on signs hung over one road" viewport="700x560"
+ */
+export interface WorldSignProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  world?: 'mango_grove' | 'small_chops' | 'good_energy' | 'japan';
+  /** Overrides the world's display name. */
+  name?: string;
+  /** Overrides the world's glyph. A locked sign always shows a lock. */
+  glyph?: string;
+  /** The line on the cream tag under the name. Defaults to the world's own. Pass "" for none. */
+  blurb?: string;
+  /** A number on a small marker at the sign's top left, for the order along the road. */
+  number?: number;
+  selected?: boolean;
+  /** A stone sign that can't be chosen. It has no button and no number. */
+  locked?: boolean;
+  /** Hangs off the sign's bottom left, such as a "Your stop" Tag. */
+  badge?: React.ReactNode;
+  onClick?: () => void;
+}
+
+export function WorldSign(props: WorldSignProps): React.JSX.Element;

package/components/contributor/WorldSign.jsx

@@ -0,0 +1,32 @@
+'use client';
+import React from 'react';
+import { WORLDS } from '../map/worlds.js';
+
+/* A sign for choosing a world: a plank on two posts with the world's name and a line about it. Press it to choose.
+   Set `locked` for a world that can't be chosen, such as the summit, and it becomes a stone sign that does nothing. */
+export function WorldSign({ world = 'mango_grove', name, glyph, blurb, number, selected = false, locked = false, badge, onClick, ...rest }) {
+  const W = WORLDS[world] || WORLDS.mango_grove;
+  const title = name || W.name;
+  const icon = locked ? 'lock' : (glyph || W.glyph);
+  const text = blurb === undefined ? W.blurb : blurb;
+  const posts = [<span key="a" className="mp-sign-post" aria-hidden="true" />, <span key="b" className="mp-sign-post" aria-hidden="true" />];
+  const plank = (
+    <span className={'mp-sign-plank' + (locked ? ' mp-sign-plank-locked' : '')}>
+      <span className="mp-sign-title" style={title.length > 16 ? { fontSize: 19 } : undefined}>
+        <i className={'ph-fill ph-' + icon} aria-hidden="true" />
+        {title}
+      </span>
+      {text && <span className="mp-sign-blurb">{text}</span>}
+      {badge && <span className="mp-sign-badge">{badge}</span>}
+      {selected && <span className="mp-sign-check" aria-hidden="true"><i className="ph-bold ph-check" /></span>}
+    </span>
+  );
+  if (locked) return <div className="mp-sign" style={{ cursor: 'default' }} {...rest}>{posts}{plank}</div>;
+  return (
+    <button type="button" className="mp-sign" data-world={world} aria-pressed={selected} onClick={onClick} {...rest}>
+      {posts}
+      {number !== undefined && <span className="mp-sign-number" aria-hidden="true"><span className="mp-step">{number}</span></span>}
+      {plank}
+    </button>
+  );
+}

package/components/contributor/WorldSign.prompt.md

@@ -0,0 +1,14 @@
+World sign: a big, friendly way to choose a world. Hang a column of them over a road with `WorldSigns`.
+
+```jsx
+<WorldSigns label="Where on the road">
+  {worlds.map((w, i) => <WorldSign key={w} world={w} number={i + 1} selected={chosen === w} onClick={() => setChosen(w)} />)}
+  <WorldSign locked name="The Summit" blurb="The author's letter" />
+</WorldSigns>
+```
+
+- Exactly one sign is chosen at a time. A chosen sign glows teal and gets a tick. It reports as a pressed button.
+- `number` puts a small marker at the top left, so the signs read in order along the road. Leave it out when order doesn't matter.
+- `badge` hangs a small label off the bottom left. Use it to flag one sign, such as the world a friend's main memory is already in.
+- A locked sign is for a world that can't be chosen. It's stone, shows a lock, and takes no presses.
+- Pressing a sign moves it down, the same way every other pressable does.

package/components/contributor/WorldSigns.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+/**
+ * Hangs a column of WorldSigns over one road, with a straight stretch of road showing between the signs.
+ * @startingPoint section="Contributor" subtitle="Signs hung over one road" viewport="700x560"
+ */
+export interface WorldSignsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** The group's accessible name, such as "Where on the road". */
+  label: string;
+  children?: React.ReactNode;
+}
+
+export function WorldSigns(props: WorldSignsProps): React.JSX.Element;

package/components/contributor/WorldSigns.jsx

@@ -0,0 +1,12 @@
+'use client';
+import React from 'react';
+
+/* Hangs a column of WorldSigns over one road, with a straight stretch of it showing between the signs. */
+export function WorldSigns({ label, children, ...rest }) {
+  return (
+    <div className="mp-signs mp-signs-road" role="group" aria-label={label} {...rest}>
+      <span className="mp-signs-spine" aria-hidden="true" />
+      {children}
+    </div>
+  );
+}

package/components/contributor/WorldSigns.prompt.md

@@ -0,0 +1,8 @@
+World signs: the road the signs hang over. Put `WorldSign`s inside it.
+
+```jsx
+<WorldSigns label="Where on the road">…signs…</WorldSigns>
+```
+
+- It draws a straight stretch of road behind the signs, in the road colours of the world it sits in. Put it inside a `data-world`, such as Base Camp.
+- Give it a `label`. It's a group, and the label is what a screen reader announces.

package/components/effects/Confetti.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+
+/**
+ * A one-shot burst of coloured paper from the middle of its parent, for a reveal or a win. Hidden for reduced motion.
+ * @startingPoint section="Effects" subtitle="One-shot paper burst" viewport="700x360"
+ */
+export interface ConfettiProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
+  /** How many pieces. Default 46. */
+  pieces?: number;
+  /** Seeds the random spread, so a burst looks the same each time. Change it for a different pattern. */
+  seed?: string;
+}
+
+export function Confetti(props: ConfettiProps): React.JSX.Element;

package/components/effects/Confetti.jsx

@@ -0,0 +1,38 @@
+'use client';
+import React, { useMemo } from 'react';
+
+const COLOURS = ['#ffd84d', '#ff7aa8', '#4fb0e8', '#58c26a', '#ff9a3d', '#b884e8', '#ffffff'];
+
+// A small deterministic random sequence, so the same burst is drawn on the server and in the browser.
+function seeded(seed) {
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i++) { h ^= seed.charCodeAt(i); h = Math.imul(h, 16777619); }
+  return () => {
+    h += 0x6d2b79f5;
+    let t = h;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/* A one-shot burst of paper from the middle of its parent. Put it inside a positioned box, behind what is being celebrated.
+   It is hidden entirely for reduced motion. */
+export function Confetti({ pieces = 46, seed = 'confetti', ...rest }) {
+  const bits = useMemo(() => {
+    const r = seeded(seed);
+    return Array.from({ length: pieces }, (_, i) => {
+      const angle = r() * Math.PI * 2;
+      const dist = 140 + r() * 220;
+      return { i, colour: COLOURS[i % COLOURS.length], dx: Math.cos(angle) * dist, dy: Math.sin(angle) * dist - 80, rot: (r() - 0.5) * 900, delay: r() * 120, w: 8 + r() * 8, round: r() < 0.3 };
+    });
+  }, [pieces, seed]);
+  return (
+    <span className="mp-confetti" aria-hidden="true" {...rest}>
+      {bits.map(b => (
+        <span key={b.i} style={{ '--dx': b.dx.toFixed(0) + 'px', '--dy': b.dy.toFixed(0) + 'px', '--rot': b.rot.toFixed(0) + 'deg', background: b.colour, width: b.w, height: b.round ? b.w : b.w * 0.5,
+          borderRadius: b.round ? '50%' : 2, animationDelay: b.delay.toFixed(0) + 'ms' }} />
+      ))}
+    </span>
+  );
+}

package/components/effects/Confetti.prompt.md

@@ -0,0 +1,12 @@
+Confetti: paper that bursts out once, from the middle of its parent.
+
+```jsx
+<div style={{ position: 'relative' }}>
+  <Confetti />
+  <RevealCard />
+</div>
+```
+
+- Put it in a positioned box and render it at the moment of the win. It plays once when it mounts; mount it again (change its `key`) to replay.
+- It sits just above its parent's content and ignores pointer events, so it never blocks a tap.
+- It is hidden for reduced motion, so don't rely on it to say anything the screen doesn't.

package/components/effects/Sparkles.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+
+/**
+ * Five gold twinkles scattered around a celebrated panel. Decorative, and still for reduced motion.
+ * @startingPoint section="Effects" subtitle="Twinkles around a panel" viewport="700x300"
+ */
+export interface SparklesProps {}
+
+export function Sparkles(props: SparklesProps): React.JSX.Element;

package/components/effects/Sparkles.jsx

@@ -0,0 +1,13 @@
+'use client';
+import React from 'react';
+
+const SPOTS = [['6%', '18px'], ['88%', '4px'], ['16%', '92px'], ['80%', '110px'], ['50%', '-6px']];
+
+/* A handful of twinkles around a celebrated panel. Decorative only: put it inside a positioned box. */
+export function Sparkles() {
+  return (
+    <>
+      {SPOTS.map(([left, top], i) => <i key={i} className="ph-fill ph-sparkle mp-sparkle-spot" aria-hidden="true" style={{ left, top, '--i': i }} />)}
+    </>
+  );
+}

package/components/effects/Sparkles.prompt.md

@@ -0,0 +1,11 @@
+Sparkles: twinkles around a panel that is being celebrated.
+
+```jsx
+<div style={{ position: 'relative' }}>
+  <Sparkles />
+  <Notice tone="gold" icon="gift">Everything is in.</Notice>
+</div>
+```
+
+- It places itself over its nearest positioned parent, so give the parent `position: relative` and a little room around it.
+- Decorative: it is hidden from screen readers and has no props.

package/components/effects/Sunburst.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+/**
+ * Soft rays of light that fan out from a point and turn slowly. SVG, so it goes inside an svg, behind the thing it lights.
+ * @startingPoint section="Effects" subtitle="Turning rays of light, for SVG" viewport="700x320"
+ */
+export interface SunburstProps {
+  /** Centre, in the svg's own units. Default 0, 0. */
+  x?: number;
+  y?: number;
+  /** How far the rays reach. Default 500. */
+  radius?: number;
+  /** How many rays, 3 to 24. Default 12. */
+  rays?: number;
+  color?: string;
+  /** Default 0.13: a faint glow. */
+  opacity?: number;
+  /** Seconds for one turn (continuous) or the whole fade (once). Default 120. */
+  duration?: number;
+  motion?: 'continuous' | 'once' | 'still';
+}
+
+export function Sunburst(props: SunburstProps): React.JSX.Element;