# TODO And Progress

This is the active implementation checklist. Architecture lives in `SPECIFICATION.md`; usage lives in `README.md`; authoring conventions live in `MARKUP_GUIDELINES.md`.

## Current Status

- The shared client is feature-rich enough for Ink gameplay: line-based book layout, animated text, TTS, music, sound effects, images, choices, glossary notes, save/load restoration, and localized UI are implemented.
- The Ink engine is the current primary development engine.
- The YAML engine and Z-code engine need regression testing after the Ink-heavy client changes.
- Browser TTS and Kokoro provider modules exist but are not yet proven reliable.
- The codebase still contains logging noise and older architecture fragments that need cleanup.

## Shared Client

### Completed

- [x] Native ES module loader, dependency graph, progress overlay, and ordered initialization.
- [x] Responsive book layout that scales page, font sizes, and word positions relative to page size.
- [x] SmartyPants, German guillemet normalization, Hyphenopoly, and Knuth-Plass layout.
- [x] Paragraph/chapter/section/drop-cap rules.
- [x] Markdown emphasis with `*` and `_` syntax.
- [x] Right-page `#gloss[term](definition)` hover/focus notes.
- [x] Image rendering for landscape, square, and portrait cases, with history/save restoration.
- [x] Sound effect and music playback, including music lead-in, loop/once, and ducking.
- [x] TTS `none`, OpenAI, ElevenLabs, Browser Speech, and Kokoro provider modules.
- [x] TTS cache keys include provider, voice, speed, language, and exact normalized string.
- [x] Persisted speech enable state, provider, voice, speed, language, and volume preferences.
- [x] Fast-forward for text animation and active TTS fade/stop.
- [x] Choice UI, explicit keys, automatic key assignment, optional-choice styling, click and keyboard selection.
- [x] Localized popups for endings, errors, achievements, and alerts.
- [x] Credits/license dialog.
- [x] Line-addressed history scrolling model.
- [x] Choice-return turns continue to the choice point when autoplay is off.

### In Progress

- [ ] Polish custom scrollbar dragging so the thumb moves freely during drag and commits the scroll target only on release.
- [ ] Tighten automated checks around top-bar/options state initialization after reload.
- [ ] Improve automated visual regression coverage for page scaling, drop caps, image wrapping, and paragraph indentation.
- [ ] Improve automated audio tests for music ducking, sound effect timing, and fast-forward fadeout.
- [ ] Validate provider-specific speed conversion for all TTS providers against real API behavior.

### Pending

- [ ] Add a logging module with levels/categories to reduce console output and improve runtime performance.
- [ ] Show startup warnings/instructions when TTS APIs still need to be selected or configured.
- [ ] Put production-ready default option values into code/config.
- [ ] Get Browser TTS working reliably.
- [ ] Get Kokoro.js TTS working for English-language games.
- [ ] Get Kokoro.js TTS working for German-language games.
- [ ] Add a TTS module for self-hosted or local OpenAI-compatible servers.
- [ ] Test every documented `#tag` parameter and effect against parser, server, client rendering, playback, and save/load behavior.
- [ ] Remove local file paths and diff-comments from third-party license markdown, refresh included third-party licenses/material, update external libraries where possible, and move any local modifications into our code.
- [ ] Improve credits page layout with more window height, a larger notices markdown pane, and a Hollywood-style title scroll for creative credits.
- [ ] Clean up unused modules, obsolete functions, legacy comments, and vestigial fragments from older architectures.
- [ ] Add optical margin alignment/punctuation protrusion as typography polish if current hanging punctuation proves insufficient.

## Shared Server Architecture

### Completed

- [x] Shared `TurnResult` protocol used by all engines.
- [x] Shared game API shape: `newGame`, `loadGame`, `saveGame`, `hasSaveGame`, `getSaveGames`, `isGameRunning`.
- [x] Per-engine config files with metadata, locale, main game file, and asset paths.
- [x] `.env` default engine selection for `npm run dev` and `npm run start`.
- [x] Engine-specific dev/start/debug/inspect scripts.
- [x] YAML server renamed to `server-yaml.ts` so it is no longer implied as the generic server.
- [x] Z-code server/config/scripts use `zcode` naming; Zork is only the current story/prompt target.

### Pending

- [ ] Extract duplicated Express/Socket.IO/static-file/port-fallback setup into a shared server base.
- [ ] Replace session-local placeholder saves with durable server-side or browser-coordinated saves where appropriate.
- [ ] Clean up start scripts and add a Dockerfile for hosting the selected engine on Coolify.
- [ ] Decide whether `src/index.ts` should remain as the YAML CLI entry or be replaced by clearer `cli-yaml.ts` and engine-specific launchers.
- [ ] Remove `test-server-yaml.ts` if no current workflow depends on it.
- [ ] Add logger configuration to scripts: `LOG_LEVEL`, `LOG_CATEGORIES`, and engine debug defaults.

## Ink Engine

### Completed

- [x] Ink source compilation through `inkjs/full`.
- [x] Split Ink source files with a master include file.
- [x] Ink metadata handoff to client.
- [x] Ink choices converted to `ChoiceResult`.
- [x] Ink tags converted to shared `StoryTag`.
- [x] Choice preview tags for `#key`, `#letter`, `#optional`, and `#action`.
- [x] Save/load of Ink state plus client history state.
- [x] `#score`, `#error`, `#achievement`, and `#alert` tag behavior.
- [x] `#gloss[term](definition)` support on right-page text.

### Pending

- [ ] Add text-input turns to Ink games, switching the UI to command input for one round and returning to choices afterward.
- [ ] Add a full dynamic description of the created character to the score panel after the game intro.
- [ ] Continue authoring and testing Eibenreith content.
- [ ] Test all documented tag syntax inside real Ink source, including edge cases with includes and choice-local tags.

## YAML Engine

### Completed

- [x] Deterministic YAML world model and `GameRunner`.
- [x] YAML CLI path for testing without browser UI.
- [x] YAML web server emits `TurnResult` objects.

### Pending

- [ ] Test/debug the YAML engine after Ink-driven client changes.
- [ ] Continue development of the YAML engine.
- [ ] Replace command mirroring with the full LLM/world-model command loop when typography/audio testing no longer needs mirroring.
- [ ] Validate YAML-generated `#` tags through the shared parser/protocol path.

## Z-code Engine

### Completed

- [x] Z-code naming for engine scripts/config/server.
- [x] Current Zork I narrator implementation using `ifvms` plus OpenRouter prompt templates.
- [x] Z-code engine emits shared `TurnResult` objects.

### Pending

- [ ] Test/debug the Z-code engine after Ink-driven client changes.
- [ ] Finish the Z-code version: optimize prompt templates, choose the best LLM for the task, and test project memory behavior.
- [ ] Separate Z-code-generic logic from Zork-specific prompt assumptions.
- [ ] Validate save/restore of Z-machine state.
- [ ] Merge this branch with `master` after YAML and Z-code regression testing.