From 6794a3e76375a9a0c5a0b19fe1efad78c6943095 Mon Sep 17 00:00:00 2001
From: Kevin Martinez <ksmartinez23@outlook.com>
Date: Thu, 12 Nov 2026 11:55:27 -0500
Subject: [PATCH 1/5] docs(diagnostics): assess developer diagnostics gaps
 (DEBUG-1)

---
 docs/evaluations/debug-1.md | 116 ++++++++++++++++++++++++++++++++++++
 odd/tasks/debug-1.md        |  44 ++++++++++++++
 2 files changed, 160 insertions(+)
 create mode 100644 docs/evaluations/debug-1.md
 create mode 100644 odd/tasks/debug-1.md

diff --git a/docs/evaluations/debug-1.md b/docs/evaluations/debug-1.md
new file mode 100644
index 00000000..ad5390bb
--- /dev/null
+++ b/docs/evaluations/debug-1.md
@@ -0,0 +1,116 @@
+# DEBUG-1: developer diagnostics and runtime inspection
+
+Issue NastMz/MicroEngine#119. Record: [`odd/tasks/debug-1.md`](../../odd/tasks/debug-1.md). Date: 2026-11-12.
+The question: can a developer outside this repository find out why their game misbehaves (a hitch, a body that falls
+through the floor, a jump that never fires, a crash) with the published SDK, without reading the engine's source? The
+issue asks for a gap assessment, a small diagnostic workflow, and only the primitives that the gaps justify, optional
+and cheap when disabled.
+
+## 1. What exists today
+
+| Area | What a game can read | Where | Default |
+| --- | --- | --- | --- |
+| Frame timing | `FrameProfiler`: per-frame events, update, render, present, steps, allocated bytes, GC counts; p50–p99.9, hitches; JSON/CSV | `src/MicroEngine/Core/FrameProfiler.cs`, `RunOptions.Profiler`, `--profile FILE` | off; the unprofiled loop takes no timestamps |
+| Graphics | `GraphicsCounters`: passes, draw calls, pipeline changes, texture bindings, uploads, live resources; cumulative, subtractable | `GraphicsDeviceBase.Counters` (`GraphicsDeviceBase.cs:220`) | always on, one count per submitted list |
+| Platform | `IPlatformDiagnostics`: renderer, driver, VSync, GPU facts | `src/MicroEngine/Core/Platform.cs:64` | SDL only |
+| Assets | `AssetScope.Loaded` (path, kind, bytes, load ms, during play), `AssetCache.Statistics`, a warning for a slow load during play | `AssetScope.cs:225`, `AssetCache.cs:297` | always on |
+| Audio | `ActiveVoices`, `MaxVoices`, `RefusedSounds` | `AudioEngine.cs:217` | always on |
+| Scenes | `SceneManager.Current/Stack/Count`; `SceneWorld.Count`, `Children`, `All<T>()`, `WorldMatrix` | `src/MicroEngine/Scenes/Scene.cs` | always on |
+| Physics | `Bodies`, `KindOf`, `PositionOf`, `RayCast`, `Overlap`, `ContactEvents`, `SensorEvents` | `IPhysicsWorld2D.cs` | always on |
+| Input | `Devices`, `Players`, `Layers`, the frame's raw `Events` | `InputSystem` | always on |
+| Logging | `ILog` (`ConsoleLog`, stderr, Info and above), `Game.Log`, replaceable service | `src/MicroEngine.Kernel/Logging/Log.cs` | on |
+| Errors | `RunResult.Error`; typed exceptions (`AssetLoadException`, `GraphicsCapabilityException`, `PhysicsCapabilityException`...) | `GameRunner.cs:82` | on |
+| Determinism | `HashState`, `--state-trace` | `StateTrace.cs` | off |
+
+`src/` uses no `EventSource`, `System.Diagnostics.Metrics` or `ActivitySource`, and no samples or guide pages use any
+of the rows above except `--profile` and asset statistics (`docs/manual/lifecycle.md` "Measuring a game",
+`docs/manual/assets.md`).
+
+## 2. Scenarios an external developer meets
+
+Each scenario is a question someone asks while making a game; the verdict says whether the published SDK answers it
+today.
+
+1. **"My game stutters every few seconds."** `--profile` records hitches, allocations and GC counts per frame, and
+   the summary reports them. The developer learns *that* a frame was slow and that it allocated, but not *which* of
+   their systems took the time: update and render are one number each, though `FrameSchedule` already has named
+   systems. They cannot watch it live either: the profiler writes a file at exit and the game cannot read it.
+   **Partial.**
+2. **"Why is rendering slow on this phone?"** Draw calls and pipeline changes are counted, but on
+   `GraphicsDeviceBase`, while `Game.Graphics` is an `IGraphicsDevice`; the developer has to know to cast. The
+   profiler does not record them per frame. **Partial, hidden.**
+3. **"My character falls through the floor / the crate does not touch the ramp."** No way to see shapes, contacts or
+   sensors: no debug draw exists, a body's shapes cannot be listed, and a shape's geometry cannot be read back from
+   `IPhysicsWorld2D`. Drawing them means keeping a copy of every `ShapeDescription` in game code. **Fails.**
+4. **"My jump does not fire."** Raw events and device state are readable, but which input layer consumed the event,
+   or which actions fired this frame, is not recorded anywhere. **Fails.**
+5. **"Something is wrong and the console says nothing."** `ILog` exists, but the engine itself writes platform,
+   audio and launcher messages straight to `Console.Error` (20 call sites), so a game that routes `ILog` to a file or
+   an overlay misses them. **Partial.**
+6. **"The game crashed on a tester's machine."** The launcher prints `error: {message}` only: no stack trace, no file,
+   no record of the frames before it. A tester cannot send anything useful. **Fails.**
+7. **"Show me an FPS counter / timings while I play."** No debug drawing that update code can call (draw a line now,
+   at this world position, for this frame), and no ready numbers to put on screen. The developer can build it on
+   `DrawAboveScenes`, `IRenderer` and `Game.Font`, given the numbers. **Fails for the numbers; the drawing is
+   possible but every game rebuilds it.**
+8. **"Is this texture still loaded? Which sounds are playing?"** Assets: answered (`AssetScope.Loaded`). Audio:
+   counts only behind a cast, no list of playing sounds. **Mostly answered.**
+9. **"Use the .NET tools I already know."** `dotnet-counters`, `dotnet-trace` and Visual Studio's diagnostics show
+   the runtime's GC and CPU, but nothing from the engine: no frame time, draw calls or voices appear there.
+   **Fails for engine data.**
+
+## 3. Options weighed
+
+- **Build a profiler UI or an inspector window.** Rejected: the issue asks for reusable infrastructure over prebuilt
+  UI, and perf-1 already ruled out embedding Tracy or Superluminal. A desktop inspector would not run on the browser
+  or mobile targets.
+- **Publish engine numbers through `System.Diagnostics.Metrics`.** Chosen for the external-tool side: it is in the
+  base library (no package), `dotnet-counters`, `dotnet-monitor` and OpenTelemetry read it, and an instrument nobody
+  listens to costs one branch. It covers scenario 9 without the engine writing any tool.
+- **One in-game diagnostics surface the game reads each frame.** Chosen for the in-game side (scenarios 1, 2, 7):
+  the same numbers the meter publishes, as a struct a game can put on screen, log or assert in a test.
+
+## 4. Proposed primitives
+
+Each is optional and costs nothing measurable when unused; each comes with a test, an example in `samples/Examples`
+and a manual page section. Contract changes are marked.
+
+1. **`Game.Diagnostics` (frame statistics).** The last frame's update, render and present time, fixed steps,
+   allocated bytes, GC counts per generation, the graphics counters for that frame (`GraphicsCounters` delta) and
+   audio voices. Off by default; `Diagnostics.Enabled = true` (or `--diagnostics`) turns on the timestamps the
+   profiler already takes. Scenarios 1, 2, 7, 8.
+2. **Per-system timing.** When enabled, `FrameSchedule` times each named system; `Diagnostics.Systems` lists name,
+   phase and time. Scenario 1.
+3. **Engine meter.** A `Meter("MicroEngine")` with frame time, draw calls, allocations and voices as observable
+   instruments, read only when a listener is attached. Scenario 9.
+4. **`DebugDraw`.** An immediate queue update code can call (`Line`, `Rect`, `Circle`, `Text`, in world or screen
+   space, with a duration), drawn after the scenes and cleared each frame; calls do nothing while it is disabled.
+   Scenarios 3, 4, 7.
+5. **Physics shape inspection.** `IPhysicsWorld2D` gains `ShapesOf(body)` and `DescriptionOf(shape)` as default
+   interface members (a contract addition, not a break: an external backend that does not override them throws
+   `PhysicsCapabilityException`), and `PhysicsDebugDraw.Draw(world, DebugDraw)` draws shapes, sensors and the step's
+   contacts. Scenario 3.
+6. **Input trace.** While diagnostics are enabled, `InputSystem` records, per frame, which layer handled each event
+   and which actions were pressed; `Diagnostics.Input` reads it. Scenario 4.
+7. **Engine messages through `ILog`.** The 20 `Console.Error` call sites go through the game's `ILog` (the default
+   still writes stderr, so the console output keeps its text). Scenario 5.
+8. **Crash report.** On an unhandled game error the launcher writes `crash-<time>.txt` beside the save folder: the
+   exception with its stack, the platform diagnostics, the last log lines and the last frames' statistics; the
+   console line names the file. Scenario 6.
+9. **Counters without casts.** `IGraphicsDevice.Counters` (default interface member returning the base class's
+   counters) and `AudioMixer.Statistics`. Scenarios 2, 8.
+
+**Workflow demonstrated** (`samples/Examples`, a "Diagnostics" example and a guide page "Diagnosing a game"): press
+F3 to show an overlay with frame time, per-system times, draw calls and allocations, physics shapes and the input
+trace; run with `dotnet-counters monitor -n <game> --counters MicroEngine` to watch the same numbers outside the game;
+crash the example on purpose and read the crash file.
+
+**Not proposed:** listing every entity or attachment type, a camera registry, asset holder counts, a list of playing
+sounds. Each is a single game-side query today or needs a design of its own (an entity inspector belongs with the
+ENTITY-1 work); they stay out until a scenario needs them.
+
+## 5. Delivery
+
+About 1,500 changed lines in four work units: (a) items 1–3 and 9, (b) items 4–5, (c) items 6–8, (d) the example,
+guide and release notes. Items 5 and 9 add interface members with defaults, item 7 changes where engine messages go
+(the default text stays the same): these are listed under `## Next release` in the release notes.
diff --git a/odd/tasks/debug-1.md b/odd/tasks/debug-1.md
new file mode 100644
index 00000000..ebbd6606
--- /dev/null
+++ b/odd/tasks/debug-1.md
@@ -0,0 +1,44 @@
+# DEBUG-1: developer diagnostics and runtime inspection
+
+Objective: find what an external developer cannot diagnose today with the published SDK, then implement the justified
+primitives, optional and cheap when disabled. Issue NastMz/MicroEngine#119. Branch `feat/debug-1`. Delivery strategy:
+`ask-on-risk`. Test runner: `dotnet test MicroEngine.slnx -c Release`. Evaluation:
+[`docs/evaluations/debug-1.md`](../../docs/evaluations/debug-1.md).
+
+## Specs
+
+- S1 Goal: "A developer needs to diagnose why their MicroEngine game misbehaves without reverse-engineering the engine.
+  Current counters/profiling exist but may not provide actionable cross-system insight."
+- S2 Inspection scope: "In-development inspection of entities/world transforms, active scenes, cameras, physics
+  collision shapes/contacts, device input and consumed actions."
+- S3 Measurement scope: "Per-system CPU/frame timing, GPU draw calls and render state, managed allocations/GC,
+  texture/asset lifetimes and scopes, audio voices."
+- S4 Tooling: "Useful error messages, logging, diagnostics capture and a possible debug overlay or inspector;
+  prioritize reusable infrastructure over prebuilt game UI."
+- S5 Reuse: "Determine what the SDK already exposes and how to integrate existing .NET tooling and diagnostics rather
+  than recreate a profiler."
+- S6 Done when: "A gap assessment and a small, usable developer-side diagnostic workflow are demonstrated; implement
+  only justified primitives, keeping diagnostics optional and cheap/disabled in production."
+- S7 Judge by an external developer (owner's rule): could someone outside the repository diagnose a misbehaving game
+  with the published SDK; research ends in implementation of the primitives that fail that check.
+
+## Tasks
+
+| Task | Specs | Route | Status | Commit / evidence |
+| --- | --- | --- | --- | --- |
+| T1 Map the existing diagnostics surface per area | S1–S5 | delegated (mapping trigger: every subsystem, >5 lookups) | done | evaluation §1, spot check of `GraphicsDeviceBase.Counters` and `FrameSchedule` |
+| T2 Evaluation `docs/evaluations/debug-1.md` with the gap list and plan | S1–S7 | inline | done | 9 scenarios, 9 primitives |
+| T3 Owner approval of the primitives (public contract additions) | S6 | owner | pending | |
+| T4a `Game.Diagnostics`, per-system timing, engine meter, counters without casts | S3 S5 | inline | pending | |
+| T4b `DebugDraw` and physics shape inspection | S2 | inline | pending | |
+| T4c Input trace, engine messages through `ILog`, crash report | S2 S4 | inline | pending | |
+| T4d Example, guide page, release notes | S6 | inline | pending | |
+
+## Log
+
+- L1 (2026-11-12) Owner: "Sigue trabajando en el siguiente issue segun la prioridad". Top open board item after
+  PHYS-1 (#149 merged): DEBUG-1 #119 (P0, M).
+- L2 (2026-11-12) Map done. Answered today: assets, platform facts, coarse `--profile`. Failing: physics shapes and
+  contacts cannot be read back or drawn, input consumption is not recorded, crashes print only the message, engine
+  messages bypass `ILog`, no live numbers or .NET metrics, counters hidden behind casts. Proposal: 9 primitives in
+  four units (evaluation §4). Next: owner approval (T3).

From 03f4100d4257b123ea8ca01cd6e8951384fb5f8f Mon Sep 17 00:00:00 2001
From: Kevin Martinez <ksmartinez23@outlook.com>
Date: Thu, 12 Nov 2026 12:08:13 -0500
Subject: [PATCH 2/5] feat(diagnostics): live frame statistics, per-system
 times and the engine meter (DEBUG-1)

---
 docs/guide/release-notes.md                   |   9 +
 odd/tasks/debug-1.md                          |   1 +
 src/MicroEngine.Audio/Audio.cs                |  13 ++
 src/MicroEngine.Graphics/Devices/Device.cs    |   6 +
 .../Frames/FrameSchedule.cs                   |  53 +++++-
 src/MicroEngine/Core/Game.cs                  |   6 +
 src/MicroEngine/Core/GameDiagnostics.cs       | 174 ++++++++++++++++++
 src/MicroEngine/Core/GameRunner.cs            |  15 +-
 tests/MicroEngine.Tests/DiagnosticsTests.cs   | 122 ++++++++++++
 .../Kernel/FrameScheduleTests.cs              |  37 ++++
 10 files changed, 431 insertions(+), 5 deletions(-)
 create mode 100644 src/MicroEngine/Core/GameDiagnostics.cs
 create mode 100644 tests/MicroEngine.Tests/DiagnosticsTests.cs

diff --git a/docs/guide/release-notes.md b/docs/guide/release-notes.md
index 387b55e2..17095784 100644
--- a/docs/guide/release-notes.md
+++ b/docs/guide/release-notes.md
@@ -14,6 +14,15 @@ An eighth package: `MicroEngine.Physics.Box2D`, optional, for dynamic bodies.
   behind `IPhysicsWorld2D` (dynamic bodies, rotation, circles, capsules, polygons, continuous collision, friction and
   mass) and carries Box2D's native library for Windows, Linux, macOS, Android, iOS and browsers. The tile backend
   stays in `MicroEngine` and needs no extra package.
+- `Game.Diagnostics` measures a running game when you ask it to: the last frame's events, update, render and present
+  times, fixed steps, allocated bytes, collections per generation, the graphics work it submitted and the audio voices
+  (`LastFrame`), and the time of every frame system (`Systems`). `FrameSchedule.MeasureTime` and `Times(phase)` give
+  the per-system times to code that drives the schedule itself. Off by default, and free while off.
+- The engine publishes its frame time, phase times, allocations, draw calls and voices on the
+  `System.Diagnostics.Metrics` meter `"MicroEngine"`: `dotnet-counters monitor --counters MicroEngine` shows them
+  live, and attaching a listener turns the measurements on.
+- `IGraphicsDevice.Counters` (in `MicroEngine.Graphics.Devices`) and `AudioMixer.Statistics` read draw calls and voices
+  without casting to the backend's class.
 
 **Removed**
 
diff --git a/odd/tasks/debug-1.md b/odd/tasks/debug-1.md
index ebbd6606..147ec025 100644
--- a/odd/tasks/debug-1.md
+++ b/odd/tasks/debug-1.md
@@ -42,3 +42,4 @@ primitives, optional and cheap when disabled. Issue NastMz/MicroEngine#119. Bran
   contacts cannot be read back or drawn, input consumption is not recorded, crashes print only the message, engine
   messages bypass `ILog`, no live numbers or .NET metrics, counters hidden behind casts. Proposal: 9 primitives in
   four units (evaluation §4). Next: owner approval (T3).
+- L3 (2026-11-12) Owner: "Approve all nine". T4a starts.
diff --git a/src/MicroEngine.Audio/Audio.cs b/src/MicroEngine.Audio/Audio.cs
index c9f5d05d..7769f5f5 100644
--- a/src/MicroEngine.Audio/Audio.cs
+++ b/src/MicroEngine.Audio/Audio.cs
@@ -238,6 +238,13 @@ public sealed class AudioMixer
     /// <summary>Name of the music playing (also while it fades out, and while a song asked for still renders in slices), or null. It follows the game's requests and the music's end on the simulation's timeline, never rendering speed.</summary>
     public string? CurrentMusic => _waiting?.Name ?? _device.CurrentMusic?.Name;
 
+    /// <summary>
+    /// The voices of the device's mixer: how many sounds play now, how many can play at once and how many the voice
+    /// policy refused so far. Zeros for a device without the engine's mixer (<see cref="SilentAudioDevice"/>).
+    /// </summary>
+    public AudioStatistics Statistics => _device is MixerAudioDevice { Engine: var engine }
+        ? new AudioStatistics(engine.ActiveVoices, engine.MaxVoices, engine.RefusedSounds)
+        : default;
     /// <summary>Registers <paramref name="clip"/> as the sound effect <paramref name="name"/>, replacing any sound with that name.</summary>
     public void AddSound(string name, AudioClip clip) => _sounds[name] = _device.LoadSound(name, clip);
     /// <summary>Registers decoded music, such as a rendered <see cref="Song"/>, under <paramref name="name"/>.</summary>
@@ -491,3 +498,9 @@ public void Update(float dt)
         _device.Update();
     }
 }
+
+/// <summary>What <see cref="AudioMixer.Statistics"/> reports about the mixer's voices.</summary>
+/// <param name="ActiveVoices">Sounds playing now, music included.</param>
+/// <param name="MaxVoices">Sounds that can play at once.</param>
+/// <param name="RefusedSounds">Sounds the voice policy refused since the start because every voice played something of higher priority.</param>
+public readonly record struct AudioStatistics(int ActiveVoices, int MaxVoices, int RefusedSounds);
diff --git a/src/MicroEngine.Graphics/Devices/Device.cs b/src/MicroEngine.Graphics/Devices/Device.cs
index 55bd6136..fa6c44d8 100644
--- a/src/MicroEngine.Graphics/Devices/Device.cs
+++ b/src/MicroEngine.Graphics/Devices/Device.cs
@@ -44,6 +44,12 @@ public interface IGraphicsDevice : IDisposable
     /// <summary>Declared capabilities.</summary>
     GraphicsCapabilities Capabilities { get; }
 
+    /// <summary>
+    /// Deterministic counts of the work submitted to this device since it was created (draw calls, passes, uploads, live
+    /// resources). Every device built on <see cref="GraphicsDeviceBase"/> counts; a device that does not reports zeros.
+    /// </summary>
+    GraphicsCounters Counters => default;
+
     /// <summary>Optional: raised only by backends that can detect loss (SDL_GPU never raises it); resources are marked <see cref="GraphicsResource.IsLost"/>.</summary>
     event Action<DeviceLostReason>? DeviceLost;
 
diff --git a/src/MicroEngine.Kernel/Frames/FrameSchedule.cs b/src/MicroEngine.Kernel/Frames/FrameSchedule.cs
index f166a19d..be861d5c 100644
--- a/src/MicroEngine.Kernel/Frames/FrameSchedule.cs
+++ b/src/MicroEngine.Kernel/Frames/FrameSchedule.cs
@@ -26,6 +26,8 @@ private sealed class Entry(FramePhase phase, string name, Action<FrameContext> r
     private readonly Dictionary<string, Entry> _entries = new(StringComparer.Ordinal);
     private Action<FrameContext>[][]? _compiled;
     private string[][]? _names;
+    private double[][]? _times;
+    private bool _measure;
     private int _added;
 
     /// <summary>Whether the schedule is fixed (the engine was built): it can run but no longer change.</summary>
@@ -105,7 +107,52 @@ public IReadOnlyList<string> Order(FramePhase phase)
     public void Run(FramePhase phase, in FrameContext context)
     {
         if (_compiled is null) Compile();
-        foreach (var system in _compiled![(int)phase]) system(context);
+        var systems = _compiled![(int)phase];
+        if (!MeasureTime)
+        {
+            foreach (var system in systems) system(context);
+            return;
+        }
+        var times = _times![(int)phase];
+        for (int i = 0; i < systems.Length; i++)
+        {
+            long start = System.Diagnostics.Stopwatch.GetTimestamp();
+            systems[i](context);
+            times[i] += System.Diagnostics.Stopwatch.GetElapsedTime(start).TotalMilliseconds;
+        }
+    }
+
+    /// <summary>
+    /// Whether <see cref="Run"/> measures how long each system takes (<see cref="Times"/>). Off by default: a schedule
+    /// that does not measure takes no timestamps. It may change once the schedule is frozen, since it changes no system.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Turning it on when the order cannot be resolved (see <see cref="Order"/>).</exception>
+    public bool MeasureTime
+    {
+        get => _measure;
+        set
+        {
+            if (value) Compile();
+            _measure = value;
+        }
+    }
+
+    /// <summary>
+    /// The milliseconds each system of <paramref name="phase"/> took since the last <see cref="ResetTimes"/>, aligned with
+    /// <see cref="Order"/>: a fixed phase adds up every step it ran. All zero while <see cref="MeasureTime"/> was off.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">The order cannot be resolved (see <see cref="Order"/>).</exception>
+    public ReadOnlySpan<double> Times(FramePhase phase)
+    {
+        Compile();
+        return _times![(int)phase];
+    }
+
+    /// <summary>Sets every measured time (<see cref="Times"/>) back to zero; the loop does it at the start of each frame.</summary>
+    public void ResetTimes()
+    {
+        if (_times is null) return;
+        foreach (var phase in _times) Array.Clear(phase);
     }
 
     /// <summary>Resolves the order and fixes the schedule; the engine does this when it is built.</summary>
@@ -128,13 +175,15 @@ private void Compile()
         if (_compiled is not null) return;
         var compiled = new Action<FrameContext>[PhaseCount][];
         var names = new string[PhaseCount][];
+        var times = new double[PhaseCount][];
         for (int p = 0; p < PhaseCount; p++)
         {
             var ordered = Resolve((FramePhase)p);
             compiled[p] = ordered.Select(e => e.Run).ToArray();
             names[p] = ordered.Select(e => e.Name).ToArray();
+            times[p] = new double[ordered.Count];
         }
-        (_compiled, _names) = (compiled, names);
+        (_compiled, _names, _times) = (compiled, names, times);
     }
 
     /// <summary>
diff --git a/src/MicroEngine/Core/Game.cs b/src/MicroEngine/Core/Game.cs
index d6204f45..09ad1a1e 100644
--- a/src/MicroEngine/Core/Game.cs
+++ b/src/MicroEngine/Core/Game.cs
@@ -187,6 +187,12 @@ private sealed class SceneUiLayer(Game game) : IInputLayer
     public TimeSettings TimeSettings => Engine.Time;
     /// <summary>The time of the frame being run (<see cref="FrameContext"/>): its delta, the fixed step, the blend and the frame number.</summary>
     public FrameContext Frame => Engine.Clock.Context;
+    private GameDiagnostics? _diagnostics;
+    /// <summary>
+    /// The live measurements of the run: the last frame's times, allocations, graphics work and audio voices, and the time
+    /// of each frame system. Off until <see cref="GameDiagnostics.Enabled"/> is set or a tool listens to the engine's meter.
+    /// </summary>
+    public GameDiagnostics Diagnostics => _diagnostics ??= new GameDiagnostics(this);
 
     /// <summary>
     /// An optional feature, if there is one: one the engine declared (<see cref="EngineBuilder.Capabilities"/>), else one
diff --git a/src/MicroEngine/Core/GameDiagnostics.cs b/src/MicroEngine/Core/GameDiagnostics.cs
new file mode 100644
index 00000000..af0d97f7
--- /dev/null
+++ b/src/MicroEngine/Core/GameDiagnostics.cs
@@ -0,0 +1,174 @@
+using System.Diagnostics;
+using System.Diagnostics.Metrics;
+using MicroEngine.Audio;
+using MicroEngine.Graphics;
+using GraphicsCounters = MicroEngine.Graphics.Devices.GraphicsCounters;
+using DeviceContract = MicroEngine.Graphics.Devices.IGraphicsDevice;
+using MicroEngine.Kernel;
+
+namespace MicroEngine.Core;
+
+/// <summary>
+/// What a frame cost, as <see cref="GameDiagnostics.LastFrame"/> reports it. Times are in milliseconds of real time.
+/// </summary>
+/// <param name="Frame">The number of the frame, from 1; 0 when nothing was measured.</param>
+/// <param name="Interval">Time since the previous measured frame started (0 for the first one).</param>
+/// <param name="Events">The platform's event pump.</param>
+/// <param name="Update">The fixed steps and the per-frame updates (<see cref="FramePhase.BeginFrame"/> to <see cref="FramePhase.LateUpdate"/>).</param>
+/// <param name="Render">Extracting and drawing (<see cref="FramePhase.Extract"/> and <see cref="FramePhase.Render"/>).</param>
+/// <param name="Present">Presenting (<see cref="FramePhase.Present"/> and <see cref="FramePhase.EndFrame"/>), which includes waiting for the display.</param>
+/// <param name="Steps">Fixed steps the frame ran.</param>
+/// <param name="Allocated">Bytes the game's thread allocated during the frame.</param>
+/// <param name="Gen0Collections">Garbage collections of generation 0 during the frame.</param>
+/// <param name="Gen1Collections">Garbage collections of generation 1 during the frame.</param>
+/// <param name="Gen2Collections">Full garbage collections during the frame.</param>
+/// <param name="Graphics">The work the frame submitted to the graphics device (draw calls, passes, uploads; <see cref="GraphicsCounters.LiveResources"/> is the count at its end). Zeros on a platform whose device does not count.</param>
+/// <param name="Audio">The mixer's voices at the end of the frame.</param>
+public readonly record struct FrameStatistics(long Frame, double Interval, double Events, double Update, double Render, double Present,
+    int Steps, long Allocated, int Gen0Collections, int Gen1Collections, int Gen2Collections, GraphicsCounters Graphics, AudioStatistics Audio)
+{
+    /// <summary>The frame's work: events, update, render and present.</summary>
+    public double Total => Events + Update + Render + Present;
+    /// <summary>Garbage collections of any generation during the frame.</summary>
+    public int Collections => Gen0Collections + Gen1Collections + Gen2Collections;
+}
+
+/// <summary>How long one system of the frame schedule took during the last frame (<see cref="GameDiagnostics.Systems"/>).</summary>
+/// <param name="Name">The system's name in <see cref="FrameSchedule"/>.</param>
+/// <param name="Phase">Its phase.</param>
+/// <param name="Milliseconds">Its time during the frame; a fixed phase adds up every step of the frame.</param>
+public readonly record struct SystemTiming(string Name, FramePhase Phase, double Milliseconds);
+
+/// <summary>
+/// The game's live measurements (<see cref="Game.Diagnostics"/>): the last frame's times, allocations, collections,
+/// graphics work and audio voices, and the time of every system of the frame schedule. Off by default; a run measures
+/// while <see cref="Enabled"/> is set or while a tool listens to the engine's meter (<see cref="MeterName"/>), and costs
+/// nothing measurable otherwise.
+/// </summary>
+/// <remarks>
+/// The same numbers are published as <see cref="System.Diagnostics.Metrics"/> instruments of the meter
+/// <c>"MicroEngine"</c>, so <c>dotnet-counters monitor --counters MicroEngine</c>, <c>dotnet-monitor</c> or an
+/// OpenTelemetry exporter read them without code in the game. The runtime's own meter (<c>System.Runtime</c>) adds the
+/// heap size, GC pauses and thread-pool figures.
+/// </remarks>
+/// <example>
+/// <code>
+/// // In Load: measure, and show the numbers when F3 is held.
+/// Diagnostics.Enabled = true;
+/// // In DrawAboveScenes:
+/// var frame = Diagnostics.LastFrame;
+/// Font.Draw(renderer, $"{frame.Total:0.0} ms  {frame.Graphics.DrawCalls} draws  {frame.Allocated} B", new Vector2(4, 4), Color.White);
+/// </code>
+/// </example>
+public sealed class GameDiagnostics
+{
+    /// <summary>The name of the engine's meter (<see cref="Meter"/>): <c>"MicroEngine"</c>.</summary>
+    public const string MeterName = "MicroEngine";
+
+    private static readonly Meter EngineMeter = new(MeterName);
+    private static GameDiagnostics? s_current;
+    private static readonly Instrument[] Instruments =
+    [
+        EngineMeter.CreateObservableGauge("microengine.frame.time", () => s_current?.LastFrame.Interval ?? 0, "ms", "Time between the starts of the last two frames."),
+        EngineMeter.CreateObservableGauge("microengine.frame.update", () => s_current?.LastFrame.Update ?? 0, "ms", "The last frame's fixed steps and updates."),
+        EngineMeter.CreateObservableGauge("microengine.frame.render", () => s_current?.LastFrame.Render ?? 0, "ms", "The last frame's drawing."),
+        EngineMeter.CreateObservableGauge("microengine.frame.present", () => s_current?.LastFrame.Present ?? 0, "ms", "The last frame's presentation, display wait included."),
+        EngineMeter.CreateObservableGauge("microengine.frame.allocated", () => s_current?.LastFrame.Allocated ?? 0, "By", "Bytes the game's thread allocated during the last frame."),
+        EngineMeter.CreateObservableGauge("microengine.graphics.draw_calls", () => (long)(s_current?.LastFrame.Graphics.DrawCalls ?? 0), "{draw}", "Draw calls of the last frame."),
+        EngineMeter.CreateObservableGauge("microengine.audio.voices", () => s_current?.LastFrame.Audio.ActiveVoices ?? 0, "{voice}", "Sounds playing at the end of the last frame."),
+    ];
+
+    private readonly Game _game;
+    private SystemTiming[] _systems = [];
+    private DeviceContract? _device;
+    private bool _deviceResolved;
+    private long _frameStart;
+    private bool _wasActive;
+
+    internal GameDiagnostics(Game game) => _game = game;
+
+    /// <summary>Whether the game measures every frame. Off by default; a tool listening to the engine's meter measures too (<see cref="Active"/>).</summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>Whether frames are measured now: <see cref="Enabled"/>, or a listener of the engine's meter is attached.</summary>
+    public bool Active
+    {
+        get
+        {
+            if (Enabled) return true;
+            foreach (var instrument in Instruments) if (instrument.Enabled) return true;
+            return false;
+        }
+    }
+
+    /// <summary>The last measured frame; <c>default</c> (frame 0) until a frame is measured. During an update it is the previous frame.</summary>
+    public FrameStatistics LastFrame { get; private set; }
+
+    /// <summary>
+    /// Every system of the frame schedule with its time during the last measured frame, in the order phases run and, within
+    /// a phase, in the order its systems run. Empty until a frame is measured.
+    /// </summary>
+    public IReadOnlyList<SystemTiming> Systems => _systems;
+
+    /// <summary>Starts a frame: true when it is measured. Turns the schedule's timing on or off to follow <see cref="Active"/>.</summary>
+    internal bool BeginFrame(FrameSchedule schedule)
+    {
+        bool active = Active;
+        if (active != _wasActive)
+        {
+            schedule.MeasureTime = active;
+            _wasActive = active;
+            if (!active) _frameStart = 0;
+        }
+        if (!active) return false;
+        s_current = this;
+        schedule.ResetTimes();
+        return true;
+    }
+
+    /// <summary>A measured frame's starting point.</summary>
+    internal Mark Start()
+    {
+        if (!_deviceResolved)
+        {
+            _device = _game.Graphics is DeviceGraphics graphics ? graphics.Device : null;
+            _deviceResolved = true;
+        }
+        long now = Stopwatch.GetTimestamp();
+        double interval = _frameStart == 0 ? 0 : Stopwatch.GetElapsedTime(_frameStart, now).TotalMilliseconds;
+        _frameStart = now;
+        return new Mark(interval, GC.GetAllocatedBytesForCurrentThread(), GC.CollectionCount(0), GC.CollectionCount(1), GC.CollectionCount(2),
+            _device?.Counters ?? default);
+    }
+
+    /// <summary>Records a measured frame that started at <paramref name="start"/>.</summary>
+    internal void End(in Mark start, long frame, double events, double update, double render, double present, int steps, FrameSchedule schedule)
+    {
+        var counters = _device?.Counters ?? default;
+        var graphics = (counters - start.Graphics) with { LiveResources = counters.LiveResources };
+        LastFrame = new FrameStatistics(frame, start.Interval, events, update, render, present, steps,
+            GC.GetAllocatedBytesForCurrentThread() - start.Allocated,
+            GC.CollectionCount(0) - start.Gen0, GC.CollectionCount(1) - start.Gen1, GC.CollectionCount(2) - start.Gen2,
+            graphics, _game.Audio?.Statistics ?? default);
+        if (_systems.Length != schedule.Count) _systems = Describe(schedule);
+        int i = 0;
+        foreach (var phase in Phases)
+            foreach (double time in schedule.Times(phase))
+            {
+                _systems[i] = _systems[i] with { Milliseconds = time };
+                i++;
+            }
+    }
+
+    private static readonly FramePhase[] Phases = Enum.GetValues<FramePhase>();
+
+    private static SystemTiming[] Describe(FrameSchedule schedule)
+    {
+        var systems = new List<SystemTiming>(schedule.Count);
+        foreach (var phase in Phases)
+            foreach (var name in schedule.Order(phase)) systems.Add(new SystemTiming(name, phase, 0));
+        return [.. systems];
+    }
+
+    internal readonly record struct Mark(double Interval, long Allocated, int Gen0, int Gen1, int Gen2, GraphicsCounters Graphics);
+}
diff --git a/src/MicroEngine/Core/GameRunner.cs b/src/MicroEngine/Core/GameRunner.cs
index de66be4d..b26b3013 100644
--- a/src/MicroEngine/Core/GameRunner.cs
+++ b/src/MicroEngine/Core/GameRunner.cs
@@ -273,7 +273,8 @@ public bool Tick()
     private bool Frame()
     {
         if (!Limit()) return false;
-        if (_options.Profiler is { } profiler) return ProfiledFrame(profiler);
+        bool diagnose = _game.Diagnostics.BeginFrame(_engine!.Schedule);
+        if (_options.Profiler is not null || diagnose) return MeasuredFrame(_options.Profiler, diagnose ? _game.Diagnostics : null);
         if (!Pump()) return _closeAccepted || _game.QuitRequested;
         var (stop, capture) = Update();
         Render();
@@ -282,9 +283,10 @@ private bool Frame()
 
     private long _frameStart;
 
-    /// <summary><see cref="Frame"/> with each phase timed into <paramref name="profiler"/>.</summary>
-    private bool ProfiledFrame(FrameProfiler profiler)
+    /// <summary><see cref="Frame"/> with each phase timed into <paramref name="profiler"/> and <paramref name="diagnostics"/>, either of which may be null.</summary>
+    private bool MeasuredFrame(FrameProfiler? profiler, GameDiagnostics? diagnostics)
     {
+        var mark = diagnostics?.Start() ?? default;
         long start = Stopwatch.GetTimestamp();
         long allocated = GC.GetAllocatedBytesForCurrentThread();
         int collections = GC.CollectionCount(0) + GC.CollectionCount(1) + GC.CollectionCount(2);
@@ -306,6 +308,13 @@ private bool ProfiledFrame(FrameProfiler profiler)
         engine.Run(Kernel.FramePhase.Present, frame);
         engine.Run(Kernel.FramePhase.EndFrame, frame);
         long presented = Stopwatch.GetTimestamp();
+        diagnostics?.End(mark, _frames + 1,
+            Stopwatch.GetElapsedTime(start, polled).TotalMilliseconds,
+            Stopwatch.GetElapsedTime(polled, updated).TotalMilliseconds,
+            Stopwatch.GetElapsedTime(updated, rendered).TotalMilliseconds,
+            Stopwatch.GetElapsedTime(rendered, presented).TotalMilliseconds,
+            (int)(_game.UpdateCount - updates), engine.Schedule);
+        if (profiler is null) return EndOfFrame(stop, capture);
         profiler.Add(new FrameSample(interval,
             Stopwatch.GetElapsedTime(start, polled).TotalMilliseconds,
             Stopwatch.GetElapsedTime(polled, updated).TotalMilliseconds,
diff --git a/tests/MicroEngine.Tests/DiagnosticsTests.cs b/tests/MicroEngine.Tests/DiagnosticsTests.cs
new file mode 100644
index 00000000..3eb1b9cc
--- /dev/null
+++ b/tests/MicroEngine.Tests/DiagnosticsTests.cs
@@ -0,0 +1,122 @@
+using System.Diagnostics.Metrics;
+using MicroEngine.Audio;
+using MicroEngine.Core;
+using MicroEngine.Kernel;
+using MicroEngine.Scenes;
+using Dev = MicroEngine.Graphics.Devices;
+
+namespace MicroEngine.Tests;
+
+/// <summary>DEBUG-1: the game's live diagnostics, per-system times, the engine meter and counters without casts.</summary>
+[TestClass]
+[DoNotParallelize] // the engine meter is process-wide
+public sealed class DiagnosticsTests
+{
+    private sealed class SlowGame(bool enabled) : Game
+    {
+        public override GameSettings Settings { get; } = new("diagnostics") { UpdateRate = 60 };
+        public FrameStatistics SeenInUpdate { get; private set; }
+
+        public override void Configure(EngineBuilder builder) =>
+            builder.Schedule.Add(FramePhase.Update, "test.slow", _ => Thread.Sleep(3));
+
+        protected override void Load()
+        {
+            Diagnostics.Enabled = enabled;
+            Scenes.Push(new Probe(this));
+        }
+
+        private sealed class Probe(SlowGame game) : Scene
+        {
+            public override void Update(float dt) => game.SeenInUpdate = game.Diagnostics.LastFrame;
+            public override void Draw(MicroEngine.Graphics.IRenderer r) { }
+        }
+    }
+
+    [TestMethod]
+    public void Disabled_diagnostics_measure_nothing()
+    {
+        var game = new SlowGame(enabled: false);
+        GameRunner.Run(game, new HeadlessPlatform(), new RunOptions { MaxUpdates = 10 });
+        Assert.IsFalse(game.Diagnostics.Enabled);
+        Assert.AreEqual(default, game.Diagnostics.LastFrame);
+        Assert.AreEqual(0, game.Diagnostics.Systems.Count);
+    }
+
+    [TestMethod]
+    public void Enabled_diagnostics_report_the_last_frame_and_each_system()
+    {
+        var game = new SlowGame(enabled: true);
+        var result = GameRunner.Run(game, new HeadlessPlatform(), new RunOptions { MaxUpdates = 10 });
+        var last = game.Diagnostics.LastFrame;
+        Assert.AreEqual(result.Frames, last.Frame, "the last frame run is the one reported");
+        Assert.IsTrue(last.Update >= 2.5, $"the update phase holds the 3 ms system: {last.Update} ms");
+        Assert.IsTrue(last.Steps >= 1);
+        Assert.IsTrue(last.Total >= last.Update);
+        Assert.IsTrue(game.SeenInUpdate.Frame >= 1, "a game reads the previous frame while it updates");
+
+        var slow = game.Diagnostics.Systems.Single(s => s.Name == "test.slow");
+        Assert.AreEqual(FramePhase.Update, slow.Phase);
+        Assert.IsTrue(slow.Milliseconds >= 2.5, $"{slow.Milliseconds} ms");
+        var scenes = game.Diagnostics.Systems.Single(s => s.Name == "engine.scenes");
+        Assert.AreEqual(FramePhase.FixedUpdate, scenes.Phase);
+        var phases = game.Diagnostics.Systems.Select(s => (int)s.Phase).ToArray();
+        CollectionAssert.AreEqual(phases.Order().ToArray(), phases, "systems are listed in the order phases run");
+    }
+
+    [TestMethod]
+    public void A_profiled_run_with_diagnostics_matches_one_without()
+    {
+        var plain = new SlowGame(enabled: false);
+        var measured = new SlowGame(enabled: true);
+        var a = GameRunner.Run(plain, new HeadlessPlatform(), new RunOptions { MaxUpdates = 12 });
+        var b = GameRunner.Run(measured, new HeadlessPlatform(), new RunOptions { MaxUpdates = 12, Profiler = new FrameProfiler() });
+        Assert.AreEqual((a.Updates, a.Frames), (b.Updates, b.Frames));
+        Assert.AreEqual(b.Frames, measured.Diagnostics.LastFrame.Frame, "the profiler and the diagnostics measure the same frames");
+    }
+
+    [TestMethod]
+    public void A_meter_listener_turns_measuring_on_and_reads_the_engine_instruments()
+    {
+        var values = new Dictionary<string, double>();
+        using var listener = new MeterListener();
+        listener.InstrumentPublished = (instrument, l) => { if (instrument.Meter.Name == GameDiagnostics.MeterName) l.EnableMeasurementEvents(instrument); };
+        listener.SetMeasurementEventCallback<double>((i, v, _, _) => values[i.Name] = v);
+        listener.SetMeasurementEventCallback<long>((i, v, _, _) => values[i.Name] = v);
+        listener.SetMeasurementEventCallback<int>((i, v, _, _) => values[i.Name] = v);
+        listener.Start();
+
+        var game = new SlowGame(enabled: false);
+        GameRunner.Run(game, new HeadlessPlatform(), new RunOptions { MaxUpdates = 10 });
+        Assert.IsTrue(game.Diagnostics.Active, "a listener makes the diagnostics measure without Enabled");
+        listener.RecordObservableInstruments();
+        CollectionAssert.IsSubsetOf(
+            new[] { "microengine.frame.time", "microengine.frame.update", "microengine.frame.render", "microengine.frame.present",
+                    "microengine.frame.allocated", "microengine.graphics.draw_calls", "microengine.audio.voices" },
+            values.Keys.ToArray());
+        Assert.IsTrue(values["microengine.frame.update"] >= 2.5, $"{values["microengine.frame.update"]} ms");
+    }
+
+    [TestMethod]
+    public void Graphics_counters_are_read_through_the_device_interface()
+    {
+        using var device = new Dev.ReferenceGraphicsDevice();
+        Dev.IGraphicsDevice contract = device;
+        using var target = device.CreateRenderTarget(new Dev.RenderTargetDescription(4, 4));
+        Assert.AreEqual(device.Counters, contract.Counters);
+        Assert.IsTrue(contract.Counters.LiveResources > 0);
+    }
+
+    [TestMethod]
+    public void Audio_statistics_come_from_the_mixer_without_casts()
+    {
+        var device = new CaptureAudioDevice();
+        var mixer = new AudioMixer(device);
+        mixer.AddSound("beep", new AudioClip(Enumerable.Repeat(0.5f, 4800).ToArray(), 48000));
+        Assert.AreEqual(new AudioStatistics(0, device.Engine.MaxVoices, 0), mixer.Statistics);
+        mixer.Play("beep");
+        device.Update();
+        Assert.AreEqual(1, mixer.Statistics.ActiveVoices);
+        Assert.AreEqual(default, new AudioMixer(new SilentAudioDevice()).Statistics, "a device without a mixer reports nothing");
+    }
+}
diff --git a/tests/MicroEngine.Tests/Kernel/FrameScheduleTests.cs b/tests/MicroEngine.Tests/Kernel/FrameScheduleTests.cs
index 84154838..da4ad363 100644
--- a/tests/MicroEngine.Tests/Kernel/FrameScheduleTests.cs
+++ b/tests/MicroEngine.Tests/Kernel/FrameScheduleTests.cs
@@ -129,4 +129,41 @@ public void Running_a_phase_allocates_nothing()
         AllocationAssert.None(() => schedule.Run(FramePhase.Update, Context), warmup: 1, calls: 100, rounds: 5);
         Assert.AreEqual(8 * (1 + 100 * 5), count, "every run runs every system");
     }
+
+    [TestMethod]
+    public void Measured_systems_report_their_time_in_order_and_accumulate_until_reset()
+    {
+        var schedule = new FrameSchedule();
+        schedule.Add(FramePhase.Update, "slow", _ => Thread.Sleep(5));
+        schedule.Add(FramePhase.Update, "fast", _ => { });
+        schedule.Add(FramePhase.FixedUpdate, "step", _ => Thread.Sleep(2));
+        schedule.Freeze();
+        Assert.IsTrue(schedule.Times(FramePhase.Update).ToArray().All(t => t == 0), "nothing measured while MeasureTime is off");
+        schedule.Run(FramePhase.Update, Context);
+        Assert.IsTrue(schedule.Times(FramePhase.Update).ToArray().All(t => t == 0), "a run while off measures nothing");
+
+        schedule.MeasureTime = true; // allowed once frozen: it changes no system
+        schedule.Run(FramePhase.Update, Context);
+        schedule.Run(FramePhase.FixedUpdate, Context);
+        schedule.Run(FramePhase.FixedUpdate, Context);
+        var update = schedule.Times(FramePhase.Update);
+        Assert.AreEqual(2, update.Length, "one time per system, aligned with Order");
+        Assert.IsTrue(update[0] >= 4, $"slow took {update[0]} ms");
+        Assert.IsTrue(update[1] < update[0]);
+        Assert.IsTrue(schedule.Times(FramePhase.FixedUpdate)[0] >= 3.5, "a fixed system adds up over the frame's steps");
+
+        schedule.ResetTimes();
+        Assert.IsTrue(schedule.Times(FramePhase.Update).ToArray().All(t => t == 0));
+        Assert.IsTrue(schedule.Times(FramePhase.FixedUpdate).ToArray().All(t => t == 0));
+    }
+
+    [TestMethod]
+    public void Running_a_measured_phase_allocates_nothing()
+    {
+        var schedule = new FrameSchedule();
+        for (int i = 0; i < 8; i++) schedule.Add(FramePhase.Update, $"s{i}", _ => { });
+        schedule.Freeze();
+        schedule.MeasureTime = true;
+        AllocationAssert.None(() => { schedule.ResetTimes(); schedule.Run(FramePhase.Update, Context); }, warmup: 1, calls: 100, rounds: 5);
+    }
 }

From 49080c471bd6d3c1410760f02996a46284490892 Mon Sep 17 00:00:00 2001
From: Kevin Martinez <ksmartinez23@outlook.com>
Date: Thu, 12 Nov 2026 12:13:05 -0500
Subject: [PATCH 3/5] feat(diagnostics): debug drawing and the physics debug
 view (DEBUG-1)

---
 docs/guide/release-notes.md                   |   8 +
 .../Box2DPhysicsWorld2D.cs                    |  18 +-
 .../TilePhysicsWorld2D.cs                     |  27 +-
 src/MicroEngine.Physics/Capabilities.cs       |   5 +
 src/MicroEngine.Physics/IPhysicsWorld2D.cs    |  13 +
 src/MicroEngine/Core/DebugDraw.cs             | 261 ++++++++++++++++++
 src/MicroEngine/Core/Game.cs                  |   7 +
 .../Box2DTests.cs                             |   2 +-
 tests/MicroEngine.Tests/DebugDrawTests.cs     | 118 ++++++++
 .../Physics/TilePhysicsTests.cs               |   2 +-
 tests/Shared/Physics/PhysicsConformance.cs    |  31 +++
 11 files changed, 488 insertions(+), 4 deletions(-)
 create mode 100644 src/MicroEngine/Core/DebugDraw.cs
 create mode 100644 tests/MicroEngine.Tests/DebugDrawTests.cs

diff --git a/docs/guide/release-notes.md b/docs/guide/release-notes.md
index 17095784..58ddbe19 100644
--- a/docs/guide/release-notes.md
+++ b/docs/guide/release-notes.md
@@ -21,6 +21,14 @@ An eighth package: `MicroEngine.Physics.Box2D`, optional, for dynamic bodies.
 - The engine publishes its frame time, phase times, allocations, draw calls and voices on the
   `System.Diagnostics.Metrics` meter `"MicroEngine"`: `dotnet-counters monitor --counters MicroEngine` shows them
   live, and attaching a listener turns the measurements on.
+- `Game.DebugDraw` draws lines, rectangles, circles, points and text from any code, in world space (under the scene's
+  camera) or screen space, for one frame or a number of seconds; calls do nothing until `DebugDraw.Enabled` is set.
+  `DebugDraw.Physics(world)` draws every shape of a physics world, the tiles in view and the contacts of the latest
+  step.
+- Physics worlds read shapes back: `IPhysicsWorld2D.ShapesOf(body, span)` and `DescriptionOf(shape)`, declared by the
+  new `PhysicsCapabilities.ShapeInspection` (both built-in backends declare it; a backend of your own that does not
+  refuses them with `PhysicsCapabilityException`). `TilePhysicsWorld2D.GridOf(shape)` returns the tiles of a tile
+  shape.
 - `IGraphicsDevice.Counters` (in `MicroEngine.Graphics.Devices`) and `AudioMixer.Statistics` read draw calls and voices
   without casting to the backend's class.
 
diff --git a/src/MicroEngine.Physics.Box2D/Box2DPhysicsWorld2D.cs b/src/MicroEngine.Physics.Box2D/Box2DPhysicsWorld2D.cs
index 0b412734..9144f9b6 100644
--- a/src/MicroEngine.Physics.Box2D/Box2DPhysicsWorld2D.cs
+++ b/src/MicroEngine.Physics.Box2D/Box2DPhysicsWorld2D.cs
@@ -38,7 +38,7 @@ public sealed unsafe class Box2DPhysicsWorld2D : IPhysicsWorld2D, IStateHashed,
     public const PhysicsCapabilities Declared = PhysicsCapabilities.DynamicBodies | PhysicsCapabilities.Rotation
         | PhysicsCapabilities.Circles | PhysicsCapabilities.Capsules | PhysicsCapabilities.Polygons
         | PhysicsCapabilities.ContinuousCollision | PhysicsCapabilities.FrictionRestitution
-        | PhysicsCapabilities.MassProperties | PhysicsCapabilities.OneWayPlatforms;
+        | PhysicsCapabilities.MassProperties | PhysicsCapabilities.OneWayPlatforms | PhysicsCapabilities.ShapeInspection;
 
     /// <summary>The most vertices a polygon may have (Box2D's limit).</summary>
     public const int MaxPolygonVertices = 8;
@@ -406,6 +406,22 @@ private void Forget(int slot)
     public bool IsAlive(ShapeId shape) =>
         shape.Generation != 0 && shape.Index < (uint)_shapeSlots.Count && _shapeSlots[(int)shape.Index] is { Alive: true } s && s.Generation == shape.Generation;
 
+    /// <inheritdoc/>
+    public int ShapesOf(BodyId body, Span<ShapeId> results)
+    {
+        var b = Resolve(body);
+        for (int i = 0; i < b.Shapes.Count && i < results.Length; i++)
+            results[i] = new ShapeId((uint)b.Shapes[i], _shapeSlots[b.Shapes[i]].Generation);
+        return b.Shapes.Count;
+    }
+
+    /// <inheritdoc/>
+    public ShapeDescription DescriptionOf(ShapeId shape)
+    {
+        if (!IsAlive(shape)) throw new InvalidOperationException($"{shape} is not a live shape of this world.");
+        return _shapeSlots[(int)shape.Index].Description;
+    }
+
     /// <inheritdoc/>
     public BodyId BodyOf(ShapeId shape)
     {
diff --git a/src/MicroEngine.Physics.Tiles/TilePhysicsWorld2D.cs b/src/MicroEngine.Physics.Tiles/TilePhysicsWorld2D.cs
index 762b75c2..1eda6a6d 100644
--- a/src/MicroEngine.Physics.Tiles/TilePhysicsWorld2D.cs
+++ b/src/MicroEngine.Physics.Tiles/TilePhysicsWorld2D.cs
@@ -32,7 +32,8 @@ namespace MicroEngine.Physics.Tiles;
 public sealed class TilePhysicsWorld2D : IPhysicsWorld2D, IStateHashed
 {
     /// <summary>The capabilities this backend declares.</summary>
-    public const PhysicsCapabilities Declared = PhysicsCapabilities.TileGeometry | PhysicsCapabilities.OneWayPlatforms | PhysicsCapabilities.MovingSolids;
+    public const PhysicsCapabilities Declared = PhysicsCapabilities.TileGeometry | PhysicsCapabilities.OneWayPlatforms | PhysicsCapabilities.MovingSolids
+        | PhysicsCapabilities.ShapeInspection;
 
     /// <summary>The distance within which a surface counts as touching a box at the end of a move (the ground probe).</summary>
     public const float ContactDistance = 0.01f;
@@ -311,6 +312,30 @@ private List<int> Candidates(in RectF area)
     public bool IsAlive(ShapeId shape) =>
         shape.Generation != 0 && shape.Index < (uint)_shapeSlots.Count && _shapeSlots[(int)shape.Index] is { Alive: true } s && s.Generation == shape.Generation;
 
+    /// <inheritdoc/>
+    public int ShapesOf(BodyId body, Span<ShapeId> results)
+    {
+        var b = Resolve(body);
+        for (int i = 0; i < b.Shapes.Count && i < results.Length; i++)
+            results[i] = new ShapeId((uint)b.Shapes[i], _shapeSlots[b.Shapes[i]].Generation);
+        return b.Shapes.Count;
+    }
+
+    /// <inheritdoc/>
+    public ShapeDescription DescriptionOf(ShapeId shape)
+    {
+        if (!IsAlive(shape)) throw new InvalidOperationException($"{shape} is not a live shape of this world.");
+        return _shapeSlots[(int)shape.Index].Description;
+    }
+
+    /// <summary>The tiles <paramref name="shape"/> stands for when it was added with <see cref="AddTiles"/>; null for any other shape.</summary>
+    /// <exception cref="InvalidOperationException">The id is stale.</exception>
+    public ICollisionGrid? GridOf(ShapeId shape)
+    {
+        if (!IsAlive(shape)) throw new InvalidOperationException($"{shape} is not a live shape of this world.");
+        return _shapeSlots[(int)shape.Index].Grid;
+    }
+
     /// <inheritdoc/>
     public BodyId BodyOf(ShapeId shape)
     {
diff --git a/src/MicroEngine.Physics/Capabilities.cs b/src/MicroEngine.Physics/Capabilities.cs
index 01448270..2b7ffed2 100644
--- a/src/MicroEngine.Physics/Capabilities.cs
+++ b/src/MicroEngine.Physics/Capabilities.cs
@@ -41,6 +41,11 @@ public enum PhysicsCapabilities
     /// kinematic bodies in its way and carries the ones resting on it.
     /// </summary>
     MovingSolids = 1 << 11,
+    /// <summary>
+    /// Reading shapes back (<see cref="IPhysicsWorld2D.ShapesOf"/>, <see cref="IPhysicsWorld2D.DescriptionOf"/>): what a
+    /// debug view needs to draw the world. Both built-in backends declare it.
+    /// </summary>
+    ShapeInspection = 1 << 12,
 }
 
 /// <summary>
diff --git a/src/MicroEngine.Physics/IPhysicsWorld2D.cs b/src/MicroEngine.Physics/IPhysicsWorld2D.cs
index 9bd20c8a..0ae8ef67 100644
--- a/src/MicroEngine.Physics/IPhysicsWorld2D.cs
+++ b/src/MicroEngine.Physics/IPhysicsWorld2D.cs
@@ -113,6 +113,19 @@ public interface IPhysicsWorld2D
     /// <summary>The body <paramref name="shape"/> is attached to.</summary>
     /// <exception cref="InvalidOperationException">The id is stale.</exception>
     BodyId BodyOf(ShapeId shape);
+    /// <summary>
+    /// Writes the live shapes of <paramref name="body"/>, in the order they were added, into <paramref name="results"/>
+    /// and returns how many it has (which may exceed the span's length: only the first ones are written).
+    /// </summary>
+    /// <exception cref="InvalidOperationException">The body is stale.</exception>
+    /// <exception cref="PhysicsCapabilityException">The backend does not declare <see cref="PhysicsCapabilities.ShapeInspection"/>.</exception>
+    int ShapesOf(BodyId body, Span<ShapeId> results) =>
+        throw new PhysicsCapabilityException(nameof(ShapesOf), Backend, PhysicsCapabilities.ShapeInspection);
+    /// <summary>The description <paramref name="shape"/> was added with (its geometry is relative to its body's origin).</summary>
+    /// <exception cref="InvalidOperationException">The id is stale.</exception>
+    /// <exception cref="PhysicsCapabilityException">The backend does not declare <see cref="PhysicsCapabilities.ShapeInspection"/>.</exception>
+    ShapeDescription DescriptionOf(ShapeId shape) =>
+        throw new PhysicsCapabilityException(nameof(DescriptionOf), Backend, PhysicsCapabilities.ShapeInspection);
 
     /// <summary>
     /// Moves a kinematic body by <paramref name="delta"/> with collide-and-slide against the shapes
diff --git a/src/MicroEngine/Core/DebugDraw.cs b/src/MicroEngine/Core/DebugDraw.cs
new file mode 100644
index 00000000..e0b3a5eb
--- /dev/null
+++ b/src/MicroEngine/Core/DebugDraw.cs
@@ -0,0 +1,261 @@
+using System.Numerics;
+using MicroEngine.Graphics;
+using MicroEngine.Physics;
+using MicroEngine.Physics.Tiles;
+using MicroEngine.World;
+
+namespace MicroEngine.Core;
+
+/// <summary>Where a <see cref="DebugDraw"/> item is placed.</summary>
+public enum DebugSpace
+{
+    /// <summary>World coordinates, under the current scene's <see cref="Scenes.Scene.WorldCamera"/> (canvas pixels when it has none).</summary>
+    World,
+    /// <summary>Canvas pixels, above the scenes, whatever the camera.</summary>
+    Screen,
+}
+
+/// <summary>
+/// Shapes and text any code can ask for while the game runs, drawn above the scenes at the end of the frame
+/// (<see cref="Game.DebugDraw"/>): a ray an enemy casts, the box a move swept, a path, a value next to an entity. Calls
+/// do nothing while <see cref="Enabled"/> is off, so they can stay in shipped code.
+/// </summary>
+/// <remarks>
+/// An item drawn with <c>seconds: 0</c> shows for one frame; ask for it every update to keep it. A longer one stays that
+/// many seconds of real time. World items follow the camera of the scene on top (<see cref="Scenes.Scene.WorldCamera"/>);
+/// screen items are in the canvas's pixels. Lines are one world unit (or one canvas pixel) thick.
+/// </remarks>
+/// <example>
+/// <code>
+/// // In Load:
+/// DebugDraw.Enabled = true;
+/// // Anywhere in an update:
+/// game.DebugDraw.Line(enemy.Position, player.Position, Color.Red);
+/// game.DebugDraw.Physics(world);
+/// </code>
+/// </example>
+public sealed class DebugDraw
+{
+    private enum Kind : byte { Line, Rect, Circle, Text }
+
+    private readonly record struct Item(Kind Kind, DebugSpace Space, Vector2 A, Vector2 B, float Radius, Color Color, string? Text, float Remaining);
+
+    /// <summary>The colours <see cref="Physics"/> uses.</summary>
+    public static class PhysicsColors
+    {
+        /// <summary>Shapes of static bodies.</summary>
+        public static readonly Color Static = new(90, 200, 90);
+        /// <summary>Shapes of kinematic bodies.</summary>
+        public static readonly Color Kinematic = new(90, 160, 255);
+        /// <summary>Shapes of dynamic bodies.</summary>
+        public static readonly Color Dynamic = new(255, 210, 60);
+        /// <summary>Sensors.</summary>
+        public static readonly Color Sensor = new(80, 230, 230, 160);
+        /// <summary>One-way shapes and one-way tiles.</summary>
+        public static readonly Color OneWay = new(255, 150, 60);
+        /// <summary>Contacts that began during the latest step: the normal from the first shape's body.</summary>
+        public static readonly Color Contact = new(255, 70, 70);
+    }
+
+    private readonly Game _game;
+    private readonly List<Item> _items = [];
+    private bool _enabled;
+
+    internal DebugDraw(Game game) => _game = game;
+
+    /// <summary>Whether calls are recorded and drawn. Off by default; turning it off drops what is pending.</summary>
+    public bool Enabled
+    {
+        get => _enabled;
+        set
+        {
+            _enabled = value;
+            if (!value) _items.Clear();
+        }
+    }
+
+    /// <summary>Items waiting to be drawn (the current frame's and the longer-lived ones).</summary>
+    public int Count => _items.Count;
+
+    /// <summary>A line from <paramref name="from"/> to <paramref name="to"/>.</summary>
+    public void Line(Vector2 from, Vector2 to, Color color, float seconds = 0, DebugSpace space = DebugSpace.World) =>
+        Add(new Item(Kind.Line, space, from, to, 0, color, null, seconds));
+
+    /// <summary>The outline of <paramref name="rect"/>.</summary>
+    public void Rect(RectF rect, Color color, float seconds = 0, DebugSpace space = DebugSpace.World) =>
+        Add(new Item(Kind.Rect, space, new Vector2(rect.X, rect.Y), new Vector2(rect.Width, rect.Height), 0, color, null, seconds));
+
+    /// <summary>The outline of a circle.</summary>
+    public void Circle(Vector2 center, float radius, Color color, float seconds = 0, DebugSpace space = DebugSpace.World) =>
+        Add(new Item(Kind.Circle, space, center, default, radius, color, null, seconds));
+
+    /// <summary>A small cross at <paramref name="position"/> (<paramref name="size"/> wide).</summary>
+    public void Point(Vector2 position, Color color, float size = 4, float seconds = 0, DebugSpace space = DebugSpace.World)
+    {
+        if (!_enabled) return;
+        float h = size / 2;
+        Line(position - new Vector2(h, 0), position + new Vector2(h, 0), color, seconds, space);
+        Line(position - new Vector2(0, h), position + new Vector2(0, h), color, seconds, space);
+    }
+
+    /// <summary><paramref name="text"/> in the game's font (<see cref="Game.Font"/>), its top-left corner at <paramref name="position"/>.</summary>
+    public void Text(Vector2 position, string text, Color color, float seconds = 0, DebugSpace space = DebugSpace.World)
+    {
+        ArgumentNullException.ThrowIfNull(text);
+        Add(new Item(Kind.Text, space, position, default, 0, color, text, seconds));
+    }
+
+    /// <summary>
+    /// Draws <paramref name="world"/> as it is now: every shape of every body (coloured by body kind; sensors and
+    /// one-way shapes in their own colour, <see cref="PhysicsColors"/>), the solid and one-way tiles of tile grids inside
+    /// <paramref name="tileArea"/> (by default what the current scene's camera shows, or the canvas), and a normal for
+    /// each contact that began during the latest step. Does nothing while <see cref="Enabled"/> is off.
+    /// </summary>
+    /// <exception cref="PhysicsCapabilityException">The backend does not declare <see cref="PhysicsCapabilities.ShapeInspection"/>.</exception>
+    public void Physics(IPhysicsWorld2D world, RectF? tileArea = null)
+    {
+        ArgumentNullException.ThrowIfNull(world);
+        if (!_enabled) return;
+        Span<ShapeId> shapes = stackalloc ShapeId[16];
+        foreach (var body in world.Bodies)
+        {
+            int count = world.ShapesOf(body, shapes);
+            var list = count <= shapes.Length ? shapes[..count] : new ShapeId[count];
+            if (count > shapes.Length) world.ShapesOf(body, list);
+            var kind = world.KindOf(body);
+            var origin = world.PositionOf(body);
+            var rotation = Rotation(world.RotationOf(body));
+            foreach (var shape in list)
+            {
+                var d = world.DescriptionOf(shape);
+                if (world is TilePhysicsWorld2D tiles && tiles.GridOf(shape) is { } grid)
+                {
+                    Tiles(grid, origin, tileArea ?? VisibleArea());
+                    continue;
+                }
+                var color = d.IsSensor ? PhysicsColors.Sensor
+                    : d.OneWay ? PhysicsColors.OneWay
+                    : kind switch { BodyKind.Static => PhysicsColors.Static, BodyKind.Kinematic => PhysicsColors.Kinematic, _ => PhysicsColors.Dynamic };
+                Shape(d, origin, rotation, color);
+            }
+        }
+        foreach (var contact in world.ContactEvents)
+        {
+            if (contact.Kind != ContactEventKind.Begin || !world.IsAlive(contact.A)) continue;
+            var from = world.PositionOf(world.BodyOf(contact.A));
+            Line(from, from + contact.Normal * 8, PhysicsColors.Contact);
+        }
+    }
+
+    private static Matrix3x2 Rotation(float radians) => radians == 0 ? Matrix3x2.Identity : Matrix3x2.CreateRotation(radians);
+
+    private void Shape(ShapeDescription d, Vector2 origin, Matrix3x2 rotation, Color color)
+    {
+        Vector2 At(Vector2 local) => origin + Vector2.Transform(d.Offset + local, rotation);
+        switch (d.Kind)
+        {
+            case ShapeKind.Box:
+                var h = d.Size / 2;
+                Polygon([At(new(-h.X, -h.Y)), At(new(h.X, -h.Y)), At(new(h.X, h.Y)), At(new(-h.X, h.Y))], color);
+                break;
+            case ShapeKind.Circle:
+                Circle(At(Vector2.Zero), d.Radius, color);
+                break;
+            case ShapeKind.Capsule:
+                float half = MathF.Max(0, d.Size.Y / 2 - d.Radius);
+                Vector2 top = At(new(0, -half)), bottom = At(new(0, half));
+                Circle(top, d.Radius, color);
+                Circle(bottom, d.Radius, color);
+                var side = Vector2.Transform(new Vector2(d.Radius, 0), rotation);
+                Line(top + side, bottom + side, color);
+                Line(top - side, bottom - side, color);
+                break;
+            default:
+                var vertices = d.Vertices.Span;
+                for (int i = 0; i < vertices.Length; i++) Line(At(vertices[i]), At(vertices[(i + 1) % vertices.Length]), color);
+                break;
+        }
+    }
+
+    private void Polygon(ReadOnlySpan<Vector2> points, Color color)
+    {
+        for (int i = 0; i < points.Length; i++) Line(points[i], points[(i + 1) % points.Length], color);
+    }
+
+    private void Tiles(ICollisionGrid grid, Vector2 origin, RectF area)
+    {
+        int size = grid.TileSize;
+        int x0 = (int)MathF.Floor((area.X - origin.X) / size), y0 = (int)MathF.Floor((area.Y - origin.Y) / size);
+        int x1 = (int)MathF.Ceiling((area.X + area.Width - origin.X) / size), y1 = (int)MathF.Ceiling((area.Y + area.Height - origin.Y) / size);
+        for (int y = y0; y < y1; y++)
+            for (int x = x0; x < x1; x++)
+            {
+                var flags = grid.FlagsAt(x, y);
+                if (flags == TileFlags.None) continue;
+                var cell = new RectF(origin.X + x * size, origin.Y + y * size, size, size);
+                if ((flags & TileFlags.Solid) != 0) Rect(cell, PhysicsColors.Static);
+                else Line(new Vector2(cell.X, cell.Y), new Vector2(cell.X + size, cell.Y), PhysicsColors.OneWay);
+            }
+    }
+
+    private RectF VisibleArea() =>
+        _game.Scenes.Current?.WorldCamera is { } camera ? camera.VisibleBounds : new RectF(0, 0, _game.Width, _game.Height);
+
+    private void Add(in Item item)
+    {
+        if (!_enabled) return;
+        if (!float.IsFinite(item.Remaining) || item.Remaining < 0) throw new ArgumentOutOfRangeException("seconds", item.Remaining, "The duration must be finite and not negative.");
+        _items.Add(item);
+    }
+
+    /// <summary>Draws the pending items, then drops those whose time is up after <paramref name="elapsed"/> seconds.</summary>
+    internal void Flush(IRenderer canvas, Camera2D? camera, float elapsed)
+    {
+        if (_items.Count == 0) return;
+        if (camera is not null) canvas.PushCamera(camera);
+        Draw(canvas, DebugSpace.World);
+        if (camera is not null) canvas.PopCamera();
+        Draw(canvas, DebugSpace.Screen);
+        int kept = 0;
+        for (int i = 0; i < _items.Count; i++)
+        {
+            var item = _items[i];
+            float remaining = item.Remaining - elapsed;
+            if (remaining > 0) _items[kept++] = item with { Remaining = remaining };
+        }
+        _items.RemoveRange(kept, _items.Count - kept);
+    }
+
+    private void Draw(IRenderer canvas, DebugSpace space)
+    {
+        foreach (var item in _items)
+        {
+            if (item.Space != space) continue;
+            switch (item.Kind)
+            {
+                case Kind.Line:
+                    canvas.DrawLine(item.A, item.B, 1, item.Color);
+                    break;
+                case Kind.Rect:
+                    Vector2 p = item.A, s = item.B;
+                    canvas.DrawLine(p, p + new Vector2(s.X, 0), 1, item.Color);
+                    canvas.DrawLine(p + new Vector2(s.X, 0), p + s, 1, item.Color);
+                    canvas.DrawLine(p + s, p + new Vector2(0, s.Y), 1, item.Color);
+                    canvas.DrawLine(p + new Vector2(0, s.Y), p, 1, item.Color);
+                    break;
+                case Kind.Circle:
+                    const int Segments = 24;
+                    for (int i = 0; i < Segments; i++)
+                    {
+                        float a0 = i * MathF.Tau / Segments, a1 = (i + 1) * MathF.Tau / Segments;
+                        canvas.DrawLine(item.A + item.Radius * new Vector2(MathF.Cos(a0), MathF.Sin(a0)),
+                            item.A + item.Radius * new Vector2(MathF.Cos(a1), MathF.Sin(a1)), 1, item.Color);
+                    }
+                    break;
+                case Kind.Text:
+                    _game.Font.Draw(canvas, item.Text!, item.A, item.Color);
+                    break;
+            }
+        }
+    }
+}
diff --git a/src/MicroEngine/Core/Game.cs b/src/MicroEngine/Core/Game.cs
index 09ad1a1e..c5c77a88 100644
--- a/src/MicroEngine/Core/Game.cs
+++ b/src/MicroEngine/Core/Game.cs
@@ -193,6 +193,12 @@ private sealed class SceneUiLayer(Game game) : IInputLayer
     /// of each frame system. Off until <see cref="GameDiagnostics.Enabled"/> is set or a tool listens to the engine's meter.
     /// </summary>
     public GameDiagnostics Diagnostics => _diagnostics ??= new GameDiagnostics(this);
+    private DebugDraw? _debugDraw;
+    /// <summary>
+    /// Lines, shapes, text and physics worlds any code can ask to see, drawn above the scenes at the end of the frame
+    /// (<see cref="Core.DebugDraw"/>). Calls do nothing until <see cref="Core.DebugDraw.Enabled"/> is set.
+    /// </summary>
+    public DebugDraw DebugDraw => _debugDraw ??= new DebugDraw(this);
 
     /// <summary>
     /// An optional feature, if there is one: one the engine declared (<see cref="EngineBuilder.Capabilities"/>), else one
@@ -514,6 +520,7 @@ private void RenderFrame(IRenderer renderer)
         renderer.Clear(Settings.Background);
         Scenes.Draw(renderer);
         DrawAboveScenes(renderer);
+        _debugDraw?.Flush(renderer, Scenes.Current?.WorldCamera, (float)Frame.Delta);
         // The UI view: at the window's resolution where the platform offers it, else in the canvas over the world.
         // The UI view starts at the first thing drawn in it, so a frame whose scenes draw no interface has none (and is
         // captured as the canvas alone, IViewCapture).
diff --git a/tests/MicroEngine.Physics.Box2D.Tests/Box2DTests.cs b/tests/MicroEngine.Physics.Box2D.Tests/Box2DTests.cs
index 295110cc..93ef196f 100644
--- a/tests/MicroEngine.Physics.Box2D.Tests/Box2DTests.cs
+++ b/tests/MicroEngine.Physics.Box2D.Tests/Box2DTests.cs
@@ -99,7 +99,7 @@ public void It_declares_the_solver_capabilities_a_skin_of_three_slops_and_y_up_b
         Assert.AreEqual("box2d", world.Backend);
         Assert.AreEqual(PhysicsCapabilities.DynamicBodies | PhysicsCapabilities.Rotation | PhysicsCapabilities.Circles | PhysicsCapabilities.Capsules
             | PhysicsCapabilities.Polygons | PhysicsCapabilities.ContinuousCollision | PhysicsCapabilities.FrictionRestitution
-            | PhysicsCapabilities.MassProperties | PhysicsCapabilities.OneWayPlatforms, world.Capabilities);
+            | PhysicsCapabilities.MassProperties | PhysicsCapabilities.OneWayPlatforms | PhysicsCapabilities.ShapeInspection, world.Capabilities);
         Assert.AreEqual(0, (int)(world.Capabilities & (PhysicsCapabilities.TileGeometry | PhysicsCapabilities.MovingSolids | PhysicsCapabilities.Joints)));
         Assert.AreEqual(0.015f, world.Skin, 1e-6f);
         Assert.AreEqual(new Vector2(0, 1), world.Up);
diff --git a/tests/MicroEngine.Tests/DebugDrawTests.cs b/tests/MicroEngine.Tests/DebugDrawTests.cs
new file mode 100644
index 00000000..bd3fcad0
--- /dev/null
+++ b/tests/MicroEngine.Tests/DebugDrawTests.cs
@@ -0,0 +1,118 @@
+using System.Numerics;
+using MicroEngine.Core;
+using MicroEngine.Graphics;
+using MicroEngine.Physics;
+using MicroEngine.Physics.Tiles;
+using MicroEngine.Scenes;
+using MicroEngine.World;
+
+namespace MicroEngine.Tests;
+
+/// <summary>DEBUG-1: the debug drawing queue and the physics debug view.</summary>
+[TestClass]
+public sealed class DebugDrawTests
+{
+    private static readonly Color Red = new(255, 0, 0);
+
+    private sealed class BlankGame : Game
+    {
+        public override GameSettings Settings { get; } = new("debug draw", 32, 16) { Background = Color.Black };
+        protected override void Load() => Scenes.Push(new Blank());
+
+        private sealed class Blank : Scene
+        {
+            public override void Update(float dt) { }
+            public override void Draw(IRenderer r) { }
+        }
+    }
+
+    private static (BlankGame Game, HeadlessPlatform Platform) Start()
+    {
+        var game = new BlankGame();
+        var platform = new HeadlessPlatform(32, 16) { Rasterize = true };
+        game.InitializeForTest(platform);
+        game.StepForTest();
+        return (game, platform);
+    }
+
+    private static PixelImage Frame(BlankGame game, HeadlessPlatform platform)
+    {
+        game.Render(platform.BeginFrame());
+        platform.EndFrame();
+        return ((IViewCapture)platform).CaptureWorld();
+    }
+
+    [TestMethod]
+    public void Calls_do_nothing_while_disabled()
+    {
+        var (game, platform) = Start();
+        Assert.IsFalse(game.DebugDraw.Enabled);
+        game.DebugDraw.Rect(new RectF(2.5f, 2.5f, 8, 8), Red, space: DebugSpace.Screen);
+        game.DebugDraw.Text(Vector2.Zero, "x", Red);
+        Assert.AreEqual(0, game.DebugDraw.Count);
+        Assert.AreEqual(Color.Black, Frame(game, platform)[2, 6]);
+    }
+
+    [TestMethod]
+    public void Items_are_drawn_above_the_scenes_for_one_frame_unless_they_last_longer()
+    {
+        var (game, platform) = Start();
+        game.DebugDraw.Enabled = true;
+        game.DebugDraw.Rect(new RectF(2.5f, 2.5f, 8, 8), Red, space: DebugSpace.Screen);
+        game.DebugDraw.Line(new Vector2(20, 12.5f), new Vector2(30, 12.5f), Color.White, seconds: 5, space: DebugSpace.Screen);
+        Assert.AreEqual(2, game.DebugDraw.Count);
+        var first = Frame(game, platform);
+        Assert.AreEqual(Red, first[2, 6], "the rectangle's left edge");
+        Assert.AreEqual(Color.Black, first[6, 6], "an outline, not a fill");
+        Assert.AreEqual(Color.White, first[25, 12]);
+        Assert.AreEqual(1, game.DebugDraw.Count, "the one-frame item is gone, the five-second one stays");
+
+        var second = Frame(game, platform);
+        Assert.AreEqual(Color.Black, second[2, 6]);
+        Assert.AreEqual(Color.White, second[25, 12]);
+        game.DebugDraw.Enabled = false;
+        Assert.AreEqual(0, game.DebugDraw.Count, "turning it off drops what is pending");
+        Assert.ThrowsExactly<ArgumentOutOfRangeException>(() => { game.DebugDraw.Enabled = true; game.DebugDraw.Line(Vector2.Zero, Vector2.One, Red, seconds: -1); });
+    }
+
+    [TestMethod]
+    public void World_items_follow_the_scene_camera_and_screen_items_do_not()
+    {
+        var (game, platform) = Start();
+        game.Scenes.Current!.WorldCamera = new Camera2D(32, 16) { Position = new Vector2(10, 0) };
+        game.DebugDraw.Enabled = true;
+        game.DebugDraw.Line(new Vector2(12.5f, 0), new Vector2(12.5f, 16), Red);
+        game.DebugDraw.Line(new Vector2(12.5f, 0), new Vector2(12.5f, 16), Color.White, space: DebugSpace.Screen);
+        var frame = Frame(game, platform);
+        Assert.AreEqual(Red, frame[2, 8], "world x 12.5 is 2.5 on screen");
+        Assert.AreEqual(Color.White, frame[12, 8]);
+    }
+
+    private sealed class Cells : ICollisionGrid
+    {
+        public int TileSize => 4;
+        public TileFlags FlagsAt(int x, int y) => (x, y) switch { (0, 3) or (1, 3) => TileFlags.Solid, (2, 3) => TileFlags.OneWay, _ => TileFlags.None };
+    }
+
+    [TestMethod]
+    public void The_physics_view_draws_every_shape_the_tiles_in_view_and_nothing_while_disabled()
+    {
+        var (game, platform) = Start();
+        var world = new TilePhysicsWorld2D();
+        var level = world.CreateBody(default, BodyDescription.Static());
+        world.AddTiles(level, new Cells());
+        var player = world.CreateBody(new EntityId(1, 1), BodyDescription.Kinematic(new Vector2(20.5f, 6.5f)));
+        world.AddShape(player, ShapeDescription.Box(new Vector2(4, 4)));
+        world.AddShape(player, ShapeDescription.Sensor(new Vector2(8, 8)));
+
+        game.DebugDraw.Physics(world);
+        Assert.AreEqual(0, game.DebugDraw.Count, "disabled: nothing is read or queued");
+
+        game.DebugDraw.Enabled = true;
+        game.DebugDraw.Physics(world);
+        Assert.AreEqual(4 + 4 + 2 + 1, game.DebugDraw.Count, "box and sensor outlines, two solid tiles, one one-way top");
+        var frame = Frame(game, platform);
+        Assert.AreEqual(DebugDraw.PhysicsColors.Kinematic, frame[18, 6], "the player box's left edge at x 18.5");
+        Assert.IsTrue(Enumerable.Range(0, 8).Any(x => Enumerable.Range(12, 4).Any(y => frame[x, y] == DebugDraw.PhysicsColors.Static)), "the solid tiles, rows 12 to 15");
+    }
+}
diff --git a/tests/MicroEngine.Tests/Physics/TilePhysicsTests.cs b/tests/MicroEngine.Tests/Physics/TilePhysicsTests.cs
index 27300f87..d247c264 100644
--- a/tests/MicroEngine.Tests/Physics/TilePhysicsTests.cs
+++ b/tests/MicroEngine.Tests/Physics/TilePhysicsTests.cs
@@ -52,7 +52,7 @@ private static BodyId Box(TilePhysicsWorld2D world, BodyDescription body, RectF
     public void It_declares_tile_geometry_one_way_platforms_and_moving_solids_a_zero_skin_and_y_down()
     {
         var world = new TilePhysicsWorld2D();
-        Assert.AreEqual(PhysicsCapabilities.TileGeometry | PhysicsCapabilities.OneWayPlatforms | PhysicsCapabilities.MovingSolids, world.Capabilities);
+        Assert.AreEqual(PhysicsCapabilities.TileGeometry | PhysicsCapabilities.OneWayPlatforms | PhysicsCapabilities.MovingSolids | PhysicsCapabilities.ShapeInspection, world.Capabilities);
         Assert.AreEqual(0, world.Skin);
         Assert.AreEqual(new Vector2(0, -1), world.Up);
         Assert.AreEqual("tiles", world.Backend);
diff --git a/tests/Shared/Physics/PhysicsConformance.cs b/tests/Shared/Physics/PhysicsConformance.cs
index a40f15b0..d0c7769c 100644
--- a/tests/Shared/Physics/PhysicsConformance.cs
+++ b/tests/Shared/Physics/PhysicsConformance.cs
@@ -161,6 +161,36 @@ public void Invalid_descriptions_are_refused_whatever_the_backend()
         Assert.AreEqual(1, world.Bodies.Length, "a refused request changes nothing");
     }
 
+    [TestMethod]
+    public void A_body_lists_its_shapes_and_each_shape_reads_back_its_description()
+    {
+        var world = CreateWorld();
+        if ((world.Capabilities & PhysicsCapabilities.ShapeInspection) == 0)
+        {
+            Assert.ThrowsExactly<PhysicsCapabilityException>(() => world.ShapesOf(world.CreateBody(default, BodyDescription.Static()), []));
+            return;
+        }
+        var body = world.CreateBody(default, BodyDescription.Static(At(world, 10, 0)));
+        var box = ShapeDescription.Box(new Vector2(4, 2) * Scale);
+        var sensor = ShapeDescription.Sensor(new Vector2(6, 6) * Scale, new Vector2(1, 0) * Scale);
+        var a = world.AddShape(body, box);
+        var b = world.AddShape(body, sensor);
+        Span<ShapeId> shapes = stackalloc ShapeId[4];
+        Assert.AreEqual(2, world.ShapesOf(body, shapes));
+        Assert.AreEqual(a, shapes[0], "in the order they were added");
+        Assert.AreEqual(b, shapes[1]);
+        Assert.AreEqual(box, world.DescriptionOf(a));
+        Assert.AreEqual(sensor, world.DescriptionOf(b));
+        Assert.AreEqual(2, world.ShapesOf(body, []), "the count even when the span is too short");
+
+        world.RemoveShape(a);
+        Assert.AreEqual(1, world.ShapesOf(body, shapes));
+        Assert.AreEqual(b, shapes[0]);
+        Assert.ThrowsExactly<InvalidOperationException>(() => world.DescriptionOf(a), "a removed shape is stale");
+        world.DestroyBody(body);
+        Assert.ThrowsExactly<InvalidOperationException>(() => world.ShapesOf(body, new ShapeId[4]), "a destroyed body is stale");
+    }
+
     [TestMethod]
     public void Every_undeclared_capability_is_refused_with_the_typed_error_and_every_declared_one_is_accepted()
     {
@@ -176,6 +206,7 @@ public void Every_undeclared_capability_is_refused_with_the_typed_error_and_ever
             (PhysicsCapabilities.OneWayPlatforms, w => w.AddShape(w.CreateBody(default, BodyDescription.Static()), ShapeDescription.Box(Vector2.One * Scale) with { OneWay = true })),
             (PhysicsCapabilities.FrictionRestitution, w => w.AddShape(w.CreateBody(default, BodyDescription.Static()), ShapeDescription.Box(Vector2.One * Scale) with { Friction = 0.5f })),
             (PhysicsCapabilities.MassProperties, w => w.AddShape(w.CreateBody(default, BodyDescription.Static()), ShapeDescription.Box(Vector2.One * Scale) with { Density = 2 })),
+            (PhysicsCapabilities.ShapeInspection, w => w.DescriptionOf(w.AddShape(w.CreateBody(default, BodyDescription.Static()), ShapeDescription.Box(Vector2.One * Scale)))),
         };
         int refused = 0, accepted = 0;
         foreach (var (flag, request) in requests)

From d4090765490a17066b8fd457802516fcf5ae6ffa Mon Sep 17 00:00:00 2001
From: Kevin Martinez <ksmartinez23@outlook.com>
Date: Thu, 12 Nov 2026 12:17:53 -0500
Subject: [PATCH 4/5] feat(diagnostics): input routing trace, backend messages
 through ILog and crash reports (DEBUG-1)

---
 docs/guide/release-notes.md                   |   9 ++
 src/MicroEngine.Hosting/HostEnvironment.cs    |   5 +
 src/MicroEngine.Input/InputSystem.cs          |  32 ++++++
 src/MicroEngine.Raylib/RaylibAudioDevice.cs   |  11 +-
 src/MicroEngine.Raylib/RaylibPlatform.cs      |   2 +-
 src/MicroEngine.Sdl/SdlAudioDevice.cs         |  28 +++--
 src/MicroEngine.Sdl/SdlPlatform.cs            |   9 +-
 src/MicroEngine/Core/CrashReport.cs           |  60 +++++++++++
 src/MicroEngine/Core/Game.cs                  |   3 +
 src/MicroEngine/Core/GameDiagnostics.cs       |   7 +-
 src/MicroEngine/Core/GameHost.cs              |  28 ++++-
 src/MicroEngine/Core/PlatformProfiles.cs      |   7 ++
 src/MicroEngine/Core/StartupLog.cs            |  44 ++++++++
 tests/MicroEngine.Tests/CrashReportTests.cs   | 102 ++++++++++++++++++
 tests/MicroEngine.Tests/DiagnosticsTests.cs   |   1 +
 .../Input/InputEventTests.cs                  |  24 +++++
 16 files changed, 351 insertions(+), 21 deletions(-)
 create mode 100644 src/MicroEngine/Core/CrashReport.cs
 create mode 100644 src/MicroEngine/Core/StartupLog.cs
 create mode 100644 tests/MicroEngine.Tests/CrashReportTests.cs

diff --git a/docs/guide/release-notes.md b/docs/guide/release-notes.md
index 58ddbe19..5d07f8b2 100644
--- a/docs/guide/release-notes.md
+++ b/docs/guide/release-notes.md
@@ -29,6 +29,15 @@ An eighth package: `MicroEngine.Physics.Box2D`, optional, for dynamic bodies.
   new `PhysicsCapabilities.ShapeInspection` (both built-in backends declare it; a backend of your own that does not
   refuses them with `PhysicsCapabilityException`). `TilePhysicsWorld2D.GridOf(shape)` returns the tiles of a tile
   shape.
+- `InputSystem.Trace` and `InputSystem.Routed` list the frame's input events with the layer that took each one (a
+  menu, the on-screen controls) or none when it reached gameplay. The game's diagnostics turn the trace on while they
+  measure.
+- When a run fails, the desktop launcher writes a crash report (`CrashReport`) to the game's save folder and names it
+  after the error: game and engine versions, system, platform facts, the last measured frame and its slowest systems,
+  and the error with its stack trace.
+- `PlatformRequest.Log`: what the SDL and raylib backends report (no audio device, no gamepads, a renderer that did
+  not start) now goes through the game's `ILog` instead of straight to standard error. With the default log the
+  console shows the same lines.
 - `IGraphicsDevice.Counters` (in `MicroEngine.Graphics.Devices`) and `AudioMixer.Statistics` read draw calls and voices
   without casting to the backend's class.
 
diff --git a/src/MicroEngine.Hosting/HostEnvironment.cs b/src/MicroEngine.Hosting/HostEnvironment.cs
index 547d2b6a..e5bd1c34 100644
--- a/src/MicroEngine.Hosting/HostEnvironment.cs
+++ b/src/MicroEngine.Hosting/HostEnvironment.cs
@@ -35,6 +35,11 @@ public sealed class HostEnvironment
     public TextWriter Error { get; init; } = Console.Error;
     /// <summary>The folder the host's program runs from (<see cref="AppContext.BaseDirectory"/> by default).</summary>
     public string BaseDirectory { get; init; } = AppContext.BaseDirectory;
+    /// <summary>
+    /// Where the desktop launcher writes the crash report of a run that fails (<c>Core.CrashReport</c>), or null for
+    /// the game's save folder (<c>SaveStore.DefaultDirectory</c>).
+    /// </summary>
+    public string? CrashDirectory { get; init; }
     /// <summary>A seed for runs that ask for none, from the clock by default (<see cref="LaunchRequest.ResolveSeed"/>).</summary>
     public Func<int> ClockSeed { get; init; } = () => Environment.TickCount & 0x7fffffff;
 
diff --git a/src/MicroEngine.Input/InputSystem.cs b/src/MicroEngine.Input/InputSystem.cs
index 880403e5..e03d3179 100644
--- a/src/MicroEngine.Input/InputSystem.cs
+++ b/src/MicroEngine.Input/InputSystem.cs
@@ -82,6 +82,7 @@ internal void BeginUpdate()
 public sealed class InputSystem : IStateHashed
 {
     private readonly List<InputEvent> _drained = [], _sent = [], _pending = [], _events = [];
+    private readonly List<RoutedEvent> _routed = [];
     private readonly List<(DeviceId Id, IInputSource Source)> _polled = [];
     private readonly Dictionary<(int Device, InputEventKind Kind, long Code), IInputLayer> _captures = [];
     private readonly Dictionary<PlayerInput, IInputSource> _views = [];
@@ -107,6 +108,28 @@ public InputSystem(InputMap first)
     /// <summary>The text channel.</summary>
     public TextInput Text { get; } = new();
 
+    /// <summary>
+    /// Whether <see cref="Routed"/> records where each event of the frame went. Off by default; the game's diagnostics
+    /// turn it on while they measure.
+    /// </summary>
+    public bool Trace
+    {
+        get => _trace;
+        set
+        {
+            _trace = value;
+            if (!value) _routed.Clear();
+        }
+    }
+    private bool _trace;
+
+    /// <summary>
+    /// While <see cref="Trace"/> is on, the events routed this frame (device changes excepted) in order, each with the
+    /// layer that took it, or none when it reached the devices and gameplay: the answer to "why did my action not fire?"
+    /// when a menu, the on-screen controls or another layer took the press.
+    /// </summary>
+    public IReadOnlyList<RoutedEvent> Routed => _routed;
+
     /// <summary>The labels of the player's keyboard layout, when the backend knows them.</summary>
     public IKeyLabels? KeyLabels { get; private set; }
 
@@ -149,6 +172,7 @@ public DeviceId AddPolled(IInputSource source)
     /// <summary>Starts a frame: routes the backend's events, then the sent ones. Called by the loop once per frame.</summary>
     public void BeginFrame()
     {
+        _routed.Clear();
         _drained.Clear();
         _backend?.Drain(_drained);
         _drained.AddRange(_sent);
@@ -179,13 +203,16 @@ public void Route(in InputEvent e)
         {
             owner.Handle(e);
             if (Ends(e)) _captures.Remove(capture);
+            if (Trace) _routed.Add(new RoutedEvent(e, owner));
             return;
         }
         if (Layers.Offer(e) is { } taker)
         {
+            if (Trace) _routed.Add(new RoutedEvent(e, taker));
             if (Starts(e) && CaptureKey(e) is { } start) _captures[start] = taker;
             return;
         }
+        if (Trace) _routed.Add(new RoutedEvent(e, null));
         if (e.IsPress && Players.OwnerOf(e.Device) is null) Players.ReportUnpaired(e);
         Devices.Apply(e);
         if (e.Kind is InputEventKind.Text or InputEventKind.TextComposition) Text.Receive(e);
@@ -386,3 +413,8 @@ public PointerState Pointer
         public IReadOnlyList<PointerInfo> Pointers => devices.Pointers;
     }
 }
+
+/// <summary>One event of the frame and where it went (<see cref="InputSystem.Routed"/>).</summary>
+/// <param name="Event">The event.</param>
+/// <param name="Layer">The input layer that took it (or that took the press it ends), or null when it reached the devices and gameplay.</param>
+public readonly record struct RoutedEvent(InputEvent Event, IInputLayer? Layer);
diff --git a/src/MicroEngine.Raylib/RaylibAudioDevice.cs b/src/MicroEngine.Raylib/RaylibAudioDevice.cs
index 6f63e11a..4d99edec 100644
--- a/src/MicroEngine.Raylib/RaylibAudioDevice.cs
+++ b/src/MicroEngine.Raylib/RaylibAudioDevice.cs
@@ -1,5 +1,6 @@
 using System.Runtime.InteropServices;
 using MicroEngine.Audio;
+using MicroEngine.Kernel;
 using MicroEngine.Platform;
 using Rl = Raylib_cs.Raylib;
 
@@ -14,17 +15,21 @@ internal sealed class RaylibAudioDevice : MixerAudioDevice
 {
     private RaylibAudioDevice(IAudioSink sink) : base(sink) => AddDecoder("mp3", DecodeMp3);
 
-    public static IAudioDevice TryCreate()
+    public static IAudioDevice TryCreate() => TryCreate(new ConsoleLog());
+
+    /// <summary>Opens raylib's audio device, or returns a silent device and writes why to <paramref name="log"/> when there is none.</summary>
+    public static IAudioDevice TryCreate(ILog log)
     {
+        ArgumentNullException.ThrowIfNull(log);
         try
         {
             Rl.InitAudioDevice();
             if (Rl.IsAudioDeviceReady()) return new RaylibAudioDevice(new RaylibFeederSink());
-            Console.Error.WriteLine("audio: no device available, continuing silently");
+            log.Write(LogLevel.Warning, "audio", "no device available, continuing silently");
         }
         catch (Exception e) when (e is DllNotFoundException or EntryPointNotFoundException)
         {
-            Console.Error.WriteLine($"audio: {e.Message}");
+            log.Write(LogLevel.Warning, "audio", $"{e.Message}");
         }
         return new SilentAudioDevice();
     }
diff --git a/src/MicroEngine.Raylib/RaylibPlatform.cs b/src/MicroEngine.Raylib/RaylibPlatform.cs
index dfc56975..70c7c0ae 100644
--- a/src/MicroEngine.Raylib/RaylibPlatform.cs
+++ b/src/MicroEngine.Raylib/RaylibPlatform.cs
@@ -132,7 +132,7 @@ private RaylibPlatform(GameSettings settings, DesktopOptions options, PlatformRe
             _vsync = graphics.VSync && options.WaitForDisplay;
             Pace();
         }
-        _audio = request?.CreateAudio(() => RaylibAudioDevice.TryCreate()) ?? (options.Mute ? new SilentAudioDevice() : RaylibAudioDevice.TryCreate());
+        _audio = request?.CreateAudio(() => RaylibAudioDevice.TryCreate(request.Log)) ?? (options.Mute ? new SilentAudioDevice() : RaylibAudioDevice.TryCreate());
         _surface = new HostSurface(GetWindowHandle(), () => (Rl.GetRenderWidth(), Rl.GetRenderHeight()),
             () => Rl.GetWindowScaleDPI().X is > 0 and var d ? d : 1, () => !OperatingSystem.IsBrowser() && Rl.IsWindowMinimized());
         // The graphics device on raylib's window; the game draws into a canvas render target through the 2D batcher and
diff --git a/src/MicroEngine.Sdl/SdlAudioDevice.cs b/src/MicroEngine.Sdl/SdlAudioDevice.cs
index 1d6a8660..78fe52d1 100644
--- a/src/MicroEngine.Sdl/SdlAudioDevice.cs
+++ b/src/MicroEngine.Sdl/SdlAudioDevice.cs
@@ -1,4 +1,5 @@
 using MicroEngine.Audio;
+using MicroEngine.Kernel;
 using MicroEngine.Platform;
 using SDL;
 using static SDL.SDL3;
@@ -22,16 +23,23 @@ public sealed class SdlAudioDevice : MixerAudioDevice
     private SdlAudioDevice(IAudioSink sink) : base(sink) { }
 
     /// <summary>Opens the default playback device, or returns a silent device (and says why) when there is none.</summary>
-    public static IAudioDevice TryCreate() => OperatingSystem.IsBrowser() ? OpenBrowser() : Open(null, DefaultLatencyMilliseconds);
+    public static IAudioDevice TryCreate() => TryCreate(new ConsoleLog());
+
+    /// <summary>Opens the default playback device, or returns a silent device and writes why to <paramref name="log"/> when there is none.</summary>
+    public static IAudioDevice TryCreate(ILog log)
+    {
+        ArgumentNullException.ThrowIfNull(log);
+        return OperatingSystem.IsBrowser() ? OpenBrowser(log) : Open(null, DefaultLatencyMilliseconds, log);
+    }
 
     /// <summary>The page's AudioWorklet sink; silence (and why) when the page offers no audio.</summary>
     [System.Runtime.Versioning.SupportedOSPlatform("browser")]
-    private static IAudioDevice OpenBrowser()
+    private static IAudioDevice OpenBrowser(ILog log)
     {
         try { return new SdlAudioDevice(new BrowserAudioSink(BrowserAudioSink.DefaultLatencyMilliseconds)); }
         catch (Exception e) when (e is not OutOfMemoryException)
         {
-            Console.Error.WriteLine($"audio: the page offers no audio output ({e.Message}), continuing silently");
+            log.Write(LogLevel.Warning, "audio", $"the page offers no audio output ({e.Message}), continuing silently");
             return new SilentAudioDevice();
         }
     }
@@ -45,7 +53,7 @@ private static IAudioDevice OpenBrowser()
     public static IAudioDevice TryCreate(string driver)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(driver);
-        return Open(driver, DefaultLatencyMilliseconds);
+        return Open(driver, DefaultLatencyMilliseconds, new ConsoleLog());
     }
 
     /// <summary>
@@ -56,10 +64,10 @@ public static IAudioDevice TryCreate(string driver)
     public static IAudioDevice TryCreate(string? driver, double latencyMilliseconds)
     {
         if (latencyMilliseconds is < 5 or > 1000) throw new ArgumentOutOfRangeException(nameof(latencyMilliseconds));
-        return Open(driver, latencyMilliseconds);
+        return Open(driver, latencyMilliseconds, new ConsoleLog());
     }
 
-    private static unsafe IAudioDevice Open(string? driver, double latency)
+    private static unsafe IAudioDevice Open(string? driver, double latency, ILog log)
     {
         try
         {
@@ -69,20 +77,20 @@ private static unsafe IAudioDevice Open(string? driver, double latency)
             finally { if (driver is not null) SDL_ResetHint(SDL_HINT_AUDIO_DRIVER); }
             if (started && driver is not null && SDL_GetCurrentAudioDriver() != driver)
             {
-                Console.Error.WriteLine($"audio: SDL audio already runs with the '{SDL_GetCurrentAudioDriver()}' driver, not '{driver}'; continuing silently");
+                log.Write(LogLevel.Warning, "audio", $"SDL audio already runs with the '{SDL_GetCurrentAudioDriver()}' driver, not '{driver}'; continuing silently");
                 SDL_QuitSubSystem(SDL_InitFlags.SDL_INIT_AUDIO);
                 return new SilentAudioDevice();
             }
             if (!started)
             {
-                Console.Error.WriteLine($"audio: {SDL_GetError()}, continuing silently");
+                log.Write(LogLevel.Warning, "audio", $"{SDL_GetError()}, continuing silently");
                 return new SilentAudioDevice();
             }
             var spec = new SDL_AudioSpec { format = SDL_AudioFormat.SDL_AUDIO_F32LE, channels = 2, freq = Rate };
             var device = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec);
             if (device == 0)
             {
-                Console.Error.WriteLine($"audio: no device available ({SDL_GetError()}), continuing silently");
+                log.Write(LogLevel.Warning, "audio", $"no device available ({SDL_GetError()}), continuing silently");
                 SDL_QuitSubSystem(SDL_InitFlags.SDL_INIT_AUDIO);
                 return new SilentAudioDevice();
             }
@@ -90,7 +98,7 @@ private static unsafe IAudioDevice Open(string? driver, double latency)
         }
         catch (Exception e) when (e is DllNotFoundException or EntryPointNotFoundException)
         {
-            Console.Error.WriteLine($"audio: {e.Message}");
+            log.Write(LogLevel.Warning, "audio", $"{e.Message}");
             return new SilentAudioDevice();
         }
     }
diff --git a/src/MicroEngine.Sdl/SdlPlatform.cs b/src/MicroEngine.Sdl/SdlPlatform.cs
index 756f6667..88fa87e3 100644
--- a/src/MicroEngine.Sdl/SdlPlatform.cs
+++ b/src/MicroEngine.Sdl/SdlPlatform.cs
@@ -8,6 +8,7 @@
 using Dev = MicroEngine.Graphics.Devices;
 using GpuBackend = MicroEngine.Graphics.SdlGpu;
 using MicroEngine.Input;
+using MicroEngine.Kernel;
 using MicroEngine.Platform;
 using SDL;
 using static SDL.SDL3;
@@ -37,6 +38,7 @@ namespace MicroEngine.Sdl;
 public sealed unsafe class SdlPlatform : IPlatform, IPlatformDiagnostics, IDisplayControl, IDisplayPacing, IPreciseDelay, IMonotonicClock, IScreenView, IViewCapture
 {
     private readonly GameSettings _settings;
+    private readonly ILog _log;
     private readonly int _captureScale;
     private readonly SDL_Window* _window;
     private readonly SDL_Renderer* _sdl; // null on the sdl-gpu device: SDL_GPU owns the window's swapchain
@@ -143,6 +145,7 @@ private SdlPlatform(PlatformRequest request, string? renderer, BrowserPage? page
         _browser = OperatingSystem.IsBrowser();
         _page = page;
         _settings = request.Settings;
+        _log = request.Log;
         Letterbox = _settings.Letterbox;
         _captureScale = Math.Max(1, request.CaptureScale);
         SDL_SetHint(SDL_HINT_APP_NAME, _settings.Title);
@@ -248,7 +251,7 @@ private SdlPlatform(PlatformRequest request, string? renderer, BrowserPage? page
         _input = new SdlInput(this);
         _combinedInput = request.CombineInput(_input);
         Mark("frame", ref started);
-        _audio = request.CreateAudio(() => SdlAudioDevice.TryCreate());
+        _audio = request.CreateAudio(() => SdlAudioDevice.TryCreate(request.Log));
         Mark("audio", ref started);
         // A host that shows a start screen asks for the gamepad subsystem to start after it (StartGamepads); without one,
         // a window that showed the game's first frame and then froze would be worse than one that appears a moment later.
@@ -303,7 +306,7 @@ private SdlRendererDevice CreateRendererDevice(PresentMode present, GraphicsSett
             try { device = new SdlRendererDevice(_surface, new GraphicsDeviceOptions(present, string.Join(',', graphics.Renderers))); }
             catch (InvalidOperationException e)
             {
-                Console.Error.WriteLine($"platform: none of the preferred renderers ({string.Join(", ", graphics.Renderers)}) could start here ({e.Message}); SDL chooses (drivers here: {string.Join(", ", RenderDrivers)})");
+                _log.Write(LogLevel.Warning, "platform", $"none of the preferred renderers ({string.Join(", ", graphics.Renderers)}) could start here ({e.Message}); SDL chooses (drivers here: {string.Join(", ", RenderDrivers)})");
             }
         }
         try { device ??= new SdlRendererDevice(_surface, new GraphicsDeviceOptions(present, renderer)); }
@@ -703,7 +706,7 @@ private void StartGamepads()
         _gamepadsStarted = true;
         long started = System.Diagnostics.Stopwatch.GetTimestamp();
         if (!SDL_InitSubSystem(SDL_InitFlags.SDL_INIT_GAMEPAD))
-            Console.Error.WriteLine($"input: gamepads unavailable ({SDL_GetError()})");
+            _log.Write(LogLevel.Warning, "input", $"gamepads unavailable ({SDL_GetError()})");
         Mark("gamepad", ref started);
     }
 
diff --git a/src/MicroEngine/Core/CrashReport.cs b/src/MicroEngine/Core/CrashReport.cs
new file mode 100644
index 00000000..fbf5104e
--- /dev/null
+++ b/src/MicroEngine/Core/CrashReport.cs
@@ -0,0 +1,60 @@
+using System.Globalization;
+using System.Reflection;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace MicroEngine.Core;
+
+/// <summary>
+/// A text file that describes a run that stopped on an error, for a tester to send: the game and engine versions, the
+/// operating system and runtime, the platform's facts (<see cref="IPlatformDiagnostics"/>), the last measured frame and
+/// its slowest systems when <see cref="Game.Diagnostics"/> measured, and the error with its stack trace. The desktop
+/// launcher writes one when a game's run fails and names it on standard error.
+/// </summary>
+public static class CrashReport
+{
+    /// <summary>The report's text for <paramref name="error"/>, which stopped <paramref name="game"/>.</summary>
+    /// <exception cref="ArgumentNullException">An argument is null.</exception>
+    public static string Describe(Game game, Exception error)
+    {
+        ArgumentNullException.ThrowIfNull(game);
+        ArgumentNullException.ThrowIfNull(error);
+        var text = new StringBuilder();
+        void Line(string line) => text.Append(line).Append('\n');
+        var identity = AppIdentity.Of(game);
+        var engine = typeof(Game).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion ?? "unknown";
+        Line("MicroEngine crash report");
+        Line($"time: {DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture)} UTC");
+        Line(identity is null ? $"game: {game.Settings.Title}" : $"game: {identity.Title} {identity.Version}{(identity.Id is { } id ? $" ({id})" : "")}");
+        Line($"engine: {engine.Split('+')[0]}");
+        Line($"runtime: {RuntimeInformation.FrameworkDescription} on {RuntimeInformation.OSDescription} ({RuntimeInformation.ProcessArchitecture})");
+        if (game.TryGetCapability(out IPlatformDiagnostics? platform))
+            foreach (var (key, value) in platform.Diagnostics.OrderBy(p => p.Key, StringComparer.Ordinal)) Line($"platform {key}: {value}");
+        var frame = game.Diagnostics.LastFrame;
+        if (frame.Frame == 0) Line("last frame: not measured (Game.Diagnostics was off)");
+        else
+        {
+            Line(string.Create(CultureInfo.InvariantCulture,
+                $"last frame: #{frame.Frame}, {frame.Total:0.00} ms (update {frame.Update:0.00}, render {frame.Render:0.00}, present {frame.Present:0.00}), {frame.Steps} steps, {frame.Allocated} B allocated, {frame.Collections} collections, {frame.Graphics.DrawCalls} draw calls, {frame.Audio.ActiveVoices} voices"));
+            foreach (var system in game.Diagnostics.Systems.OrderByDescending(s => s.Milliseconds).Take(5))
+                Line(string.Create(CultureInfo.InvariantCulture, $"  {system.Name} ({system.Phase}): {system.Milliseconds:0.000} ms"));
+        }
+        Line("error:");
+        text.Append(error.ToString().ReplaceLineEndings("\n")).Append('\n');
+        return text.ToString();
+    }
+
+    /// <summary>Writes the report into <paramref name="directory"/> (created if needed) as <c>crash-&lt;UTC time&gt;.txt</c> and returns its path.</summary>
+    /// <exception cref="ArgumentNullException">An argument is null.</exception>
+    /// <exception cref="IOException">The file cannot be written.</exception>
+    /// <exception cref="UnauthorizedAccessException">The folder is not writable.</exception>
+    public static string Write(Game game, Exception error, string directory)
+    {
+        ArgumentNullException.ThrowIfNull(directory);
+        var text = Describe(game, error);
+        Directory.CreateDirectory(directory);
+        var path = Path.Combine(directory, $"crash-{DateTime.UtcNow.ToString("yyyyMMdd-HHmmss-fff", CultureInfo.InvariantCulture)}.txt");
+        File.WriteAllText(path, text);
+        return path;
+    }
+}
diff --git a/src/MicroEngine/Core/Game.cs b/src/MicroEngine/Core/Game.cs
index c5c77a88..9b1fbe53 100644
--- a/src/MicroEngine/Core/Game.cs
+++ b/src/MicroEngine/Core/Game.cs
@@ -193,6 +193,8 @@ private sealed class SceneUiLayer(Game game) : IInputLayer
     /// of each frame system. Off until <see cref="GameDiagnostics.Enabled"/> is set or a tool listens to the engine's meter.
     /// </summary>
     public GameDiagnostics Diagnostics => _diagnostics ??= new GameDiagnostics(this);
+    /// <summary>What the platform reported before the engine existed; replayed into <see cref="Log"/> when the game starts.</summary>
+    internal StartupLog StartupLog { get; } = new();
     private DebugDraw? _debugDraw;
     /// <summary>
     /// Lines, shapes, text and physics worlds any code can ask to see, drawn above the scenes at the end of the frame
@@ -312,6 +314,7 @@ internal void Initialize(IPlatform platform, int seed, GraphicsSettings graphics
         Prompts = services.Get<ActionPrompts>();
         Assets = services.Get<AssetCache>();
         Assets.Log = engine.Log;
+        StartupLog.Attach(engine.Log);
         Audio = services.Get<AudioMixer>();
         // Deterministic runs keep audio state on the simulation's timeline only (songs render when waited for, sounds
         // never re-anchor to the device), so two runs hash and sound the same.
diff --git a/src/MicroEngine/Core/GameDiagnostics.cs b/src/MicroEngine/Core/GameDiagnostics.cs
index af0d97f7..795572a8 100644
--- a/src/MicroEngine/Core/GameDiagnostics.cs
+++ b/src/MicroEngine/Core/GameDiagnostics.cs
@@ -110,13 +110,18 @@ public bool Active
     /// </summary>
     public IReadOnlyList<SystemTiming> Systems => _systems;
 
-    /// <summary>Starts a frame: true when it is measured. Turns the schedule's timing on or off to follow <see cref="Active"/>.</summary>
+    /// <summary>
+    /// Starts a frame: true when it is measured. Turns the schedule's timing and the input trace
+    /// (<see cref="Input.InputSystem.Trace"/>, read through <see cref="Input.InputSystem.Routed"/>) on or off to follow
+    /// <see cref="Active"/>.
+    /// </summary>
     internal bool BeginFrame(FrameSchedule schedule)
     {
         bool active = Active;
         if (active != _wasActive)
         {
             schedule.MeasureTime = active;
+            _game.InputSystem.Trace = active;
             _wasActive = active;
             if (!active) _frameStart = 0;
         }
diff --git a/src/MicroEngine/Core/GameHost.cs b/src/MicroEngine/Core/GameHost.cs
index b8b1638f..1365d834 100644
--- a/src/MicroEngine/Core/GameHost.cs
+++ b/src/MicroEngine/Core/GameHost.cs
@@ -186,6 +186,7 @@ public PlatformRequest CreateRequest(Game game, RunOptions options)
             Mute = arguments.Mute,
             AudioOutput = arguments.Audio == AudioOutput.Automatic && deterministic ? AudioOutput.Silent : arguments.Audio,
             Identity = identity,
+            Log = game.StartupLog,
         };
         foreach (var change in _parts.RequestChanges) request = change(request) ?? throw new InvalidOperationException("A request change returned null.");
         return request;
@@ -225,6 +226,20 @@ public IReadOnlyList<PlatformProfile> Candidates(GraphicsSettings graphics)
         }
     }
 
+    /// <summary>Writes the crash report of a failed run and names it on <paramref name="errors"/>; a report that cannot be written is reported instead.</summary>
+    private void WriteCrashReport(Game game, Exception error, TextWriter errors)
+    {
+        try
+        {
+            var directory = _environment.CrashDirectory ?? SaveStore.DefaultDirectory(AppIdentity.Of(game)?.Id ?? game.Settings.Title);
+            errors.WriteLine($"crash report: {CrashReport.Write(game, error, directory)}");
+        }
+        catch (Exception e) when (e is IOException or UnauthorizedAccessException or ArgumentException)
+        {
+            errors.WriteLine($"crash report: not written ({e.Message})");
+        }
+    }
+
     /// <summary>A loop for one run of <paramref name="game"/> on <paramref name="platform"/>, with the composition applied to its engine.</summary>
     public GameLoop CreateLoop(Game game, IPlatform platform, RunOptions options) => new(game, platform, options, Compose);
 
@@ -232,9 +247,14 @@ public IReadOnlyList<PlatformProfile> Candidates(GraphicsSettings graphics)
     public RunResult Run(Game game, IPlatform platform, RunOptions options)
     {
         var loop = CreateLoop(game, platform, options);
-        if (loop.Start())
-            while (loop.Tick()) { }
-        return loop.Finish();
+        try
+        {
+            if (loop.Start())
+                while (loop.Tick()) { }
+            return loop.Finish();
+        }
+        // A run that failed before its engine existed still shows what the platform reported.
+        finally { game.StartupLog.Attach(new Kernel.ConsoleLog(_environment.Error)); }
     }
 
     /// <summary>
@@ -307,6 +327,7 @@ public int Run()
         try { (platform, profile) = CreatePlatform(request); }
         catch (PlatformConfigurationException e)
         {
+            game.StartupLog.Attach(new Kernel.ConsoleLog(errors));
             errors.WriteLine($"error: {e.Message}");
             return 1;
         }
@@ -339,6 +360,7 @@ public int Run()
         if (result.Error is { } error)
         {
             errors.WriteLine($"error: {error}");
+            WriteCrashReport(game, error, errors);
             return 1;
         }
         output.WriteLine($"done: {result.Updates} updates, {result.Frames} frames");
diff --git a/src/MicroEngine/Core/PlatformProfiles.cs b/src/MicroEngine/Core/PlatformProfiles.cs
index 9e665c99..8f18ee5e 100644
--- a/src/MicroEngine/Core/PlatformProfiles.cs
+++ b/src/MicroEngine/Core/PlatformProfiles.cs
@@ -64,6 +64,13 @@ public sealed record PlatformRequest(GameSettings Settings)
     /// <summary>The game's application identity (name, id, icon, orientation); null keeps the backend's defaults.</summary>
     public AppIdentity? Identity { get; init; }
 
+    /// <summary>
+    /// Where the backend reports what it could not do and how it carried on (no audio device, no gamepads, a renderer
+    /// that did not start). Standard error by default; <see cref="GameHost"/> passes one that reaches the game's
+    /// <see cref="Game.Log"/> once the game starts, so a game that sends its log elsewhere receives these too.
+    /// </summary>
+    public Kernel.ILog Log { get; init; } = new Kernel.ConsoleLog();
+
     /// <summary>Whether the backend should open its own audio device: no device was supplied, no mute, and the output is not silent.</summary>
     public bool OpensOwnAudio => Audio is null && !Mute && AudioOutput != AudioOutput.Silent;
 
diff --git a/src/MicroEngine/Core/StartupLog.cs b/src/MicroEngine/Core/StartupLog.cs
new file mode 100644
index 00000000..8e958e97
--- /dev/null
+++ b/src/MicroEngine/Core/StartupLog.cs
@@ -0,0 +1,44 @@
+using MicroEngine.Kernel;
+
+namespace MicroEngine.Core;
+
+/// <summary>
+/// The log a platform writes to before the game's engine exists: it keeps the messages until it is attached to the
+/// game's <see cref="ILog"/>, then replays them in order and forwards every later one.
+/// </summary>
+internal sealed class StartupLog : ILog
+{
+    private readonly List<(LogLevel Level, string Category, string Message)> _pending = [];
+    private ILog? _target;
+    private readonly Lock _lock = new();
+
+    /// <summary>Whether <see cref="Attach"/> was called.</summary>
+    public bool IsAttached => _target is not null;
+
+    public void Write(LogLevel level, string category, string message)
+    {
+        lock (_lock)
+        {
+            if (_target is null)
+            {
+                _pending.Add((level, category, message));
+                return;
+            }
+        }
+        _target.Write(level, category, message);
+    }
+
+    /// <summary>Sends the kept messages to <paramref name="target"/> and every later one; nothing when already attached.</summary>
+    public void Attach(ILog target)
+    {
+        (LogLevel, string, string)[] pending;
+        lock (_lock)
+        {
+            if (_target is not null) return;
+            _target = target;
+            pending = [.. _pending];
+            _pending.Clear();
+        }
+        foreach (var (level, category, message) in pending) target.Write(level, category, message);
+    }
+}
diff --git a/tests/MicroEngine.Tests/CrashReportTests.cs b/tests/MicroEngine.Tests/CrashReportTests.cs
new file mode 100644
index 00000000..7b309ae4
--- /dev/null
+++ b/tests/MicroEngine.Tests/CrashReportTests.cs
@@ -0,0 +1,102 @@
+using MicroEngine.Core;
+using MicroEngine.Hosting;
+using MicroEngine.Kernel;
+using MicroEngine.Platform;
+using MicroEngine.Scenes;
+
+namespace MicroEngine.Tests;
+
+/// <summary>DEBUG-1: the crash report of a failed run, and platform messages reaching the game's log.</summary>
+[TestClass]
+public sealed class CrashReportTests
+{
+    private sealed class FailingGame : Game
+    {
+        public override GameSettings Settings { get; } = new("crash test");
+        protected override void Load()
+        {
+            Diagnostics.Enabled = true;
+            Scenes.Push(new Failing());
+        }
+
+        private sealed class Failing : Scene
+        {
+            private int _updates;
+            public override void Update(float dt)
+            {
+                if (++_updates == 3) Explode();
+            }
+            private static void Explode() => throw new InvalidOperationException("the boss fell out of the world");
+            public override void Draw(Graphics.IRenderer r) { }
+        }
+    }
+
+    [TestMethod]
+    public void A_failed_run_writes_a_report_with_the_error_its_stack_and_the_last_frame_and_names_it()
+    {
+        var directory = Path.Combine(Path.GetTempPath(), $"me-crash-{Guid.NewGuid():N}");
+        var errors = new StringWriter();
+        try
+        {
+            var environment = new HostEnvironment(HostKind.Test) { Out = new StringWriter(), Error = errors, CrashDirectory = directory };
+            var host = GameHost.Create(environment, new LaunchRequest { Headless = true, Frames = 10 }, h => h.UseGame(() => new FailingGame()));
+            Assert.AreEqual(1, host.Run());
+            var line = errors.ToString().Split('\n').Single(l => l.StartsWith("crash report: ", StringComparison.Ordinal)).Trim();
+            var path = line["crash report: ".Length..];
+            Assert.AreEqual(directory, Path.GetDirectoryName(path));
+            var report = File.ReadAllText(path);
+            StringAssert.StartsWith(report, "MicroEngine crash report\n");
+            StringAssert.Contains(report, "\ngame: ");
+            StringAssert.Contains(report, "the boss fell out of the world");
+            StringAssert.Contains(report, "Explode", "the stack trace names the method that threw");
+            StringAssert.Contains(report, "last frame: #", "diagnostics were on, so the last frame is described");
+            StringAssert.Contains(report, "engine.scenes");
+        }
+        finally
+        {
+            if (Directory.Exists(directory)) Directory.Delete(directory, recursive: true);
+        }
+    }
+
+    [TestMethod]
+    public void Without_diagnostics_the_report_says_the_frame_was_not_measured()
+    {
+        var game = new HeadlessGame();
+        game.InitializeForTest(new HeadlessPlatform());
+        var report = CrashReport.Describe(game, new InvalidOperationException("boom"));
+        StringAssert.Contains(report, "last frame: not measured");
+        StringAssert.Contains(report, "System.InvalidOperationException: boom");
+    }
+
+    private sealed class HeadlessGame : Game
+    {
+        public override GameSettings Settings { get; } = new("plain");
+        protected override void Load() { }
+    }
+
+    private sealed class Lines : ILog
+    {
+        public List<string> Written { get; } = [];
+        public void Write(LogLevel level, string category, string message) => Written.Add($"{level} {category}: {message}");
+    }
+
+    private sealed class LoggedGame : Game
+    {
+        public Lines Lines { get; } = new();
+        public override GameSettings Settings { get; } = new("logged");
+        public override void Configure(EngineBuilder builder) => builder.Services.Replace<ILog>(Lines);
+        protected override void Load() { }
+    }
+
+    [TestMethod]
+    public void What_the_platform_reports_before_the_game_starts_reaches_the_game_log()
+    {
+        var game = new LoggedGame();
+        var environment = new HostEnvironment(HostKind.Test) { Out = new StringWriter(), Error = new StringWriter() };
+        var host = GameHost.Create(environment, new LaunchRequest { Headless = true, Frames = 1 }, h => h.UseGame(() => game)
+            .ConfigureRequest(r => { r.Log.Write(LogLevel.Warning, "audio", "no device available, continuing silently"); return r; }));
+        Assert.AreEqual(0, host.Run());
+        CollectionAssert.Contains(game.Lines.Written, "Warning audio: no device available, continuing silently");
+        Assert.AreEqual("", environment.Error.ToString(), "nothing went around the game's log");
+    }
+}
diff --git a/tests/MicroEngine.Tests/DiagnosticsTests.cs b/tests/MicroEngine.Tests/DiagnosticsTests.cs
index 3eb1b9cc..8b22c8f5 100644
--- a/tests/MicroEngine.Tests/DiagnosticsTests.cs
+++ b/tests/MicroEngine.Tests/DiagnosticsTests.cs
@@ -60,6 +60,7 @@ public void Enabled_diagnostics_report_the_last_frame_and_each_system()
         Assert.IsTrue(slow.Milliseconds >= 2.5, $"{slow.Milliseconds} ms");
         var scenes = game.Diagnostics.Systems.Single(s => s.Name == "engine.scenes");
         Assert.AreEqual(FramePhase.FixedUpdate, scenes.Phase);
+        Assert.IsTrue(game.InputSystem.Trace, "measuring traces input routing too");
         var phases = game.Diagnostics.Systems.Select(s => (int)s.Phase).ToArray();
         CollectionAssert.AreEqual(phases.Order().ToArray(), phases, "systems are listed in the order phases run");
     }
diff --git a/tests/MicroEngine.Tests/Input/InputEventTests.cs b/tests/MicroEngine.Tests/Input/InputEventTests.cs
index b4772c98..cb575133 100644
--- a/tests/MicroEngine.Tests/Input/InputEventTests.cs
+++ b/tests/MicroEngine.Tests/Input/InputEventTests.cs
@@ -226,6 +226,30 @@ public void A_layer_that_takes_a_press_also_takes_its_release_and_gameplay_never
         Assert.AreEqual(0, rig.Input.Events.Count);
     }
 
+    [TestMethod]
+    public void A_trace_records_which_layer_took_each_event_of_the_frame()
+    {
+        var rig = new Rig();
+        var menu = new RecordingLayer(e => e.Key == Key.Escape);
+        rig.Input.Layers.Add(menu, InputLayerOrder.UI);
+        rig.Send(InputEvent.KeyDown(Keyboard, Key.Escape)).Update();
+        Assert.AreEqual(0, rig.Input.Routed.Count, "nothing is recorded while Trace is off");
+        rig.End();
+
+        rig.Input.Trace = true;
+        rig.Send(InputEvent.KeyUp(Keyboard, Key.Escape)).Send(InputEvent.KeyDown(Keyboard, Key.Space)).Update();
+        Assert.AreEqual(2, rig.Input.Routed.Count);
+        Assert.AreEqual((InputEventKind.KeyUp, (IInputLayer?)menu), (rig.Input.Routed[0].Event.Kind, rig.Input.Routed[0].Layer),
+            "the release went to the layer that took the press");
+        Assert.AreEqual(Key.Space, rig.Input.Routed[1].Event.Key);
+        Assert.IsNull(rig.Input.Routed[1].Layer, "no layer took it: it reached gameplay");
+        rig.End();
+
+        rig.Update();
+        Assert.AreEqual(0, rig.Input.Routed.Count, "the trace holds one frame");
+        rig.Input.Trace = false;
+    }
+
     [TestMethod]
     public void Layers_see_events_from_the_highest_order_down()
     {

From 07098646cbae487b6d2eb378f17ae279e4bdf9d4 Mon Sep 17 00:00:00 2001
From: Kevin Martinez <ksmartinez23@outlook.com>
Date: Thu, 12 Nov 2026 12:27:14 -0500
Subject: [PATCH 5/5] docs(diagnostics): diagnosing-a-game manual page and the
 diagnostics example (DEBUG-1)

---
 docs/api/MicroEngine.Audio.AudioMixer.md      |  13 +
 docs/api/MicroEngine.Audio.AudioStatistics.md | 179 ++++++++
 docs/api/MicroEngine.Audio.md                 |   4 +
 docs/api/MicroEngine.Core.CrashReport.md      |  83 ++++
 ...icroEngine.Core.DebugDraw.PhysicsColors.md |  94 +++++
 docs/api/MicroEngine.Core.DebugDraw.md        | 187 +++++++++
 docs/api/MicroEngine.Core.DebugSpace.md       |  27 ++
 docs/api/MicroEngine.Core.FrameStatistics.md  | 383 ++++++++++++++++++
 docs/api/MicroEngine.Core.Game.md             |  26 ++
 docs/api/MicroEngine.Core.GameDiagnostics.md  | 105 +++++
 docs/api/MicroEngine.Core.PlatformRequest.md  |  14 +
 docs/api/MicroEngine.Core.SystemTiming.md     | 179 ++++++++
 docs/api/MicroEngine.Core.md                  |  36 ++
 ...Engine.Graphics.Devices.IGraphicsDevice.md |  13 +
 .../MicroEngine.Hosting.HostEnvironment.md    |  13 +
 docs/api/MicroEngine.Input.InputSystem.md     |  27 ++
 docs/api/MicroEngine.Input.RoutedEvent.md     | 161 ++++++++
 docs/api/MicroEngine.Input.md                 |   4 +
 docs/api/MicroEngine.Kernel.FrameSchedule.md  |  50 +++
 .../MicroEngine.Physics.IPhysicsWorld2D.md    |  55 +++
 ...MicroEngine.Physics.PhysicsCapabilities.md |   7 +
 ...Engine.Physics.Tiles.TilePhysicsWorld2D.md |  79 +++-
 docs/api/MicroEngine.Sdl.SdlAudioDevice.md    |  16 +
 docs/evaluations/debug-1.md                   |   6 +-
 docs/guide/status.md                          |   1 +
 docs/manual/diagnostics.md                    | 172 ++++++++
 docs/manual/lifecycle.md                      |   3 +-
 odd/tasks/debug-1.md                          |  24 +-
 .../Examples/Examples/DiagnosticsExample.cs   | 144 +++++++
 samples/Examples/ExamplesGame.cs              |   1 +
 site/src/lib/repo-docs.mjs                    |   1 +
 tests/Samples.Tests/SampleTests.cs            |  27 ++
 32 files changed, 2125 insertions(+), 9 deletions(-)
 create mode 100644 docs/api/MicroEngine.Audio.AudioStatistics.md
 create mode 100644 docs/api/MicroEngine.Core.CrashReport.md
 create mode 100644 docs/api/MicroEngine.Core.DebugDraw.PhysicsColors.md
 create mode 100644 docs/api/MicroEngine.Core.DebugDraw.md
 create mode 100644 docs/api/MicroEngine.Core.DebugSpace.md
 create mode 100644 docs/api/MicroEngine.Core.FrameStatistics.md
 create mode 100644 docs/api/MicroEngine.Core.GameDiagnostics.md
 create mode 100644 docs/api/MicroEngine.Core.SystemTiming.md
 create mode 100644 docs/api/MicroEngine.Input.RoutedEvent.md
 create mode 100644 docs/manual/diagnostics.md
 create mode 100644 samples/Examples/Examples/DiagnosticsExample.cs

diff --git a/docs/api/MicroEngine.Audio.AudioMixer.md b/docs/api/MicroEngine.Audio.AudioMixer.md
index 87ddd0e7..40a5ef37 100644
--- a/docs/api/MicroEngine.Audio.AudioMixer.md
+++ b/docs/api/MicroEngine.Audio.AudioMixer.md
@@ -133,6 +133,19 @@ public float SfxVolume { get; set; }
 
  [float](https://learn.microsoft.com/dotnet/api/system.single)
 
+### <a id="MicroEngine_Audio_AudioMixer_Statistics"></a> Statistics
+
+The voices of the device's mixer: how many sounds play now, how many can play at once and how many the voice
+policy refused so far. Zeros for a device without the engine's mixer ([SilentAudioDevice](MicroEngine.Audio.SilentAudioDevice.md)).
+
+```csharp
+public AudioStatistics Statistics { get; }
+```
+
+#### Property Value
+
+ [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
 ## Methods
 
 ### <a id="MicroEngine_Audio_AudioMixer_AddMusic_System_String_MicroEngine_Audio_AudioClip_System_Boolean_"></a> AddMusic\(string, AudioClip, bool\)
diff --git a/docs/api/MicroEngine.Audio.AudioStatistics.md b/docs/api/MicroEngine.Audio.AudioStatistics.md
new file mode 100644
index 00000000..8fda3258
--- /dev/null
+++ b/docs/api/MicroEngine.Audio.AudioStatistics.md
@@ -0,0 +1,179 @@
+# Struct AudioStatistics
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Audio](MicroEngine.Audio.md)  
+Assembly: MicroEngine.Audio.dll  
+Guide: [Audio](../manual/audio.md)  
+
+What [Statistics](MicroEngine.Audio.AudioMixer.md#MicroEngine_Audio_AudioMixer_Statistics) reports about the mixer's voices.
+
+```csharp
+public readonly struct AudioStatistics : IEquatable<AudioStatistics>
+```
+
+#### Implements
+
+[IEquatable<AudioStatistics\>](https://learn.microsoft.com/dotnet/api/system.iequatable\-1)
+
+## Constructors
+
+### <a id="MicroEngine_Audio_AudioStatistics__ctor_System_Int32_System_Int32_System_Int32_"></a> AudioStatistics\(int, int, int\)
+
+What [Statistics](MicroEngine.Audio.AudioMixer.md#MicroEngine_Audio_AudioMixer_Statistics) reports about the mixer's voices.
+
+```csharp
+public AudioStatistics(int ActiveVoices, int MaxVoices, int RefusedSounds)
+```
+
+#### Parameters
+
+`ActiveVoices` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Sounds playing now, music included.
+
+`MaxVoices` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Sounds that can play at once.
+
+`RefusedSounds` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Sounds the voice policy refused since the start because every voice played something of higher priority.
+
+## Properties
+
+### <a id="MicroEngine_Audio_AudioStatistics_ActiveVoices"></a> ActiveVoices
+
+Sounds playing now, music included.
+
+```csharp
+public int ActiveVoices { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Audio_AudioStatistics_MaxVoices"></a> MaxVoices
+
+Sounds that can play at once.
+
+```csharp
+public int MaxVoices { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Audio_AudioStatistics_RefusedSounds"></a> RefusedSounds
+
+Sounds the voice policy refused since the start because every voice played something of higher priority.
+
+```csharp
+public int RefusedSounds { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+## Methods
+
+### <a id="MicroEngine_Audio_AudioStatistics_Deconstruct_System_Int32__System_Int32__System_Int32__"></a> Deconstruct\(out int, out int, out int\)
+
+```csharp
+public void Deconstruct(out int ActiveVoices, out int MaxVoices, out int RefusedSounds)
+```
+
+#### Parameters
+
+`ActiveVoices` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+`MaxVoices` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+`RefusedSounds` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Audio_AudioStatistics_Equals_System_Object_"></a> Equals\(object\)
+
+```csharp
+public override bool Equals(object obj)
+```
+
+#### Parameters
+
+`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Audio_AudioStatistics_Equals_MicroEngine_Audio_AudioStatistics_"></a> Equals\(AudioStatistics\)
+
+```csharp
+public bool Equals(AudioStatistics other)
+```
+
+#### Parameters
+
+`other` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Audio_AudioStatistics_GetHashCode"></a> GetHashCode\(\)
+
+```csharp
+public override int GetHashCode()
+```
+
+#### Returns
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Audio_AudioStatistics_ToString"></a> ToString\(\)
+
+```csharp
+public override string ToString()
+```
+
+#### Returns
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+## Operators
+
+### <a id="MicroEngine_Audio_AudioStatistics_op_Equality_MicroEngine_Audio_AudioStatistics_MicroEngine_Audio_AudioStatistics_"></a> operator ==\(AudioStatistics, AudioStatistics\)
+
+```csharp
+public static bool operator ==(AudioStatistics left, AudioStatistics right)
+```
+
+#### Parameters
+
+`left` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+`right` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Audio_AudioStatistics_op_Inequality_MicroEngine_Audio_AudioStatistics_MicroEngine_Audio_AudioStatistics_"></a> operator \!=\(AudioStatistics, AudioStatistics\)
+
+```csharp
+public static bool operator !=(AudioStatistics left, AudioStatistics right)
+```
+
+#### Parameters
+
+`left` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+`right` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+</div>
diff --git a/docs/api/MicroEngine.Audio.md b/docs/api/MicroEngine.Audio.md
index 57ae26af..849d3fc8 100644
--- a/docs/api/MicroEngine.Audio.md
+++ b/docs/api/MicroEngine.Audio.md
@@ -80,6 +80,10 @@ An opaque handle to a loaded sound effect.
 
 ### Structs
 
+ [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+What [Statistics](MicroEngine.Audio.AudioMixer.md#MicroEngine_Audio_AudioMixer_Statistics) reports about the mixer's voices.
+
  [PlayParameters](MicroEngine.Audio.PlayParameters.md)
 
 How a sound plays.
diff --git a/docs/api/MicroEngine.Core.CrashReport.md b/docs/api/MicroEngine.Core.CrashReport.md
new file mode 100644
index 00000000..3c2da039
--- /dev/null
+++ b/docs/api/MicroEngine.Core.CrashReport.md
@@ -0,0 +1,83 @@
+# Class CrashReport
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+A text file that describes a run that stopped on an error, for a tester to send: the game and engine versions, the
+operating system and runtime, the platform's facts ([IPlatformDiagnostics](MicroEngine.Core.IPlatformDiagnostics.md)), the last measured frame and
+its slowest systems when [Diagnostics](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Diagnostics) measured, and the error with its stack trace. The desktop
+launcher writes one when a game's run fails and names it on standard error.
+
+```csharp
+public static class CrashReport
+```
+
+#### Inheritance
+
+[object](https://learn.microsoft.com/dotnet/api/system.object) ← 
+[CrashReport](MicroEngine.Core.CrashReport.md)
+
+## Methods
+
+### <a id="MicroEngine_Core_CrashReport_Describe_MicroEngine_Core_Game_System_Exception_"></a> Describe\(Game, Exception\)
+
+The report's text for <code class="paramref">error</code>, which stopped <code class="paramref">game</code>.
+
+```csharp
+public static string Describe(Game game, Exception error)
+```
+
+#### Parameters
+
+`game` [Game](MicroEngine.Core.Game.md)
+
+`error` [Exception](https://learn.microsoft.com/dotnet/api/system.exception)
+
+#### Returns
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+#### Exceptions
+
+ [ArgumentNullException](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)
+
+An argument is null.
+
+### <a id="MicroEngine_Core_CrashReport_Write_MicroEngine_Core_Game_System_Exception_System_String_"></a> Write\(Game, Exception, string\)
+
+Writes the report into <code class="paramref">directory</code> (created if needed) as <code>crash-&lt;UTC time&gt;.txt</code> and returns its path.
+
+```csharp
+public static string Write(Game game, Exception error, string directory)
+```
+
+#### Parameters
+
+`game` [Game](MicroEngine.Core.Game.md)
+
+`error` [Exception](https://learn.microsoft.com/dotnet/api/system.exception)
+
+`directory` [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+#### Returns
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+#### Exceptions
+
+ [ArgumentNullException](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)
+
+An argument is null.
+
+ [IOException](https://learn.microsoft.com/dotnet/api/system.io.ioexception)
+
+The file cannot be written.
+
+ [UnauthorizedAccessException](https://learn.microsoft.com/dotnet/api/system.unauthorizedaccessexception)
+
+The folder is not writable.
+
+</div>
diff --git a/docs/api/MicroEngine.Core.DebugDraw.PhysicsColors.md b/docs/api/MicroEngine.Core.DebugDraw.PhysicsColors.md
new file mode 100644
index 00000000..1cb365bd
--- /dev/null
+++ b/docs/api/MicroEngine.Core.DebugDraw.PhysicsColors.md
@@ -0,0 +1,94 @@
+# Class DebugDraw.PhysicsColors
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+The colours [Physics](MicroEngine.Core.DebugDraw.md#MicroEngine_Core_DebugDraw_Physics_MicroEngine_Physics_IPhysicsWorld2D_System_Nullable_MicroEngine_RectF__) uses.
+
+```csharp
+public static class DebugDraw.PhysicsColors
+```
+
+#### Inheritance
+
+[object](https://learn.microsoft.com/dotnet/api/system.object) ← 
+[DebugDraw.PhysicsColors](MicroEngine.Core.DebugDraw.PhysicsColors.md)
+
+## Fields
+
+### <a id="MicroEngine_Core_DebugDraw_PhysicsColors_Contact"></a> Contact
+
+Contacts that began during the latest step: the normal from the first shape's body.
+
+```csharp
+public static readonly Color Contact
+```
+
+#### Field Value
+
+ [Color](MicroEngine.Color.md)
+
+### <a id="MicroEngine_Core_DebugDraw_PhysicsColors_Dynamic"></a> Dynamic
+
+Shapes of dynamic bodies.
+
+```csharp
+public static readonly Color Dynamic
+```
+
+#### Field Value
+
+ [Color](MicroEngine.Color.md)
+
+### <a id="MicroEngine_Core_DebugDraw_PhysicsColors_Kinematic"></a> Kinematic
+
+Shapes of kinematic bodies.
+
+```csharp
+public static readonly Color Kinematic
+```
+
+#### Field Value
+
+ [Color](MicroEngine.Color.md)
+
+### <a id="MicroEngine_Core_DebugDraw_PhysicsColors_OneWay"></a> OneWay
+
+One-way shapes and one-way tiles.
+
+```csharp
+public static readonly Color OneWay
+```
+
+#### Field Value
+
+ [Color](MicroEngine.Color.md)
+
+### <a id="MicroEngine_Core_DebugDraw_PhysicsColors_Sensor"></a> Sensor
+
+Sensors.
+
+```csharp
+public static readonly Color Sensor
+```
+
+#### Field Value
+
+ [Color](MicroEngine.Color.md)
+
+### <a id="MicroEngine_Core_DebugDraw_PhysicsColors_Static"></a> Static
+
+Shapes of static bodies.
+
+```csharp
+public static readonly Color Static
+```
+
+#### Field Value
+
+ [Color](MicroEngine.Color.md)
+
+</div>
diff --git a/docs/api/MicroEngine.Core.DebugDraw.md b/docs/api/MicroEngine.Core.DebugDraw.md
new file mode 100644
index 00000000..b1e53f72
--- /dev/null
+++ b/docs/api/MicroEngine.Core.DebugDraw.md
@@ -0,0 +1,187 @@
+# Class DebugDraw
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+Shapes and text any code can ask for while the game runs, drawn above the scenes at the end of the frame
+([DebugDraw](MicroEngine.Core.Game.md#MicroEngine_Core_Game_DebugDraw)): a ray an enemy casts, the box a move swept, a path, a value next to an entity. Calls
+do nothing while [Enabled](MicroEngine.Core.DebugDraw.md#MicroEngine_Core_DebugDraw_Enabled) is off, so they can stay in shipped code.
+
+```csharp
+public sealed class DebugDraw
+```
+
+#### Inheritance
+
+[object](https://learn.microsoft.com/dotnet/api/system.object) ← 
+[DebugDraw](MicroEngine.Core.DebugDraw.md)
+
+## Examples
+
+```csharp
+// In Load:
+DebugDraw.Enabled = true;
+// Anywhere in an update:
+game.DebugDraw.Line(enemy.Position, player.Position, Color.Red);
+game.DebugDraw.Physics(world);
+```
+
+## Remarks
+
+An item drawn with <code>seconds: 0</code> shows for one frame; ask for it every update to keep it. A longer one stays that
+many seconds of real time. World items follow the camera of the scene on top ([WorldCamera](MicroEngine.Scenes.Scene.md#MicroEngine_Scenes_Scene_WorldCamera));
+screen items are in the canvas's pixels. Lines are one world unit (or one canvas pixel) thick.
+
+## Properties
+
+### <a id="MicroEngine_Core_DebugDraw_Count"></a> Count
+
+Items waiting to be drawn (the current frame's and the longer-lived ones).
+
+```csharp
+public int Count { get; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_DebugDraw_Enabled"></a> Enabled
+
+Whether calls are recorded and drawn. Off by default; turning it off drops what is pending.
+
+```csharp
+public bool Enabled { get; set; }
+```
+
+#### Property Value
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+## Methods
+
+### <a id="MicroEngine_Core_DebugDraw_Circle_System_Numerics_Vector2_System_Single_MicroEngine_Color_System_Single_MicroEngine_Core_DebugSpace_"></a> Circle\(Vector2, float, Color, float, DebugSpace\)
+
+The outline of a circle.
+
+```csharp
+public void Circle(Vector2 center, float radius, Color color, float seconds = 0, DebugSpace space = DebugSpace.World)
+```
+
+#### Parameters
+
+`center` [Vector2](https://learn.microsoft.com/dotnet/api/system.numerics.vector2)
+
+`radius` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`color` [Color](MicroEngine.Color.md)
+
+`seconds` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`space` [DebugSpace](MicroEngine.Core.DebugSpace.md)
+
+### <a id="MicroEngine_Core_DebugDraw_Line_System_Numerics_Vector2_System_Numerics_Vector2_MicroEngine_Color_System_Single_MicroEngine_Core_DebugSpace_"></a> Line\(Vector2, Vector2, Color, float, DebugSpace\)
+
+A line from <code class="paramref">from</code> to <code class="paramref">to</code>.
+
+```csharp
+public void Line(Vector2 from, Vector2 to, Color color, float seconds = 0, DebugSpace space = DebugSpace.World)
+```
+
+#### Parameters
+
+`from` [Vector2](https://learn.microsoft.com/dotnet/api/system.numerics.vector2)
+
+`to` [Vector2](https://learn.microsoft.com/dotnet/api/system.numerics.vector2)
+
+`color` [Color](MicroEngine.Color.md)
+
+`seconds` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`space` [DebugSpace](MicroEngine.Core.DebugSpace.md)
+
+### <a id="MicroEngine_Core_DebugDraw_Physics_MicroEngine_Physics_IPhysicsWorld2D_System_Nullable_MicroEngine_RectF__"></a> Physics\(IPhysicsWorld2D, RectF?\)
+
+Draws <code class="paramref">world</code> as it is now: every shape of every body (coloured by body kind; sensors and
+one-way shapes in their own colour, [PhysicsColors](MicroEngine.Core.DebugDraw.PhysicsColors.md)), the solid and one-way tiles of tile grids inside
+<code class="paramref">tileArea</code> (by default what the current scene's camera shows, or the canvas), and a normal for
+each contact that began during the latest step. Does nothing while [Enabled](MicroEngine.Core.DebugDraw.md#MicroEngine_Core_DebugDraw_Enabled) is off.
+
+```csharp
+public void Physics(IPhysicsWorld2D world, RectF? tileArea = null)
+```
+
+#### Parameters
+
+`world` [IPhysicsWorld2D](MicroEngine.Physics.IPhysicsWorld2D.md)
+
+`tileArea` [RectF](MicroEngine.RectF.md)?
+
+#### Exceptions
+
+ [PhysicsCapabilityException](MicroEngine.Physics.PhysicsCapabilityException.md)
+
+The backend does not declare [ShapeInspection](MicroEngine.Physics.PhysicsCapabilities.md).
+
+### <a id="MicroEngine_Core_DebugDraw_Point_System_Numerics_Vector2_MicroEngine_Color_System_Single_System_Single_MicroEngine_Core_DebugSpace_"></a> Point\(Vector2, Color, float, float, DebugSpace\)
+
+A small cross at <code class="paramref">position</code> (<code class="paramref">size</code> wide).
+
+```csharp
+public void Point(Vector2 position, Color color, float size = 4, float seconds = 0, DebugSpace space = DebugSpace.World)
+```
+
+#### Parameters
+
+`position` [Vector2](https://learn.microsoft.com/dotnet/api/system.numerics.vector2)
+
+`color` [Color](MicroEngine.Color.md)
+
+`size` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`seconds` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`space` [DebugSpace](MicroEngine.Core.DebugSpace.md)
+
+### <a id="MicroEngine_Core_DebugDraw_Rect_MicroEngine_RectF_MicroEngine_Color_System_Single_MicroEngine_Core_DebugSpace_"></a> Rect\(RectF, Color, float, DebugSpace\)
+
+The outline of <code class="paramref">rect</code>.
+
+```csharp
+public void Rect(RectF rect, Color color, float seconds = 0, DebugSpace space = DebugSpace.World)
+```
+
+#### Parameters
+
+`rect` [RectF](MicroEngine.RectF.md)
+
+`color` [Color](MicroEngine.Color.md)
+
+`seconds` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`space` [DebugSpace](MicroEngine.Core.DebugSpace.md)
+
+### <a id="MicroEngine_Core_DebugDraw_Text_System_Numerics_Vector2_System_String_MicroEngine_Color_System_Single_MicroEngine_Core_DebugSpace_"></a> Text\(Vector2, string, Color, float, DebugSpace\)
+
+<code class="paramref">text</code> in the game's font ([Font](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Font)), its top-left corner at <code class="paramref">position</code>.
+
+```csharp
+public void Text(Vector2 position, string text, Color color, float seconds = 0, DebugSpace space = DebugSpace.World)
+```
+
+#### Parameters
+
+`position` [Vector2](https://learn.microsoft.com/dotnet/api/system.numerics.vector2)
+
+`text` [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+`color` [Color](MicroEngine.Color.md)
+
+`seconds` [float](https://learn.microsoft.com/dotnet/api/system.single)
+
+`space` [DebugSpace](MicroEngine.Core.DebugSpace.md)
+
+</div>
diff --git a/docs/api/MicroEngine.Core.DebugSpace.md b/docs/api/MicroEngine.Core.DebugSpace.md
new file mode 100644
index 00000000..a65d9b2a
--- /dev/null
+++ b/docs/api/MicroEngine.Core.DebugSpace.md
@@ -0,0 +1,27 @@
+# Enum DebugSpace
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+Where a [DebugDraw](MicroEngine.Core.DebugDraw.md) item is placed.
+
+```csharp
+public enum DebugSpace
+```
+
+## Fields
+
+`Screen = 1` 
+
+Canvas pixels, above the scenes, whatever the camera.
+
+
+
+`World = 0` 
+
+World coordinates, under the current scene's [WorldCamera](MicroEngine.Scenes.Scene.md#MicroEngine_Scenes_Scene_WorldCamera) (canvas pixels when it has none).
+
+</div>
diff --git a/docs/api/MicroEngine.Core.FrameStatistics.md b/docs/api/MicroEngine.Core.FrameStatistics.md
new file mode 100644
index 00000000..227f86f5
--- /dev/null
+++ b/docs/api/MicroEngine.Core.FrameStatistics.md
@@ -0,0 +1,383 @@
+# Struct FrameStatistics
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+What a frame cost, as [LastFrame](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_LastFrame) reports it. Times are in milliseconds of real time.
+
+```csharp
+public readonly struct FrameStatistics : IEquatable<FrameStatistics>
+```
+
+#### Implements
+
+[IEquatable<FrameStatistics\>](https://learn.microsoft.com/dotnet/api/system.iequatable\-1)
+
+## Constructors
+
+### <a id="MicroEngine_Core_FrameStatistics__ctor_System_Int64_System_Double_System_Double_System_Double_System_Double_System_Double_System_Int32_System_Int64_System_Int32_System_Int32_System_Int32_MicroEngine_Graphics_Devices_GraphicsCounters_MicroEngine_Audio_AudioStatistics_"></a> FrameStatistics\(long, double, double, double, double, double, int, long, int, int, int, GraphicsCounters, AudioStatistics\)
+
+What a frame cost, as [LastFrame](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_LastFrame) reports it. Times are in milliseconds of real time.
+
+```csharp
+public FrameStatistics(long Frame, double Interval, double Events, double Update, double Render, double Present, int Steps, long Allocated, int Gen0Collections, int Gen1Collections, int Gen2Collections, GraphicsCounters Graphics, AudioStatistics Audio)
+```
+
+#### Parameters
+
+`Frame` [long](https://learn.microsoft.com/dotnet/api/system.int64)
+
+The number of the frame, from 1; 0 when nothing was measured.
+
+`Interval` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+Time since the previous measured frame started (0 for the first one).
+
+`Events` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+The platform's event pump.
+
+`Update` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+The fixed steps and the per-frame updates ([BeginFrame](MicroEngine.Kernel.FramePhase.md) to [LateUpdate](MicroEngine.Kernel.FramePhase.md)).
+
+`Render` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+Extracting and drawing ([Extract](MicroEngine.Kernel.FramePhase.md) and [Render](MicroEngine.Kernel.FramePhase.md)).
+
+`Present` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+Presenting ([Present](MicroEngine.Kernel.FramePhase.md) and [EndFrame](MicroEngine.Kernel.FramePhase.md)), which includes waiting for the display.
+
+`Steps` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Fixed steps the frame ran.
+
+`Allocated` [long](https://learn.microsoft.com/dotnet/api/system.int64)
+
+Bytes the game's thread allocated during the frame.
+
+`Gen0Collections` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Garbage collections of generation 0 during the frame.
+
+`Gen1Collections` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Garbage collections of generation 1 during the frame.
+
+`Gen2Collections` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+Full garbage collections during the frame.
+
+`Graphics` [GraphicsCounters](MicroEngine.Graphics.Devices.GraphicsCounters.md)
+
+The work the frame submitted to the graphics device (draw calls, passes, uploads; [LiveResources](MicroEngine.Graphics.Devices.GraphicsCounters.md#MicroEngine_Graphics_Devices_GraphicsCounters_LiveResources) is the count at its end). Zeros on a platform whose device does not count.
+
+`Audio` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+The mixer's voices at the end of the frame.
+
+## Properties
+
+### <a id="MicroEngine_Core_FrameStatistics_Allocated"></a> Allocated
+
+Bytes the game's thread allocated during the frame.
+
+```csharp
+public long Allocated { get; init; }
+```
+
+#### Property Value
+
+ [long](https://learn.microsoft.com/dotnet/api/system.int64)
+
+### <a id="MicroEngine_Core_FrameStatistics_Audio"></a> Audio
+
+The mixer's voices at the end of the frame.
+
+```csharp
+public AudioStatistics Audio { get; init; }
+```
+
+#### Property Value
+
+ [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+### <a id="MicroEngine_Core_FrameStatistics_Collections"></a> Collections
+
+Garbage collections of any generation during the frame.
+
+```csharp
+public int Collections { get; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_FrameStatistics_Events"></a> Events
+
+The platform's event pump.
+
+```csharp
+public double Events { get; init; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_FrameStatistics_Frame"></a> Frame
+
+The number of the frame, from 1; 0 when nothing was measured.
+
+```csharp
+public long Frame { get; init; }
+```
+
+#### Property Value
+
+ [long](https://learn.microsoft.com/dotnet/api/system.int64)
+
+### <a id="MicroEngine_Core_FrameStatistics_Gen0Collections"></a> Gen0Collections
+
+Garbage collections of generation 0 during the frame.
+
+```csharp
+public int Gen0Collections { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_FrameStatistics_Gen1Collections"></a> Gen1Collections
+
+Garbage collections of generation 1 during the frame.
+
+```csharp
+public int Gen1Collections { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_FrameStatistics_Gen2Collections"></a> Gen2Collections
+
+Full garbage collections during the frame.
+
+```csharp
+public int Gen2Collections { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_FrameStatistics_Graphics"></a> Graphics
+
+The work the frame submitted to the graphics device (draw calls, passes, uploads; [LiveResources](MicroEngine.Graphics.Devices.GraphicsCounters.md#MicroEngine_Graphics_Devices_GraphicsCounters_LiveResources) is the count at its end). Zeros on a platform whose device does not count.
+
+```csharp
+public GraphicsCounters Graphics { get; init; }
+```
+
+#### Property Value
+
+ [GraphicsCounters](MicroEngine.Graphics.Devices.GraphicsCounters.md)
+
+### <a id="MicroEngine_Core_FrameStatistics_Interval"></a> Interval
+
+Time since the previous measured frame started (0 for the first one).
+
+```csharp
+public double Interval { get; init; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_FrameStatistics_Present"></a> Present
+
+Presenting ([Present](MicroEngine.Kernel.FramePhase.md) and [EndFrame](MicroEngine.Kernel.FramePhase.md)), which includes waiting for the display.
+
+```csharp
+public double Present { get; init; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_FrameStatistics_Render"></a> Render
+
+Extracting and drawing ([Extract](MicroEngine.Kernel.FramePhase.md) and [Render](MicroEngine.Kernel.FramePhase.md)).
+
+```csharp
+public double Render { get; init; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_FrameStatistics_Steps"></a> Steps
+
+Fixed steps the frame ran.
+
+```csharp
+public int Steps { get; init; }
+```
+
+#### Property Value
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_FrameStatistics_Total"></a> Total
+
+The frame's work: events, update, render and present.
+
+```csharp
+public double Total { get; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_FrameStatistics_Update"></a> Update
+
+The fixed steps and the per-frame updates ([BeginFrame](MicroEngine.Kernel.FramePhase.md) to [LateUpdate](MicroEngine.Kernel.FramePhase.md)).
+
+```csharp
+public double Update { get; init; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+## Methods
+
+### <a id="MicroEngine_Core_FrameStatistics_Deconstruct_System_Int64__System_Double__System_Double__System_Double__System_Double__System_Double__System_Int32__System_Int64__System_Int32__System_Int32__System_Int32__MicroEngine_Graphics_Devices_GraphicsCounters__MicroEngine_Audio_AudioStatistics__"></a> Deconstruct\(out long, out double, out double, out double, out double, out double, out int, out long, out int, out int, out int, out GraphicsCounters, out AudioStatistics\)
+
+```csharp
+public void Deconstruct(out long Frame, out double Interval, out double Events, out double Update, out double Render, out double Present, out int Steps, out long Allocated, out int Gen0Collections, out int Gen1Collections, out int Gen2Collections, out GraphicsCounters Graphics, out AudioStatistics Audio)
+```
+
+#### Parameters
+
+`Frame` [long](https://learn.microsoft.com/dotnet/api/system.int64)
+
+`Interval` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+`Events` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+`Update` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+`Render` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+`Present` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+`Steps` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+`Allocated` [long](https://learn.microsoft.com/dotnet/api/system.int64)
+
+`Gen0Collections` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+`Gen1Collections` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+`Gen2Collections` [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+`Graphics` [GraphicsCounters](MicroEngine.Graphics.Devices.GraphicsCounters.md)
+
+`Audio` [AudioStatistics](MicroEngine.Audio.AudioStatistics.md)
+
+### <a id="MicroEngine_Core_FrameStatistics_Equals_System_Object_"></a> Equals\(object\)
+
+```csharp
+public override bool Equals(object obj)
+```
+
+#### Parameters
+
+`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_FrameStatistics_Equals_MicroEngine_Core_FrameStatistics_"></a> Equals\(FrameStatistics\)
+
+```csharp
+public bool Equals(FrameStatistics other)
+```
+
+#### Parameters
+
+`other` [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_FrameStatistics_GetHashCode"></a> GetHashCode\(\)
+
+```csharp
+public override int GetHashCode()
+```
+
+#### Returns
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_FrameStatistics_ToString"></a> ToString\(\)
+
+```csharp
+public override string ToString()
+```
+
+#### Returns
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+## Operators
+
+### <a id="MicroEngine_Core_FrameStatistics_op_Equality_MicroEngine_Core_FrameStatistics_MicroEngine_Core_FrameStatistics_"></a> operator ==\(FrameStatistics, FrameStatistics\)
+
+```csharp
+public static bool operator ==(FrameStatistics left, FrameStatistics right)
+```
+
+#### Parameters
+
+`left` [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+`right` [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_FrameStatistics_op_Inequality_MicroEngine_Core_FrameStatistics_MicroEngine_Core_FrameStatistics_"></a> operator \!=\(FrameStatistics, FrameStatistics\)
+
+```csharp
+public static bool operator !=(FrameStatistics left, FrameStatistics right)
+```
+
+#### Parameters
+
+`left` [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+`right` [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+</div>
diff --git a/docs/api/MicroEngine.Core.Game.md b/docs/api/MicroEngine.Core.Game.md
index a81c78d3..6090d3c0 100644
--- a/docs/api/MicroEngine.Core.Game.md
+++ b/docs/api/MicroEngine.Core.Game.md
@@ -109,6 +109,32 @@ protected virtual string? ContentRoot { get; }
 
  [string](https://learn.microsoft.com/dotnet/api/system.string)?
 
+### <a id="MicroEngine_Core_Game_DebugDraw"></a> DebugDraw
+
+Lines, shapes, text and physics worlds any code can ask to see, drawn above the scenes at the end of the frame
+([DebugDraw](MicroEngine.Core.DebugDraw.md)). Calls do nothing until [Enabled](MicroEngine.Core.DebugDraw.md#MicroEngine_Core_DebugDraw_Enabled) is set.
+
+```csharp
+public DebugDraw DebugDraw { get; }
+```
+
+#### Property Value
+
+ [DebugDraw](MicroEngine.Core.DebugDraw.md)
+
+### <a id="MicroEngine_Core_Game_Diagnostics"></a> Diagnostics
+
+The live measurements of the run: the last frame's times, allocations, graphics work and audio voices, and the time
+of each frame system. Off until [Enabled](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Enabled) is set or a tool listens to the engine's meter.
+
+```csharp
+public GameDiagnostics Diagnostics { get; }
+```
+
+#### Property Value
+
+ [GameDiagnostics](MicroEngine.Core.GameDiagnostics.md)
+
 ### <a id="MicroEngine_Core_Game_Font"></a> Font
 
 The built-in pixel font, created before [Load](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Load) and disposed by the engine when the game shuts down.
diff --git a/docs/api/MicroEngine.Core.GameDiagnostics.md b/docs/api/MicroEngine.Core.GameDiagnostics.md
new file mode 100644
index 00000000..f0995242
--- /dev/null
+++ b/docs/api/MicroEngine.Core.GameDiagnostics.md
@@ -0,0 +1,105 @@
+# Class GameDiagnostics
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+The game's live measurements ([Diagnostics](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Diagnostics)): the last frame's times, allocations, collections,
+graphics work and audio voices, and the time of every system of the frame schedule. Off by default; a run measures
+while [Enabled](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Enabled) is set or while a tool listens to the engine's meter ([MeterName](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_MeterName)), and costs
+nothing measurable otherwise.
+
+```csharp
+public sealed class GameDiagnostics
+```
+
+#### Inheritance
+
+[object](https://learn.microsoft.com/dotnet/api/system.object) ← 
+[GameDiagnostics](MicroEngine.Core.GameDiagnostics.md)
+
+## Examples
+
+```csharp
+// In Load: measure, and show the numbers when F3 is held.
+Diagnostics.Enabled = true;
+// In DrawAboveScenes:
+var frame = Diagnostics.LastFrame;
+Font.Draw(renderer, $"{frame.Total:0.0} ms  {frame.Graphics.DrawCalls} draws  {frame.Allocated} B", new Vector2(4, 4), Color.White);
+```
+
+## Remarks
+
+The same numbers are published as `Metrics` instruments of the meter
+<code>"MicroEngine"</code>, so <code>dotnet-counters monitor --counters MicroEngine</code>, <code>dotnet-monitor</code> or an
+OpenTelemetry exporter read them without code in the game. The runtime's own meter (<code>System.Runtime</code>) adds the
+heap size, GC pauses and thread-pool figures.
+
+## Fields
+
+### <a id="MicroEngine_Core_GameDiagnostics_MeterName"></a> MeterName
+
+The name of the engine's meter (`Meter`): <code>"MicroEngine"</code>.
+
+```csharp
+public const string MeterName = "MicroEngine"
+```
+
+#### Field Value
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+## Properties
+
+### <a id="MicroEngine_Core_GameDiagnostics_Active"></a> Active
+
+Whether frames are measured now: [Enabled](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Enabled), or a listener of the engine's meter is attached.
+
+```csharp
+public bool Active { get; }
+```
+
+#### Property Value
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_GameDiagnostics_Enabled"></a> Enabled
+
+Whether the game measures every frame. Off by default; a tool listening to the engine's meter measures too ([Active](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Active)).
+
+```csharp
+public bool Enabled { get; set; }
+```
+
+#### Property Value
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_GameDiagnostics_LastFrame"></a> LastFrame
+
+The last measured frame; <code>default</code> (frame 0) until a frame is measured. During an update it is the previous frame.
+
+```csharp
+public FrameStatistics LastFrame { get; }
+```
+
+#### Property Value
+
+ [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+### <a id="MicroEngine_Core_GameDiagnostics_Systems"></a> Systems
+
+Every system of the frame schedule with its time during the last measured frame, in the order phases run and, within
+a phase, in the order its systems run. Empty until a frame is measured.
+
+```csharp
+public IReadOnlyList<SystemTiming> Systems { get; }
+```
+
+#### Property Value
+
+ [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[SystemTiming](MicroEngine.Core.SystemTiming.md)\>
+
+</div>
diff --git a/docs/api/MicroEngine.Core.PlatformRequest.md b/docs/api/MicroEngine.Core.PlatformRequest.md
index 41b97f59..dfd4cf43 100644
--- a/docs/api/MicroEngine.Core.PlatformRequest.md
+++ b/docs/api/MicroEngine.Core.PlatformRequest.md
@@ -120,6 +120,20 @@ public AppIdentity? Identity { get; init; }
 
  [AppIdentity](MicroEngine.Core.AppIdentity.md)?
 
+### <a id="MicroEngine_Core_PlatformRequest_Log"></a> Log
+
+Where the backend reports what it could not do and how it carried on (no audio device, no gamepads, a renderer
+that did not start). Standard error by default; [GameHost](MicroEngine.Core.GameHost.md) passes one that reaches the game's
+[Log](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Log) once the game starts, so a game that sends its log elsewhere receives these too.
+
+```csharp
+public ILog Log { get; init; }
+```
+
+#### Property Value
+
+ [ILog](MicroEngine.Kernel.ILog.md)
+
 ### <a id="MicroEngine_Core_PlatformRequest_Mute"></a> Mute
 
 No sound: the backend opens no audio device.
diff --git a/docs/api/MicroEngine.Core.SystemTiming.md b/docs/api/MicroEngine.Core.SystemTiming.md
new file mode 100644
index 00000000..2576082e
--- /dev/null
+++ b/docs/api/MicroEngine.Core.SystemTiming.md
@@ -0,0 +1,179 @@
+# Struct SystemTiming
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Core](MicroEngine.Core.md)  
+Assembly: MicroEngine.dll  
+Guide: [Game lifecycle and time](../manual/lifecycle.md)  
+
+How long one system of the frame schedule took during the last frame ([Systems](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Systems)).
+
+```csharp
+public readonly struct SystemTiming : IEquatable<SystemTiming>
+```
+
+#### Implements
+
+[IEquatable<SystemTiming\>](https://learn.microsoft.com/dotnet/api/system.iequatable\-1)
+
+## Constructors
+
+### <a id="MicroEngine_Core_SystemTiming__ctor_System_String_MicroEngine_Kernel_FramePhase_System_Double_"></a> SystemTiming\(string, FramePhase, double\)
+
+How long one system of the frame schedule took during the last frame ([Systems](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Systems)).
+
+```csharp
+public SystemTiming(string Name, FramePhase Phase, double Milliseconds)
+```
+
+#### Parameters
+
+`Name` [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+The system's name in [FrameSchedule](MicroEngine.Kernel.FrameSchedule.md).
+
+`Phase` [FramePhase](MicroEngine.Kernel.FramePhase.md)
+
+Its phase.
+
+`Milliseconds` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+Its time during the frame; a fixed phase adds up every step of the frame.
+
+## Properties
+
+### <a id="MicroEngine_Core_SystemTiming_Milliseconds"></a> Milliseconds
+
+Its time during the frame; a fixed phase adds up every step of the frame.
+
+```csharp
+public double Milliseconds { get; init; }
+```
+
+#### Property Value
+
+ [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_SystemTiming_Name"></a> Name
+
+The system's name in [FrameSchedule](MicroEngine.Kernel.FrameSchedule.md).
+
+```csharp
+public string Name { get; init; }
+```
+
+#### Property Value
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+### <a id="MicroEngine_Core_SystemTiming_Phase"></a> Phase
+
+Its phase.
+
+```csharp
+public FramePhase Phase { get; init; }
+```
+
+#### Property Value
+
+ [FramePhase](MicroEngine.Kernel.FramePhase.md)
+
+## Methods
+
+### <a id="MicroEngine_Core_SystemTiming_Deconstruct_System_String__MicroEngine_Kernel_FramePhase__System_Double__"></a> Deconstruct\(out string, out FramePhase, out double\)
+
+```csharp
+public void Deconstruct(out string Name, out FramePhase Phase, out double Milliseconds)
+```
+
+#### Parameters
+
+`Name` [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+`Phase` [FramePhase](MicroEngine.Kernel.FramePhase.md)
+
+`Milliseconds` [double](https://learn.microsoft.com/dotnet/api/system.double)
+
+### <a id="MicroEngine_Core_SystemTiming_Equals_System_Object_"></a> Equals\(object\)
+
+```csharp
+public override bool Equals(object obj)
+```
+
+#### Parameters
+
+`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_SystemTiming_Equals_MicroEngine_Core_SystemTiming_"></a> Equals\(SystemTiming\)
+
+```csharp
+public bool Equals(SystemTiming other)
+```
+
+#### Parameters
+
+`other` [SystemTiming](MicroEngine.Core.SystemTiming.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_SystemTiming_GetHashCode"></a> GetHashCode\(\)
+
+```csharp
+public override int GetHashCode()
+```
+
+#### Returns
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Core_SystemTiming_ToString"></a> ToString\(\)
+
+```csharp
+public override string ToString()
+```
+
+#### Returns
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+## Operators
+
+### <a id="MicroEngine_Core_SystemTiming_op_Equality_MicroEngine_Core_SystemTiming_MicroEngine_Core_SystemTiming_"></a> operator ==\(SystemTiming, SystemTiming\)
+
+```csharp
+public static bool operator ==(SystemTiming left, SystemTiming right)
+```
+
+#### Parameters
+
+`left` [SystemTiming](MicroEngine.Core.SystemTiming.md)
+
+`right` [SystemTiming](MicroEngine.Core.SystemTiming.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Core_SystemTiming_op_Inequality_MicroEngine_Core_SystemTiming_MicroEngine_Core_SystemTiming_"></a> operator \!=\(SystemTiming, SystemTiming\)
+
+```csharp
+public static bool operator !=(SystemTiming left, SystemTiming right)
+```
+
+#### Parameters
+
+`left` [SystemTiming](MicroEngine.Core.SystemTiming.md)
+
+`right` [SystemTiming](MicroEngine.Core.SystemTiming.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+</div>
diff --git a/docs/api/MicroEngine.Core.md b/docs/api/MicroEngine.Core.md
index a3b1ce61..f280eb83 100644
--- a/docs/api/MicroEngine.Core.md
+++ b/docs/api/MicroEngine.Core.md
@@ -62,6 +62,23 @@ executable (games copy it there at build time). Missing files fail with the full
 broken install or a typo is obvious. A content source ([IContentSource](MicroEngine.Platform.IContentSource.md)) over a
 [FolderContentSource](MicroEngine.Platform.FolderContentSource.md).
 
+ [CrashReport](MicroEngine.Core.CrashReport.md)
+
+A text file that describes a run that stopped on an error, for a tester to send: the game and engine versions, the
+operating system and runtime, the platform's facts ([IPlatformDiagnostics](MicroEngine.Core.IPlatformDiagnostics.md)), the last measured frame and
+its slowest systems when [Diagnostics](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Diagnostics) measured, and the error with its stack trace. The desktop
+launcher writes one when a game's run fails and names it on standard error.
+
+ [DebugDraw.PhysicsColors](MicroEngine.Core.DebugDraw.PhysicsColors.md)
+
+The colours [Physics](MicroEngine.Core.DebugDraw.md#MicroEngine_Core_DebugDraw_Physics_MicroEngine_Physics_IPhysicsWorld2D_System_Nullable_MicroEngine_RectF__) uses.
+
+ [DebugDraw](MicroEngine.Core.DebugDraw.md)
+
+Shapes and text any code can ask for while the game runs, drawn above the scenes at the end of the frame
+([DebugDraw](MicroEngine.Core.Game.md#MicroEngine_Core_Game_DebugDraw)): a ray an enemy casts, the box a move swept, a path, a value next to an entity. Calls
+do nothing while [Enabled](MicroEngine.Core.DebugDraw.md#MicroEngine_Core_DebugDraw_Enabled) is off, so they can stay in shipped code.
+
  [DisplayInfo](MicroEngine.Core.DisplayInfo.md)
 
 A display (monitor) as the system reports it.
@@ -83,6 +100,13 @@ What a profiled run looked like. [MotionError](MicroEngine.Core.FrameSummary.md#
 the game time it advanced differs from the wall time that passed, so a frame that repeats the previous picture or
 jumps two steps counts even when every frame took the same time.
 
+ [GameDiagnostics](MicroEngine.Core.GameDiagnostics.md)
+
+The game's live measurements ([Diagnostics](MicroEngine.Core.Game.md#MicroEngine_Core_Game_Diagnostics)): the last frame's times, allocations, collections,
+graphics work and audio voices, and the time of every system of the frame schedule. Off by default; a run measures
+while [Enabled](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Enabled) is set or while a tool listens to the engine's meter ([MeterName](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_MeterName)), and costs
+nothing measurable otherwise.
+
  [GameHost](MicroEngine.Core.GameHost.md)
 
 The one launch path of every host: desktop ([GameLauncher](MicroEngine.Core.GameLauncher.md)), browser pages, Android and iOS apps and
@@ -350,6 +374,10 @@ Totals over a scope and its children ([Statistics](MicroEngine.Core.AssetCache.m
 
 One frame as [FrameProfiler](MicroEngine.Core.FrameProfiler.md) measured it. Times are in milliseconds.
 
+ [FrameStatistics](MicroEngine.Core.FrameStatistics.md)
+
+What a frame cost, as [LastFrame](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_LastFrame) reports it. Times are in milliseconds of real time.
+
  [Percentiles](MicroEngine.Core.Percentiles.md)
 
 Percentiles of one frame measurement, in milliseconds.
@@ -358,6 +386,10 @@ Percentiles of one frame measurement, in milliseconds.
 
 One recorded drawing call.
 
+ [SystemTiming](MicroEngine.Core.SystemTiming.md)
+
+How long one system of the frame schedule took during the last frame ([Systems](MicroEngine.Core.GameDiagnostics.md#MicroEngine_Core_GameDiagnostics_Systems)).
+
 ### Interfaces
 
  [IDisplayControl](MicroEngine.Core.IDisplayControl.md)
@@ -411,6 +443,10 @@ Screen orientations a game allows on phones (<code>MicroEngineOrientation</code>
 
 Where a run's sound may go ([AudioOutput](MicroEngine.Core.PlatformRequest.md#MicroEngine_Core_PlatformRequest_AudioOutput), the launcher's <code>--audio</code>).
 
+ [DebugSpace](MicroEngine.Core.DebugSpace.md)
+
+Where a [DebugDraw](MicroEngine.Core.DebugDraw.md) item is placed.
+
  [GpuPreference](MicroEngine.Core.GpuPreference.md)
 
 Which GPU a game prefers on machines with an integrated and a dedicated one. The system has the last word: on
diff --git a/docs/api/MicroEngine.Graphics.Devices.IGraphicsDevice.md b/docs/api/MicroEngine.Graphics.Devices.IGraphicsDevice.md
index 2f32dac6..df3dda46 100644
--- a/docs/api/MicroEngine.Graphics.Devices.IGraphicsDevice.md
+++ b/docs/api/MicroEngine.Graphics.Devices.IGraphicsDevice.md
@@ -35,6 +35,19 @@ GraphicsCapabilities Capabilities { get; }
 
  [GraphicsCapabilities](MicroEngine.Graphics.Devices.GraphicsCapabilities.md)
 
+### <a id="MicroEngine_Graphics_Devices_IGraphicsDevice_Counters"></a> Counters
+
+Deterministic counts of the work submitted to this device since it was created (draw calls, passes, uploads, live
+resources). Every device built on [GraphicsDeviceBase](MicroEngine.Graphics.Devices.GraphicsDeviceBase.md) counts; a device that does not reports zeros.
+
+```csharp
+GraphicsCounters Counters { get; }
+```
+
+#### Property Value
+
+ [GraphicsCounters](MicroEngine.Graphics.Devices.GraphicsCounters.md)
+
 ## Methods
 
 ### <a id="MicroEngine_Graphics_Devices_IGraphicsDevice_BeginCommands"></a> BeginCommands\(\)
diff --git a/docs/api/MicroEngine.Hosting.HostEnvironment.md b/docs/api/MicroEngine.Hosting.HostEnvironment.md
index 5f12198c..47a640ff 100644
--- a/docs/api/MicroEngine.Hosting.HostEnvironment.md
+++ b/docs/api/MicroEngine.Hosting.HostEnvironment.md
@@ -59,6 +59,19 @@ public Func<int> ClockSeed { get; init; }
 
  [Func](https://learn.microsoft.com/dotnet/api/system.func\-1)<[int](https://learn.microsoft.com/dotnet/api/system.int32)\>
 
+### <a id="MicroEngine_Hosting_HostEnvironment_CrashDirectory"></a> CrashDirectory
+
+Where the desktop launcher writes the crash report of a run that fails (<code>Core.CrashReport</code>), or null for
+the game's save folder (<code>SaveStore.DefaultDirectory</code>).
+
+```csharp
+public string? CrashDirectory { get; init; }
+```
+
+#### Property Value
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)?
+
 ### <a id="MicroEngine_Hosting_HostEnvironment_Error"></a> Error
 
 Where the host prints errors (the console's standard error by default, as it was when this was created).
diff --git a/docs/api/MicroEngine.Input.InputSystem.md b/docs/api/MicroEngine.Input.InputSystem.md
index b9a3d1dc..706c8103 100644
--- a/docs/api/MicroEngine.Input.InputSystem.md
+++ b/docs/api/MicroEngine.Input.InputSystem.md
@@ -118,6 +118,20 @@ public IReadOnlyList<(DeviceId Id, IInputSource Source)> PolledSources { get; }
 
  [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<\([DeviceId](MicroEngine.Input.DeviceId.md) [Id](https://learn.microsoft.com/dotnet/api/system.valuetuple\-microengine.input.deviceid,microengine.input.iinputsource\-.id), [IInputSource](MicroEngine.Input.IInputSource.md) [Source](https://learn.microsoft.com/dotnet/api/system.valuetuple\-microengine.input.deviceid,microengine.input.iinputsource\-.source)\)\>
 
+### <a id="MicroEngine_Input_InputSystem_Routed"></a> Routed
+
+While [Trace](MicroEngine.Input.InputSystem.md#MicroEngine_Input_InputSystem_Trace) is on, the events routed this frame (device changes excepted) in order, each with the
+layer that took it, or none when it reached the devices and gameplay: the answer to "why did my action not fire?"
+when a menu, the on-screen controls or another layer took the press.
+
+```csharp
+public IReadOnlyList<RoutedEvent> Routed { get; }
+```
+
+#### Property Value
+
+ [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[RoutedEvent](MicroEngine.Input.RoutedEvent.md)\>
+
 ### <a id="MicroEngine_Input_InputSystem_Text"></a> Text
 
 The text channel.
@@ -130,6 +144,19 @@ public TextInput Text { get; }
 
  [TextInput](MicroEngine.Input.TextInput.md)
 
+### <a id="MicroEngine_Input_InputSystem_Trace"></a> Trace
+
+Whether [Routed](MicroEngine.Input.InputSystem.md#MicroEngine_Input_InputSystem_Routed) records where each event of the frame went. Off by default; the game's diagnostics
+turn it on while they measure.
+
+```csharp
+public bool Trace { get; set; }
+```
+
+#### Property Value
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
 ## Methods
 
 ### <a id="MicroEngine_Input_InputSystem_AddPolled_MicroEngine_Input_IInputSource_"></a> AddPolled\(IInputSource\)
diff --git a/docs/api/MicroEngine.Input.RoutedEvent.md b/docs/api/MicroEngine.Input.RoutedEvent.md
new file mode 100644
index 00000000..46ca114a
--- /dev/null
+++ b/docs/api/MicroEngine.Input.RoutedEvent.md
@@ -0,0 +1,161 @@
+# Struct RoutedEvent
+
+<div data-pagefind-weight="0.3">
+
+Namespace: [MicroEngine.Input](MicroEngine.Input.md)  
+Assembly: MicroEngine.Input.dll  
+Guide: [Input](../manual/input.md)  
+
+One event of the frame and where it went ([Routed](MicroEngine.Input.InputSystem.md#MicroEngine_Input_InputSystem_Routed)).
+
+```csharp
+public readonly struct RoutedEvent : IEquatable<RoutedEvent>
+```
+
+#### Implements
+
+[IEquatable<RoutedEvent\>](https://learn.microsoft.com/dotnet/api/system.iequatable\-1)
+
+## Constructors
+
+### <a id="MicroEngine_Input_RoutedEvent__ctor_MicroEngine_Input_InputEvent_MicroEngine_Input_IInputLayer_"></a> RoutedEvent\(InputEvent, IInputLayer?\)
+
+One event of the frame and where it went ([Routed](MicroEngine.Input.InputSystem.md#MicroEngine_Input_InputSystem_Routed)).
+
+```csharp
+public RoutedEvent(InputEvent Event, IInputLayer? Layer)
+```
+
+#### Parameters
+
+`Event` [InputEvent](MicroEngine.Input.InputEvent.md)
+
+The event.
+
+`Layer` [IInputLayer](MicroEngine.Input.IInputLayer.md)?
+
+The input layer that took it (or that took the press it ends), or null when it reached the devices and gameplay.
+
+## Properties
+
+### <a id="MicroEngine_Input_RoutedEvent_Event"></a> Event
+
+The event.
+
+```csharp
+public InputEvent Event { get; init; }
+```
+
+#### Property Value
+
+ [InputEvent](MicroEngine.Input.InputEvent.md)
+
+### <a id="MicroEngine_Input_RoutedEvent_Layer"></a> Layer
+
+The input layer that took it (or that took the press it ends), or null when it reached the devices and gameplay.
+
+```csharp
+public IInputLayer? Layer { get; init; }
+```
+
+#### Property Value
+
+ [IInputLayer](MicroEngine.Input.IInputLayer.md)?
+
+## Methods
+
+### <a id="MicroEngine_Input_RoutedEvent_Deconstruct_MicroEngine_Input_InputEvent__MicroEngine_Input_IInputLayer__"></a> Deconstruct\(out InputEvent, out IInputLayer?\)
+
+```csharp
+public void Deconstruct(out InputEvent Event, out IInputLayer? Layer)
+```
+
+#### Parameters
+
+`Event` [InputEvent](MicroEngine.Input.InputEvent.md)
+
+`Layer` [IInputLayer](MicroEngine.Input.IInputLayer.md)?
+
+### <a id="MicroEngine_Input_RoutedEvent_Equals_System_Object_"></a> Equals\(object\)
+
+```csharp
+public override bool Equals(object obj)
+```
+
+#### Parameters
+
+`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Input_RoutedEvent_Equals_MicroEngine_Input_RoutedEvent_"></a> Equals\(RoutedEvent\)
+
+```csharp
+public bool Equals(RoutedEvent other)
+```
+
+#### Parameters
+
+`other` [RoutedEvent](MicroEngine.Input.RoutedEvent.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Input_RoutedEvent_GetHashCode"></a> GetHashCode\(\)
+
+```csharp
+public override int GetHashCode()
+```
+
+#### Returns
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+### <a id="MicroEngine_Input_RoutedEvent_ToString"></a> ToString\(\)
+
+```csharp
+public override string ToString()
+```
+
+#### Returns
+
+ [string](https://learn.microsoft.com/dotnet/api/system.string)
+
+## Operators
+
+### <a id="MicroEngine_Input_RoutedEvent_op_Equality_MicroEngine_Input_RoutedEvent_MicroEngine_Input_RoutedEvent_"></a> operator ==\(RoutedEvent, RoutedEvent\)
+
+```csharp
+public static bool operator ==(RoutedEvent left, RoutedEvent right)
+```
+
+#### Parameters
+
+`left` [RoutedEvent](MicroEngine.Input.RoutedEvent.md)
+
+`right` [RoutedEvent](MicroEngine.Input.RoutedEvent.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+### <a id="MicroEngine_Input_RoutedEvent_op_Inequality_MicroEngine_Input_RoutedEvent_MicroEngine_Input_RoutedEvent_"></a> operator \!=\(RoutedEvent, RoutedEvent\)
+
+```csharp
+public static bool operator !=(RoutedEvent left, RoutedEvent right)
+```
+
+#### Parameters
+
+`left` [RoutedEvent](MicroEngine.Input.RoutedEvent.md)
+
+`right` [RoutedEvent](MicroEngine.Input.RoutedEvent.md)
+
+#### Returns
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+</div>
diff --git a/docs/api/MicroEngine.Input.md b/docs/api/MicroEngine.Input.md
index 9611eaf6..6d4a3d3e 100644
--- a/docs/api/MicroEngine.Input.md
+++ b/docs/api/MicroEngine.Input.md
@@ -200,6 +200,10 @@ A pointer the game can read: the mouse while it is over the window, or a finger
 
 The mouse (or another pointer) over the game's virtual canvas.
 
+ [RoutedEvent](MicroEngine.Input.RoutedEvent.md)
+
+One event of the frame and where it went ([Routed](MicroEngine.Input.InputSystem.md#MicroEngine_Input_InputSystem_Routed)).
+
  [TouchControlView](MicroEngine.Input.TouchControlView.md)
 
 Everything a skin needs to draw one control as it is this frame, in screen pixels.
diff --git a/docs/api/MicroEngine.Kernel.FrameSchedule.md b/docs/api/MicroEngine.Kernel.FrameSchedule.md
index fc990995..8d8bc0dc 100644
--- a/docs/api/MicroEngine.Kernel.FrameSchedule.md
+++ b/docs/api/MicroEngine.Kernel.FrameSchedule.md
@@ -59,6 +59,25 @@ public bool IsFrozen { get; }
 
  [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
 
+### <a id="MicroEngine_Kernel_FrameSchedule_MeasureTime"></a> MeasureTime
+
+Whether [Run](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Run_MicroEngine_Kernel_FramePhase_MicroEngine_Kernel_FrameContext__) measures how long each system takes ([Times](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Times_MicroEngine_Kernel_FramePhase_)). Off by default: a schedule
+that does not measure takes no timestamps. It may change once the schedule is frozen, since it changes no system.
+
+```csharp
+public bool MeasureTime { get; set; }
+```
+
+#### Property Value
+
+ [bool](https://learn.microsoft.com/dotnet/api/system.boolean)
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+Turning it on when the order cannot be resolved (see [Order](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Order_MicroEngine_Kernel_FramePhase_)).
+
 ## Methods
 
 ### <a id="MicroEngine_Kernel_FrameSchedule_Add_MicroEngine_Kernel_FramePhase_System_String_System_Action_MicroEngine_Kernel_FrameContext__System_String_System_String_"></a> Add\(FramePhase, string, Action<FrameContext\>, string?, string?\)
@@ -258,6 +277,14 @@ No system is named <code class="paramref">name</code>.
 
 The schedule is frozen.
 
+### <a id="MicroEngine_Kernel_FrameSchedule_ResetTimes"></a> ResetTimes\(\)
+
+Sets every measured time ([Times](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Times_MicroEngine_Kernel_FramePhase_)) back to zero; the loop does it at the start of each frame.
+
+```csharp
+public void ResetTimes()
+```
+
 ### <a id="MicroEngine_Kernel_FrameSchedule_Run_MicroEngine_Kernel_FramePhase_MicroEngine_Kernel_FrameContext__"></a> Run\(FramePhase, in FrameContext\)
 
 Runs the systems of <code class="paramref">phase</code>, in order, with <code class="paramref">context</code>.
@@ -282,4 +309,27 @@ An exception thrown by a system stops the phase and reaches the caller.
 
 The order cannot be resolved (see [Order](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Order_MicroEngine_Kernel_FramePhase_)).
 
+### <a id="MicroEngine_Kernel_FrameSchedule_Times_MicroEngine_Kernel_FramePhase_"></a> Times\(FramePhase\)
+
+The milliseconds each system of <code class="paramref">phase</code> took since the last [ResetTimes](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_ResetTimes), aligned with
+[Order](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Order_MicroEngine_Kernel_FramePhase_): a fixed phase adds up every step it ran. All zero while [MeasureTime](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_MeasureTime) was off.
+
+```csharp
+public ReadOnlySpan<double> Times(FramePhase phase)
+```
+
+#### Parameters
+
+`phase` [FramePhase](MicroEngine.Kernel.FramePhase.md)
+
+#### Returns
+
+ [ReadOnlySpan](https://learn.microsoft.com/dotnet/api/system.readonlyspan\-1)<[double](https://learn.microsoft.com/dotnet/api/system.double)\>
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+The order cannot be resolved (see [Order](MicroEngine.Kernel.FrameSchedule.md#MicroEngine_Kernel_FrameSchedule_Order_MicroEngine_Kernel_FramePhase_)).
+
 </div>
diff --git a/docs/api/MicroEngine.Physics.IPhysicsWorld2D.md b/docs/api/MicroEngine.Physics.IPhysicsWorld2D.md
index 07346d4c..68847fe8 100644
--- a/docs/api/MicroEngine.Physics.IPhysicsWorld2D.md
+++ b/docs/api/MicroEngine.Physics.IPhysicsWorld2D.md
@@ -227,6 +227,32 @@ The description needs an undeclared capability.
 
 The description is invalid ([Validate](MicroEngine.Physics.BodyDescription.md#MicroEngine_Physics_BodyDescription_Validate)).
 
+### <a id="MicroEngine_Physics_IPhysicsWorld2D_DescriptionOf_MicroEngine_Physics_ShapeId_"></a> DescriptionOf\(ShapeId\)
+
+The description <code class="paramref">shape</code> was added with (its geometry is relative to its body's origin).
+
+```csharp
+ShapeDescription DescriptionOf(ShapeId shape)
+```
+
+#### Parameters
+
+`shape` [ShapeId](MicroEngine.Physics.ShapeId.md)
+
+#### Returns
+
+ [ShapeDescription](MicroEngine.Physics.ShapeDescription.md)
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+The id is stale.
+
+ [PhysicsCapabilityException](MicroEngine.Physics.PhysicsCapabilityException.md)
+
+The backend does not declare [ShapeInspection](MicroEngine.Physics.PhysicsCapabilities.md).
+
 ### <a id="MicroEngine_Physics_IPhysicsWorld2D_DestroyBody_MicroEngine_Physics_BodyId_"></a> DestroyBody\(BodyId\)
 
 Destroys the body and its shapes; nothing for a stale or none id. Their sensor pairs end at the next step.
@@ -497,6 +523,35 @@ void SetVelocity(BodyId body, Vector2 velocity)
 
 The backend does not declare [DynamicBodies](MicroEngine.Physics.PhysicsCapabilities.md).
 
+### <a id="MicroEngine_Physics_IPhysicsWorld2D_ShapesOf_MicroEngine_Physics_BodyId_System_Span_MicroEngine_Physics_ShapeId__"></a> ShapesOf\(BodyId, Span<ShapeId\>\)
+
+Writes the live shapes of <code class="paramref">body</code>, in the order they were added, into <code class="paramref">results</code>
+and returns how many it has (which may exceed the span's length: only the first ones are written).
+
+```csharp
+int ShapesOf(BodyId body, Span<ShapeId> results)
+```
+
+#### Parameters
+
+`body` [BodyId](MicroEngine.Physics.BodyId.md)
+
+`results` [Span](https://learn.microsoft.com/dotnet/api/system.span\-1)<[ShapeId](MicroEngine.Physics.ShapeId.md)\>
+
+#### Returns
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+The body is stale.
+
+ [PhysicsCapabilityException](MicroEngine.Physics.PhysicsCapabilityException.md)
+
+The backend does not declare [ShapeInspection](MicroEngine.Physics.PhysicsCapabilities.md).
+
 ### <a id="MicroEngine_Physics_IPhysicsWorld2D_Step_System_Single_"></a> Step\(float\)
 
 Advances the world by <code class="paramref">dt</code> seconds: dynamic bodies move, and the events of this step replace the
diff --git a/docs/api/MicroEngine.Physics.PhysicsCapabilities.md b/docs/api/MicroEngine.Physics.PhysicsCapabilities.md
index 22be4f22..b753e820 100644
--- a/docs/api/MicroEngine.Physics.PhysicsCapabilities.md
+++ b/docs/api/MicroEngine.Physics.PhysicsCapabilities.md
@@ -92,6 +92,13 @@ Rotated bodies ([Rotation](MicroEngine.Physics.BodyDescription.md#MicroEngine_Ph
 
 
 
+`ShapeInspection = 4096` 
+
+Reading shapes back ([ShapesOf](MicroEngine.Physics.IPhysicsWorld2D.md#MicroEngine_Physics_IPhysicsWorld2D_ShapesOf_MicroEngine_Physics_BodyId_System_Span_MicroEngine_Physics_ShapeId__), [DescriptionOf](MicroEngine.Physics.IPhysicsWorld2D.md#MicroEngine_Physics_IPhysicsWorld2D_DescriptionOf_MicroEngine_Physics_ShapeId_)): what a
+debug view needs to draw the world. Both built-in backends declare it.
+
+
+
 `TileGeometry = 1` 
 
 Grid-aligned static geometry fed directly from tile layers (the tile backend's own <code>AddTiles</code>).
diff --git a/docs/api/MicroEngine.Physics.Tiles.TilePhysicsWorld2D.md b/docs/api/MicroEngine.Physics.Tiles.TilePhysicsWorld2D.md
index 64773cdf..e2fb8fa0 100644
--- a/docs/api/MicroEngine.Physics.Tiles.TilePhysicsWorld2D.md
+++ b/docs/api/MicroEngine.Physics.Tiles.TilePhysicsWorld2D.md
@@ -73,7 +73,7 @@ public const float ContactDistance = 0.01
 The capabilities this backend declares.
 
 ```csharp
-public const PhysicsCapabilities Declared = TileGeometry | OneWayPlatforms | MovingSolids
+public const PhysicsCapabilities Declared = TileGeometry | OneWayPlatforms | MovingSolids | ShapeInspection
 ```
 
 #### Field Value
@@ -284,6 +284,32 @@ public BodyId CreateBody(EntityId owner, in BodyDescription body)
 
  [BodyId](MicroEngine.Physics.BodyId.md)
 
+### <a id="MicroEngine_Physics_Tiles_TilePhysicsWorld2D_DescriptionOf_MicroEngine_Physics_ShapeId_"></a> DescriptionOf\(ShapeId\)
+
+The description <code class="paramref">shape</code> was added with (its geometry is relative to its body's origin).
+
+```csharp
+public ShapeDescription DescriptionOf(ShapeId shape)
+```
+
+#### Parameters
+
+`shape` [ShapeId](MicroEngine.Physics.ShapeId.md)
+
+#### Returns
+
+ [ShapeDescription](MicroEngine.Physics.ShapeDescription.md)
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+The id is stale.
+
+ [PhysicsCapabilityException](MicroEngine.Physics.PhysicsCapabilityException.md)
+
+The backend does not declare [ShapeInspection](MicroEngine.Physics.PhysicsCapabilities.md).
+
 ### <a id="MicroEngine_Physics_Tiles_TilePhysicsWorld2D_DestroyBody_MicroEngine_Physics_BodyId_"></a> DestroyBody\(BodyId\)
 
 Destroys the body and its shapes; nothing for a stale or none id. Their sensor pairs end at the next step.
@@ -296,6 +322,28 @@ public void DestroyBody(BodyId body)
 
 `body` [BodyId](MicroEngine.Physics.BodyId.md)
 
+### <a id="MicroEngine_Physics_Tiles_TilePhysicsWorld2D_GridOf_MicroEngine_Physics_ShapeId_"></a> GridOf\(ShapeId\)
+
+The tiles <code class="paramref">shape</code> stands for when it was added with [AddTiles](MicroEngine.Physics.Tiles.TilePhysicsWorld2D.md#MicroEngine_Physics_Tiles_TilePhysicsWorld2D_AddTiles_MicroEngine_Physics_BodyId_MicroEngine_World_ICollisionGrid_System_UInt64_System_UInt64_); null for any other shape.
+
+```csharp
+public ICollisionGrid? GridOf(ShapeId shape)
+```
+
+#### Parameters
+
+`shape` [ShapeId](MicroEngine.Physics.ShapeId.md)
+
+#### Returns
+
+ [ICollisionGrid](MicroEngine.World.ICollisionGrid.md)?
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+The id is stale.
+
 ### <a id="MicroEngine_Physics_Tiles_TilePhysicsWorld2D_HashState_MicroEngine_Kernel_StateHasher_"></a> HashState\(StateHasher\)
 
 Adds the world's simulation state: the step count, every live body (id, kind, position, shapes) and the sensor pairs.
@@ -534,6 +582,35 @@ public void SetVelocity(BodyId body, Vector2 velocity)
 
 Always.
 
+### <a id="MicroEngine_Physics_Tiles_TilePhysicsWorld2D_ShapesOf_MicroEngine_Physics_BodyId_System_Span_MicroEngine_Physics_ShapeId__"></a> ShapesOf\(BodyId, Span<ShapeId\>\)
+
+Writes the live shapes of <code class="paramref">body</code>, in the order they were added, into <code class="paramref">results</code>
+and returns how many it has (which may exceed the span's length: only the first ones are written).
+
+```csharp
+public int ShapesOf(BodyId body, Span<ShapeId> results)
+```
+
+#### Parameters
+
+`body` [BodyId](MicroEngine.Physics.BodyId.md)
+
+`results` [Span](https://learn.microsoft.com/dotnet/api/system.span\-1)<[ShapeId](MicroEngine.Physics.ShapeId.md)\>
+
+#### Returns
+
+ [int](https://learn.microsoft.com/dotnet/api/system.int32)
+
+#### Exceptions
+
+ [InvalidOperationException](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception)
+
+The body is stale.
+
+ [PhysicsCapabilityException](MicroEngine.Physics.PhysicsCapabilityException.md)
+
+The backend does not declare [ShapeInspection](MicroEngine.Physics.PhysicsCapabilities.md).
+
 ### <a id="MicroEngine_Physics_Tiles_TilePhysicsWorld2D_Step_System_Single_"></a> Step\(float\)
 
 Advances the world by <code class="paramref">dt</code> seconds: dynamic bodies move, and the events of this step replace the
diff --git a/docs/api/MicroEngine.Sdl.SdlAudioDevice.md b/docs/api/MicroEngine.Sdl.SdlAudioDevice.md
index 7445c9b8..89a0a103 100644
--- a/docs/api/MicroEngine.Sdl.SdlAudioDevice.md
+++ b/docs/api/MicroEngine.Sdl.SdlAudioDevice.md
@@ -76,6 +76,22 @@ Opens the default playback device, or returns a silent device (and says why) whe
 public static IAudioDevice TryCreate()
 ```
 
+#### Returns
+
+ [IAudioDevice](MicroEngine.Audio.IAudioDevice.md)
+
+### <a id="MicroEngine_Sdl_SdlAudioDevice_TryCreate_MicroEngine_Kernel_ILog_"></a> TryCreate\(ILog\)
+
+Opens the default playback device, or returns a silent device and writes why to <code class="paramref">log</code> when there is none.
+
+```csharp
+public static IAudioDevice TryCreate(ILog log)
+```
+
+#### Parameters
+
+`log` [ILog](MicroEngine.Kernel.ILog.md)
+
 #### Returns
 
  [IAudioDevice](MicroEngine.Audio.IAudioDevice.md)
diff --git a/docs/evaluations/debug-1.md b/docs/evaluations/debug-1.md
index ad5390bb..0484ce2f 100644
--- a/docs/evaluations/debug-1.md
+++ b/docs/evaluations/debug-1.md
@@ -47,8 +47,10 @@ today.
 5. **"Something is wrong and the console says nothing."** `ILog` exists, but the engine itself writes platform,
    audio and launcher messages straight to `Console.Error` (20 call sites), so a game that routes `ILog` to a file or
    an overlay misses them. **Partial.**
-6. **"The game crashed on a tester's machine."** The launcher prints `error: {message}` only: no stack trace, no file,
-   no record of the frames before it. A tester cannot send anything useful. **Fails.**
+6. **"The game crashed on a tester's machine."** The launcher prints the exception with its stack trace on standard
+   error and nothing else: no file, no versions or platform facts, no record of the frames before it. A tester who
+   double-clicked the game has no console and nothing to send. **Fails.** (Corrected after the map: the map read the
+   host-creation error line, which prints the message only; a game's run error already printed the stack.)
 7. **"Show me an FPS counter / timings while I play."** No debug drawing that update code can call (draw a line now,
    at this world position, for this frame), and no ready numbers to put on screen. The developer can build it on
    `DrawAboveScenes`, `IRenderer` and `Game.Font`, given the numbers. **Fails for the numbers; the drawing is
diff --git a/docs/guide/status.md b/docs/guide/status.md
index c84c3131..22f955f6 100644
--- a/docs/guide/status.md
+++ b/docs/guide/status.md
@@ -13,6 +13,7 @@ iOS and in web browsers. It is in Alpha: public APIs may still change between 0.
 | Tooling | The `microengine` tool: create a game from a template, run it, build it, and package it for every target ([The microengine tool](cli.md)) |
 | Distribution | Packages for players on each platform, with the game's own name, id, version and icon ([Packaging](packaging.md), [Application identity](app-identity.md)) |
 | Testing | Headless runs, scripted input and screenshot captures for automated tests of your game ([Testing](../examples/testing.md)) |
+| Diagnostics | Live frame and per-system timings, draw calls, allocations and voices, debug drawing with a physics view, input routing, crash reports and .NET metrics for `dotnet-counters` ([Diagnosing a game](../manual/diagnostics.md)) |
 | Examples | Hello Engine (the smallest complete game) and four complete demo games ([demos](/demos/)) |
 
 ## What it does not do
diff --git a/docs/manual/diagnostics.md b/docs/manual/diagnostics.md
new file mode 100644
index 00000000..3deb347c
--- /dev/null
+++ b/docs/manual/diagnostics.md
@@ -0,0 +1,172 @@
+# Diagnosing a game
+
+When a game stutters, a body falls through the floor, a jump never fires or a tester's copy crashes, the engine can
+show you what it saw. Everything on this page is off until you ask for it and costs nothing measurable while off, so
+the calls can stay in the game you ship.
+
+| Question | Where to look |
+| --- | --- |
+| Which part of the frame is slow? | `Game.Diagnostics.LastFrame` and `Game.Diagnostics.Systems` |
+| How many draw calls, allocations, voices? | `LastFrame.Graphics`, `LastFrame.Allocated`, `LastFrame.Audio` |
+| Where are the physics shapes and contacts? | `Game.DebugDraw.Physics(world)` |
+| Why did my action not fire? | `Game.InputSystem.Routed` |
+| What did the engine report? | `Game.Log` (the `ILog` service) |
+| Why did it crash on another machine? | the crash report the launcher writes |
+| Can I watch it from outside the game? | `dotnet-counters monitor --counters MicroEngine` |
+
+The [Diagnostics example](#an-overlay-in-a-few-lines) in `samples/Examples` puts all of it behind F3.
+
+## Frame measurements
+
+`Game.Diagnostics.Enabled = true` measures every frame. `LastFrame` (a `FrameStatistics`) is the last complete frame:
+while your update runs, it is the previous one.
+
+- `Events`, `Update`, `Render`, `Present` and `Total`, in milliseconds. `Update` holds the fixed steps and the
+  per-frame updates; `Present` includes waiting for the display when VSync is on.
+- `Steps`: the fixed steps the frame ran. Two or more mean the game is catching up.
+- `Allocated`: bytes the game's thread allocated during the frame. `Gen0Collections`, `Gen1Collections` and
+  `Gen2Collections` count the garbage collections during it. A steady game allocates close to nothing per frame.
+- `Graphics`: the work the frame sent to the graphics device (`DrawCalls`, `Passes`, `PipelineChanges`,
+  `TextureBindings`, `BytesUploaded`), and `LiveResources` at its end. On a backend whose device does not count, these
+  are zeros.
+- `Audio`: `ActiveVoices`, `MaxVoices` and `RefusedSounds` (sounds dropped because every voice was busy with something
+  more important). `Game.Audio.Statistics` gives the same at any time.
+
+`Game.Diagnostics.Systems` lists every system of the frame schedule with its time during the last frame: the
+engine's own (`engine.scenes`, `engine.render`...) and those your `Configure` added. Sort it to find the slow one. A
+system of a fixed phase adds up all the steps of the frame.
+
+For a whole run, `--profile FILE` records every frame to a file and prints percentiles and hitches
+([Measuring a game](lifecycle.md#measuring-a-game)). Diagnostics are the live view of the same measurements, and both
+can run together.
+
+## Debug drawing
+
+`Game.DebugDraw` draws from any code, at the end of the frame, above the scenes: `Line`, `Rect`, `Circle`, `Point`
+and `Text`. Items are in world space by default, under the camera of the scene on top (`Scene.WorldCamera`), or in
+canvas pixels with `space: DebugSpace.Screen`. An item lasts one frame; pass `seconds` to keep it longer, which helps
+with something that happens once, like a hit:
+
+```csharp
+Game.DebugDraw.Line(enemy.Position, target, Color.Red);                // this frame
+Game.DebugDraw.Circle(hit.Point, 6, Color.Yellow, seconds: 1);         // a second
+Game.DebugDraw.Text(new Vector2(4, 4), state.ToString(), Color.White, space: DebugSpace.Screen);
+```
+
+Calls do nothing until `Game.DebugDraw.Enabled` is set, and turning it off drops what is pending.
+
+### The physics view
+
+`Game.DebugDraw.Physics(world)` draws a physics world as it is now: every shape of every body in the colour of its
+kind (static, kinematic, dynamic; sensors and one-way shapes in their own colours, `DebugDraw.PhysicsColors`), the
+solid and one-way tiles inside the camera's view, and a normal for each contact that began during the latest step.
+Call it after the world moved, every update you want to see it.
+
+It reads the world through `IPhysicsWorld2D.ShapesOf(body, span)` and `DescriptionOf(shape)`, which your own code can
+use too: they return the shapes a body has and the description each was added with. Both built-in backends declare
+them (`PhysicsCapabilities.ShapeInspection`).
+
+## Where input went
+
+Input passes through layers before gameplay: the UI, the on-screen controls, a key-rebinding prompt, layers of your
+own ([Input](input.md)). When an action does not fire, the usual cause is a layer that took the press.
+`Game.InputSystem.Routed` lists the frame's events, each with the layer that took it, or `null` when it reached the
+devices and your actions. It records while `InputSystem.Trace` is on, which the diagnostics turn on while they
+measure.
+
+<!-- code: samples/Examples/Examples/DiagnosticsExample.cs#input -->
+```csharp
+/// <summary>Keeps the last few routed events: which layer took each one, or gameplay.</summary>
+private void Remember()
+{
+    foreach (var routed in Game.InputSystem.Routed)
+    {
+        if (routed.Event.Kind is not (InputEventKind.KeyDown or InputEventKind.ButtonDown or InputEventKind.PointerDown)) continue;
+        var target = routed.Layer?.GetType().Name ?? "gameplay";
+        _lastInput.Insert(0, $"{routed.Event.Kind} {routed.Event.Key} -> {target}");
+        if (_lastInput.Count > 3) _lastInput.RemoveAt(3);
+    }
+}
+```
+
+The actions themselves already answer the rest: `Input.Down`, `Pressed` and `IsConsumed` (a menu that called
+`Consume` took the action for the update).
+
+## Log messages
+
+The engine writes what it could not do through the game's log (`Game.Log`, the `ILog` service): no audio device, no
+gamepads, a renderer that did not start, an asset that loaded slowly during play. By default it goes to standard
+error. Register an `ILog` of your own in `Configure` (a `FileLog` you write, say) to send it to a file, the overlay or your telemetry; messages the
+platform wrote before the game started are replayed into it.
+
+```csharp
+public override void Configure(EngineBuilder builder) => builder.Services.Replace<ILog>(new FileLog("game.log"));
+```
+
+## Crash reports
+
+When a run fails, the desktop launcher writes a crash report to the game's save folder (on Windows
+`%LOCALAPPDATA%\MicroEngine\<game id>`) and prints its path after the error. It holds the game and engine versions,
+the system and runtime, the platform's facts (renderer, driver, display), the last measured frame and its slowest
+systems when diagnostics were on, and the error with its stack trace. Ask testers for that file. `CrashReport.Describe`
+and `CrashReport.Write` produce the same report from your own error handling.
+
+## Outside the game
+
+The engine publishes its numbers as `System.Diagnostics.Metrics` instruments of the meter `"MicroEngine"`:
+`microengine.frame.time`, `.update`, `.render`, `.present`, `.allocated`, `microengine.graphics.draw_calls` and
+`microengine.audio.voices`. Attaching a listener turns the measurements on, so you can watch a running game without
+changing it:
+
+```bash
+dotnet-counters monitor -n MyGame --counters MicroEngine,System.Runtime
+```
+
+`System.Runtime` adds the runtime's own figures: heap size, GC pauses, thread pool. The same meter feeds
+`dotnet-monitor` and OpenTelemetry exporters. For CPU profiles and allocation traces, use `dotnet-trace` or your IDE's
+profiler on a desktop build; the engine does not ship a profiler of its own.
+
+## An overlay in a few lines
+
+The Diagnostics example turns measuring and drawing on together with one action:
+
+<!-- code: samples/Examples/Examples/DiagnosticsExample.cs#toggle -->
+```csharp
+public override void Update(float dt)
+{
+    if (Input.Pressed("pause")) { Game.Scenes.Pop(); return; }
+    if (Input.Pressed("diagnostics"))
+    {
+        // Measuring and drawing are separate switches; this example turns both on and off together.
+        bool on = !Game.Diagnostics.Enabled;
+        Game.Diagnostics.Enabled = on;
+        Game.DebugDraw.Enabled = on;
+    }
+    Move(dt);
+    // Both calls do nothing while the debug drawing is off, so they can stay in the game.
+    Game.DebugDraw.Physics(_world);
+    var at = _world.PositionOf(_player);
+    Game.DebugDraw.Line(at, at + _velocity * 0.1f, Color.White);
+    Remember();
+}
+```
+
+and prints the numbers above its scene:
+
+<!-- code: samples/Examples/Examples/DiagnosticsExample.cs#overlay -->
+```csharp
+private void Overlay(IRenderer r)
+{
+    var frame = Game.Diagnostics.LastFrame;
+    var lines = new List<string>
+    {
+        string.Create(CultureInfo.InvariantCulture, $"FRAME {frame.Total:0.00} MS  UPDATE {frame.Update:0.00}  RENDER {frame.Render:0.00}"),
+        string.Create(CultureInfo.InvariantCulture, $"{frame.Graphics.DrawCalls} DRAWS  {frame.Allocated} B  GC {frame.Collections}  VOICES {frame.Audio.ActiveVoices}"),
+    };
+    foreach (var system in Game.Diagnostics.Systems.OrderByDescending(s => s.Milliseconds).Take(3))
+        lines.Add(string.Create(CultureInfo.InvariantCulture, $"  {system.Name} {system.Milliseconds:0.000}"));
+    lines.AddRange(_lastInput);
+    r.FillRect(new RectF(4, 16, 220, 8 * lines.Count + 4), Color.Black.WithAlpha(0.7f));
+    for (int i = 0; i < lines.Count; i++) Font.Draw(r, lines[i].ToUpperInvariant(), new Vector2(6, 18 + 8 * i), Color.White);
+}
+```
diff --git a/docs/manual/lifecycle.md b/docs/manual/lifecycle.md
index 3ea90f62..85f4fc42 100644
--- a/docs/manual/lifecycle.md
+++ b/docs/manual/lifecycle.md
@@ -260,7 +260,8 @@ moved from the time it stood on screen, for the last update and for a game drawi
 every frame (CSV when the file ends in `.csv`) for comparing runs; compare only runs on the same machine, platform,
 window size and scene. The engine sees when presenting returns, not when the display shows the frame: for that, use the
 system's tools (PresentMon on Windows, Perfetto on Android, Instruments on Apple systems, the browser's performance
-panel). A run without `--profile` measures nothing.
+panel). A run without `--profile` measures nothing. To read the same measurements while the game runs, per system and
+on screen, see [Diagnosing a game](diagnostics.md).
 
 ## Quitting and shutdown
 
diff --git a/odd/tasks/debug-1.md b/odd/tasks/debug-1.md
index 147ec025..79d3d16e 100644
--- a/odd/tasks/debug-1.md
+++ b/odd/tasks/debug-1.md
@@ -28,11 +28,11 @@ primitives, optional and cheap when disabled. Issue NastMz/MicroEngine#119. Bran
 | --- | --- | --- | --- | --- |
 | T1 Map the existing diagnostics surface per area | S1–S5 | delegated (mapping trigger: every subsystem, >5 lookups) | done | evaluation §1, spot check of `GraphicsDeviceBase.Counters` and `FrameSchedule` |
 | T2 Evaluation `docs/evaluations/debug-1.md` with the gap list and plan | S1–S7 | inline | done | 9 scenarios, 9 primitives |
-| T3 Owner approval of the primitives (public contract additions) | S6 | owner | pending | |
-| T4a `Game.Diagnostics`, per-system timing, engine meter, counters without casts | S3 S5 | inline | pending | |
-| T4b `DebugDraw` and physics shape inspection | S2 | inline | pending | |
-| T4c Input trace, engine messages through `ILog`, crash report | S2 S4 | inline | pending | |
-| T4d Example, guide page, release notes | S6 | inline | pending | |
+| T3 Owner approval of the primitives (public contract additions) | S6 | owner | done | L3 |
+| T4a `Game.Diagnostics`, per-system timing, engine meter, counters without casts | S3 S5 | inline | done | 03f4100; DiagnosticsTests 6/6, FrameScheduleTests +2 |
+| T4b `DebugDraw` and physics shape inspection | S2 | inline | done | 49080c4; DebugDrawTests 4/4, conformance on both backends, Box2D 103/103 |
+| T4c Input trace, engine messages through `ILog`, crash report | S2 S4 | inline | done | d409076; CrashReportTests 3/3, input trace test |
+| T4d Example, guide page, release notes | S6 | inline | done | Diagnostics example + test, `docs/manual/diagnostics.md`, API pages regenerated, site build 513 pages |
 
 ## Log
 
@@ -43,3 +43,17 @@ primitives, optional and cheap when disabled. Issue NastMz/MicroEngine#119. Bran
   messages bypass `ILog`, no live numbers or .NET metrics, counters hidden behind casts. Proposal: 9 primitives in
   four units (evaluation §4). Next: owner approval (T3).
 - L3 (2026-11-12) Owner: "Approve all nine". T4a starts.
+- L4 (2026-11-12) Units A–C committed. Deviations from the evaluation: no `--diagnostics` launcher flag (the game sets
+  `Diagnostics.Enabled`, and a meter listener turns measuring on); actions fired are already readable (`Input.Actions`,
+  `Down`, `IsConsumed`), so the input trace records only layer routing; launcher and host notes stay on the host's
+  error writer (they come before any game exists), backend messages (SDL, raylib) go through `PlatformRequest.Log`,
+  replayed into the game's `ILog` at start; the crash report holds no recent log lines, because collecting them would
+  mean wrapping the game's `ILog` service (what `Services.Get<ILog>()` returns would change).
+  Correction to L2: a failed run already printed the exception with its stack on standard error (`error: {error}`); only
+  host-creation errors print the message alone. The gap is the missing file a tester can send (evaluation §2.6 fixed).
+- L5 (2026-11-12) Full suite: every project passes except `MicroEngine.Desktop.Tests` clipboard check, which also fails
+  intermittently on `main` here (2 of 3 runs): the machine's clipboard, not this change. Snippets, `api-reference --check`,
+  site tests 71/71 and `SITE_DEMOS=none npm run build` (check-dist) pass. Headless capture of the example: overlay,
+  tile outlines (2,565 px in the static colour), one-way tops and the player's box drawn. Draw calls read 0 headless
+  (its device does not count), as documented. Not verified: SDL/raylib desktop window, browser and mobile runs of the
+  overlay; `dotnet-counters` against a live process (the meter is checked with an in-process `MeterListener`).
diff --git a/samples/Examples/Examples/DiagnosticsExample.cs b/samples/Examples/Examples/DiagnosticsExample.cs
new file mode 100644
index 00000000..11639092
--- /dev/null
+++ b/samples/Examples/Examples/DiagnosticsExample.cs
@@ -0,0 +1,144 @@
+using System.Globalization;
+using System.Numerics;
+using MicroEngine;
+using MicroEngine.Graphics;
+using MicroEngine.Input;
+using MicroEngine.Physics;
+using MicroEngine.Physics.Tiles;
+using MicroEngine.Scenes;
+using MicroEngine.World;
+
+namespace Examples;
+
+/// <summary>
+/// Diagnosing a game: F3 (or the gamepad's Back) turns on what the engine measures and draws. The overlay shows the last
+/// frame's times, draw calls, allocations and slowest systems, and where the latest input went; the physics view draws
+/// the tiles, the player's box, the sensor and the player's velocity.
+/// </summary>
+public sealed class DiagnosticsExample : Scene
+{
+    private const int Tile = 16;
+    private const float Gravity = 700, JumpSpeed = 260, RunSpeed = 90;
+
+    private static readonly string[] Rows =
+    [
+        "####################",
+        "#                  #",
+        "#                  #",
+        "#                  #",
+        "#      ====        #",
+        "#                  #",
+        "#           ###    #",
+        "#                  #",
+        "#   ##             #",
+        "#                  #",
+        "####################",
+    ];
+
+    private readonly TileGrid _grid = new(
+        TileLayer.Parse(Rows, new Dictionary<char, int> { ['#'] = 1, ['='] = 2 }),
+        Tile,
+        new Dictionary<int, TileFlags> { [1] = TileFlags.Solid, [2] = TileFlags.OneWay });
+    private readonly TilePhysicsWorld2D _world = new();
+    private readonly List<string> _lastInput = [];
+    private BodyId _player;
+    private Vector2 _velocity;
+    private MoveResult _last;
+
+    public bool Showing => Game.Diagnostics.Enabled;
+    public Vector2 PlayerPosition => _world.PositionOf(_player);
+
+    public override void Enter()
+    {
+        Input.Bind("diagnostics", [Key.F3], [PadButton.Back]);
+        var level = _world.CreateBody(default, BodyDescription.Static());
+        _world.AddTiles(level, _grid);
+        _player = _world.CreateBody(default, BodyDescription.Kinematic(new Vector2(60, 140)));
+        _world.AddShape(_player, ShapeDescription.Box(new Vector2(10, 14)));
+        var gem = _world.CreateBody(default, BodyDescription.Static(new Vector2(250, 140)));
+        _world.AddShape(gem, ShapeDescription.Sensor(new Vector2(12, 12)));
+    }
+
+    public override void Exit()
+    {
+        Input.Unbind("diagnostics");
+        Game.Diagnostics.Enabled = false;
+        Game.DebugDraw.Enabled = false;
+    }
+
+    #region toggle
+    public override void Update(float dt)
+    {
+        if (Input.Pressed("pause")) { Game.Scenes.Pop(); return; }
+        if (Input.Pressed("diagnostics"))
+        {
+            // Measuring and drawing are separate switches; this example turns both on and off together.
+            bool on = !Game.Diagnostics.Enabled;
+            Game.Diagnostics.Enabled = on;
+            Game.DebugDraw.Enabled = on;
+        }
+        Move(dt);
+        // Both calls do nothing while the debug drawing is off, so they can stay in the game.
+        Game.DebugDraw.Physics(_world);
+        var at = _world.PositionOf(_player);
+        Game.DebugDraw.Line(at, at + _velocity * 0.1f, Color.White);
+        Remember();
+    }
+    #endregion
+
+    private void Move(float dt)
+    {
+        _velocity.X = Input.Axis("left", "right") * RunSpeed;
+        _velocity.Y += Gravity * dt;
+        if (_last.OnGround && Input.Pressed("confirm")) _velocity.Y = -JumpSpeed;
+        _last = _world.Move(_player, _velocity * dt);
+        if ((_last.OnGround && _velocity.Y > 0) || (_last.HitCeiling && _velocity.Y < 0)) _velocity.Y = 0;
+        _world.Step(dt);
+    }
+
+    #region input
+    /// <summary>Keeps the last few routed events: which layer took each one, or gameplay.</summary>
+    private void Remember()
+    {
+        foreach (var routed in Game.InputSystem.Routed)
+        {
+            if (routed.Event.Kind is not (InputEventKind.KeyDown or InputEventKind.ButtonDown or InputEventKind.PointerDown)) continue;
+            var target = routed.Layer?.GetType().Name ?? "gameplay";
+            _lastInput.Insert(0, $"{routed.Event.Kind} {routed.Event.Key} -> {target}");
+            if (_lastInput.Count > 3) _lastInput.RemoveAt(3);
+        }
+    }
+    #endregion
+
+    public override void Draw(IRenderer r)
+    {
+        for (int y = 0; y < Rows.Length; y++)
+            for (int x = 0; x < Rows[y].Length; x++)
+            {
+                var flags = _grid.FlagsAt(x, y);
+                if (flags == TileFlags.Solid) r.FillRect(new RectF(x * Tile, y * Tile, Tile, Tile), Color.Hex("3b5dc9"));
+                else if (flags == TileFlags.OneWay) r.FillRect(new RectF(x * Tile, y * Tile, Tile, 4), Color.Hex("ef7d57"));
+            }
+        var at = _world.PositionOf(_player);
+        r.FillRect(new RectF(at.X - 5, at.Y - 7, 10, 14), Color.Hex("a7f070"));
+        Heading.Draw(r, Font, "DIAGNOSTICS", "F3: OVERLAY");
+        if (Showing) Overlay(r);
+    }
+
+    #region overlay
+    private void Overlay(IRenderer r)
+    {
+        var frame = Game.Diagnostics.LastFrame;
+        var lines = new List<string>
+        {
+            string.Create(CultureInfo.InvariantCulture, $"FRAME {frame.Total:0.00} MS  UPDATE {frame.Update:0.00}  RENDER {frame.Render:0.00}"),
+            string.Create(CultureInfo.InvariantCulture, $"{frame.Graphics.DrawCalls} DRAWS  {frame.Allocated} B  GC {frame.Collections}  VOICES {frame.Audio.ActiveVoices}"),
+        };
+        foreach (var system in Game.Diagnostics.Systems.OrderByDescending(s => s.Milliseconds).Take(3))
+            lines.Add(string.Create(CultureInfo.InvariantCulture, $"  {system.Name} {system.Milliseconds:0.000}"));
+        lines.AddRange(_lastInput);
+        r.FillRect(new RectF(4, 16, 220, 8 * lines.Count + 4), Color.Black.WithAlpha(0.7f));
+        for (int i = 0; i < lines.Count; i++) Font.Draw(r, lines[i].ToUpperInvariant(), new Vector2(6, 18 + 8 * i), Color.White);
+    }
+    #endregion
+}
diff --git a/samples/Examples/ExamplesGame.cs b/samples/Examples/ExamplesGame.cs
index 1cff0759..a77c67ce 100644
--- a/samples/Examples/ExamplesGame.cs
+++ b/samples/Examples/ExamplesGame.cs
@@ -33,6 +33,7 @@ public static readonly (string Name, Func<ExamplesGame, Scene> Create)[] All =
         ("Saving", g => new SaveExample(g.SaveDirectory)),
         ("Camera", g => new CameraExample()),
         ("Platformer: tiles and collision", g => new PlatformerExample()),
+        ("Diagnostics and debug drawing", g => new DiagnosticsExample()),
         ("Particles and light", g => new ParticlesExample()),
         ("Tweens and coroutines", g => new TweensExample()),
         ("Dialogue", g => new DialogueExample()),
diff --git a/site/src/lib/repo-docs.mjs b/site/src/lib/repo-docs.mjs
index dff55364..aa6e5428 100644
--- a/site/src/lib/repo-docs.mjs
+++ b/site/src/lib/repo-docs.mjs
@@ -81,6 +81,7 @@ const guidePages = [
   { source: 'docs/manual/persistence.md', slug: 'docs/manual/persistence', group: 'manual', label: 'Saving data' },
   { source: 'docs/manual/achievements.md', slug: 'docs/manual/achievements', group: 'manual', label: 'Achievements' },
   { source: 'docs/examples/testing.md', slug: 'docs/examples/testing', group: 'manual', label: 'Testing your game' },
+  { source: 'docs/manual/diagnostics.md', slug: 'docs/manual/diagnostics', group: 'manual', label: 'Diagnosing a game' },
   { source: 'docs/guide/platforms.md', slug: 'docs/platforms', group: 'platforms', label: 'Platforms' },
   { source: 'docs/guide/packaging.md', slug: 'docs/packaging', group: 'platforms', label: 'Packaging a game' },
   { source: 'docs/guide/app-identity.md', slug: 'docs/app-identity', group: 'platforms', label: 'Name, id, version and icon' },
diff --git a/tests/Samples.Tests/SampleTests.cs b/tests/Samples.Tests/SampleTests.cs
index f6968b51..e8344506 100644
--- a/tests/Samples.Tests/SampleTests.cs
+++ b/tests/Samples.Tests/SampleTests.cs
@@ -762,3 +762,30 @@ public void JumpsUpThroughAOneWayPlatformLandsOnItAndDropsBack()
         Assert.AreEqual(160, scene.Player.Bottom, "down + jump drops through it to the floor");
     }
 }
+
+[TestClass]
+public sealed class DiagnosticsExampleTests
+{
+    [TestMethod]
+    public void TheToggleTurnsOnMeasuringAndDrawingAndLeavingTheExampleTurnsThemOff()
+    {
+        var game = new ExamplesGame(Path.GetTempPath());
+        game.InitializeForTest(new HeadlessPlatform());
+        var scene = new DiagnosticsExample();
+        game.Scenes.Push(scene);
+        for (int i = 0; i < 60; i++) game.StepForTest();
+        Assert.AreEqual(153, scene.PlayerPosition.Y, 1e-3f, "the player's box rests on the floor (top 160)");
+        Assert.IsFalse(scene.Showing);
+        Assert.AreEqual(0, game.DebugDraw.Count, "nothing is queued while the debug drawing is off");
+
+        game.Input.SetForced("diagnostics", true);
+        game.StepForTest();
+        game.Input.SetForced("diagnostics", false);
+        Assert.IsTrue(game.Diagnostics.Enabled && game.DebugDraw.Enabled);
+        Assert.IsTrue(game.DebugDraw.Count > 0, "the physics view and the velocity line are queued");
+
+        game.Scenes.Pop();
+        game.StepForTest();
+        Assert.IsFalse(game.Diagnostics.Enabled || game.DebugDraw.Enabled, "leaving the example turns both off");
+    }
+}