Epic-The-Musical-Timeline/docs/design/002-sea-chart-spikes/09-chart-transit-report.md

09 — Schematic sea chart (09-chart-transit): report

Status: done. Built from the saved plan. bun test (42 pass) and bun run typecheck pass. The build goes to the scratchpad outdir r2-09-chart-transit, served on port 4109. Nothing is committed.

Files: src/mockups/09-chart-transit/layout.ts (new), main.ts, style.css. index.html is unchanged.

The navigation idea

The ship's course is straightened into a transit-map schematic, like mockup 03:

• x is story time: a hop of 92 between songs, +100 per year, +70 when the saga changes.
• Each saga is a horizontal row, and the rows are joined by single 45° diagonals in the gaps between ports. Every port therefore sits on a horizontal, and every label is level and unrotated.
• Under the course is a faint Admiralty-style chart: pale water, rhumb lines from a compass rose, buff "saga islands" with a shoal band and dashed depth contours, and a dashed storm cell at Storm.

Motifs run as coloured lanes parallel to the magenta course:

• Character themes run on the left of the course and musical motifs on the right, each in a fixed lane.
• A lane is solid where the motif plays in consecutive songs. A single song gets a ~30px stub.
• A dotted lane means the theme is silent there and returns later.
• Each port is a capsule across the course and every lane that calls there.

A slider (with "Schematic" and "True geography" end buttons that animate) morphs every sample of the course to a rough equirectangular Aegean–Ionian map. Land crossfades to coastlines, a graticule fades in, lanes pull closer to the course, and names give way to track numbers.

What works

• Readable at a glance (the round's question). At the default 1440×900, all ten song titles, three saga names, every in-story time label, the year tags (Year 0, 1, 3) and the gap notes ("a year passes", "two years pass") are visible together with no hunting. Straightening the course is what makes this possible.
• Motif tracing is very clear.
  • Selecting a theme fades the other lanes to 13% and rings its ports in the theme colour.
  • Ports that don't carry it are greyed.
  • The key prints "plays in 5 songs: …".
  • The dotted "returns later" stretches show when a theme goes silent and comes back. 03 couldn't show that.
• One chart serves both uses. At ?overlay=1 the same SVG renders inside a ~1180×650 card over a dimmed sea gradient:
  • the viewBox is cropped to the course;
  • time labels are hidden and the key becomes chips;
  • a magenta ship marker reads "You are here: Survive";
  • clicking a port opens a popover with Sail here (the ship animates along the course and the pill reads "Sailing to Storm", then "You are here: Storm") and Song details.
• The morph earns its place. At ?morph=1 you see that the voyage really doubles back westward, and the slider makes the cost of geography obvious: ports 06–09 cluster at Messina and their names can't fit.
• Detail drawer.
  • Contents: track and saga, title, story time with years after Troy, Odyssey link, theme chips (which select the motif), parts with singers and motif dots, createAudioSlot and createVideoCards.
  • The chart pans left when the open port would sit under the drawer, e.g. Storm.
• Interactions and accessibility.
  • URL state: ?song=, ?motif=, ?overlay=1, plus ?morph=0..1 and ?pop=<id> for screenshots.
  • Escape closes the popover, then the drawer, then the motif.
  • Ports are keyboard-focusable.
  • Reduced motion is respected.
• Credits. The credit is fixed at the bottom and fully visible in every state.
• Verification. Click flows were checked over Chrome DevTools: port → drawer, key → motif, geography button → morph=1, overlay popover → Sail here → arrival, and popover → details. No console errors.

What doesn't work (or is weak)

• Geo mode is a demo of the trade-off, not a usable view.
  • The four Troy ports and the four Cyclops ports bunch up.
  • Capsules overlap at the turnarounds, and you only get track numbers.
  • The midpoint of the morph (~0.5) is messy: big rotated capsules and two land layers crossfading.
• The coastlines are hand-drafted and rough. Hellas and Thrace are one blob, and the Peloponnese is crude.
• Song positions are illustrative. Geo positions per song are rough guesses: Troy and Ismarus, off Cape Malea, the cave on Sicily's east coast, and Storm north-west of Sicily. They are not checked against the musical.
• Interchanges were redefined. In the sample data every song has 2 or more themes, so I made an "interchange" mean 3 or more themes meet. Otherwise every port would be one.
• Horizontal space is tight. The hop of 92 only works because titles wrap onto two balanced lines. The full album (~40 songs) won't fit one screen at this density, so it would need horizontal panning like 03, or rows that wrap per saga.
• Many dotted lanes. Seven lanes plus dotted returns along the whole course get busy. Without a motif selected, the dotted returns compete a little.
• Small chart details.
  • In overlay mode, the "N" of the compass is cropped and the ship marker covers the Survive capsule.
  • The Odysseus colour was pushed to a brown (contrast 4.6) so it doesn't collide with Warrior gold. It is no longer the data colour #f2e3b3.
• The key covers some land. The key panel covers the south-west corner of the Troy island, and the western lon labels in geo mode.

Screenshots

• screenshots/09-chart-transit-default.png
• screenshots/09-chart-transit-motif.png (?motif=warrior)
• screenshots/09-chart-transit-song.png (?song=storm, chart panned clear of the drawer)
• screenshots/09-chart-transit-overlay.png (?overlay=1)
• Extras:
  • screenshots/09-chart-transit-overlay-pop.png (Sail here popover)
  • screenshots/09-chart-transit-geo.png (?morph=1)
  • screenshots/09-chart-transit-mid.png (?morph=0.5)