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

status

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).