feat(hud): F3 debug overlay — FPS, frame time, worst frame, state

A top-left readout for performance work: smoothed FPS and frame time, the worst
frame in a rolling two-second window, the active view, player speed, a frame
counter and the player's position in metres from the project origin.

- F3 toggles it, through the console variable gigline.Debug so a packaged build can
  be checked without a rebuild (IA_ToggleDebug).
- On automatically for -perf and -qaselftest, so a performance capture never depends
  on pressing a key first; off in the built demo, because a player should not see an
  FPS counter over Hollywood Boulevard.
- The first two seconds are a warm-up window excluded from the worst-frame figure.
  Without it the readout showed "worst 400 ms" for a healthy run: the startup shader
  and streaming hitches dominated the rolling maximum.

Measured cost on the self-test route at 1440p: 2.64 to 2.77 ms average, about 5 %,
still 6x the floor. The release-check number stays the overlay-off run; the
overlay-on series is committed beside it as
Docs/perf/0.2.0-walk-frametimes-overlay.csv.

Docs: controls (F3 row, overlay section, switch table), release checks (cost row),
architecture building block view (HUD and input list).

Docs/controls.md

@@ -13,6 +13,7 @@ Keyboard and mouse. The same list is shown in-game, bottom-right of the frame (`
 | Reset to start | `R` | Returns to the grounded spawn point |
 | Pause / release mouse | `Escape` | Second press resumes and recaptures the mouse |
 | Swap first / third person | `V` | First person is the default; the body is hidden in that view |
+| Show / hide debug overlay | `F3` | FPS, frame time, worst frame, view mode, speed and player position |
 
 ## Notes
 
@@ -24,6 +25,14 @@ Keyboard and mouse. The same list is shown in-game, bottom-right of the frame (`
 
 - **`V` swaps first and third person** (`0.2.0`, `IA_ToggleCamera`). The shipped default view is still first person, as the owner decided for `0.1.0`; third person adds a collision-tested spring-arm camera and a visible, animated body. `Escape` still pauses and releases the mouse in either view.
 
+## Debug overlay
+
+`F3` toggles a top-left readout: smoothed **FPS** and frame time, the **worst** frame in a rolling two-second window, the active view (first or third person), player speed, a frame counter, and the player's position in metres from the project origin. The first two seconds of a session are a warm-up window and are excluded from the worst-frame figure, because shader and streaming hitches there made a healthy run read as a 400 ms stall.
+
+It is **off in the built demo** — a player should not see an FPS counter over Hollywood Boulevard — and **on automatically** when the process is started with `-perf` or `-qaselftest`, so a performance capture never depends on someone pressing a key first. In a running build it can also be forced with the console variable `gigline.Debug 1`.
+
+Cost: about **5 %** of frame time at 1440p in the demo (2.64 → 2.77 ms average), measured in the same self-test route. The performance release check is recorded without the overlay for that reason; the overlay run is kept beside it as `Docs/perf/0.2.0-walk-frametimes-overlay.csv`.
+
 ## Review and harness switches
 
 These are command-line switches for the screenshot pipeline and QA runs, not player controls. They exist so a capture is reproducible rather than dependent on a human pressing keys at the right moment.
@@ -32,7 +41,8 @@ These are command-line switches for the screenshot pipeline and QA runs, not pla
 | --- | --- |
 | `-thirdperson` | Starts the pawn in the third-person rig, so a capture shows the body without anyone pressing `V` |
 | `-walk` | Holds forward input from the first frame — what makes the stride shot possible |
-| `-qaselftest` | Runs the scripted walk / reset / pause / transect checks and quits |
+| `-qaselftest` | Runs the scripted walk / reset / pause / transect checks and quits; also enables the debug overlay |
+| `-perf` | Enables the debug overlay for a manual frame-time check |
 
 The walking shot is driven per shot rather than by the switch: the shot actor enables the walk only while a tracking (`ShotFollow`) camera is being captured, and returns the pawn to spawn afterwards, so the fixed-camera shots still find it in place.