feat: headless mode

[Pertempto]

Implements spec from #46

Testing

• just build-docker
• just run-docker headless --bind 0.0.0.0
  • You need the --bind because the headless server runs inside the docker container
• Try accessing localhost:8484/render/latest in your browser
• It should show main screen of the TUI
• just input key "?"
• Try accessing localhost:8484/render/latest in your browser
• It should show help screen of the TUI

[github-actions]

cmd/headless/input.go — ParseKeyMsg: the ctrl branch uses tea.KeyCtrlA + tea.KeyType(baseKey[0]-'a'). This is brittle and unsafe (indexing baseKey[0] can panic for empty or multi-byte input, and arithmetic on key constants is fragile).

Please:

• Validate len(baseKey) >= 1 and restrict to a-z (ASCII) before mapping.
• Replace the arithmetic with an explicit mapping from letters to the corresponding tea.KeyCtrlX constants (or a small switch/table). This is safer and clearer.

[github-actions]

In cmd/headless/render.go:

• loadFonts() returns fontErr but callers don't check for regularFont/boldFont being nil before using them. Consider returning a clear error message if embedded fonts are missing and avoid dereferencing nil fonts in drawChar.

• parseANSI advances curY on newline without bounds checking; writing beyond rend.height may occur. Add bounds checks when incrementing or writing to grid to prevent panics.

• decodeUTF8 and parseANSI use manual UTF-8 decoding; consider using utf8.DecodeRuneInString from the standard library to handle edge cases and invalid sequences safely.

• drawChar recreates a truetype Face per cell and defers face.Close() each time; that's expensive. Cache font.Face objects per font/size in Renderer to avoid allocating per-glyph.

These changes will improve robustness and performance of the renderer.

[github-actions]

Changes Requested

• Fix unsafe ctrl key mapping in cmd/headless/input.go to validate input and use explicit mapping.
• Avoid calling s.model.Update while holding s.mu in cmd/headless/headless.go; release lock before model update and re-acquire when updating render storage.
• Add bounds checks in cmd/headless/render.go parseANSI for newline handling and use utf8.DecodeRuneInString. Cache truetype faces instead of recreating per-cell.

Summary of Changes

• Added new headless subcommand and HTTP server with endpoints /input, /state, /render/latest, and /render/{ts}.png.
• Implemented ANSI-to-PNG renderer with embedded fonts and tests for parsing and rendering.
• Implemented input parsing (ParseKeyMsg, ParseTypeToKeyMsgs) and request handling with FIFO render storage.
• Updated docs (README.md, AGENTS.md, specs/007-headless-mode.md) and added just recipes for headless usage.

Overall Feedback

• The feature is a substantial and useful addition, enabling programmatic interaction with the TUI and providing helpful tooling for agents and CI. However, there are some safety and performance issues that need addressing before merging:
  • Negative: Several unsafe assumptions (indexing strings, holding locks across model updates, manual UTF-8 decoding, per-cell font allocation) can lead to panics, deadlocks, or high CPU/memory use. These need fixes.
  • Positive: The tests are comprehensive for the new package, documentation and tooling were updated, and the design (render FIFO, endpoints, JSON responses) is solid. Great work on the spec implementation! 🎉

If you want, I can provide small code snippets for the ctrl mapping, utf8 usage, and face caching to speed up fixes. 🙂

[Pertempto]

@bambam955 something really cool you can do with this if you have jq installed to parse the output JSON from the POST /input:

just input key "tab" | jq -r ".ansi"

[Pertempto]

Code review bot feedback should be addressed in 7252225 and cdaae04

[Pertempto]

I ran all test steps on my end and it seemed to work well.