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

---
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 -p 10.20.20.2:8099:3000 --name epic-timeline-preview epic-timeline`
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.

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