Epic-The-Musical-Timeline/docs/specs/001-timeline-mockups.md

---
status: implemented
---

# EPIC: The Musical Timeline — Repo bootstrap and 7 design-direction mockups

Status: approved by user 2026-10-23 · Date: 2026-10-23

## Intent

An interactive, unofficial fan website for *EPIC: The Musical* by Jorge Rivera-Herrans. The core is one long
timeline of the songs. Recurring musical motifs and character themes are drawn as threads between the songs
where they appear, and the gaps between songs show how much in-story time passes. Opening a song shows its
place in Homer's *Odyssey*, its in-story time, its lyrics split into the song's parts, the motifs in each
part, fun facts, and related videos. The finished site should feel smooth and polished, and may use 3D
(three.js).

This document covers only the **first step**: preparing the repository, and building **7 visual mockups**
that each show a different design direction. The user will pick a direction, or combine several, and the real
app will get its own spec after that.

## Goals

1. **Repo prepared for agentic development.** Follow the playbook at
   `/home/user/preparing-repos-for-agents/skill/preparing-repos-for-agents/SKILL.md` all the way through
   (AGENTS.md, CLAUDE.md/GEMINI.md pointers, `docs/` tree, permissions, PRODUCT.md, DESIGN.md, .gitignore).
   Use `git init` with the default branch `main`. Set the remote `origin` to
   `https://gitea.lucaswinther.info/lucasw89/Epic-The-Musical-Timeline.git`.
2. **Bun app that builds to a Docker image.** A minimal skeleton that serves an index page linking to all 7
   mockups. Include `bun run dev`, `bun run build`, and a `Dockerfile` that produces a runnable image.
3. **7 mockups**, one per direction (see the table below). All 7 read from one shared sample dataset.
4. **Fan-project notice and credits** on the index page and on every mockup. The notice says the site is
   unofficial and not affiliated with the creator, and thanks Jorge Rivera-Herrans as the creator of EPIC.

## Non-goals

- These are **mockups, not full pages**. Each one shows a visual direction and how it feels to interact with.
  None of them is a finished product.
- No complete song catalogue, real backend, CMS, search, or accounts.
- No polish for mobile or accessibility beyond "doesn't fall apart". Mockups target a desktop viewport of
  about 1440×900.
- No decision yet on the final design system. DESIGN.md records that the direction is still open.

## Anti-goals (failures even if they technically work)

- Seven variations of one layout with different colours. The directions must differ in kind.
- Generic, templated "AI-looking" UI. Each direction commits fully to its own aesthetic.
- Any page that is missing the fan notice or the credit to Jorge Rivera-Herrans.
- Shipping the content as if it were fact-checked. Any sample field the builder couldn't verify is marked
  `// TODO(verify)` in the data.

## The 7 directions

| # | Name | Core idea | Must show |
|---|------|-----------|-----------|
| 1 | Editorial scroll | Clean horizontal line in a parchment-and-serif editorial style. Motifs are thin coloured threads underneath. | Horizontal pan, gap length proportional to in-story time, one song opened |
| 2 | Vertical story | The voyage scrolls downward. Songs reveal one at a time beside a detail panel that stays in place (sticky). | Vertical line, sticky detail updating on scroll |
| 3 | Transit map | Each motif is a coloured metro line and each song is a station. Songs where several motifs meet are interchanges. | Lines running between stations, interchange stations, legend |
| 4 | Greek frieze | The timeline is an unrolled black-figure vase frieze, panned sideways. | Frieze styling, song panels, one song opened |
| 5 | Score / waveform | The line is a music staff or audio waveform. Song parts are segments, and motifs are recurring marks. | Song parts visible as segments, motif recurrence marks |
| 6 | Constellation (3D) | Songs are stars along a path through space, joined by motif "constellation" lines. three.js. | Camera fly-through, a hovered star, an opened song |
| 7 | Sea voyage (3D) | A ship crosses a 3D sea, with islands for the sagas, and the camera follows the route. three.js. | Ship moving along the route, saga islands, an opened song |

Every mockup must also show:
- **A song detail state**: Odyssey reference, in-story time, lyrics divided into parts with the singer of
  each part, the motifs in each part, a fun fact, related-video link cards (YouTube), and an audio slot.
  The audio slot plays a direct MP3 when the song has one (user requirement: the app supports direct MP3s
  as well as YouTube). The sample data ships with no MP3s, so the mockups show the slot's empty state.
- **Motif linking**: selecting a motif highlights every song (and, where possible, every part) where it
  appears.

"Interactive enough to feel it" means hover and click to open a song, plus scrolling, panning or a camera
move. Routing, deep links, persistence and edge cases are out of scope.

## Sample data (shared by all mockups)

One typed module is the single source for all 7 mockups. Its shape should be close to what the real app will
use:

- **Saga**: id, name, order.
- **Song**: id, title, sagaId, track number, `storyTime` (a number of years since the fall of Troy, plus a
  human label), `odyssey` (book, line range, and a URL to a public-domain translation), `parts[]`, `facts[]`,
  `videos[]` (title, URL), and optional `audio` (URL to a direct MP3 file).
- **Part**: name (for example "Verse 1"), singer(s), lyric lines, motif ids present in the part, and an
  optional start time in seconds (so a part can be played from the song's MP3).
- **Motif / character theme**: id, name, kind (`motif` | `character`), colour, and a short description.

Scope: the **Troy Saga** (5 songs) and the **Cyclops Saga** (4 songs), plus **1–2 later songs** where a motif
from those sagas returns, so the threads have something to connect. Any fact, time or Odyssey reference the
builder can't confirm is marked `// TODO(verify)`.

Lyrics *(builder's call)*: mockups use **placeholder lyric lines** (clearly marked, 2–4 lines per part) in
the real data shape. The mockups compare designs, not content, and recalling lyrics from memory risks
inaccuracy. Real lyrics come with the real app; the copyright question is deferred by the user.

## Constraints

- Runtime and package manager: **Bun** (1.3.x is installed locally). Use Bun's own server and bundler, with
  HTML imports. Don't add a separate framework (Vite, Next, etc.) for the mockups.
- **three.js** only in mockups 6 and 7.
- **Self-contained at runtime** *(builder's call)*: three.js and fonts are bundled from npm (e.g.
  `@fontsource/*`), not loaded from a CDN. Video slots are link cards to YouTube (title + link, no embedded
  player), so a mockup works offline apart from following the link.
- Docker: a multi-stage image based on the official `oven/bun` image. `docker build` and `docker run` must
  work, and the running container must serve the index page and all 7 mockups.
- Every page carries the fan notice and credits, from one shared snippet.
- **Build process (user's instruction):** the mockups are built by AI subagents in **batches of 2–3** running
  in parallel. The shared foundation (server, index page, sample data, credits snippet) is built before the
  first batch so the agents don't conflict.

## Git

- One commit for the repo bootstrap, then one commit per stage (foundation, each mockup batch).
- Push `main` to `origin` (Gitea) when all stages are done (user approved). If the remote already has commits, integrate them (rebase/merge), never force-push.

## Left to the builder

- File layout under `src/`, naming, and how the shared credits snippet is included.
- Visual details within each direction (palette, typefaces, motion), as long as each direction commits to its
  concept.
- The specific later songs chosen as motif callbacks, and which motifs are included.
- How the batches are grouped (for example 1–3, 4–5, 6–7).
- Whether to add a smoke test (for example, the server returns 200 for every mockup route).