Map shell service pump control loop

docs/control-loop-atlas.md

@@ -16,13 +16,13 @@ anchor it, and where control is handed to neighboring subsystems.
 
 ## Bootstrap and Shell Service Bring-Up
 
-- Roots: `app_bootstrap_main` at `0x00484440` and `bootstrap_init_shell_window_services` at `0x004840e0`.
+- Roots: `app_bootstrap_main` at `0x00484440`, `bootstrap_init_shell_window_services` at `0x004840e0`, and `shell_install_global_controller` at `0x0051ff90`.
 - Trigger/Cadence: one-time bootstrap handoff immediately after CRT completion.
-- Key Dispatchers: `app_bootstrap_main`, `bootstrap_init_shell_window_services`, graphics config load or default-init helpers, runtime capability probes, and early shell service initializers under the `0x004610..0x0053f0..` branch.
-- State Anchors: shell service bundle rooted at `0x006d4024`, display/runtime globals under `0x006d4024` and `0x006d4030`, host capability flags gathered by `bootstrap_probe_system_profile`.
-- Subsystem Handoffs: hands control into shell/UI configuration, presentation defaults, and later per-frame shell work.
-- Evidence: `startup-call-chain.md`, function-map rows for `app_bootstrap_main`, `bootstrap_init_shell_window_services`, `shell_load_graphics_config_or_init_defaults`, `shell_reset_display_runtime_defaults`, and related graphics setup helpers.
-- Open Questions: where the first persistent main-loop owner object becomes stable; whether `0x0046c230` or one of the unnamed bootstrap children is the shell's first long-lived coordinator.
+- Key Dispatchers: `app_bootstrap_main`, `bootstrap_init_shell_window_services`, `shell_install_global_controller`, `shell_service_pump_iteration`, graphics config load or default-init helpers, runtime capability probes, and early shell service initializers under the `0x004610..0x0053f0..` branch.
+- State Anchors: global shell controller pointer `0x006d4024`, sibling display/runtime globals under `0x006d402c` and `0x006d4030`, and host capability flags gathered by `bootstrap_probe_system_profile`.
+- Subsystem Handoffs: after the global shell controller has been installed the bootstrap path enters the repeating `shell_service_pump_iteration` loop, which services shell-state work and hands each iteration down into the controller frame path.
+- Evidence: `startup-call-chain.md`, function-map rows for `app_bootstrap_main`, `bootstrap_init_shell_window_services`, `shell_install_global_controller`, `shell_service_pump_iteration`, `shell_load_graphics_config_or_init_defaults`, `shell_reset_display_runtime_defaults`, and related graphics setup helpers.
+- Open Questions: whether `bootstrap_init_shell_window_services` remains the long-lived shell main loop for all shell modes or later hands control to another outer coordinator after certain transitions.
 
 ## Shell UI Command and Deferred Work Flow
 
@@ -30,19 +30,19 @@ anchor it, and where control is handed to neighboring subsystems.
 - Trigger/Cadence: event-driven UI command dispatch plus deferred-message queue flushing during shell activity.
 - Key Dispatchers: `shell_dispatch_ui_command`, `shell_enqueue_deferred_work_message`, `shell_post_deferred_message_type5`, `shell_post_deferred_message_type6`, `shell_enqueue_deferred_message_type4`, `shell_enqueue_deferred_message_type1`.
 - State Anchors: shell object at `0x0062be68`, queue roots around `[this+0x11369d]`, `[this+0x1136a1]`, and `[this+0x1136a5]`, plus global routing gates at `0x006d4034`.
-- Subsystem Handoffs: routes into graphics config, scenario-text export, overlay generation, multiplayer UI, and presentation-facing deferred work.
+- Subsystem Handoffs: routes into graphics config, scenario-text export, overlay generation, multiplayer UI, and presentation-facing deferred work later drained by `shell_service_frame_cycle`.
 - Evidence: function-map shell rows around `0x00464410` and `0x0051f1d0..0x0051f460`.
-- Open Questions: where the deferred queues are drained in the wider frame loop; whether the shell command dispatcher is also used by hotkeys or only by UI callback tables.
+- Open Questions: whether the shell command dispatcher is also used by hotkeys or only by UI callback tables.
 
 ## Presentation, Overlay, and Frame Timing
 
-- Roots: shell display runtime setup and the frame-time history path under `shell_update_frame_time_history` at `0x0051fd70`.
-- Trigger/Cadence: recurring shell or presentation update loop once the window and display runtime are live.
-- Key Dispatchers: `shell_update_frame_time_history`, `shell_set_gamma_ramp_scalar`, 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 frame history ring at `0x006d403c`, display/runtime state inside the shell block near `[this+0x114282]` and `[this+0x11428a]`, presentation service pointer at `[this+0x0c]`.
-- Subsystem Handoffs: consumes world/object state for overlays and pushes deferred presentation messages back through shell queues.
-- Evidence: function-map rows for shell frame history, gamma ramp, world-anchor overlay builders, and graphics runtime helpers.
-- Open Questions: the exact outer frame pump is still unnamed; simulation cadence and shell presentation cadence may be separate loops that only rendezvous through shared shell state.
+- 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.
+- Open Questions: whether this bootstrap-owned shell pump also remains the steady-state owner for later shell modes and how simulation cadence rendezvous with the shell presentation cadence once gameplay takes over.
 
 ## Map and Scenario Content Load
 
@@ -76,7 +76,7 @@ anchor it, and where control is handed to neighboring subsystems.
 
 ## Next Mapping Passes
 
-- Name the first stable owner of the outer shell or presentation loop above the existing frame-history helpers.
+- Determine whether `bootstrap_init_shell_window_services` and `shell_service_pump_iteration` remain the long-lived shell main loop after early shell transitions or later hand off to another outer coordinator.
 - Connect the map bundle open path to the broader map/scenario load coordinator instead of only the database leaves.
 - Identify the owner loop that repeatedly services multiplayer transport I/O and dispatch-store work.
 - Ground the first real input ingest path and the first gameplay save/load dispatcher.