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
- 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>
134 lines
8.2 KiB
Markdown
134 lines
8.2 KiB
Markdown
[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.
|