Files
aevolution/docs/adr/0084-engineering-ui-toolkit.md
T
dingoandClaude Opus 5.5 3320a8a574
Foundation / checks (deploy) (push) Successful in 3m26s
Foundation / checks (ecs) (push) Successful in 2m2s
Foundation / checks (client) (push) Successful in 12m47s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 11m44s
Foundation / checks (checks) (push) Canceled after 17m14s
Foundation / checks (postgres) (push) Canceled after 4m27s
client: skip used grants; scale the engineering UI with the window
- A stale_grant before Welcome spends only that grant: the session tries the next one
  in the bundle and ends as exhausted when none is left (other refusals still stop).
- UI scale (ADR-0084 amendment): embedded scalable font (ProggyForever), scale from
  logical window height (720 reference, 1.0-2.5) times a Ctrl+= / Ctrl+- nudge; panel
  sizes and table columns in logical units; movable panels placed again per scale.
- --size W,H for engineering review screenshots.
- Tests: client_remote_session (stale grant, exhausted), client_ui_state (scale).
Refresh the dev session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 12:09:57 -04:00

134 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
[Reviewed]
# ADR-0084: Engineering UI toolkit and ownership boundary
## Status
Accepted for the isolated M9.8a engineering UI probe, 2026-10-02. User delegated
UI selection. Dear ImGui 1.92.9b, MIT, upstream commit
`f1cc2ae15e53a861a874c3034aae6798fde194ab`; archive SHA-256
`21d8a0a565e85dce943e375db00812c2f3f0ab21f3f0f7964e364a63422d7f99`.
Published 2026-07-31; upstream latest-release API and tag checked 2026-10-02.
Checksum is locally measured over the upstream HTTPS archive, not an independent
signature. The pin is in tools/imgui-pin.cmake. Broader application integration
follows the probe. Final player UI remains undecided.
## Context
M9.4/M9.5 intentionally used rectangles and unlabelled gauges. M9.8 now requires
readable text, a launcher, dialogs, dismissible notifications, click selection and
control rebinding. The existing client uses SDL3 and SDL_Renderer. The headless
libraries and immutable biological views must remain toolkit-independent.
## Decision
Use Dear ImGui's upstream SDL3 platform and SDL_Renderer3 rendering adapters behind
the private native client boundary. Implement owned application state for toasts,
selection, dialogs and action bindings; do not equate toolkit widget state with
simulation or session authority. Reuse toolkit text, input, layout and widgets
instead of implementing those primitives. Disable unnecessary multi-window features.
Keep public biological/render snapshot contracts free of ImGui and SDL types.
Toolkit initialization follows the window/renderer; shutdown precedes their teardown.
UI capture is resolved before generating world intentions. Document and test event
ordering, focus loss, modal capture and binding changes together with API changes.
Before merge of integration: choose a reviewed release supported by its actual
source history (not an assumed latest version), record source commit/archive hash,
retain MIT licence and embedded font/third-party notices, build only needed sources,
measure incremental artifact size and idle/frame cost, and verify lifecycle on both
supported toolchains. Normal configure must not download dependencies. Use explicit
preparation and pinned sources as in ADR-0077; no new general package manager.
## Alternatives considered
| Option | Assessment |
|---|---|
| Dear ImGui | C++ widget API and upstream SDL3/SDL_Renderer adapters fit the current engineering client. Low integration surface; immediate-mode work and accessibility limitations need measurement/review. Preferred. |
| RmlUi | Retained documents and styling could suit final game interfaces. Integration adds document/assets/font and render-interface work; no demonstrated M9 benefit over the existing renderer path. Keep as a later product-UI candidate. |
| Custom text/widgets | Avoids a toolkit dependency but requires fonts, editing, focus, layout and popup behavior to be built and maintained; rejects the user's preference for an established framework. |
These are integration assessments, not measured performance or binary-size rankings.
## Benefits
Readable engineering tools, reusable interaction primitives and narrow dependencies.
The simulation stays independent and the final game UI is not prematurely selected.
## Costs
New pinned source and licence obligations, text/atlas resource lifetime, input capture
integration and Windows/Linux visual validation. Toast/binding policies remain ours.
## Risks
Toolkit input capture can leak movement or selection if handled after world input.
Immediate-mode UI is not a hard frame-time guarantee. Font/DPI/accessibility behavior
requires real review. Dependency versions and notices must be checked in the pinning
segment, not inferred from this high-level comparison.
## Consequences
Revisits ADR-0081's scoped decision to defer ImGui once labelled engineering UI is
needed. M9.8a records the pin and executed probe evidence in VALIDATION.md.
M9.8 delivery is tracked in ../engineering/M9_8_DELIVERY_PLAN.md.
## Primary-source evidence reviewed 2026-10-02
- https://github.com/ocornut/imgui/blob/master/docs/BACKENDS.md — upstream SDL3 and SDL_Renderer3 adapters; platform/render separation.
- https://github.com/ocornut/imgui/blob/master/LICENSE.txt — MIT licence; notice inventory in third_party/imgui/README.md.
- https://github.com/ocornut/imgui/blob/master/docs/FAQ.md — input capture guidance and integration responsibilities.
- https://github.com/ocornut/imgui/releases — release/maintenance evidence; v1.92.9b selected above.
- https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html — context and rendering integration requirements for the alternative.
The probe compiles core, draw, tables, widgets and the SDL3/SDL_Renderer3 backends;
no demo, docking, multi-viewport, FreeType or external font dependency is introduced.
Use the embedded ProggyClean bitmap font explicitly for the probe. Retain LICENSE.txt,
docs/FONTS.md, imgui_draw.cpp and the stb headers' embedded notices at
packaging. The bundled ProggyForever data also carries notices in imgui_draw.cpp;
include the source notice inventory even when that font is not selected.
Normal headless/client configuration does not require ImGui until explicitly enabled.
## M9.8b application state contract
Accepted for bounded toolkit-independent state. See
[CLIENT_UI_STATE](../engineering/CLIENT_UI_STATE.md): eight notifications with
240-byte text and explicit expiry/overflow; one id-matched modal. Input capture
requested by an external UI cannot be disabled by the legacy Tab shortcut.
Rendering and toolkit focus integration remain M9.8c.
SessionClient's local event delivery is capped at 1024, reserving room for all 256
unresolved intentions plus loss/backpressure events. On backlog it disconnects,
marks views stale and waits for the consumer to drain before reconnecting. Earlier
queued outcomes are preserved. This changes no wire format or biological rules.
## M9.8c integration
Accepted for the engineering client. The toolkit context is owned by the platform
`Application` (created after and destroyed before the SDL renderer, reattached on
device reset), with ini/log files disabled and the embedded bitmap font. Toolkit
events are routed before world input; `WantCaptureKeyboard`/`WantCaptureMouse`
feed the same capture path as external capture, so typing in a field or clicking
a panel never moves, pans, zooms or selects. Only the app's panels file draws
widgets; launcher/selection/label/outcome-log state stays toolkit-independent and
tested without SDL. Remote failures are reported through fixed launcher text; no
path, certificate or grant byte is displayed, logged or saved.
`SessionClient::unreachable_attempts()` (additive API) counts connection attempts
that fail before any session event, so the launcher bounds "unreachable" without
an event per retry. No wire format, grant or biological rule changes.
M9.8c review corrections: the adapter reads the pinned toolkit's internal window
list (`imgui_internal.h`: active, unhidden windows' clipped rectangles and the open
popup stack) to decide pointer ownership per SDL event; `WantCaptureMouse` alone is
one frame late for same-batch input. This internal use is tied to the 1.92.9b pin
and must be rechecked on any toolkit update (the lifecycle and panel tests fail if
it regresses). External capture no longer cancels the Tab toggle. Mode and remote
session lifetime are owned together (`SessionHost`).
## Amendment (2026-10-09): scalable font and UI scale
The maintainer asked that the UI grow with the window, after a maximized window left it
at 13 px.
- **Font.** The client now loads Dear ImGui's embedded scalable font, ProggyForever
(`AddFontDefaultVector`), in place of the ProggyClean bitmap font. Both are embedded
in the pinned 1.92.9b sources, and the package's notice inventory already lists
them. No new dependency.
- **UI scale.** Logical window height over 720, clamped to 1.0–2.5, times a user nudge
of 0.5–2.0 in steps of 0.1 (Ctrl+= and Ctrl+-, consumed before world input and not
saved). Display DPI is already in the logical size, through SDL's high-pixel-density
window and the renderer's framebuffer scale.
- **Applying it.** The scale goes to ImGui's `FontScaleMain` and to `ScaleAllSizes`,
taken from the unscaled style. Panel sizes are given in logical units at that scale.
Movable panels return to their default place and size once, at each new scale.