optional preview frame

src/README.md

@@ -33,6 +33,12 @@ DeckLinkOutputThread
   consumes completed system-memory frames
   schedules them into DeckLink up to target depth
   never renders
+
+PreviewWindowThread
+  optionally owns a Win32/GDI preview window
+  copies the latest completed or scheduled system-memory frame without consuming it
+  skips preview ticks instead of waiting for the frame exchange lock
+  never calls GL, DeckLink, shader build, or render cadence code
 ```
 
 Startup builds a small output preroll reserve before DeckLink scheduled playback starts. When DeckLink input is available, startup also waits briefly for three ready input frames before the render thread starts so the first render ticks are deliberate rather than lucky.
@@ -74,6 +80,7 @@ Included now:
 - trigger parameters as latest-pulse controls with shader-visible count/time
 - startup config provider for `config/runtime-host.json`
 - quiet telemetry health monitor
+- optional preview window fed from completed system-memory frames on its own thread
 - non-GL frame-exchange tests
 - non-GL input-mailbox tests
 
@@ -87,7 +94,6 @@ Intentionally not included yet:
 - OSC control
 - persistent control/state writes
 - trigger event history for stacked repeated pulses
-- preview
 - screenshots
 - persistence
 
@@ -140,7 +146,7 @@ This tracks parity with `apps/LoopThroughWithOpenGLCompositing`.
 - [ ] Full runtime state store/read model
 - [ ] Persistent layer stack/config writes
 - [ ] OSC ingress
-- [ ] Preview output
+- [x] Preview output from a non-consuming system-memory tap
 - [ ] Screenshot capture
 - [ ] External keying support
 - [ ] Full V1 health/runtime presentation model
@@ -198,9 +204,12 @@ Currently consumed fields:
 - `outputFrameRate`
 - `autoReload`
 - `maxTemporalHistoryFrames`
+- `previewEnabled`
 - `previewFps`
 - `enableExternalKeying`
 
+When `previewEnabled` is true, the preview window runs on `PreviewWindowThread`. It paints BGRA8 system-memory frames with Win32/GDI after render readback has already completed, so it does not bind GL and does not consume frames from DeckLink output.
+
 The loaded config is treated as a read-only startup snapshot. Subsystems that need config should receive this snapshot or a narrowed config struct from app orchestration; they should not reload files independently.
 
 Supported CLI overrides: