docs: restore stacked speed control documentation

Agent-Logs-Url: https://github.com/bedaHovorka/interlockSim/sessions/943bd48f-c5aa-4ff9-9008-4338e3578772

Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com>

Author: Copilot

CLAUDE.md

@@ -52,31 +52,37 @@ This project uses Gradle with Kotlin DSL. Java 21 LTS is required.
 ./gradlew runEditor               # Launch editor GUI
 ./gradlew runExampleGui           # Animated GUI simulation (Issue #268, milestone complete 2026-02-04)
 
+# Goal 7 speed-control shortcuts (simulation mode only)
+# 1-5    -> 0.5x, 1x, 2x, 5x, 10x
+# +/-    -> multiply or divide speed by 1.5
+# Space  -> pause/resume toggle (Goal 8 integration point)
+
 # Other tasks
 ./gradlew javadoc                 # Generate documentation
 ./gradlew dependencies            # Show dependency tree
 ```
 
 For complete build system documentation including dependency management, GitHub Packages authentication, manual JAR execution, and Gradle configuration files, see **[docs/KOTLIN_STYLE_GUIDE.md](docs/KOTLIN_STYLE_GUIDE.md)** under "Build & Development Environment".
 
-### Running Animated Simulation (Current Branch)
+### Running Simulation with Speed Control
 
-Use the animated GUI when you need the current real-time animated desktop view:
+Use the animated GUI when you need live speed changes:
 
 ```bash
-# Built-in animated example
+# Built-in animated example with speed controls
 ./gradlew runExampleGui
 
 # Equivalent manual JAR launch
 java -jar build/libs/interlockSim.jar exampleGui shuntingLoop 300
 ```
 
-Current branch behavior:
+For XML files loaded from the desktop UI, use **Simulation → Start...** and then adjust speed with:
+
+- the speed slider (`0.1x` to `10.0x`)
+- preset buttons/menu items (`0.1x`, `0.5x`, `1x`, `2x`, `5x`, `10x`, `50x`)
+- global keyboard shortcuts (`1`-`5`, `+`, `-`, `Space`)
 
-- `runExampleGui` uses fixed real-time synchronization for the built-in GUI example
-- the top `ControlPanel` shows time and status only
-- `StatusBar` is hidden in simulation mode
-- interactive Goal 7 speed controls are not wired into the current desktop UI on this branch
+The status bar shows `Speed: X.Xx` whenever the speed differs from `1.0x`.
 
 ### Directory Structure
 
@@ -189,9 +195,12 @@ For complete navigation services architecture, Koin DI integration patterns, and
 - AnimatedSim: Real-time animated GUI simulation (Issue #268, milestone complete 2026-02-04)
   - Physics-accurate rendering with velocity/acceleration visualization
   - Visual train movement with smooth interpolation
-  - `runExampleGui` currently starts a fixed `1.0x` real-time synchronized `ShuntingLoop` for the built-in GUI example
-  - `Frame` shows the animation `ControlPanel` and `EventTimelinePanel` in simulation mode and hides `StatusBar`
-  - Interactive Goal 7 speed controls are not currently wired into `Frame` on this branch
+  - Goal 7 speed control is built around `SimulationRunner`, which applies wall-clock throttling without changing event semantics
+  - `SimulationController` owns lifecycle, persists the selected speed, and reapplies it on the next simulation start
+  - `SimulationControlPanel` provides a `0.1x`-`10.0x` slider plus preset buttons up to `50x`
+  - `StatusBar.updateSpeedIndicator()` shows the live multiplier whenever speed is not `1.0x`
+  - `SimulationKeyBindings` installs global shortcuts (`1`-`5`, `+`, `-`, `Space`) while the frame is in simulation mode
+  - `Space` currently toggles `SimulationRunner.isPaused` directly as Goal 8 pause-feature groundwork
   - See `docs/ANIMATION_ARCHITECTURE.md` for technical details
 
 **XML Configuration:**

docs/SIMULATION_SPEED_CONTROL.md

@@ -1,29 +1,27 @@
 # Simulation Speed Control
 
-This branch does **not** expose interactive Goal 7 speed controls in the desktop GUI yet.
+Goal 7 adds live wall-clock speed control to the animated simulation GUI.
 
-What is currently available is a fixed real-time animated simulation mode for built-in GUI examples. This document describes the current user-visible behavior so the desktop UI is not documented more broadly than it is implemented.
+The control changes how fast events are presented to the user. It does **not** change simulation semantics, event ordering, or physics calculations.
 
-## Current Status
+## Overview
 
-The animated GUI currently provides:
+Use speed control when you want to:
 
-- a top `ControlPanel` with **Time** and **Status**
-- an `EventTimelinePanel` for simulation events
-- real-time synchronization for the built-in GUI example path
+- slow the model down for teaching or demos
+- run near real time while watching train movement
+- fast-forward through long scenarios
+- pause temporarily while preparing for deeper Goal 8 debugging workflows
 
-The animated GUI currently does **not** provide:
+Supported range:
 
-- a speed slider
-- speed preset buttons
-- speed-related menu items
-- keyboard shortcuts for speed changes
-- pause/resume controls
-- a speed indicator in the status bar during simulation mode
+- **0.1x** minimum speed
+- **50x** highest one-click preset
+- **100x** absolute runner limit
 
 ## Quick Start
 
-Launch the animated GUI example:
+Start the animated GUI:
 
 ```bash
 ./gradlew runExampleGui
@@ -35,46 +33,94 @@ Or run the JAR directly after building:
 java -jar build/libs/interlockSim.jar exampleGui shuntingLoop 300
 ```
 
-## Current GUI Behavior
+For your own XML file, open the desktop UI and use **Simulation → Start...**.
 
-When `exampleGui` starts, the application shows:
+When simulation mode is active, the GUI shows:
 
-- the animated railway canvas
-- the top control panel with `Time` and `Status`
-- the event timeline
+- the animated control panel (`Time`, `Status`, `Stop`)
+- the speed control panel (`Speed` slider, presets, live speed label)
+- the status bar speed indicator when speed is not `1.0x`
 
-During simulation mode, `Frame` hides the `StatusBar`, so there is no separate speed readout in the current UI.
+## GUI Controls
 
-## What “Speed Control” Means on This Branch
+### Speed slider
 
-For the built-in animated GUI example, `ExampleRegistry` creates `ShuntingLoop` with:
+- Range: **0.1x to 10.0x**
+- Step: **0.1x**
+- Best for fine adjustment while the simulation is already running
 
-- `enableRealTimeSync = true`
-- `speedMultiplier = 1.0`
+### Preset buttons
 
-That means the current GUI example runs at a fixed real-time rate intended for observation, not live user adjustment.
+The panel and **Simulation → Speed** menu provide these presets:
 
-The console example path still runs without this GUI-specific real-time synchronization.
+- `0.1x`
+- `0.5x`
+- `1x`
+- `2x`
+- `5x`
+- `10x`
+- `50x`
+
+`50x` is intentionally above the slider range. The slider stays clamped at its maximum visual position while the runner continues at `50x`.
+
+### Status indicator
+
+The status bar shows `Speed: X.Xx` whenever the current speed differs from `1.0x`. At the default speed the indicator is hidden to keep the bar uncluttered.
+
+![Simulation speed control panel](images/simulation-speed-control-panel.png)
+
+![Simulation speed status indicator](images/simulation-speed-status-indicator.png)
+
+## Keyboard Shortcuts
+
+Shortcuts are active in **simulation mode** while the application window has focus.
+
+| Shortcut | Action |
+| --- | --- |
+| `1` | Set speed to `0.5x` |
+| `2` | Set speed to `1x` |
+| `3` | Set speed to `2x` |
+| `4` | Set speed to `5x` |
+| `5` | Set speed to `10x` |
+| `+` | Increase speed by `×1.5` |
+| `-` | Decrease speed by `÷1.5` |
+| `Space` | Pause or resume the active simulation |
+
+Notes:
+
+- On most keyboards, `+` is **Shift+`=`**.
+- Numpad `+` and `-` are also supported.
+- `Space` is the current Goal 8 integration point: it toggles the runner pause flag directly.
+
+## Common Use Cases
+
+- **Educational demo:** start at `0.5x` or `1x`, then drop to `0.1x` before a switch or semaphore change.
+- **Normal observation:** keep the model at `1x` or `2x` and watch the event timeline.
+- **Long scenario review:** jump to `10x` or `50x` to move through uneventful periods quickly.
+- **Pre-debug pause workflow:** press `Space`, inspect the current state, then resume.
 
 ## Technical Details
 
-- `exampleGui` launches the animated desktop UI from `Main.runExampleGui(...)`.
-- The GUI example uses `ShuntingLoop(..., enableRealTimeSync = true, speedMultiplier = 1.0)`.
-- `Main.runExampleGui(...)` starts `context.run()` on a background thread.
-- `Frame` updates the animated `ControlPanel` time display with a 10 Hz Swing timer.
-- `Frame.switchToSimulationMode()` hides `StatusBar` and shows `ControlPanel` plus `EventTimelinePanel`.
-- A standalone `SimulationRunner` class exists in `desktop-ui`, but it is not wired into `Frame` or the current animated GUI flow on this branch.
+- Speed control is implemented by `SimulationRunner`.
+- The runner wraps `SimulationContext.run()` on a dedicated simulation thread.
+- Wall-clock throttling uses `sleep(simDelta / speedMultiplier)`.
+- `SimulationController` owns lifecycle, remembers the desired speed, and reapplies it on the next run.
+- Swing updates stay on the EDT; simulation execution stays off the EDT.
+- Pause blocks the simulation thread without advancing simulation time.
 
 ## Limitations
 
-- No runtime speed adjustment is available in the desktop UI.
-- No keyboard shortcut support is available for speed changes or pause/resume.
-- No speed indicator is visible during simulation mode because `StatusBar` is hidden there.
-- The built-in animated GUI example is fixed to `1.0x` real-time synchronization.
+- The slider stops at **10x** even though the runner supports up to **100x**.
+- `50x` is available from presets and the menu; reaching speeds above that requires incremental shortcuts or programmatic control.
+- Speeds above roughly **10x** are useful for throughput, but animation becomes progressively harder to follow visually.
+- At **50x** and especially **100x**, small simulation deltas often round down to **0 ms sleep**, so execution becomes effectively CPU-bound.
+- In CPU-bound ranges, expect higher processor usage and less visually smooth animation than at `1x`.
+- Console-mode runs do not expose the GUI speed controls.
 
 ## Troubleshooting
 
-- **I expected a speed slider or preset buttons:** they are not part of the current GUI on this branch.
-- **I cannot find a speed indicator:** the status bar is hidden in simulation mode.
-- **The simulation seems fixed to real time:** that is the current behavior of `exampleGui`.
-- **I need a faster run:** use the console example path when animation is not required.
+- **I cannot see the controls:** make sure you started the animated GUI, not the console example.
+- **The speed indicator disappeared:** that is expected at `1.0x`.
+- **`Space` does nothing:** a simulation must be running and the frame must have keyboard focus.
+- **The simulation feels too fast to follow:** use a preset such as `1x`, `0.5x`, or `0.1x`.
+- **CPU usage is high at very high speeds:** reduce speed to re-enable more wall-clock throttling.