UI platform matrix¶
CCB's UI is one semantic action and view-model layer presented through several rendering and input routes. Every UI change must name which routes were exercised.
Routes¶
| Route | Build/runtime boundary | Evidence to collect |
|---|---|---|
| Curses | terminal cells, terminal colors and keyboard | terminal type/size, locale, key path |
| SDL2 tiles | fallback desktop renderer and SDL2 input/audio | OS, renderer, scale, font, device |
| SDL3 tiles | SDL3 renderer/GPU shader and recovery path | GPU/backend, artifact format, recovery |
| Native UI | ui_adaptor, input_context, curses-compatible windows |
resize/redraw and input actions |
| Lua UI/ImGui | capability-gated Lua pages and native ImGui integration | manifest, API v5, native fallback |
| Android | Java HUD/touch/text input plus SDL3 native runtime | device/API, UI mode, orientation, touch |
Shared invariants¶
Semantic action IDs remain stable; cell and pixel coordinates are converted at explicit boundaries; resize establishes layout before redraw; renderer recreation invalidates GPU resources; translated text and font fallback cannot assume a fixed byte or glyph width; and a new UI remains operable at narrow sizes.
Validation matrix¶
At minimum exercise keyboard navigation, cancel/confirm, resize, narrow viewport, translation, and the route directly changed. Renderer or coordinate changes need SDL2/SDL3 and Android where those branches differ. Lua UI work also validates the disabled/native fallback build.
Accessibility and failure evidence¶
Preserve visible focus, understandable action names, non-color-only state, readable contrast, and keyboard operation. Capture route, mode, resolution/scale, locale, input device, screenshot or recording, and the first debug log around a stale frame, bad coordinate, or lost input.
Generated and local data¶
Screenshots, recordings, renderer captures, and local UI profiles are evidence artifacts unless the task explicitly adds a checked fixture. Never commit user keybindings or device-specific layout state as project defaults without policy review.