chore: design cleanup, dead-code purge, README/doc refresh

Audit-driven follow-up after the SAFETY-debt commit (Oracle steps 6-7).
End state: cargo clippy --release --all-targets still 0 errors; private_interfaces
and type_complexity warnings cleared.

Design cleanups (Oracle step 6):
  - cap_portal.rs: introduce PortalFormatInfo struct to replace the
    Rc<Cell<Option<(u32,u32,u32,u64)>>> cross-callback hand-off. Self-
    documenting struct fields replace positional tuple access at the
    format-change and process callbacks.
  - avhw.rs: import_dma_buf_to_vaapi signature collapses from 8 args
    (fd/width/height/drm_format/modifier/stride/offset) to
    (*mut AVBufferRef, &PwDmaBufFrame). Callers in avhw.rs,
    state_portal.rs, and vaapi_import_bench.rs now pass the frame by
    reference instead of unpacking 7 fields just to repack them. Drops
    the unused width parameter and the too_many_arguments(8/7) warning.
  - state.rs: visibility hygiene. EncConstructionStage and WlrHeadInfo
    downgrade pub -> pub(crate); State.stage field downgrades to
    pub(crate). These are internal state-machine types not exposed
    across the crate boundary; making them pub(crate) clears all
    private_interfaces warnings without leaking more types.

Dead-code purge (Oracle step 7):
  - transform.rs: remove unused Rect struct, transform_basis,
    screen_to_frame, fit_inside_bounds helpers and their 18 dedicated
    tests. Transform enum and transpose_if_transform_transposed remain
    (both are actively used by state.rs and avhw.rs). File shrinks
    from 409 -> 109 lines.

Repository housekeeping (Oracle step 7):
  - .gitignore: add review.json (stray review-tool output that
    regenerates per run).
  - README.md: refresh CLI table to match src/args.rs (now lists
    --backend, --no-persist, --port-as-WebRTC-signaling, --max-bitrate,
    --stats). Add capture-backend explainer + 4 new usage examples.
    Note in README points readers at src/args.rs as the authoritative
    source. Remove stale 'WebTransport, unused in MVP' description.

avhw.rs: AsRawFd import annotated with a rustc-quirk explanation — the
import triggers a false 'unused_imports' warning but E0599 if removed.
Left as-is with explanatory comment rather than chasing the lint.

All 79 remaining unit tests + 3 integration tests still pass. Cargo
build --release clean.

README.md

@@ -38,19 +38,46 @@ wl-webrtc --output output.mp4 --drm-device /dev/dri/renderD128
 
 # Verbose mode
 wl-webrtc --output output.mp4 -v
+
+# WebRTC streaming mode (HTTP signaling server)
+wl-webrtc --port 8080 -v
+
+# Force a fresh portal authorization dialog (ignore saved restore token)
+wl-webrtc --output output.mp4 --no-persist
+
+# Pin the capture backend instead of auto-detecting
+wl-webrtc --output output.mp4 --backend portal    # or: --backend screencopy
 ```
 
 ## CLI Arguments
 
+> `src/args.rs` is the authoritative source. Run `wl-webrtc --help` for the live list.
+
 | Argument | Default | Description |
 |---|---|---|
-| `-o`, `--output` | (required) | Output file path (e.g., output.mp4) |
+| `-o`, `--output` | (optional) | Output file path (e.g. output.mp4). Optional when using `--port` for WebRTC mode. |
 | `--output-name` | auto | Wayland output name to capture |
 | `--fps` | 30 | Target frames per second |
 | `--codec` | h264 | Video codec (h264 only for MVP) |
 | `--hw-accel` | vaapi | Hardware acceleration method |
 | `--drm-device` | auto | DRM render device path |
 | `--bitrate` | auto | Target bitrate in bps |
+| `--max-bitrate` | 8000000 | Max bitrate cap for WebRTC mode (caps BWE escalation; no effect in MP4 mode) |
 | `--gop-size` | auto | Group of Pictures size |
 | `-v`, `--verbose` | false | Enable verbose logging |
-| `--port` | 0 | WebTransport server port (unused in MVP) |
+| `--backend` | auto | Capture backend: `screencopy` (wlroots) or `portal` (KWin/KDE). Auto-detected if omitted. |
+| `--port` | 0 | WebRTC HTTP signaling server port. `0` keeps MP4 file output mode. |
+| `--no-persist` | false | Force re-authorization (ignore saved portal restore token) |
+| `--stats` | false | Print per-second pipeline statistics for stutter diagnosis |
+
+## Capture backends
+
+The tool supports two Wayland capture backends, auto-detected by default:
+
+- **wlr-screencopy** (preferred when `zwlr_screencopy_manager_v1` is advertised):
+  works on wlroots-based compositors (Sway, Hyprland, etc.).
+- **XDG Portal / PipeWire** (fallback when D-Bus ScreenCast is available):
+  works on KWin/KDE and any compositor that implements the XDG Desktop Portal
+  screen-cast protocol. The first run shows an authorization dialog; a restore
+  token is cached under `wl-webrtc/portal-restore-token` so subsequent runs
+  don't re-prompt (use `--no-persist` to force a fresh authorization).