refactor(pf-capture): structural splits + collapse the restated signal set (Phase 5)

Refactors LAST, after every defect fix, so no behaviour change hides in a move diff — and so the
newly-exposed review surface was already clean when it landed (the WP7 discipline). 28f8fc71's
recorded trap (an inline `use super::X` inside a moved body silently changing meaning) was audited
first: every `use super::` in the moved code is either at module level — where `super` still means
`linux` — or inside a `mod tests` that moved with its parent.

5.1 `mod pipewire` → `linux/pipewire.rs`. It was 1,900 of that file's lines. `mod.rs` is a directory
module, so a plain `mod pipewire;` resolves with no `#[path]`.

5.2 out of that, `linux/pw_pods.rs` (the 7 param-pod builders + `serialize_pod` + the PQ constant
and its test) and `linux/pw_cursor.rs` (`CursorState`, `decode_bitmap_pixel`, `update_cursor_meta`,
`dst_offsets`, both `composite_cursor*`). The pods are the crate's WIRE surface — a missing property
is not a compile error but a link that stalls in `negotiating`; the cursor half is producer-driven
and bounds-critical. Both are now pure enough to unit-test without a compositor, which is what
Phase 6 needs.

5.3 `linux/portal.rs`: the ScreenCast/RemoteDesktop handshake, the cursor-mode choice and GNOME's
BT.2100 probe — the async/tokio/zbus control plane, separated from the realtime half. Zero
re-exports changed: `mod.rs` re-exports `gnome_hdr_monitor_active` at its old path.

5.4 `idd_push/open.rs` (the whole one-time construction path + `SharedObjectSa` + `AttachTexFail`)
and `idd_push/compose_kick.rs`. Read `open.rs` when a session will not START and the parent when one
stops flowing; the steady state stays with the parent by decision. Also moved the ~65-line stall
REPORTING block out of `try_consume` (the hot loop) into `StallWatch::report`, taking its two
correlation counters with it — they were capturer fields nothing else touched.

5.5 `windows/dxgi/selftest.rs`: `p010_reference`, both self-tests, `hdr_p010_convert_bars_on_luid`,
`f32_to_f16` and the two test modules — the validation path, none of which runs in a session. The
two `pub` entry points are re-exported, so `main.rs`'s subcommand and pf-encode's live e2e keep
their paths. (An explicit `#[path]`, like `idd_push`'s children: this file is itself reached through
a `#[path]`, so a bare `mod` would resolve to `windows/selftest.rs`.)

5.6 `CaptureSignals`. The seven shared flags/slots were created in `spawn_pipewire`, `_cb`-cloned one
by one, passed as seven of `pipewire_thread`'s parameters, and then re-declared as fields on
`PwHandles`, `PortalCapturer` AND `UserData` — the same list written four times, each with its own
drifting copy of the doc comment. One `#[derive(Clone)]` struct instead (a refcount bump per field),
which also makes it structurally obvious that producer and consumer share ONE set. And `CaptureOpts`
for the four trailing `bool`s: four adjacent same-typed positional arguments are a
silent-transposition footgun — swap `want_444` and `want_hdr` and it compiles, negotiates the wrong
pod family, and surfaces as a black screen ten seconds later.

5.7 trait shape, targeted: `set_active(&self)` → `&mut self` (it took `&self` only because the flag
happened to be an `Arc<AtomicBool>` — an implementation detail leaking into the contract);
`capture_target_id` ⇒ `resize_output`'s pairing rule stated on both methods and in a cluster note;
one-line cluster headers over the 13 methods.

NOT done from 5.7: taking the gamescope targets as an `open_*` option instead of the trait method.
It would put a Linux-only parameter on the cross-platform `open_virtual_output` and on the host's
`capture_virtual_output` facade — a `#[cfg]`-shaped wart in two shared signatures to delete one
already-`cfg`'d defaulted method whose lifecycle rule 2.5c had already made harmless. Wrong trade
under 5.7's own "no churn for no defect fixed" principle.

File sizes: `linux/mod.rs` 2,778 → 770 (target ≤900 ✓), `windows/dxgi.rs` 1,374 → 954, and
`windows/idd_push.rs` 2,694 → 1,922. The last two miss the plan's ≤850/≤1,300 targets, which were
computed against the ORIGINAL line counts — Phases 1–4 added several hundred lines of SAFETY proofs
and defect rationale to exactly these files before the split. The moves themselves are the ones the
plan specifies; closing the rest would mean inventing new splits it does not call for.

Zero behaviour delta. pf-capture 20/20; workspace clippy --all-targets clean on Linux and on
windows-msvc.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

crates/pf-capture/src/lib.rs

@@ -26,6 +26,11 @@ use pf_frame::DmabufFrame;
 /// (drop-oldest), so a stalled consumer costs the intermediate frames and is still handed the
 /// freshest one.
 pub trait Capturer: Send {
+    // ---- Frames -----------------------------------------------------------------------------
+    // `next_frame` blocks for one; `try_latest` is the steady-state non-blocking read;
+    // `wait_arrival` + `supports_arrival_wait` are the frame-driven trigger that replaces a
+    // free-running tick.
+
     fn next_frame(&mut self) -> Result<CapturedFrame>;
 
     /// [`next_frame`](Self::next_frame) with a caller-chosen first-frame budget instead of the
@@ -63,11 +68,18 @@ pub trait Capturer: Send {
     /// following `try_latest`.
     fn wait_arrival(&mut self, _deadline: std::time::Instant) {}
 
+    // ---- Lifecycle --------------------------------------------------------------------------
+    // Whether the capturer is being used right now, and whether it can still be used at all.
+
     /// Gate expensive per-frame work so the capturer can be kept alive (reused) between
-    /// streams without burning CPU. The portal capturer skips the de-pad copy while inactive;
-    /// the default is a no-op (synthetic sources are produced on demand). Set `true` for the
-    /// duration of a stream, `false` when it ends.
-    fn set_active(&self, _active: bool) {}
+    /// streams without burning CPU. The portal capturer skips the de-pad copy while inactive and
+    /// flushes its frame mailbox on `false`; the default is a no-op (synthetic sources are produced
+    /// on demand). Set `true` for the duration of a stream, `false` when it ends.
+    ///
+    /// `&mut self`: it mutates capturer state, and every caller owns the capturer. It took `&self`
+    /// only because the flag happened to be an `Arc<AtomicBool>` — an implementation detail leaking
+    /// into the contract, and one the mailbox flush this now also does would not have shared.
+    fn set_active(&mut self, _active: bool) {}
 
     /// Whether this capturer can still produce frames — the gate a caller that POOLS capturers
     /// across streams must consult before reusing one.
@@ -87,6 +99,9 @@ pub trait Capturer: Send {
         true
     }
 
+    // ---- Cursor -----------------------------------------------------------------------------
+    // The out-of-band pointer: where it is, who draws it, and (Linux/gamescope) where to read it.
+
     /// The capture source's LIVE cursor state, when it arrives out-of-band from the frames
     /// (the Windows IddCx hardware-cursor channel). Polled by the encode loop every tick and
     /// preferred over `CapturedFrame::cursor` — with a hardware cursor, pointer-only moves
@@ -116,6 +131,8 @@ pub trait Capturer: Send {
     #[cfg(target_os = "linux")]
     fn attach_gamescope_cursor(&mut self, _targets: GamescopeCursorTargets) {}
 
+    // ---- Stream properties ------------------------------------------------------------------
+
     /// The source's static HDR mastering metadata (SMPTE ST.2086 + content light level), when the
     /// capturer can read it from the output (Windows `IDXGIOutput6::GetDesc1`). `None` = unknown /
     /// SDR / a backend that doesn't expose it (the default — Linux capture has no HDR path yet).
@@ -135,10 +152,18 @@ pub trait Capturer: Send {
         1
     }
 
+    // ---- Host-initiated resize --------------------------------------------------------------
+    // These two are ONE operation split in half and must be implemented together: a backend that
+    // returns `Some` from `capture_target_id` is promising `resize_output` works, and one that
+    // implements `resize_output` without the identity leaves the caller no way to check that the
+    // display it just reconfigured is still this capturer's. Both defaults decline.
+
     /// The OS display-target id this capturer is bound to (Windows IDD-push), so the resize path
     /// can verify the display it just reconfigured is STILL the one this capturer serves (an
     /// in-place resize keeps the target; a re-arrival fallback mints a new one, which needs a
     /// fresh capturer). `None` = the backend has no such identity (every non-IDD backend).
+    ///
+    /// PAIRED with [`resize_output`](Self::resize_output) — see the cluster note above.
     fn capture_target_id(&self) -> Option<u32> {
         None
     }
@@ -149,6 +174,8 @@ pub trait Capturer: Send {
     /// EXTERNAL changes only) and no teardown: the capture pipeline and its send thread survive;
     /// only the encoder is swapped by the caller once the first new-size frame arrives. Returns
     /// `true` when handled; `false` (the default) routes the caller to the full-rebuild path.
+    ///
+    /// PAIRED with [`capture_target_id`](Self::capture_target_id) — see the cluster note above.
     fn resize_output(&mut self, _width: u32, _height: u32) -> bool {
         false
     }