ai.interactive.fiction/TODO.md

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

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

• Shared TurnResult protocol used by all engines.
• Shared game API shape: newGame, loadGame, saveGame, hasSaveGame, getSaveGames, isGameRunning.
• Per-engine config files with metadata, locale, main game file, and asset paths.
• .env default engine selection for npm run dev and npm run start.
• Engine-specific dev/start/debug/inspect scripts.
• YAML server renamed to server-yaml.ts so it is no longer implied as the generic server.
• 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

• Ink source compilation through inkjs/full.
• Split Ink source files with a master include file.
• Ink metadata handoff to client.
• Ink choices converted to ChoiceResult.
• Ink tags converted to shared StoryTag.
• Choice preview tags for #key, #letter, #optional, #action, and #auto.
• Save/load of Ink state plus client history state.
• #score, #error, #achievement, and #alert tag behavior.
• #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

• Deterministic YAML world model and GameRunner.
• YAML CLI path for testing without browser UI.
• 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

• Z-code naming for engine scripts/config/server.
• Current Zork I narrator implementation using ifvms plus OpenRouter prompt templates.
• 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.