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_portal.rs

@@ -479,20 +479,11 @@ impl StatePortal {
         if let Some(enc) = self.enc.as_mut() {
             // 将 DMA-BUF 帧零拷贝导入 VAAPI 硬件帧池
             // SAFETY: delegates to avhw::import_dma_buf_to_vaapi (itself an unsafe fn);
-            // frames_rgb pointer is a valid AVBufferRef owned by enc, and frame's
-            // fd/width/height/format/modifier/stride/offset come straight from the
-            // PipeWire-formatted PwDmaBufFrame. See that function's own SAFETY contract.
+            // frames_rgb pointer is a valid AVBufferRef owned by enc, and `frame` is the
+            // PipeWire-formatted PwDmaBufFrame whose metadata the function reads directly.
+            // See that function's own SAFETY contract.
             let mut vaapi_frame = unsafe {
-                avhw::import_dma_buf_to_vaapi(
-                    enc.frames_rgb().as_ptr(),
-                    frame.fd.as_raw_fd(),
-                    frame.width,
-                    frame.height,
-                    frame.format,
-                    frame.modifier,
-                    frame.stride,
-                    frame.offset,
-                )
+                avhw::import_dma_buf_to_vaapi(enc.frames_rgb().as_ptr(), &frame)
             }?;
 
             let import_us = t_import_start.elapsed().as_micros() as u64;
@@ -522,18 +513,9 @@ impl StatePortal {
             self.stats.record_encode(&timings);
         } else if let Some(import) = self.enc_import.as_mut() {
             // SAFETY: same contract as the enc branch above — frames_rgb owned by
-            // import, frame fields come from the PipeWire PwDmaBufFrame.
+            // import, `frame` carries the PipeWire DMA-BUF metadata.
             let mut vaapi_frame = unsafe {
-                avhw::import_dma_buf_to_vaapi(
-                    import.frames_rgb().as_ptr(),
-                    frame.fd.as_raw_fd(),
-                    frame.width,
-                    frame.height,
-                    frame.format,
-                    frame.modifier,
-                    frame.stride,
-                    frame.offset,
-                )
+                avhw::import_dma_buf_to_vaapi(import.frames_rgb().as_ptr(), &frame)
             }?;
             // SAFETY: vaapi_frame is the valid AVFrame returned above; pts is plain i64.
             unsafe {