Adom Hydrogen (platform base)

@@ -12,14 +12,21 @@ description: >   choice, source selection, the cap+reason, and the "● Recording" indicator. Also   covers AUDIO-ONLY / narration capture (`adom-cli hydrogen audio` → WebM/Opus in   ~/project/audio/), AD host desktop recording (desktop_record_start, Windows-only),-  the tab-vs-desktop footgun, and what `--mic` does. Trigger words — record,+  the tab-vs-desktop footgun, and what `--mic` does. TWO ENGINES: wgc (GPU, real+  displays) and gdigrab (ffmpeg GDI — the ONLY engine that records on VMs / virtual+  / indirect displays / VNC); engine:"auto" probes and falls forward; GET+  /recording/native/capabilities reports what THIS box supports. Multi-monitor:+  screen:1..N or screen:all. Trigger words — record,   recording, screen recording, record my screen, record kicad, record a window,   record whole screen, record the workspace, record a demo, record with mic, record   no audio, mic on, mic off, voiceover, record audio, audio-only, record a narration,   record my voice, narrate, narration track, record a voice track, h264, h265, hevc,   mp4, webm, opus, codec, recordings folder, audio folder, ffmpeg, stitch clips,   max duration, recording indicator, desktop_record_start, browser_record_start,-  start recording, stop and save.+  start recording, stop and save, record on a vm, virtual display, indirect display,+  headless recording, vnc recording, 0 frames, zero frames, gdigrab, gdi capture,+  recording engine, capture engine, record all monitors, record second monitor,+  multi-monitor recording, recording capabilities, can this machine record. ---  # Hydrogen Desktop — Screen & Window Recording@@ -87,6 +94,65 @@ control API) — AD cannot do it.  --- +## ⭐ Engines: wgc vs gdigrab — and why VMs are different++HD's native recorder has **two engines**, because the machine you're on decides what can+physically capture frames:++| | `wgc` (default on real displays) | `gdigrab` |+|---|---|---|+| Backend | Windows.Graphics.Capture + DXGI, Media Foundation MFT encoder | ffmpeg GDI capture (legacy, compositor-independent) |+| GPU accelerated | yes (~60fps) | no (~15-30fps, CPU) |+| Real display (laptop/desktop) | ✅ best choice | works, lower fps |+| **VM / virtual / indirect display / VNC / headless** | ❌ **captures 0 FRAMES, silently** | ✅ **the only engine that works** |+| Sources | screen, screen:N, window:X, self | screen, screen:N, **screen:all**, window:X |+| Containers | mp4 | mp4, mkv |+| Needs | nothing | ffmpeg (auto-fetched ~40MB on first use, cached) |++**The trap this exists for (ADOMGPU, 2026-07-19):** on a box whose desktop sits on an+indirect display driver (IddCx "Virtual Display Driver", Hyper-V Video, Parsec/Sunshine,+VNC-only), WGC *and* DXGI Desktop Duplication return success but deliver **zero frames**+— and `GraphicsCaptureSession.IsSupported()` still says True, so it can't warn you.+Legacy GDI keeps working there. HD now handles this for you:++- **`engine:"auto"` (the default)** probes the display adapters; on a virtual-display box+  it goes straight to gdigrab, otherwise wgc — and if wgc still yields 0 frames in ~2s it+  **falls forward to gdigrab automatically** (`fellForward:true` in the response).+- **Fail-fast:** `/start` verifies frames are actually flowing before returning success.+  A 0-frame take errors AT START with the fix in the message — never again a 90s take+  that turns out empty at stop.+- **`GET /recording/native/capabilities`** = the ground truth for THIS box: engines ++  ffmpeg readiness, every adapter (with `virtual:true` flags), every monitor, codecs,+  containers, and `recommended.engine` with the reason. **On any unfamiliar machine (a+  VM, a cloud box, anything over VNC), read this before recording.**++### Multi-monitor++`GET /recording/native/sources` (and `/capabilities`) list every monitor with its index,+geometry and `primary` flag. You can:+- record **one** monitor: `source:"screen:1"`, `"screen:2"`, … (each row's `select` value),+- record **all** monitors at once as a single spanning video: `source:"screen:all"`+  (gdigrab engine — WGC cannot span monitors),+- or just `source:"screen"` for the primary.++```bash+BASE="$(cat ~/.adom/hd-control-url)"+# What can this box record? (do this first on a VM)+curl -s "$BASE/recording/native/capabilities"+# Record monitor 2 explicitly via gdigrab (e.g. on a VM):+curl -s -X POST -H 'Content-Type: application/json' \+  -d '{"source":"screen:2","engine":"gdigrab"}' "$BASE/recording/native/start"+# Record ALL monitors as one spanning video:+curl -s -X POST -H 'Content-Type: application/json' \+  -d '{"source":"screen:all"}' "$BASE/recording/native/start"+```++`status` and `stop` now report `engine`, `frames`, and **measured `fps`** — check them:+frames climbing + fps > 0 is a live take; the start already fail-fasts a dead one.+Note: `mic` audio is wgc-only (gdigrab records video-only for now).++---+ ## (a) HD native recording (WGC + DXGI) — the default  **Mechanism:** Rust `crates/hd-control/src/recorder.rs` — Windows.Graphics.Capture