---
status: approved
---

# 002 — The voyage app (v1)

Status: approved by user 2026-10-30 (direction approval; the user's standing rule: carry an approved
design through spec → plan → execution without review stops). Design record:
`docs/design/002-voyage-app.md`. Content source: `docs/specs/003-content-mount.md`.

## Intent

Turn the approved mockup direction (17) into the real site at `/`: the whole album (9 sagas, 40 songs)
as a stylised 3D sea voyage with the frieze as the curtain call between scenes, three landing
sublevels, a persistent side panel, and a bottom timeline of motif threads, using the real audio,
synced lyrics and the Odyssey text from the mounted content folder.

## Goals

1. **Routes.** The app is served at `/`. The mockup gallery moves to `/mockups/` (mockups stay at
   `/mockups/NN-slug/`). Every page keeps the fan notice and credit.
2. **Data for the whole album.** `src/data/` describes 9 sagas and 40 songs in album order (titles and
   track numbers as in the content folder) with: story time (years after Troy + a label), the Odyssey
   reference as a **book number and passage keywords** (Butler's prose has no line numbers), singers,
   motifs per song (and per part where known), facts, and video links. A curated motif set (musical
   motifs and character themes) with stable colours. Anything not certain is marked `// TODO(verify)`.
   Fan works: a typed, credited list (title, creator, type, URL, licence/permission note), **empty in
   v1** — no invented works.
3. **The voyage.** One 3D world: a route past nine places (Troy, the Cyclops' island, the open sea/storm,
   Aeaea, the Underworld, Scylla/the thunder sea, Olympus/the wisdom sea, Charybdis/vengeance, Ithaca).
   Each song is a stop on the route; selecting a song sails the ship there. Stylised per the design
   record.
4. **Curtain call.** Entering a saga (from the previous saga or by jumping) drops that saga's frieze
   band (black-figure on terracotta, the saga's name and its song titles as inscriptions), which then
   lifts into the sea with the horizon on the frieze's ground line. Within a saga, songs change without
   the curtain. Jumps across several sagas fade through the curtain colour.
5. **Three landings.** Cyclops' cave, the God Games arena (Athena), Ithaca's hall. Each is entered from
   its saga's frieze ("Go ashore") or automatically when its song is chosen (Survive; God Games; the
   Ithaca songs from The Challenge on — exact song→landing mapping in the plan), and left with
   "Back to sea".
6. **Side panel** with About, Listen & lyrics (player + synced lyrics + Watch), Paths (motif detail +
   strip when the timeline is hidden + chart of the nine places), Fan works (list or empty state).
   Collapsible; header play button.
7. **Bottom timeline** for 40 songs: all sagas visible as groups; the current saga expanded with
   titles, other sagas compact; you-are-here; motif threads for the current song's motifs across the
   whole album. Hideable (strip moves into Paths). "Threads on the sea" toggle.
8. **Navigation and state.** Previous/next song (buttons, ←/→), click any stop, Play voyage (steps
   through songs, silent), deep links (`?song=`, `?tab=`, `?motif=`, `?timeline=`, `?ribbons=`), browser
   back/forward restore state. Esc closes the reading view / leaves a landing.
9. **Robustness.** Works without the content folder (no audio/lyrics, a clear note). Works without
   WebGL (the frieze and panel still navigate; a note explains). Respects `prefers-reduced-motion`
   (crossfades). Keyboard reachable with visible focus. Desktop first (1280–1920 wide); below 900px
   the panel becomes a bottom sheet and the timeline compact — usable, not polished.

## Non-goals (v1)

- Bespoke frieze art for every song; per-saga friezes may reuse a shared figure kit.
- Time-aligning parts and motifs to the recordings (needs a content mapping file; see 17's report).
- Collecting real fan works; mobile polish; i18n; removing the mockups.

## Acceptance criteria

- `bun test` covers: the dataset (40 songs matching the content folder's titles and order, every motif
  used and defined, story times non-decreasing in album order, every song in exactly one saga),
  the route/stop geometry (one stop per song, ordered along the route), URL state round-trip, timeline
  layout (40 stops, no title overlaps in the expanded saga), and the `/` and `/mockups/` routes.
- With the content folder mounted, at 1440×900: every saga's frieze, each landing, the panel tabs,
  playback with synced lyrics, and the timeline/ribbons render correctly in headless screenshots that
  were looked at; without it, the fallback renders.
- `bun run typecheck`, `bun run build` pass; the preview container serves the app at `/`.
- Docs: ARCHITECTURE, DECISIONS, DESIGN.md (the chosen direction as tokens and rules), AGENTS.md, TODO.