Files
aevolution/docs/engineering/CLIENT_UI_STATE.md
T
dingoandClaude Opus 5.5 897055883a Add M9.8c launcher, legend, labelled inspector and click selection
Toolkit-independent launcher, selection, label and outcome-log models with
bounded inputs and fixed error text; Dear ImGui overlay in the native adapter
with toolkit-first event routing and capture; engineering panels for fixture vs
dev region, legend, inspector, session outcomes, notices and dialog. Additive
SessionClient::unreachable_attempts() bounds unreachable connects. Docs, CI
targets and validation evidence updated.

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

53 lines
3.3 KiB
Markdown

# M9.8b/c UI state, launcher and event bounds
Owned, toolkit-independent state; all calls on the client main thread. No authority
or simulation state. Time is explicit monotonic milliseconds supplied by the host.
Notifications: at most eight, text at most 240 bytes; reject invalid/oversized input,
expire by deadline, dismiss by unique id. Overflow evicts oldest and increments a
visible saturating counter. Notifications are not durable outcome history.
Dialogs: one active modal, title at most 96 bytes and body at most 240; opening a
second fails. Close requires the matching id so a stale click cannot close a newer
dialog. IDs never wrap. No credentials or grant bytes enter display messages.
SessionClient keeps at most 1024 queued ClientEvents. At 766 regular events it emits
a local backpressure event, disconnects, and has room for loss plus 256 unknown
intentions. It preserves all previously queued events and pauses reconnect until
take_events drains the queue. This is a local condition, not a protocol change.
Unprocessed wire outcomes remain unknown, never assumed failed or committed.
The native adapter's externally requested capture cannot be disabled by the legacy
Tab toggle. Releasing capture drains already queued input before new world actions.
M9.8c renders these through the toolkit overlay (below).
## M9.8c launcher, selection and panels
Toolkit-independent models (src/client/ui, tested by `client-ui-model`):
- **Launcher** (`launcher.hpp`): phases choosing, fixture, connecting, connected,
failed. Fields are at most 1024 bytes; endpoint is `host:port` with port 1-65535.
Files are read only when Connect is pressed: the CA at most 64 KiB and PEM-shaped,
the grant bundle 1-64 whole 108-byte records. Nothing is persisted; material lives
only in the session client. Errors are an enum with fixed text that never contains
paths or file bytes. Before the first Welcome, three losses (including refused
TCP/TLS attempts, counted by `SessionClient::unreachable_attempts()`) fail as
unreachable; a refused grant or exhausted bundle fails at once. Failed offers
Retry/Cancel; Cancel drops the session (its unresolved intentions become unknown).
- **Selection** (`selection.hpp`): topmost organism under the click, else the
habitat cell, else none. A selected organism absent from the latest view is
cleared; with no view at all the selection is kept but shows nothing.
- **Labels** (`labels.hpp`): value, present zero, missing (requested, no value), not
requested and undefined moisture are distinct kinds and texts. Freshness is
printed as current, stale or none.
- **Outcome log** (`outcome_log.hpp`): last 64 intentions by sequence with sent,
admitted, rejected, durable, not committed or unknown. It is the visible record;
notifications are not.
Native adapter (`Application`): toolkit events are processed first; while the
toolkit wants the keyboard or pointer, keys, wheel and clicks do not reach world
input. A click is a left press and release within 4 pixels that began outside any
panel. Capture changes from toolkit focus release world actions and require fresh
presses; the Tab toggle keeps its earlier ordering. The overlay callback runs after
world drawing; `request_screenshot` saves the next frame as BMP (engineering review).
Toolkit settings files and logs are disabled (`IniFilename`/`LogFilename` null).