Epic-The-Musical-Timeline/docs/design/002-direction-round-notes.md

status

status
in-progress (brainstorming, round 2)

002 — Direction round notes (after the 7 mockups)

A running record of the user's words and the decisions they lead to, kept so that nothing gets lost between sessions. User quotes are verbatim. Lines marked (Claude's proposal) are suggestions the user has not confirmed yet. Newest entries go at the bottom.

Context: spec docs/specs/001-timeline-mockups.md produced mockups 01–07 (merged to main, 2026-10-23). This round picks the direction for the real app.

2026-10-23

1. Mockups that were dropped

"First off, a lot of good stuff. Lets start with the easy ones. Vertical story, constellation and score/waveform is too uninteresting."

• Dropped: 02 Vertical story, 05 Score/waveform, 06 Constellation.
• Still in play: 01 Editorial scroll, 03 Transit map, 04 Greek frieze, 07 Sea voyage.
• The dropped mockups' code stays in place until the direction is settled.

2. A 2D version alongside a 3D version

"They are all very nice. I see both a 2D version, and an accompanying 3D version, The editorial scroll combined with the transit map in some way could be nice fo9r a 2D layout / map, while using the sea voyage in 3d together with the greek frieze in some way could be nice as well. The sea voyage is nice to start off, buth could then in the different islands and places have sublevels, eg. landings where we see the cave of the cyclops, we see athenas fight in god games, and odysseus ithica when he comes home."

• 2D: editorial scroll combined with transit map, as a layout/map.
• 3D: sea voyage combined with the Greek frieze.
• The 3D starts on the sea voyage.
• Sublevels at islands and places ("landings"), with the user's examples:
  • the Cyclops' cave;
  • Athena's fight in God Games;
  • Odysseus coming home to Ithaca.
• Implication: the sample data must grow beyond Troy, Cyclops and Storm (Wisdom saga / God Games, Ithaca saga) so that those landings have content.

3. The frieze as the transition between 2D and 3D

"Hmm. Maybe we can have the freize's look be the one that tries the different stuff together, like a curtain call from the first section to go over in the second, where it starts off 2d with the freize, then slowly morphs into the sea voytage, then when he lands on cyclops islands, it goes back to the freize, then into the cave? For the looks, im not sure. On one hand I want the 2D map to be a browsable and perhaps simple display, yet I also want it to be a kind of map in the 3D one."

• The frieze is the connecting device, "like a curtain call" between sections.
• The flow:
  1. The experience starts in 2D, on the frieze.
  2. The frieze morphs into the 3D sea voyage.
  3. At a landing (e.g. the Cyclops' island) it returns to the frieze.
  4. From the frieze it goes into the 3D sublevel (the cave).
• Looks: undecided.
• The 2D map has two roles:
  • a browsable, perhaps simple display;
  • a map used inside the 3D experience.

4. The sea chart

(Claude's proposal) A single map serves both uses. On its own it is the browsable 2D page. Inside 3D it is the same chart, unrolled as an overlay on the captain's table. Clicking a port sails or jumps there.

"Yeah i did think sea chart, im just not sure how we have it easy to navigate and look at as with the editorial scroll and transit map."

• Agreed: the 2D map is a sea chart.
• Open problem: keeping the chart as easy to navigate and read as 01 and 03.

5. Sea-chart mockup round

"Hmm sure. Lets do 3 or 4 mockups and see."

• Four throwaway spikes on branch feat/sea-chart-round:
  • 08 Sea chart + log line
  • 09 Schematic sea chart
  • 10 Unrolling chart
  • 11 Atlas with insets
• Each spike also shows the chart as the compact in-3D overlay.
• Spike rules: no formal review loop; the user picks from what they see.

6. Process requests

"Remember to write my words and thoughts down, such that if context is autocompacted, we dont lose anything"

This file exists because of that request. It gets updated after every user message in this round.

7. Paused at the usage limit

"we have almost reached usage limit. Make the agents save their work for now, so we can continue without losing progress."

State when paused (branch feat/sea-chart-round, not pushed):

Spike	State
08	Only src/mockups/08-chart-logline/geo.ts is written: chart geography, route and log-line maths. Nothing imports it yet, and it has not been typechecked. main.ts and style.css are still stubs.
09	No code yet; the stub is unchanged. The design plan and resume checklist are written.
10	No code yet; the stub is unchanged. The design plan and resume checklist are written.
11	Not started. It is still a stub. Idea: an overview chart of the whole sea; clicking an island opens a zoomed inset chart with that saga's songs as ports.

• Brief and per-spike plans: docs/design/002-sea-chart-spikes/. It holds round2-brief.md and one <slug>-report.md per spike, each with a design plan, a what's-left checklist and the next step. Agents should keep writing reports to .superpowers/brainstorm/, and the controller copies them into this folder.
• Preview: http://10.20.20.2:8099/ still runs the main build (01–07). It does not show 08–11 yet.

To resume:

1. Read this file and the brief.
2. Dispatch one agent per spike, at most 3 at a time. Point each at its report file and the brief, and tell it to continue from the checklist.
3. Build 11.
4. Rebuild the preview container from this branch: docker build -t epic-timeline . && docker rm -f epic-timeline-preview && docker run -d --restart unless-stopped -e PORT=3000 -e CONTENT_DIR=/content -v /home/user/epic-the-musical-content:/content:ro -p 10.20.20.2:8099:3000 --name epic-timeline-preview epic-timeline (the content mount was added 2026-10-30, spec 003)
5. Ask the user which chart approach reads best.

2026-10-29

8. Resumed

"continue."

• Resumed from section 7. Spikes 08, 09 and 10 were redispatched (3 concurrent), each continuing from its saved report.
• Spike 11 follows when a slot frees.
• All four spikes are finished and committed on feat/sea-chart-round. Each final report is in docs/design/002-sea-chart-spikes/<slug>-report.md.
  • 08 Sea chart + log line: a full Admiralty-style chart on top, synced to an editorial log line below.
  • 09 Schematic sea chart: an octilinear transit diagram over a faint chart, with a slider that morphs it into rough true geography.
  • 10 Unrolling chart: the editorial scroll drawn on a vellum portolan, with a ship marker and a minimap.
  • 11 Atlas with insets: an overview of the whole voyage on one screen; each island opens an atlas plate.
• The preview at http://10.20.20.2:8099/ was rebuilt from this branch so the user can compare them.

9. Verdict on the sea-chart spikes

"8 and 9 doesnt work too well. 11 work ssurprisingly well, but the mtro map when you zoom into stuff doesnt hit as well. The style of 10 is much cooler."

• Dropped: 08 Sea chart + log line, 09 Schematic sea chart.
• Keep from 11: the atlas navigation: the whole voyage on one overview, islands opening inset plates.
• Not working in 11: the transit-style ("metro map") motif lines inside the zoomed plates.
• Keep from 10: the style: vellum portolan, rods, red dashed route, ship, compass rose.
• (Claude's proposal) Converge into one mockup, 12 Vellum atlas: 11's overview → plate navigation drawn in 10's vellum style. The metro band inside plates is replaced, and the plate motif treatment is a toggle inside the mockup with three options to compare:
  • A. Threads under the sea (10/01-style): soft threads below the route, knots at ports.
  • B. Pennants at ports: no lines; each port flies small coloured pennants for its motifs, and a selected motif draws a faint sea-current curve linking its ports.
  • C. Ink only: no motif marks on the chart until a motif is picked; then its ports are ringed and named parts are written beside them in the motif's ink colour.

10. Paused again at the usage limit

"We are going to hit 5 hour limit soon, wind down and wait for my go to continue."

• 12 Vellum atlas was being built by one agent from docs/design/002-sea-chart-spikes/12-vellum-atlas-brief.md. It was told to stop and write a pause report (what's done / checklist / next step) to docs/design/002-sea-chart-spikes/12-vellum-atlas-report.md; its partial work is in src/mockups/12-vellum-atlas/ and committed as WIP on feat/sea-chart-round (not pushed).
• To resume (only on the user's go): read this file, the 12 brief and the 12 report; dispatch one agent to continue from the report's checklist; check its screenshots; rebuild the preview container (command in §7); tell the user 12 is live and ask A/B/C.

11. Resumed

"All right, usage limits back. Continue."

• Resumed from §10: one agent continues 12 from its pause report.

• 12 is finished and committed (feat/sea-chart-round, not pushed); final report in docs/design/002-sea-chart-spikes/12-vellum-atlas-report.md. Preview rebuilt with 01–12.

• (Agent's recommendation, unconfirmed) A as default with more room on busy plates, borrowing C's hand-lettered part names for the picked theme. Known weak spot: A's faded labels on the 7-theme Cyclops plate are ~9px.

12. Motifs inside a plate: threads

"Threads, definetly."

• Chosen: treatment A, Threads under the sea, for motifs inside a plate. B (pennants) and C (ink only) are deselected.
• Known weak spot to fix when it is built for real: faded thread labels on busy plates (~9px on the 7-theme Cyclops plate) need more room.
• (Claude's proposal) The 2D sea chart is now 12 Vellum atlas with threads. Next open questions are the look of the whole and how the frieze/3D layers attach to this chart.

13. A short mockup of the transition

(Claude's question) The look of the whole: 1 vellum throughout, 2 two worlds (vellum chart and 3D, terracotta frieze only at transitions; Claude's recommendation), 3 frieze-led. Offered a short mockup of the transition.

"Short mockup please :)"

• The user did not pick 1/2/3 yet, so mockup 13 Curtain call shows the transition sequence with the look as a toggle (1/2/3), defaulting to 2.

• Sequence: frieze (2D) → morphs into the 3D sea → ship reaches Cyclops' Island → back to the frieze → into the cave. The vellum chart (12) appears as the map on the captain's table at sea.

• three.js is allowed in 13 (it is already a dependency; it reuses 07's sea).

• 13 is finished and committed (feat/sea-chart-round, not pushed); report in docs/design/002-sea-chart-spikes/13-curtain-call-report.md. Preview rebuilt with 01–13. Known rough spots: a small sideways camera shuffle at landfall, sun glare in looks 1/2, a boxy giant.

14. Verdict on 13 Curtain call

"Yes it looks pretty good! Small design issues here and there but these can be fixed. 1, 2 and 3 all look decent. The UI of 2 and 3 tend to look a bit better though. For the models/3d, its better to go stylistic than realistic. While going through the 3D experience, its still important to have the right side window open, to show information, paths, lyrics, and fan works."

• Accepted: the curtain-call flow (frieze → sea → landfall → frieze → landing) works; small design issues are fixable later.

• Look: all three are "decent"; the UI of 2 (two worlds) and 3 (frieze-led) looks better. Look 1 (vellum throughout) is effectively out; 2 vs 3 is not decided.

• 3D models: stylistic, not realistic.

• New requirement: during the 3D experience a right-side window stays open, showing:

  • information (about the current song/place);
  • paths (motif threads / the route);
  • lyrics;
  • fan works.

• (Claude's proposal) Converge into 14 Voyage with side panel: 13's flow with stylised models and a persistent right panel (tabs: About · Paths · Lyrics · Fan works), with a 2/3 look toggle. Fan works and lyrics are placeholders (no real lyrics, no real fan artists' names or links).

• 14 is finished and committed (feat/sea-chart-round, not pushed); report in docs/design/002-sea-chart-spikes/14-voyage-panel-report.md. Preview rebuilt with 01–14. Agent's choices: the panel stays open in all five beats (frieze beats too); the small vellum chart moved into the Paths tab. Rough spots: empty space around the frieze band with the panel open, light sea patches that read like lily pads, heavy outlines on the giant.

15. Verdict on 14: leaning look 2, paths too hidden

"This is actually surprisingly really good work. The design for 3 really makes the whole site feels like it works together, both in terms of frieze, the side panel and the world. However, im leaning a lot more towards 2. The colors pop a lot more. The paths feel a bit too hidden away now. All in all though, its looking better and better"

• Look: leaning strongly to 2 (two worlds): "the colors pop a lot more".

• What 3 does better: it makes frieze, side panel and world feel like one site. Worth carrying that cohesion into 2.

• Problem: the paths (motif threads) are "a bit too hidden away" inside the Paths tab.

• Not yet a final approval ("looking better and better").

• (Claude's proposal) Mockup 15 Voyage, look 2: look 2 only, borrowing 3's cohesion (shared frieze border/ornament and type across frieze, panel and HUD), and paths brought out of the tab, with a toggle of three placements:

  • A. Pinned strip — a compact thread strip always visible at the top of the panel, above the tabs.
  • B. Threads in the world — the current song's motifs as coloured ribbons in the 3D sea, trailing the ship and running ahead to where they return.
  • C. Timeline at the bottom — the step bar becomes a horizontal song timeline with motif threads under it (the original "big horizontal line"), with "you are here".

• 15 is finished and committed (feat/sea-chart-round, not pushed); report in docs/design/002-sea-chart-spikes/15-voyage-look2-report.md. Preview rebuilt with 01–15. Agent's recommendation (unconfirmed): C (bottom timeline) as the home for paths, with B's ribbons as an optional extra in 3D. Known: B's labels stack over the cave mouth; A is dense (numbers only); C takes ~220px of stage height.

• User asked to compare with 14: "can you open mockup 14 again so i can compare?" (14 is still served unchanged at /mockups/14-voyage-panel/.)

16. 14 vs 15 compared

"Thanks. First off, 15's font is very hard to read. 15 Accents with the freisa patterns on all the menus are very nice though, and the colors on the "between sagas a year at sea" looks nice. The hard question is paths A, B and C, cause they all have their strengths. In terms of menu, listen should be easier to do, and perhaps closer tied to the lyrics tab."

• Fix: 15's typography is "very hard to read" (the small, wide-tracked Cormorant capitals used for labels, and small SVG text). Go back to readable labels (14's style) at comfortable sizes.
• Keep: the frieze-pattern accents on all menus/panels (15).
• Keep: the colours of the "Between sagas · a year at sea" beat (15's beat 2).
• Paths A/B/C: undecided, "they all have their strengths".
• Listen: should be easier, and tied more closely to the Lyrics tab.
• (Claude's proposal) Mockup 16 from 15:
  • readable type: Inter for all labels/UI (no wide-tracked small caps), Cormorant only for large titles; nothing under 13px;
  • Listen + Lyrics as one tab: a player at the top of the tab (play, scrub bar with part markers), lyrics by part below; clicking a part jumps there, the current part is highlighted as it plays; plus a play button always visible in the panel header;
  • paths combined rather than chosen: C's timeline is the default home and can be collapsed to a slim bar; when collapsed, A's strip appears in the panel; B's ribbons in the sea are an on/off switch ("Threads on the sea").

17. Real content added outside the repo

"We have also added audio files, as well as a full version of Homer's Oddysey and Illiad to the epic-the-musical-content directory in home."

What is in ~/epic-the-musical-content/ (1.5 GB, checked 2026-10-30):

• Songs and Lyrics/EPIC - The <Saga> Saga (<year>)/: all 9 sagas, 40 songs as FLAC, 37 .lrc timed-lyrics files (3 songs have none), plus album.nfo (saga blurb, fandom-wiki credited) and folder.jpg cover art. File names: Jorge Rivera-Herrans - EPIC - The <Saga> Saga - NN - <Title>.flac|.lrc.
• Homers the Odyssey Book/The Odyssey.txt and The Illiad.txt: Project Gutenberg #1727 and #2199, Samuel Butler's prose translations (public domain). Being prose, they have books and paragraphs, not line numbers, so the sample data's "Book 9, lines 105–460" references will not map onto them.

(Claude's notes)

• The .lrc files make synced lyrics possible: the Listen & lyrics player can highlight the current line, not just the current part.

• The Odyssey text makes the "real place in the Odyssey" link able to open the actual passage.

• The audio, lyrics and cover art are Jorge Rivera-Herrans' copyrighted work. AGENTS.md currently says "lyrics are placeholders, never real lyrics". Proposed: keep this folder out of git and out of the Docker image; the server reads it from a CONTENT_DIR path, mounted read-only into the container. Needs the user's OK (it touches src/server.ts, the Dockerfile and the lyrics rule).

• User's answers (2026-10-30): content access: "Mount it, never commit"; next step: "Yes, in 17 after 16" (16 finishes with its simulated player, then 17 uses real FLAC playback, line-synced .lrc lyrics and the actual Odyssey passage). Implemented as spec docs/specs/003-content-mount.md.

• Note: Butler's translation uses Roman names (Ulysses, Minerva, Jove). Worth a line in the UI.

• 16 is finished and committed; report in docs/design/002-sea-chart-spikes/16-voyage-readable-report.md. Preview rebuilt with 01–16 and the content folder mounted. Known: timeline at its height budget with 3 motif rows; the panel strip still shows numbers only; ribbon labels sit on the mountain face.

18. Paused at the usage limit (third time)

"Wind down current session and wait for usage limit reset."

State (branch feat/sea-chart-round, not pushed, working tree clean):

• 01–16 committed; preview at http://10.20.20.2:8099/ runs 01–16 with the content folder mounted (/content/library.json, audio with seeking, Homer books all verified 200/206; no content in the image).
• Spec 003 (content mount) implemented and committed; docs/plans/003-content-mount.md must be git rm'd before a merge request.
• Not started: 17 (real audio, line-synced .lrc lyrics, the actual Odyssey passage), agreed by the user as "Yes, in 17 after 16". No agents are running.
• The user has not yet reacted to 16.

To resume (only on the user's go): read this file; show the user 16 (http://10.20.20.2:8099/mockups/16-voyage-readable/) and ask for their reaction; then wire slot 17 (server route, registry, index card, count test 16→17, AGENTS/PERMISSIONS count refs, three.js note) and brief one agent from a copy of 16, using /content/library.json, parseLrc from src/shared/lrc.ts and /content/homer/odyssey/<book>.json. Its test server must run with CONTENT_DIR=/home/user/epic-the-musical-content.

19. Resumed

"Continue."

• Resumed from §18. 17 (real content) is started now, as agreed; the user's reaction to 16 is asked in parallel.

• 17 is finished and committed; report in docs/design/002-sea-chart-spikes/17-voyage-real-report.md. Real FLAC playback with seeking, line-synced lyrics (click a line to seek), the Butler Odyssey passage in a reading view, fallback to 16 without the folder. Agent's choices: "Play voyage" stays silent (no excerpts, avoids near-autoplay); part buttons dropped in real mode (sample part times don't match the recordings). Open: passage start points are keyword guesses; parts/motifs aren't timed to the recordings yet (report proposes a small mapping file in the content folder).

20. Direction approved

(Claude's question) "If this is the direction, say so. I'll then write it up and build the real app (full album, all sagas) without stopping for more reviews…"

"Yes. But listen wit hthe lyrics and watch should probably both be in the listen & lyrics tab. Threads on the sea toggle works nicely. If hide timeline is off, maybe just put it into paths or something."

• Approved: the direction of 16/17 (look 2, frieze accents, curtain-call voyage, stylised 3D, side panel, bottom timeline with threads, real content) → build the real app. Per the user's global rule: spec → plan → execution with no extra review stops; report decisions at the end.
• Changes on top of 17:
  • "Listen with the lyrics" and Watch both live in the Listen & lyrics tab (not in About).
  • "Threads on the sea" toggle: keep as is ("works nicely").
  • When the timeline is hidden, the motif strip goes into the Paths tab (not pinned above the tabs).

21. Greek names, not Roman

"I dont like that Samuel Butler uses Roman names instead, is there a version with original names we can download on Project Gutenberg?"

• Yes. Downloaded into the content folder (Butler's files kept as a fallback):
  • The Odyssey (Butcher and Lang).txt: Gutenberg #1728, S. H. Butcher & Andrew Lang (1879): Odysseus, Athene, Poseidon, Zeus.
  • The Iliad (Lang, Leaf and Myers).txt: Gutenberg #3059, Lang, Leaf & Myers: same Greek names.
  • Checked by counting names: Butcher & Lang has 718× "Odysseus", 0× "Ulysses"; Pope's and Cowper's translations also use Roman names.
• The server now prefers these (src/content/routes.ts); the app drops the Roman-names note.

22. Resumed after a PC restart

"Continue work. We had to restart the pC."

• Build state (branch feat/voyage-app, not pushed): Task 1 album data, Task 2 shell/state, Tasks 3+4 content client + panel are committed. Tasks 5 (timeline) and 6 (world/landings/friezes) were interrupted mid-way; their partial files were on disk and both agents were resumed from their transcripts. Next: Task 7 (controller), Task 8 (docs, verify, deploy).

Open questions (in priority order)

1. Which sea-chart approach (08–11) reads best, or which mix? 11's navigation + 10's style (§9). Then A/B/C inside plates: A threads (§12).
2. What is the look of the whole? Leaning strongly to look 2, with 3's cohesion (§15). Where do paths live (15's A/B/C)?
3. How do 2D and 3D relate as products? Partly answered: in 3D a right-side panel stays open with info, paths, lyrics and fan works (§14). Whether the chart also stands alone is unconfirmed. 3b. Fan works: what are they (art, covers, animatics?), where do they come from, and how are they credited? No data model for them yet.
4. Which landings are in scope for the first build? The user's examples are the Cyclops' cave, God Games and Ithaca.
5. Earlier, still open from 001: lyrics copyright (deferred), branching policy, linter, and what happens to dropped mockups.