rrt/docs/control-loop-atlas/presentation-overlay-and-frame-timing.md

## Presentation, Overlay, and Frame Timing

- Roots: the bootstrap-owned `shell_service_pump_iteration` at `0x00483f70`, the shell-state service
  pass `shell_state_service_active_mode_frame` at `0x00482160`, the installed global shell
  controller at `0x006d4024`, the pending frame-cycle owner `shell_service_frame_cycle` at
  `0x00520620`, and the frame-time history path under `shell_update_frame_time_history` at
  `0x0051fd70`.
- Trigger/Cadence: recurring bootstrap-owned shell service work once the active mode, controller
  window, and display runtime are live; special modal or content-building paths can also force
  immediate frame servicing inside that broader cadence.
- Key Dispatchers: `shell_service_pump_iteration`, `shell_state_service_active_mode_frame`,
  `shell_service_frame_cycle`, `shell_refresh_presentation_frame`,
  `shell_update_frame_time_history`, `shell_get_smoothed_frame_scalar`,
  `shell_set_gamma_ramp_scalar`, and overlay builders such as
  `shell_queue_single_world_anchor_overlay`, `shell_queue_world_anchor_overlay_list`, and
  `shell_queue_indexed_world_anchor_marker`.
- State Anchors: shell state at `0x006cec74`, active mode pointer `0x006cec78`, shell frame history
  ring at `0x006d403c`, display/runtime state inside the controller block near `[this+0x114282]` and
  `[this+0x11428a]`, presentation service pointer at `[this+0x0c]`, and the native controller window
  handle at `[this+0x00]`.
- Subsystem Handoffs: the bootstrap-owned pump runs shell-bundle polling and shell-state maintenance
  before the shell-state pass synchronizes active-mode helpers and modal-status work and dispatches
  the controller frame cycle, which then consumes world/object state for overlays and presentation
  refresh, uses the controller window handle for one-time `ShowWindow` and related UI interaction,
  and drains the deferred work queues at the end of the cycle.
- Evidence: function-map rows for `shell_service_pump_iteration`,
  `shell_state_service_active_mode_frame`, `shell_service_frame_cycle`,
  `shell_flush_deferred_work_queues`, frame history, gamma ramp, world-anchor overlay builders, and
  graphics runtime helpers.
- Current Boundary: the current static boundary keeps simulation cadence rendezvous inside the same
  shell-owned presentation path. After world entry, later stepping still re-enters
  `shell_state_service_active_mode_frame` and `shell_service_frame_cycle` rather than surfacing a
  detached gameplay-only presentation loop.