Epic-The-Musical-Timeline/docs/TODO.md

TODO

Durable backlog. Agents append here instead of leaving TODO comments in source. Small, specific, independently actionable. Remove only when actually done.

Now

• Verify every // TODO(verify) field in src/data/sample.ts (56 after final review: saga names, singers, story times, Odyssey book/lines, motif descriptions, facts) before any content leaves mockup stage.

Next

• After a direction is chosen: decide whether the unused mockups are deleted or kept, and record the chosen direction in DESIGN.md.
• Add CI under .gitea/workflows/ (none exists): bun install --frozen-lockfile, bun test, bun run typecheck, bun run build; plus a check that AGENTS.md, CLAUDE.md, GEMINI.md and the docs/ paths exist and AGENTS.md is under 150 lines. Proposed, not added.

Someday

• Make bun dist/server.js work from any cwd (Bun 1.3.14 resolves bundled assets relative to cwd; try --asset-naming / naming, or re-check on a newer Bun). Today bun run start and Docker work around it.
• Derive src/server.ts routes and src/index.html cards from src/mockups/registry.ts instead of three hand-kept lists (tests catch drift today).
• Decide whether real lyrics may be shown (copyright question, deferred).

Recurring

• Maintain AGENTS.md:
  • Add a rule only in response to a real failure. When an agent repeatedly gets something wrong, that is a gap; add one line, ideally with a code example. Do not pre-empt hypothetical mistakes.
  • Update in the same PR as the convention change. A stale rules file is worse than none — it actively misleads.
  • Prune quarterly. Delete rules whose convention has changed or whose mistake no longer occurs.
  • Optional, cheap validation: run the same task twice in clean sessions, with and without the file, and compare steps and token use. This is how the published numbers were produced, and it is the only way to know your file is helping rather than costing 20% for nothing.

Known issues

• bun dist/server.js from the repo root crashes: TypeError: Bundled file "./index-….js" not found. Repro: bun run build && bun dist/server.js. Workaround: bun run start.
• Two mockups with byte-identical style.css fail bun run build with "Multiple files share the same output path" (reproduced by copying 01-editorial/style.css over 02-vertical-story/style.css). Identical main.ts files do not trigger it.

Deferred from final review (2026-10-23)

Shared / foundation

• src/server.ts: routes are hand-listed; generate them from src/mockups/registry.ts (see Someday).

Docs / permissions

• docs/DECISIONS.md: entries are oldest-first; the template is newest-first. Pick one.
• AGENTS.md: the architecture map duplicates docs/ARCHITECTURE.md; trim one.
• docs/plans/README.md: says "feature branch" while branching is still TODO(maintainer).

Sample data

• src/data/sample.ts: odyssey.url points at Butler's prose translation, so "lines X-Y" will not match the linked text; switch to book/chapter references or a lineated edition when verifying.

Mockup 01 editorial

• src/mockups/01-editorial/style.css: credit footer clips at about 761-1068px width with the folio open (parked; spec targets desktop 1440x900).

Mockup 02 vertical story

• src/mockups/02-vertical-story/main.ts: frame() interleaves layout reads and writes.
• src/mockups/02-vertical-story/style.css: saga marker padding inflates boundary gaps; .sea background snaps between sagas.

Mockup 03 transit map

• src/mockups/03-transit-map/main.ts: ruler repeat label reads "Year 0" for fall-of-Troy songs.
• src/mockups/03-transit-map/main.ts: --footer-h is not re-measured after fonts load.

Mockup 04 greek frieze

• src/mockups/04-greek-frieze/main.ts: post-drag click-swallow listener can stay armed if no click fires.

Mockup 05 score

• src/mockups/05-score/main.ts: .part.is-cued is not cleared on song change or close.
• src/mockups/05-score/main.ts: chip click re-renders the panel, which would restart the MP3.
• src/mockups/05-score/main.ts: has-song class is unused.

Mockup 06 constellation

• src/mockups/06-constellation/: per-frame Vector3 allocations; constructor failure leaks the canvas; WebGL probe context is not released.
• src/mockups/06-constellation/: label box cache goes stale on resize; Enter on the credits link opens a song.
• src/mockups/06-constellation/: fallback ruler is inert; legend/panel overflow; Troy saga caption is clipped.
• src/mockups/06-constellation/: check intro flight and easing in a real browser (unverifiable headless).

Mockup 07 sea voyage

• src/mockups/07-sea-voyage/: per-frame Color/Vector3 allocations; WebGL probe context is not released.

• src/mockups/07-sea-voyage/: no webglcontextlost handler; DPR is read once.

• src/mockups/07-sea-voyage/: waypoint tag innerHTML is unescaped; drawer clips the "The open sea" label.

• Mockup 14: the cave-mouth mask may repeat as holes during the curtain drop (Chrome, oversized mask region). Fixed in 15 by shrinking the region; 14 left as is (superseded).

• Homer books: with Butler's fallback text, the last book (Odyssey XXIV) also swallows the translator's notes after it. The preferred Butcher & Lang text does not have this problem.

• App v1 (spec 002) follow-ups:

  • 97 album values are // TODO(verify) (story years, some singers, Odyssey books/keywords, facts).
  • Parts and motifs are not time-aligned to the recordings; needs a mapping file in the content folder (part → first lyric line). Then the lyrics can show part headings and motif colours per line.
  • Passage starts in the Odyssey reading view are keyword guesses.
  • Fan works: decide sourcing, credit and permission process; the data type exists, the list is empty.
  • Mobile (<900px) is usable but not polished; no favicon yet (one 404 per page load).
  • Some frieze figures are small at five songs per saga; Charybdis reads mainly as a ring from the ship.
  • Timeline motif inks on parchment can look alike (Warrior / Thunder Bringer / Zeus).
  • tests/frieze.test.ts covers the curtain only on the reduced-motion (crossfade) path; the parting and doorway-zoom animations are checked by screenshots, not tests.
  • Ribbon labels on the sea are not clickable (the world has no click callback).