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.

src/state.rs

@@ -98,7 +98,9 @@ pub struct PartialOutputInfo {
 
 
 /// Stores head info from wlr-output-management for name-based matching with wl_output.
-struct WlrHeadInfo {
+// `pub(crate)` (not module-private): exposed via `EncConstructionStage::ProbingOutputs.wlr_heads`
+// which is reached from main.rs during the wlr-screencopy probing loop.
+pub(crate) struct WlrHeadInfo {
     position: Option<(i32, i32)>,
 }
 
@@ -144,8 +146,14 @@ impl StreamingEncoder {
 // ---------------------------------------------------------------------------
 // EncConstructionStage
 // ---------------------------------------------------------------------------
+//
+// `pub(crate)` (not `pub`): this enum leaks the private `WlrHeadInfo` type via
+// its `wlr_heads` field, and the construction-stage state machine is an
+// internal implementation detail. Crate-internal consumers (main.rs) get there
+// via `crate::state::`; there is no need to expose this across the crate
+// boundary. See Oracle audit 2026-06-28.
 
-pub enum EncConstructionStage<S: CaptureSource> {
+pub(crate) enum EncConstructionStage<S: CaptureSource> {
     ProbingOutputs {
         outputs: Vec<PartialOutputInfo>,
         bound_outputs: Vec<WlOutput>,
@@ -199,7 +207,7 @@ pub enum InFlightSurface<S: CaptureSource> {
 // ---------------------------------------------------------------------------
 
 pub struct State<S: CaptureSource> {
-    pub stage: EncConstructionStage<S>,
+    pub(crate) stage: EncConstructionStage<S>,
     pub in_flight_surface: InFlightSurface<S>,
     pub starting_timestamp: Option<i64>,
     pub stats_start_time: Option<Instant>,