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