docs(agents): update module paths after directory-form refactor

Update the 'Runtime architecture' section to reflect that state.rs /
cap_portal.rs / state_portal.rs / webrtc.rs are now parent modules of
directory trees:

- src/state.rs -> src/state/mod.rs (+ src/state/dispatch/ for the 13
  Wayland Dispatch impls)
- src/state_portal.rs still exists; helpers split into
  src/state_portal/{bitrate,threads}.rs
- src/cap_portal.rs holds the struct; setup/token_fs/pipewire_thread
  split into src/cap_portal/
- src/webrtc.rs gains src/webrtc/html_page.rs sibling

No content changes beyond the path references; the rest of AGENTS.md
remains accurate.

AGENTS.md

@@ -24,8 +24,8 @@
 - `src/main.rs` is the real entrypoint: parse `Args`, initialize tracing from `RUST_LOG` or `-v`, reject non-H.264, require `--output` or `--port`, detect backend, then run one of two loops.
 - Backend detection in `src/backend_detect.rs`: explicit `--backend portal|screencopy` wins; otherwise wlr-screencopy is preferred when the Wayland global `zwlr_screencopy_manager_v1` exists, else Portal/PipeWire is used if D-Bus ScreenCast is available.
 - Do not use `ashpd` for backend availability checks; `backend_detect.rs` intentionally uses raw `zbus` because `ashpd` caches a `zbus::Connection` in a global and can hang after its owning Tokio runtime is dropped.
-- `src/state.rs` drives the wlroots path using a mio Wayland fd loop and `State<CapWlrScreencopy>`; `src/state_portal.rs` drives the Portal/PipeWire path through `CapPortal` frame channels.
-- `src/webrtc.rs` is a small embedded HTTP/WebRTC signaling server using `str0m`; `--port 0` means file-output mode, `--port > 0` enables WebRTC mode.
+- `src/state/mod.rs` drives the wlroots path using a mio Wayland fd loop and `State<CapWlrScreencopy>` (Wayland `Dispatch` impls live under `src/state/dispatch/`); `src/state_portal.rs` drives the Portal/PipeWire path through `CapPortal` frame channels (bitrate helpers and encode/webrtc thread loops are split into `src/state_portal/{bitrate,threads}.rs`). `src/cap_portal.rs` holds the `CapPortal` struct itself; its setup logic, token filesystem helpers, and PipeWire capture thread live under `src/cap_portal/`.
+- `src/webrtc.rs` is a small embedded HTTP/WebRTC signaling server using `str0m`; the embedded HTML test page is in `src/webrtc/html_page.rs`. `--port 0` means file-output mode, `--port > 0` enables WebRTC mode.
 
 ## Unsafe and FFI work
 

src/avhw/mod.rs

@@ -63,6 +63,8 @@ pub use types::{
     BitrateCommand, CpuNv12Frame, EncodeOutcome, EncodeStages, EncodedH264Frame, ResolutionChange,
     SwEncodeTiming,
 };
+#[allow(unused_imports)]
+pub use util::av_err_to_string;
 pub(crate) use util::ff_err;
 
 // ---------------------------------------------------------------------------

src/avhw/util.rs

@@ -1,7 +1,7 @@
 use ffmpeg_next::ffi;
 
 /// Convert an FFmpeg error code to a human-readable string.
-pub(crate) fn av_err_to_string(err: i32) -> String {
+pub fn av_err_to_string(err: i32) -> String {
     let mut buf = vec![0u8; 128];
     // SAFETY: buf points to 128 writable bytes and lives for the duration of
     // av_strerror.

src/backend_detect.rs

@@ -113,25 +113,23 @@ fn check_portal_available() -> bool {
 
         // The most likely operation to hang — requires actual Portal-side work.
         // 最可能卡住的操作，需要 Portal 端实际处理。
-        let version = match tokio::time::timeout(
-            PORTAL_DBUS_TIMEOUT,
-            inner.get_property::<u32>("version"),
-        )
-        .await
-        {
-            Ok(Ok(version)) => {
-                tracing::info!("Portal ScreenCast available (version: {version})");
-                true
-            }
-            Ok(Err(e)) => {
-                tracing::info!("Portal ScreenCast version query failed: {e}");
-                false
-            }
-            Err(_) => {
-                log_portal_unresponsive("querying ScreenCast version");
-                false
-            }
-        };
+        let version =
+            match tokio::time::timeout(PORTAL_DBUS_TIMEOUT, inner.get_property::<u32>("version"))
+                .await
+            {
+                Ok(Ok(version)) => {
+                    tracing::info!("Portal ScreenCast available (version: {version})");
+                    true
+                }
+                Ok(Err(e)) => {
+                    tracing::info!("Portal ScreenCast version query failed: {e}");
+                    false
+                }
+                Err(_) => {
+                    log_portal_unresponsive("querying ScreenCast version");
+                    false
+                }
+            };
         version
     })
 }

src/bin/common/mod.rs

@@ -0,0 +1,76 @@
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+use ffmpeg_next::packet::Mut;
+use wl_webrtc::cap_portal::{CapPortal, PwCtrlEvent};
+
+pub fn receive_first_frame(cap: &CapPortal) -> Result<wl_webrtc::cap_portal::PwDmaBufFrame> {
+    // Drain-and-wait loop that mirrors production's repeated-poll semantics
+    // (state_portal.rs::poll_and_encode driven by main.rs's outer loop), but with
+    // a single bounded 10s total deadline appropriate for a bench tool. Unlike a
+    // single 10s blocking wait, this loop actually iterates: each turn drains ALL
+    // pending control events (the ctrl channel is bounded to 8 — a single
+    // if-let would silently miss backlog) and then waits a short slice for a
+    // frame, so StreamEnded/Error arriving mid-wait are observed within ~200ms.
+    const TOTAL_DEADLINE: std::time::Duration = std::time::Duration::from_secs(10);
+    const WAIT_SLICE: std::time::Duration = std::time::Duration::from_millis(200);
+    let deadline = Instant::now() + TOTAL_DEADLINE;
+    loop {
+        while let Ok(ctrl) = cap.event_receiver().try_recv() {
+            match ctrl {
+                PwCtrlEvent::StreamEnded => bail!("PipeWire stream ended before first frame"),
+                PwCtrlEvent::FormatChanged { .. } => {}
+                PwCtrlEvent::Error(e) => bail!("PipeWire error: {e}"),
+            }
+        }
+        let remaining = match deadline.checked_duration_since(Instant::now()) {
+            Some(r) if !r.is_zero() => r,
+            _ => bail!("Timeout waiting for first frame (10s)"),
+        };
+        let slice = remaining.min(WAIT_SLICE);
+        match cap.frame_receiver().recv_timeout(slice) {
+            Ok(frame) => return Ok(frame),
+            Err(crossbeam_channel::RecvTimeoutError::Timeout) => continue,
+            Err(crossbeam_channel::RecvTimeoutError::Disconnected) => {
+                bail!("PipeWire frame channel disconnected");
+            }
+        }
+    }
+}
+
+pub fn drain_encoder(
+    enc_video: &mut ff::encoder::video::Video,
+    octx: &mut ff::format::context::Output,
+) -> Result<()> {
+    loop {
+        let mut pkt = ff::Packet::empty();
+        // SAFETY: enc_video is the opened encoder; pkt is an empty Packet whose
+        // inner AVPacket pointer is valid. avcodec_receive_packet fills pkt with
+        // the next encoded packet, or returns EAGAIN/EOF when drained.
+        let ret = unsafe { ffi::avcodec_receive_packet(enc_video.as_mut_ptr(), pkt.as_mut_ptr()) };
+        if ret < 0 {
+            if ret == ffi::AVERROR(ffi::EAGAIN) || ret == ffi::AVERROR_EOF {
+                break;
+            }
+            eprintln!("avcodec_receive_packet failed: {ret}");
+            break;
+        }
+
+        let enc_tb = enc_video.time_base();
+        // SAFETY: octx.as_ptr() is a valid AVFormatContext; streams is a NULL-terminated
+        // array of AVStream*. We index [0] which exists because we created exactly one
+        // stream in setup. Reading time_base is a plain AVRational field access.
+        let stream_tb = unsafe {
+            let streams = (*octx.as_ptr()).streams;
+            let st = *streams.add(0);
+            ff::Rational::from((*st).time_base)
+        };
+        pkt.rescale_ts(enc_tb, stream_tb);
+        pkt.set_stream(0);
+        pkt.write_interleaved(octx)
+            .map_err(|e| anyhow::anyhow!("write packet failed: {e}"))?;
+    }
+    Ok(())
+}

src/bin/sw_encode_bench/main.rs

@@ -15,85 +15,16 @@ use clap::Parser;
 
 use ffmpeg_next as ff;
 use ffmpeg_next::ffi;
-use ffmpeg_next::packet::Mut;
 
 use wl_webrtc::args::Args;
 use wl_webrtc::cap_portal::{CapPortal, PwCtrlEvent};
 
-#[derive(Parser, Debug)]
-#[command(
-    name = "sw_encode_bench",
-    about = "Software encoding pipeline benchmark"
-)]
-struct BenchArgs {
-    #[arg(short, long)]
-    output: String,
+#[path = "../common/mod.rs"]
+mod common;
 
-    #[arg(long, default_value_t = 120)]
-    frames: u32,
+mod stats;
 
-    #[arg(long, default_value_t = 2560)]
-    enc_width: u32,
-
-    #[arg(long, default_value_t = 1440)]
-    enc_height: u32,
-}
-
-#[derive(Default)]
-struct FrameStats {
-    mmap_us: Vec<u64>,
-    scale_us: Vec<u64>,
-    encode_us: Vec<u64>,
-    total_us: Vec<u64>,
-    mmap_failures: u32,
-}
-
-impl FrameStats {
-    fn avg_ms(data: &[u64]) -> f64 {
-        if data.is_empty() {
-            return 0.0;
-        }
-        data.iter().sum::<u64>() as f64 / data.len() as f64 / 1000.0
-    }
-}
-
-fn pix_fmt(p: ff::format::Pixel) -> ffi::AVPixelFormat {
-    Into::<ffi::AVPixelFormat>::into(p)
-}
-
-fn receive_first_frame(cap: &CapPortal) -> Result<wl_webrtc::cap_portal::PwDmaBufFrame> {
-    // Drain-and-wait loop that mirrors production's repeated-poll semantics
-    // (state_portal.rs::poll_and_encode driven by main.rs's outer loop), but with
-    // a single bounded 10s total deadline appropriate for a bench tool. Unlike a
-    // single 10s blocking wait, this loop actually iterates: each turn drains ALL
-    // pending control events (the ctrl channel is bounded to 8 — a single
-    // if-let would silently miss backlog) and then waits a short slice for a
-    // frame, so StreamEnded/Error arriving mid-wait are observed within ~200ms.
-    const TOTAL_DEADLINE: std::time::Duration = std::time::Duration::from_secs(10);
-    const WAIT_SLICE: std::time::Duration = std::time::Duration::from_millis(200);
-    let deadline = Instant::now() + TOTAL_DEADLINE;
-    loop {
-        while let Ok(ctrl) = cap.event_receiver().try_recv() {
-            match ctrl {
-                PwCtrlEvent::StreamEnded => bail!("PipeWire stream ended before first frame"),
-                PwCtrlEvent::FormatChanged { .. } => {}
-                PwCtrlEvent::Error(e) => bail!("PipeWire error: {e}"),
-            }
-        }
-        let remaining = match deadline.checked_duration_since(Instant::now()) {
-            Some(r) if !r.is_zero() => r,
-            _ => bail!("Timeout waiting for first frame (10s)"),
-        };
-        let slice = remaining.min(WAIT_SLICE);
-        match cap.frame_receiver().recv_timeout(slice) {
-            Ok(frame) => return Ok(frame),
-            Err(crossbeam_channel::RecvTimeoutError::Timeout) => continue,
-            Err(crossbeam_channel::RecvTimeoutError::Disconnected) => {
-                bail!("PipeWire frame channel disconnected");
-            }
-        }
-    }
-}
+use stats::{pix_fmt, BenchArgs, FrameStats};
 
 fn main() -> Result<()> {
     let bench_args = BenchArgs::parse();
@@ -133,7 +64,7 @@ fn main() -> Result<()> {
     println!("[1/4] Portal connected, PipeWire stream active\n");
 
     println!("[2/4] Waiting for first frame from PipeWire...");
-    let first_frame = receive_first_frame(&cap)?;
+    let first_frame = common::receive_first_frame(&cap)?;
 
     let src_width = first_frame.width;
     let src_height = first_frame.height;
@@ -462,7 +393,7 @@ fn main() -> Result<()> {
             }
         }
 
-        drain_encoder(&mut enc_video, &mut octx)?;
+        common::drain_encoder(&mut enc_video, &mut octx)?;
 
         stats
             .encode_us
@@ -489,7 +420,7 @@ fn main() -> Result<()> {
     unsafe {
         ffi::avcodec_send_frame(enc_video.as_mut_ptr(), ptr::null());
     }
-    drain_encoder(&mut enc_video, &mut octx)?;
+    common::drain_encoder(&mut enc_video, &mut octx)?;
 
     octx.write_trailer()
         .map_err(|e| anyhow::anyhow!("Failed to write trailer: {e}"))?;
@@ -577,38 +508,3 @@ fn main() -> Result<()> {
     println!("Output written to: {}", bench_args.output);
     Ok(())
 }
-
-fn drain_encoder(
-    enc_video: &mut ff::encoder::video::Video,
-    octx: &mut ff::format::context::Output,
-) -> Result<()> {
-    loop {
-        let mut pkt = ff::Packet::empty();
-        // SAFETY: enc_video is the opened encoder; pkt is an empty Packet whose
-        // inner AVPacket pointer is valid. avcodec_receive_packet fills pkt with
-        // the next encoded packet, or returns EAGAIN/EOF when drained.
-        let ret = unsafe { ffi::avcodec_receive_packet(enc_video.as_mut_ptr(), pkt.as_mut_ptr()) };
-        if ret < 0 {
-            if ret == ffi::AVERROR(ffi::EAGAIN) || ret == ffi::AVERROR_EOF {
-                break;
-            }
-            eprintln!("avcodec_receive_packet failed: {ret}");
-            break;
-        }
-
-        let enc_tb = enc_video.time_base();
-        // SAFETY: octx.as_ptr() is a valid AVFormatContext; streams is a NULL-terminated
-        // array of AVStream*. We index [0] which exists because we created exactly one
-        // stream in setup. Reading time_base is a plain AVRational field access.
-        let stream_tb = unsafe {
-            let streams = (*octx.as_ptr()).streams;
-            let st = *streams.add(0);
-            ff::Rational::from((*st).time_base)
-        };
-        pkt.rescale_ts(enc_tb, stream_tb);
-        pkt.set_stream(0);
-        pkt.write_interleaved(octx)
-            .map_err(|e| anyhow::anyhow!("write packet failed: {e}"))?;
-    }
-    Ok(())
-}

src/bin/sw_encode_bench/stats.rs

@@ -0,0 +1,45 @@
+use clap::Parser;
+
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "sw_encode_bench",
+    about = "Software encoding pipeline benchmark"
+)]
+pub(crate) struct BenchArgs {
+    #[arg(short, long)]
+    pub(crate) output: String,
+
+    #[arg(long, default_value_t = 120)]
+    pub(crate) frames: u32,
+
+    #[arg(long, default_value_t = 2560)]
+    pub(crate) enc_width: u32,
+
+    #[arg(long, default_value_t = 1440)]
+    pub(crate) enc_height: u32,
+}
+
+#[derive(Default)]
+pub(crate) struct FrameStats {
+    pub(crate) mmap_us: Vec<u64>,
+    pub(crate) scale_us: Vec<u64>,
+    pub(crate) encode_us: Vec<u64>,
+    pub(crate) total_us: Vec<u64>,
+    pub(crate) mmap_failures: u32,
+}
+
+impl FrameStats {
+    pub(crate) fn avg_ms(data: &[u64]) -> f64 {
+        if data.is_empty() {
+            return 0.0;
+        }
+        data.iter().sum::<u64>() as f64 / data.len() as f64 / 1000.0
+    }
+}
+
+pub(crate) fn pix_fmt(p: ff::format::Pixel) -> ffi::AVPixelFormat {
+    Into::<ffi::AVPixelFormat>::into(p)
+}

src/bin/vaapi_import_bench/main.rs

@@ -0,0 +1,218 @@
+// vaapi_import_bench.rs — VAAPI DMA-BUF import + GPU-side downscale benchmark
+//
+// Tests: Portal capture -> av_hwframe_map (ARGB sw_format) -> transfer -> sw encode
+//
+// Usage: cargo run --bin vaapi_import_bench -- --output /tmp/vaapi_bench.mp4
+
+use std::os::fd::AsRawFd;
+use std::path::Path;
+use std::ptr;
+use std::time::Instant;
+
+use anyhow::Result;
+use clap::Parser;
+
+use ffmpeg_next as ff;
+
+use wl_webrtc::args::Args;
+use wl_webrtc::avhw::{import_dma_buf_to_vaapi, AvHwDevCtx, AvHwFrameCtx};
+use wl_webrtc::cap_portal::CapPortal;
+
+#[path = "../common/mod.rs"]
+mod common;
+
+mod pipeline_cpu;
+mod pipeline_gpu;
+mod software;
+mod stats;
+mod util;
+
+use pipeline_cpu::run_cpu_pipeline;
+use pipeline_gpu::run_gpu_pipeline;
+use stats::{BenchArgs, PipelineMode};
+use util::{output_for_mode, print_comparison, print_detailed_results};
+
+fn main() -> Result<()> {
+    let bench_args = BenchArgs::parse();
+
+    println!("=== VAAPI Import Benchmark ===");
+    println!("Output: {}", bench_args.output);
+    println!("Target frames: {}", bench_args.frames);
+    println!(
+        "Encode resolution: {}x{}",
+        bench_args.enc_width, bench_args.enc_height
+    );
+    println!("DRM device: {}", bench_args.drm_device);
+    println!();
+
+    ff::init()?;
+
+    println!("[1/3] Requesting screen capture via XDG Portal...");
+    println!("       (Select a screen to share in the portal dialog)");
+
+    let portal_args = Args {
+        output: Some(bench_args.output.clone()),
+        output_name: None,
+        fps: 60,
+        codec: "h264".to_string(),
+        hw_accel: "vaapi".to_string(),
+        drm_device: None,
+        bitrate: None,
+        max_bitrate: 8_000_000,
+        gop_size: None,
+        verbose: false,
+        backend: Some("portal".to_string()),
+        port: 0,
+        no_persist: false,
+        stats: false,
+    };
+
+    let cap = CapPortal::new(&portal_args)?;
+    println!("[1/3] Portal connected, PipeWire stream active\n");
+
+    println!("[2/3] Waiting for first frame from PipeWire...");
+    let first_frame = common::receive_first_frame(&cap)?;
+
+    let src_width = first_frame.width;
+    let src_height = first_frame.height;
+    let src_format = first_frame.format;
+
+    println!(
+        "[2/3] First frame: {}x{}, format=0x{:08X}, stride={}, modifier=0x{:X}",
+        src_width, src_height, src_format, first_frame.stride, first_frame.modifier
+    );
+
+    println!("\n[2/3] Testing av_hwframe_map with sw_format=BGRA...");
+    println!(
+        "       DRM format chain: PipeWire BGRA -> DRM_FORMAT_ARGB8888 (0x{:08X}) -> VA_FOURCC_BGRA -> AV_PIX_FMT_BGRA",
+        src_format
+    );
+
+    let drm_device = Path::new(&bench_args.drm_device);
+    let hw_dev = AvHwDevCtx::new_vaapi(drm_device)?;
+    println!("       VAAPI device context created OK");
+
+    let frames_ctx =
+        AvHwFrameCtx::for_capture(&hw_dev, src_width, src_height, ff::format::Pixel::BGRA)?;
+    println!("       VAAPI frames context created OK (sw_format=BGRA)");
+
+    // SAFETY: delegates to avhw::import_dma_buf_to_vaapi (itself an unsafe fn).
+    // frames_ctx is a valid AVBufferRef from AvHwFrameCtx::for_capture above;
+    // `first_frame` is the PipeWire-formatted PwDmaBufFrame whose metadata the
+    // function reads directly. See that function's own SAFETY contract for the
+    // full rationale.
+    let vaapi_frame = unsafe { import_dma_buf_to_vaapi(frames_ctx.as_ptr(), &first_frame) };
+
+    match &vaapi_frame {
+        Ok(_) => {
+            println!("       Result: SUCCESS — av_hwframe_map imported DMA-BUF to VAAPI surface!");
+        }
+        Err(e) => {
+            println!("       Result: FAILED");
+            println!("       Error: {e}");
+            println!();
+            println!("       Possible causes:");
+            println!("       - sw_format mismatch (current: BGRA)");
+            println!("       - DRM format modifier not supported by VAAPI");
+            println!("       - VAAPI driver doesn't support DMA-BUF import for this format");
+            println!();
+            println!("       Falling back to mmap readback test for comparison...");
+
+            let mmap_size = (first_frame.stride as usize) * (first_frame.height as usize);
+            let mmap_start = Instant::now();
+            // SAFETY: first_frame.fd is an open DMA-BUF; offset/size from PipeWire.
+            // PROT_READ+MAP_SHARED is the standard read-only DMA-BUF mapping. Returns
+            // MAP_FAILED on error (checked below).
+            let mmap_ptr = unsafe {
+                libc::mmap(
+                    ptr::null_mut(),
+                    mmap_size,
+                    libc::PROT_READ,
+                    libc::MAP_SHARED,
+                    first_frame.fd.as_raw_fd(),
+                    first_frame.offset as i64,
+                )
+            };
+            let mmap_elapsed = mmap_start.elapsed();
+
+            if mmap_ptr == libc::MAP_FAILED {
+                let errno = std::io::Error::last_os_error();
+                println!("       mmap also FAILED: {errno}");
+            } else {
+                println!(
+                    "       mmap SUCCESS: {:.1} MB, setup in {:.2}ms",
+                    mmap_size as f64 / 1024.0 / 1024.0,
+                    mmap_elapsed.as_secs_f64() * 1000.0
+                );
+                // SAFETY: mmap_ptr is a valid mapping (MAP_FAILED path was handled
+                // above); mmap_size matches the original mapping. POSIX munmap(2).
+                unsafe {
+                    libc::munmap(mmap_ptr, mmap_size);
+                }
+            }
+
+            println!();
+            println!("=== Benchmark ended: av_hwframe_map import FAILED ===");
+            println!("Fix the import issue before proceeding to GPU downscale tests.");
+            return Ok(());
+        }
+    }
+
+    drop(vaapi_frame);
+    drop(first_frame);
+
+    println!("\n[3/3] Benchmarking selected pipeline(s)...");
+
+    let enc_width = bench_args.enc_width;
+    let enc_height = bench_args.enc_height;
+    let split_outputs = bench_args.mode == PipelineMode::Both;
+    let mut cpu_stats = None;
+    let mut gpu_stats = None;
+
+    if matches!(bench_args.mode, PipelineMode::Cpu | PipelineMode::Both) {
+        let output = output_for_mode(&bench_args.output, PipelineMode::Cpu, split_outputs);
+        cpu_stats = Some(run_cpu_pipeline(
+            &cap,
+            &frames_ctx,
+            &output,
+            bench_args.frames,
+            src_width,
+            src_height,
+            enc_width,
+            enc_height,
+        )?);
+    }
+
+    if matches!(bench_args.mode, PipelineMode::Gpu | PipelineMode::Both) {
+        let output = output_for_mode(&bench_args.output, PipelineMode::Gpu, split_outputs);
+        gpu_stats = Some(run_gpu_pipeline(
+            &cap,
+            &hw_dev,
+            &frames_ctx,
+            &output,
+            bench_args.frames,
+            src_width,
+            src_height,
+            enc_width,
+            enc_height,
+        )?);
+    }
+
+    if let Some(stats) = cpu_stats.as_ref() {
+        print_detailed_results("CPU", stats, src_width, src_height, enc_width, enc_height);
+    }
+    if let Some(stats) = gpu_stats.as_ref() {
+        print_detailed_results("GPU", stats, src_width, src_height, enc_width, enc_height);
+    }
+    print_comparison(cpu_stats.as_ref(), gpu_stats.as_ref());
+
+    if cpu_stats
+        .as_ref()
+        .into_iter()
+        .chain(gpu_stats.as_ref())
+        .any(|stats| stats.achieved_fps() < 30.0 && stats.frames_encoded > 0)
+    {
+        println!("NOTE: At least one achieved FPS result is below 30 FPS target.");
+    }
+    Ok(())
+}

src/bin/vaapi_import_bench/pipeline_cpu.rs

@@ -0,0 +1,152 @@
+use std::path::Path;
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+
+use ffmpeg_next::ffi;
+
+use wl_webrtc::avhw::{av_err_to_string, AvHwFrameCtx};
+use wl_webrtc::cap_portal::{CapPortal, PwCtrlEvent};
+
+use crate::pipeline_gpu::import_frame;
+use crate::software::{
+    create_software_encoder, create_sws_context, encode_yuv_frame, finish_encoder,
+};
+use crate::stats::FrameStats;
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn run_cpu_pipeline(
+    cap: &CapPortal,
+    frames_ctx: &AvHwFrameCtx,
+    output: &str,
+    frames: u32,
+    src_width: u32,
+    src_height: u32,
+    enc_width: u32,
+    enc_height: u32,
+) -> Result<FrameStats> {
+    let mut encoder = create_software_encoder(Path::new(output), enc_width, enc_height)?;
+    let sws_ctx = create_sws_context(
+        src_width,
+        src_height,
+        ffi::AVPixelFormat::AV_PIX_FMT_BGRA,
+        enc_width,
+        enc_height,
+    )?;
+
+    println!(
+        "       Encoder: {}, {}x{} YUV420P",
+        encoder.codec_name, enc_width, enc_height
+    );
+    println!("       Output: {output}");
+    println!("       CPU Pipeline: DMA-BUF 4K BGRA -> av_hwframe_map -> av_hwframe_transfer_data -> sws_scale -> YUV420P 2K -> encode\n");
+
+    let mut stats = FrameStats {
+        codec_name: encoder.codec_name.clone(),
+        output_path: output.to_string(),
+        ..FrameStats::default()
+    };
+    let total_start = Instant::now();
+    let mut pts: i64 = 0;
+
+    while stats.frames_encoded < frames {
+        if let Ok(ctrl) = cap.event_receiver().try_recv() {
+            match ctrl {
+                PwCtrlEvent::StreamEnded => break,
+                PwCtrlEvent::Error(e) => bail!(
+                    "PipeWire error after {} CPU frames: {e}",
+                    stats.frames_encoded
+                ),
+                PwCtrlEvent::FormatChanged { .. } => {}
+            }
+        }
+
+        let frame = match cap
+            .frame_receiver()
+            .recv_timeout(std::time::Duration::from_secs(5))
+        {
+            Ok(f) => f,
+            Err(_) => break,
+        };
+
+        let frame_start = Instant::now();
+        let t_import = Instant::now();
+        let vaapi_frame = match import_frame(frames_ctx, &frame) {
+            Ok(f) => f,
+            Err(e) => {
+                stats.import_failures += 1;
+                if stats.import_failures <= 3 {
+                    eprintln!("CPU frame {}: import failed: {e}", stats.frames_encoded);
+                }
+                continue;
+            }
+        };
+        let import_us = t_import.elapsed().as_micros() as u64;
+
+        let t_transfer = Instant::now();
+        // SAFETY: sw_frame is allocated by FFmpeg and freed on all paths below.
+        let mut sw_frame = unsafe { ffi::av_frame_alloc() };
+        if sw_frame.is_null() {
+            bail!("CPU frame {}: av_frame_alloc failed", stats.frames_encoded);
+        }
+        // SAFETY: sw_frame is an allocated destination; vaapi_frame is a valid VAAPI source frame.
+        let transfer_ret =
+            unsafe { ffi::av_hwframe_transfer_data(sw_frame, vaapi_frame.as_ptr(), 0) };
+        if transfer_ret < 0 {
+            // SAFETY: sw_frame was allocated above and has not been freed yet.
+            unsafe { ffi::av_frame_free(&mut sw_frame) };
+            bail!(
+                "CPU frame {}: av_hwframe_transfer_data failed: {} ({})",
+                stats.frames_encoded,
+                transfer_ret,
+                av_err_to_string(transfer_ret)
+            );
+        }
+        let transfer_us = t_transfer.elapsed().as_micros() as u64;
+
+        let t_scale = Instant::now();
+        // SAFETY: sw_frame contains transferred BGRA data; encoder.yuv_frame is writable YUV420P
+        // at the configured output dimensions; sws_ctx converts and downscales between them.
+        unsafe {
+            ffi::av_frame_make_writable(encoder.yuv_frame);
+            ffi::sws_scale(
+                sws_ctx.0,
+                (*sw_frame).data.as_ptr() as *const *const u8,
+                (*sw_frame).linesize.as_ptr(),
+                0,
+                (*sw_frame).height,
+                (*encoder.yuv_frame).data.as_ptr() as *mut *mut u8,
+                (*encoder.yuv_frame).linesize.as_ptr(),
+            );
+        }
+        let scale_us = t_scale.elapsed().as_micros() as u64;
+        // SAFETY: sw_frame was allocated above and is no longer needed after scaling.
+        unsafe { ffi::av_frame_free(&mut sw_frame) };
+
+        let encode_us = encode_yuv_frame(&mut encoder, &mut pts)?;
+        let total_us = frame_start.elapsed().as_micros() as u64;
+
+        stats.import_us.push(import_us);
+        stats.transfer_us.push(transfer_us);
+        stats.scale_us.push(scale_us);
+        stats.encode_us.push(encode_us);
+        stats.total_us.push(total_us);
+        stats.frames_encoded += 1;
+
+        if stats.frames_encoded <= 3 || stats.frames_encoded.is_multiple_of(30) {
+            println!(
+                "       CPU frame {:>4}/{frames}: import={:.2}ms transfer={:.2}ms scale={:.2}ms encode={:.2}ms total={:.2}ms",
+                stats.frames_encoded,
+                import_us as f64 / 1000.0,
+                transfer_us as f64 / 1000.0,
+                scale_us as f64 / 1000.0,
+                encode_us as f64 / 1000.0,
+                total_us as f64 / 1000.0,
+            );
+        }
+    }
+
+    finish_encoder(encoder)?;
+    stats.elapsed_secs = total_start.elapsed().as_secs_f64();
+    Ok(stats)
+}

src/bin/vaapi_import_bench/pipeline_gpu.rs

@@ -0,0 +1,250 @@
+use std::path::Path;
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use wl_webrtc::avhw::{av_err_to_string, import_dma_buf_to_vaapi, AvHwDevCtx, AvHwFrameCtx};
+use wl_webrtc::cap_portal::{CapPortal, PwCtrlEvent};
+
+use crate::software::{
+    create_software_encoder, create_sws_context, encode_yuv_frame, finish_encoder,
+};
+use crate::stats::FrameStats;
+
+pub(crate) fn import_frame(
+    frames_ctx: &AvHwFrameCtx,
+    frame: &wl_webrtc::cap_portal::PwDmaBufFrame,
+) -> Result<ff::frame::Video> {
+    // SAFETY: frames_ctx is a live VAAPI frames context configured for the capture format; frame
+    // carries a valid DMA-BUF fd and metadata from PipeWire for the duration of the call.
+    // SAFETY: frames_ctx is a valid VAAPI frames context; `frame` carries the
+    // DMA-BUF metadata read by the function.
+    unsafe { import_dma_buf_to_vaapi(frames_ctx.as_ptr(), frame) }
+}
+
+fn build_gpu_filter_graph(
+    hw_dev: &AvHwDevCtx,
+    frames_rgb: &AvHwFrameCtx,
+    width: u32,
+    height: u32,
+    enc_width: u32,
+    enc_height: u32,
+) -> Result<ff::filter::Graph> {
+    let mut graph = ff::filter::Graph::new();
+    let buffersrc =
+        ff::filter::find("buffer").ok_or_else(|| anyhow::anyhow!("filter 'buffer' not found"))?;
+    let buffersink = ff::filter::find("buffersink")
+        .ok_or_else(|| anyhow::anyhow!("filter 'buffersink' not found"))?;
+    let scale_vaapi = ff::filter::find("scale_vaapi")
+        .ok_or_else(|| anyhow::anyhow!("filter 'scale_vaapi' not found"))?;
+
+    // pix_fmt must be set via av_buffersrc_parameters_set (below), not in args —
+    // FFmpeg 8.0+ rejects HW pixel formats during init() if hw_frames_ctx is missing.
+    // Use a placeholder SW format here; it gets overridden by parameters_set below.
+    let args = format!(
+        "video_size={}x{}:pix_fmt=bgra:time_base=1/60:pixel_aspect=1/1",
+        width, height,
+    );
+    let mut src_ctx = graph.add(&buffersrc, "in", &args)?;
+
+    // SAFETY: Allocate buffersrc parameters, attach a ref-counted hw_frames_ctx compatible with
+    // imported VAAPI BGRA frames, apply it, then free only the parameter struct (not the ref).
+    let par = unsafe { ffi::av_buffersrc_parameters_alloc() };
+    if par.is_null() {
+        bail!("av_buffersrc_parameters_alloc returned null");
+    }
+    // SAFETY: par and src_ctx are valid; frames_rgb.ref_clone returns an owned AVBufferRef.
+    unsafe {
+        (*par).format = Into::<ffi::AVPixelFormat>::into(ff::format::Pixel::VAAPI) as i32;
+        (*par).width = width as i32;
+        (*par).height = height as i32;
+        (*par).time_base = ffi::AVRational { num: 1, den: 60 };
+        (*par).hw_frames_ctx = frames_rgb.ref_clone();
+        let ret = ffi::av_buffersrc_parameters_set(src_ctx.as_mut_ptr(), par);
+        ffi::av_free(par as *mut _);
+        if ret < 0 {
+            bail!("av_buffersrc_parameters_set failed: error {ret}");
+        }
+    }
+
+    let mut scale_ctx = graph.add(
+        &scale_vaapi,
+        "scale",
+        &format!("{enc_width}:{enc_height}:format=nv12"),
+    )?;
+    // SAFETY: scale_vaapi uses this ref-counted VAAPI device context while graph is alive.
+    unsafe {
+        (*scale_ctx.as_mut_ptr()).hw_device_ctx = hw_dev.ref_clone();
+    }
+
+    let mut sink_ctx = graph.add(&buffersink, "out", "")?;
+    src_ctx.link(0, &mut scale_ctx, 0);
+    scale_ctx.link(0, &mut sink_ctx, 0);
+    graph
+        .validate()
+        .map_err(|e| anyhow::anyhow!("GPU filter graph validation failed: {e}"))?;
+
+    Ok(graph)
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn run_gpu_pipeline(
+    cap: &CapPortal,
+    hw_dev: &AvHwDevCtx,
+    frames_ctx: &AvHwFrameCtx,
+    output: &str,
+    frames: u32,
+    src_width: u32,
+    src_height: u32,
+    enc_width: u32,
+    enc_height: u32,
+) -> Result<FrameStats> {
+    let mut encoder = create_software_encoder(Path::new(output), enc_width, enc_height)?;
+    let format_ctx = create_sws_context(
+        enc_width,
+        enc_height,
+        ffi::AVPixelFormat::AV_PIX_FMT_NV12,
+        enc_width,
+        enc_height,
+    )?;
+    let mut graph = build_gpu_filter_graph(
+        hw_dev, frames_ctx, src_width, src_height, enc_width, enc_height,
+    )?;
+
+    println!(
+        "       Encoder: {}, {}x{} YUV420P",
+        encoder.codec_name, enc_width, enc_height
+    );
+    println!("       Output: {output}");
+    println!("       GPU Pipeline: DMA-BUF 4K BGRA -> av_hwframe_map -> scale_vaapi 2K NV12 -> transfer small NV12 -> sws_scale format-only -> encode\n");
+
+    let mut stats = FrameStats {
+        codec_name: encoder.codec_name.clone(),
+        output_path: output.to_string(),
+        ..FrameStats::default()
+    };
+    let total_start = Instant::now();
+    let mut pts: i64 = 0;
+
+    while stats.frames_encoded < frames {
+        if let Ok(ctrl) = cap.event_receiver().try_recv() {
+            match ctrl {
+                PwCtrlEvent::StreamEnded => break,
+                PwCtrlEvent::Error(e) => bail!(
+                    "PipeWire error after {} GPU frames: {e}",
+                    stats.frames_encoded
+                ),
+                PwCtrlEvent::FormatChanged { .. } => {}
+            }
+        }
+
+        let frame = match cap
+            .frame_receiver()
+            .recv_timeout(std::time::Duration::from_secs(5))
+        {
+            Ok(f) => f,
+            Err(_) => break,
+        };
+
+        let frame_start = Instant::now();
+        let t_import = Instant::now();
+        let vaapi_frame = match import_frame(frames_ctx, &frame) {
+            Ok(f) => f,
+            Err(e) => {
+                stats.import_failures += 1;
+                if stats.import_failures <= 3 {
+                    eprintln!("GPU frame {}: import failed: {e}", stats.frames_encoded);
+                }
+                continue;
+            }
+        };
+        let import_us = t_import.elapsed().as_micros() as u64;
+
+        let t_filter = Instant::now();
+        let mut filter_src_ctx = graph.get("in").unwrap();
+        let mut filter_src = filter_src_ctx.source();
+        let mut filter_sink_ctx = graph.get("out").unwrap();
+        let mut filter_sink = filter_sink_ctx.sink();
+        filter_src
+            .add(&vaapi_frame)
+            .map_err(|e| anyhow::anyhow!("GPU filter source add failed: {e}"))?;
+
+        let mut filtered = ff::frame::Video::empty();
+        match filter_sink.frame(&mut filtered) {
+            Ok(()) => {}
+            Err(ff::Error::Other { errno }) if errno == ffi::EAGAIN => continue,
+            Err(e) => bail!("GPU filter sink get frame failed: {e}"),
+        }
+        let filter_us = t_filter.elapsed().as_micros() as u64;
+
+        let t_transfer = Instant::now();
+        // SAFETY: sw_nv12 is allocated by FFmpeg and freed after format conversion.
+        let mut sw_nv12 = unsafe { ffi::av_frame_alloc() };
+        if sw_nv12.is_null() {
+            bail!("GPU frame {}: av_frame_alloc failed", stats.frames_encoded);
+        }
+        // SAFETY: sw_nv12 is an allocated destination; filtered is a valid 2K NV12 VAAPI frame.
+        let transfer_ret = unsafe { ffi::av_hwframe_transfer_data(sw_nv12, filtered.as_ptr(), 0) };
+        if transfer_ret < 0 {
+            // SAFETY: sw_nv12 was allocated above and has not been freed yet.
+            unsafe { ffi::av_frame_free(&mut sw_nv12) };
+            bail!(
+                "GPU frame {}: av_hwframe_transfer_data failed: {} ({})",
+                stats.frames_encoded,
+                transfer_ret,
+                av_err_to_string(transfer_ret)
+            );
+        }
+        let transfer_us = t_transfer.elapsed().as_micros() as u64;
+
+        let t_format = Instant::now();
+        // SAFETY: sw_nv12 contains CPU-side NV12 at enc dimensions; encoder.yuv_frame is writable
+        // YUV420P at the same dimensions, so sws_scale performs only chroma deinterleave/format conversion.
+        unsafe {
+            ffi::av_frame_make_writable(encoder.yuv_frame);
+            ffi::sws_scale(
+                format_ctx.0,
+                (*sw_nv12).data.as_ptr() as *const *const u8,
+                (*sw_nv12).linesize.as_ptr(),
+                0,
+                (*sw_nv12).height,
+                (*encoder.yuv_frame).data.as_ptr() as *mut *mut u8,
+                (*encoder.yuv_frame).linesize.as_ptr(),
+            );
+        }
+        let format_us = t_format.elapsed().as_micros() as u64;
+        // SAFETY: sw_nv12 was allocated above and is no longer needed.
+        unsafe { ffi::av_frame_free(&mut sw_nv12) };
+
+        let encode_us = encode_yuv_frame(&mut encoder, &mut pts)?;
+        let total_us = frame_start.elapsed().as_micros() as u64;
+
+        stats.import_us.push(import_us);
+        stats.filter_us.push(filter_us);
+        stats.transfer_us.push(transfer_us);
+        stats.format_us.push(format_us);
+        stats.encode_us.push(encode_us);
+        stats.total_us.push(total_us);
+        stats.frames_encoded += 1;
+
+        if stats.frames_encoded <= 3 || stats.frames_encoded.is_multiple_of(30) {
+            println!(
+                "       GPU frame {:>4}/{frames}: import={:.2}ms filter={:.2}ms transfer={:.2}ms format={:.2}ms encode={:.2}ms total={:.2}ms",
+                stats.frames_encoded,
+                import_us as f64 / 1000.0,
+                filter_us as f64 / 1000.0,
+                transfer_us as f64 / 1000.0,
+                format_us as f64 / 1000.0,
+                encode_us as f64 / 1000.0,
+                total_us as f64 / 1000.0,
+            );
+        }
+    }
+
+    finish_encoder(encoder)?;
+    stats.elapsed_secs = total_start.elapsed().as_secs_f64();
+    Ok(stats)
+}

src/bin/vaapi_import_bench/software.rs

@@ -0,0 +1,228 @@
+use std::ffi::CString;
+use std::path::Path;
+use std::ptr;
+use std::time::Instant;
+
+use anyhow::{bail, Result};
+
+use ffmpeg_next as ff;
+use ffmpeg_next::ffi;
+
+use crate::common::drain_encoder;
+
+pub(crate) struct SoftwareEncoder {
+    pub(crate) enc_video: ff::codec::encoder::video::Video,
+    pub(crate) octx: ff::format::context::Output,
+    pub(crate) yuv_frame: *mut ffi::AVFrame,
+    pub(crate) codec_name: String,
+}
+
+impl Drop for SoftwareEncoder {
+    fn drop(&mut self) {
+        // SAFETY: yuv_frame is allocated by av_frame_alloc in create_software_encoder and
+        // owned exclusively by this SoftwareEncoder.
+        unsafe {
+            ffi::av_frame_free(&mut self.yuv_frame);
+        }
+    }
+}
+
+pub(crate) struct SwsContext(pub(crate) *mut ffi::SwsContext);
+
+impl Drop for SwsContext {
+    fn drop(&mut self) {
+        // SAFETY: Context is either null or returned by sws_getContext and owned here.
+        unsafe {
+            ffi::sws_freeContext(self.0);
+        }
+    }
+}
+
+pub(crate) fn create_software_encoder(
+    output_path: &Path,
+    width: u32,
+    height: u32,
+) -> Result<SoftwareEncoder> {
+    let output_cstr = CString::new(output_path.to_str().unwrap())?;
+    let codec = ff::encoder::find_by_name("libx264")
+        .or_else(|| ff::encoder::find_by_name("libopenh264"))
+        .ok_or_else(|| {
+            anyhow::anyhow!("No H.264 software encoder found (tried libx264, libopenh264)")
+        })?;
+
+    let codec_name = codec.name().to_string();
+    let mut enc = {
+        let ctx = ff::codec::Context::new_with_codec(codec);
+        ctx.encoder().video()?
+    };
+
+    enc.set_width(width);
+    enc.set_height(height);
+    enc.set_format(ff::format::Pixel::YUV420P);
+    enc.set_time_base(ff::Rational::new(1, 60));
+    enc.set_max_b_frames(0);
+    enc.set_gop(60);
+
+    if codec_name == "libx264" {
+        // SAFETY: priv_data belongs to the not-yet-opened encoder context. Option strings are
+        // valid NUL-terminated C strings for the duration of each av_opt_set call.
+        unsafe {
+            let key = CString::new("preset").unwrap();
+            let val = CString::new("veryfast").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+            let key = CString::new("tune").unwrap();
+            let val = CString::new("zerolatency").unwrap();
+            ffi::av_opt_set((*enc.as_mut_ptr()).priv_data, key.as_ptr(), val.as_ptr(), 0);
+        }
+    }
+
+    let opened = enc.open()?;
+    let enc_video = opened.0;
+
+    let use_null_muxer = output_path
+        .to_str()
+        .map(|s| s.contains("null"))
+        .unwrap_or(false);
+    let fmt_name = if use_null_muxer {
+        CString::new("null").unwrap()
+    } else {
+        CString::new("").unwrap()
+    };
+    let fmt_name_ptr = if use_null_muxer {
+        fmt_name.as_ptr()
+    } else {
+        ptr::null()
+    };
+
+    let mut fmt_ctx_ptr: *mut ffi::AVFormatContext = ptr::null_mut();
+    // SAFETY: fmt_ctx_ptr is an out parameter initialized by FFmpeg; output_cstr and fmt_name live
+    // across the call.
+    let ret = unsafe {
+        ffi::avformat_alloc_output_context2(
+            &mut fmt_ctx_ptr,
+            ptr::null_mut(),
+            fmt_name_ptr,
+            output_cstr.as_ptr(),
+        )
+    };
+    if ret < 0 || fmt_ctx_ptr.is_null() {
+        bail!("Failed to allocate output format context: error {ret}");
+    }
+
+    // SAFETY: fmt_ctx_ptr is a valid output context allocated above.
+    let stream_ptr = unsafe { ffi::avformat_new_stream(fmt_ctx_ptr, ptr::null()) };
+    if stream_ptr.is_null() {
+        bail!("Failed to create output stream");
+    }
+
+    // SAFETY: stream and codec context pointers are valid; parameters are copied into stream.
+    let ret =
+        unsafe { ffi::avcodec_parameters_from_context((*stream_ptr).codecpar, enc_video.as_ptr()) };
+    if ret < 0 {
+        bail!("Failed to copy codec parameters: error {ret}");
+    }
+
+    // SAFETY: fmt_ctx_ptr is valid; pb is initialized for non-NOFILE muxers.
+    unsafe {
+        if (*(*fmt_ctx_ptr).oformat).flags & ffi::AVFMT_NOFILE == 0 {
+            let ret = ffi::avio_open(
+                &mut (*fmt_ctx_ptr).pb,
+                output_cstr.as_ptr(),
+                ffi::AVIO_FLAG_WRITE,
+            );
+            if ret < 0 {
+                bail!("Failed to open output file: error {ret}");
+            }
+        }
+    }
+
+    // SAFETY: fmt_ctx_ptr is a fully configured output context.
+    let ret = unsafe { ffi::avformat_write_header(fmt_ctx_ptr, ptr::null_mut()) };
+    if ret < 0 {
+        bail!("Failed to write header: error {ret}");
+    }
+
+    // SAFETY: ownership of fmt_ctx_ptr transfers into ffmpeg-next Output wrapper.
+    let octx = unsafe { ff::format::context::Output::wrap(fmt_ctx_ptr) };
+
+    // SAFETY: Allocate and configure an owned writable YUV420P frame for encoder input.
+    let yuv_frame = unsafe {
+        let mut f = ffi::av_frame_alloc();
+        if f.is_null() {
+            bail!("av_frame_alloc failed");
+        }
+        (*f).width = width as i32;
+        (*f).height = height as i32;
+        (*f).format = ffi::AVPixelFormat::AV_PIX_FMT_YUV420P as i32;
+        let r = ffi::av_frame_get_buffer(f, 0);
+        if r < 0 {
+            ffi::av_frame_free(&mut f);
+            bail!("av_frame_get_buffer failed: {r}");
+        }
+        f
+    };
+
+    Ok(SoftwareEncoder {
+        enc_video,
+        octx,
+        yuv_frame,
+        codec_name,
+    })
+}
+
+pub(crate) fn create_sws_context(
+    src_width: u32,
+    src_height: u32,
+    src_fmt: ffi::AVPixelFormat,
+    dst_width: u32,
+    dst_height: u32,
+) -> Result<SwsContext> {
+    // SAFETY: sws_getContext creates an owned scaler context for the provided dimensions/formats.
+    let ctx = unsafe {
+        ffi::sws_getContext(
+            src_width as i32,
+            src_height as i32,
+            src_fmt,
+            dst_width as i32,
+            dst_height as i32,
+            ffi::AVPixelFormat::AV_PIX_FMT_YUV420P,
+            2,
+            ptr::null_mut(),
+            ptr::null_mut(),
+            ptr::null_mut(),
+        )
+    };
+    if ctx.is_null() {
+        bail!("Failed to create sws_scale context");
+    }
+    Ok(SwsContext(ctx))
+}
+
+pub(crate) fn encode_yuv_frame(encoder: &mut SoftwareEncoder, pts: &mut i64) -> Result<u64> {
+    let t_encode = Instant::now();
+    // SAFETY: yuv_frame is allocated, writable, and formatted as the encoder's configured
+    // YUV420P input frame. FFmpeg consumes but does not take ownership.
+    unsafe {
+        (*encoder.yuv_frame).pts = *pts;
+        *pts += 1;
+        let r = ffi::avcodec_send_frame(encoder.enc_video.as_mut_ptr(), encoder.yuv_frame);
+        if r < 0 {
+            bail!("avcodec_send_frame failed: {r}");
+        }
+    }
+    drain_encoder(&mut encoder.enc_video, &mut encoder.octx)?;
+    Ok(t_encode.elapsed().as_micros() as u64)
+}
+
+pub(crate) fn finish_encoder(mut encoder: SoftwareEncoder) -> Result<()> {
+    // SAFETY: Sending a null frame flushes the encoder; context remains owned by encoder.
+    unsafe {
+        ffi::avcodec_send_frame(encoder.enc_video.as_mut_ptr(), ptr::null());
+    }
+    drain_encoder(&mut encoder.enc_video, &mut encoder.octx)?;
+    encoder
+        .octx
+        .write_trailer()
+        .map_err(|e| anyhow::anyhow!("Failed to write trailer: {e}"))?;
+    Ok(())
+}

src/bin/vaapi_import_bench/stats.rs

@@ -0,0 +1,76 @@
+use clap::{Parser, ValueEnum};
+
+#[derive(Parser, Debug)]
+#[command(name = "vaapi_import_bench", about = "VAAPI DMA-BUF import benchmark")]
+pub(crate) struct BenchArgs {
+    #[arg(short, long)]
+    pub(crate) output: String,
+
+    #[arg(long, default_value_t = 60)]
+    pub(crate) frames: u32,
+
+    #[arg(long, default_value_t = 2560)]
+    pub(crate) enc_width: u32,
+
+    #[arg(long, default_value_t = 1440)]
+    pub(crate) enc_height: u32,
+
+    #[arg(long, default_value = "/dev/dri/renderD128")]
+    pub(crate) drm_device: String,
+
+    #[arg(long, value_enum, default_value_t = PipelineMode::Both)]
+    pub(crate) mode: PipelineMode,
+}
+
+#[derive(Copy, Clone, Debug, Eq, PartialEq, ValueEnum)]
+pub(crate) enum PipelineMode {
+    Cpu,
+    Gpu,
+    Both,
+}
+
+#[derive(Default)]
+pub(crate) struct FrameStats {
+    pub(crate) import_us: Vec<u64>,
+    pub(crate) filter_us: Vec<u64>,
+    pub(crate) transfer_us: Vec<u64>,
+    pub(crate) scale_us: Vec<u64>,
+    pub(crate) format_us: Vec<u64>,
+    pub(crate) encode_us: Vec<u64>,
+    pub(crate) total_us: Vec<u64>,
+    pub(crate) import_failures: u32,
+    pub(crate) frames_encoded: u32,
+    pub(crate) elapsed_secs: f64,
+    pub(crate) codec_name: String,
+    pub(crate) output_path: String,
+}
+
+impl FrameStats {
+    pub(crate) fn avg_ms(data: &[u64]) -> f64 {
+        if data.is_empty() {
+            return 0.0;
+        }
+        data.iter().sum::<u64>() as f64 / data.len() as f64 / 1000.0
+    }
+
+    pub(crate) fn avg_total_ms(&self) -> f64 {
+        Self::avg_ms(&self.total_us)
+    }
+
+    pub(crate) fn achieved_fps(&self) -> f64 {
+        if self.frames_encoded > 0 && self.elapsed_secs > 0.0 {
+            self.frames_encoded as f64 / self.elapsed_secs
+        } else {
+            0.0
+        }
+    }
+
+    pub(crate) fn theoretical_fps(&self) -> f64 {
+        let avg = self.avg_total_ms();
+        if avg > 0.0 {
+            1000.0 / avg
+        } else {
+            0.0
+        }
+    }
+}

src/bin/vaapi_import_bench/util.rs

@@ -0,0 +1,107 @@
+use std::path::Path;
+
+use crate::stats::{FrameStats, PipelineMode};
+
+pub(crate) fn output_for_mode(base: &str, mode: PipelineMode, split: bool) -> String {
+    if !split || base.contains("null") {
+        return base.to_string();
+    }
+
+    let path = Path::new(base);
+    let suffix = match mode {
+        PipelineMode::Cpu => "cpu",
+        PipelineMode::Gpu => "gpu",
+        PipelineMode::Both => unreachable!(),
+    };
+    let file_name = path.file_name().and_then(|s| s.to_str()).unwrap_or(base);
+    let split_name = if let Some((stem, ext)) = file_name.rsplit_once('.') {
+        format!("{stem}.{suffix}.{ext}")
+    } else {
+        format!("{file_name}.{suffix}")
+    };
+    path.with_file_name(split_name)
+        .to_string_lossy()
+        .into_owned()
+}
+
+pub(crate) fn print_detailed_results(
+    label: &str,
+    stats: &FrameStats,
+    src_width: u32,
+    src_height: u32,
+    enc_width: u32,
+    enc_height: u32,
+) {
+    println!();
+    println!("=== {label} Pipeline Results ===");
+    println!("Capture resolution: {}x{}", src_width, src_height);
+    println!("Encode resolution:  {}x{}", enc_width, enc_height);
+    println!("Frames encoded:     {}", stats.frames_encoded);
+    println!("Total time:         {:.2}s", stats.elapsed_secs);
+    println!("Output:             {}", stats.output_path);
+    if stats.import_failures > 0 {
+        println!("Import failures:    {}", stats.import_failures);
+    }
+    println!(
+        "import avg:         {:.2} ms/frame",
+        FrameStats::avg_ms(&stats.import_us)
+    );
+    if !stats.filter_us.is_empty() {
+        println!(
+            "filter avg:         {:.2} ms/frame",
+            FrameStats::avg_ms(&stats.filter_us)
+        );
+    }
+    println!(
+        "transfer avg:       {:.2} ms/frame",
+        FrameStats::avg_ms(&stats.transfer_us)
+    );
+    if !stats.scale_us.is_empty() {
+        println!(
+            "scale avg:          {:.2} ms/frame",
+            FrameStats::avg_ms(&stats.scale_us)
+        );
+    }
+    if !stats.format_us.is_empty() {
+        println!(
+            "format avg:         {:.2} ms/frame",
+            FrameStats::avg_ms(&stats.format_us)
+        );
+    }
+    println!(
+        "encode ({}):        {:.2} ms/frame",
+        stats.codec_name,
+        FrameStats::avg_ms(&stats.encode_us)
+    );
+    println!("total avg:          {:.2} ms/frame", stats.avg_total_ms());
+    println!("achieved FPS:       {:.1}", stats.achieved_fps());
+    println!("max theoretical:    {:.1} FPS", stats.theoretical_fps());
+}
+
+pub(crate) fn print_comparison(cpu: Option<&FrameStats>, gpu: Option<&FrameStats>) {
+    println!();
+    println!("=== Pipeline Comparison ===");
+    if let Some(s) = cpu {
+        println!(
+            "CPU: import={:.2}ms transfer={:.2}ms scale={:.2}ms encode={:.2}ms total={:.2}ms ({:.1} FPS)",
+            FrameStats::avg_ms(&s.import_us),
+            FrameStats::avg_ms(&s.transfer_us),
+            FrameStats::avg_ms(&s.scale_us),
+            FrameStats::avg_ms(&s.encode_us),
+            s.avg_total_ms(),
+            s.theoretical_fps(),
+        );
+    }
+    if let Some(s) = gpu {
+        println!(
+            "GPU: import={:.2}ms filter={:.2}ms transfer={:.2}ms format={:.2}ms encode={:.2}ms total={:.2}ms ({:.1} FPS)",
+            FrameStats::avg_ms(&s.import_us),
+            FrameStats::avg_ms(&s.filter_us),
+            FrameStats::avg_ms(&s.transfer_us),
+            FrameStats::avg_ms(&s.format_us),
+            FrameStats::avg_ms(&s.encode_us),
+            s.avg_total_ms(),
+            s.theoretical_fps(),
+        );
+    }
+}

src/cap_portal/fourcc.rs

@@ -0,0 +1,73 @@
+/// 将 PipeWire SPA 视频格式转换为 DRM FourCC 格式
+///
+/// PipeWire 使用自己的 VideoFormat 枚举，而 DRM/KMS 使用 FourCC 格式标识。
+/// 此函数建立了两者之间的映射关系。
+///
+/// 支持的格式:
+/// 不支持的格式返回 0
+/// DRM 格式名描述像素值位布局（大端序），而非内存字节序。
+/// 例如 DRM_FORMAT_ARGB8888 在小端 x86 上内存为 [B,G,R,A] = PipeWire BGRA。
+pub(super) fn spa_to_drm_fourcc(format: libspa::param::video::VideoFormat) -> u32 {
+    use drm_fourcc::DrmFourcc;
+    use libspa::param::video::VideoFormat;
+    match format {
+        VideoFormat::BGRA => DrmFourcc::Argb8888 as u32,
+        VideoFormat::BGRx => DrmFourcc::Xrgb8888 as u32,
+        VideoFormat::RGBA => DrmFourcc::Abgr8888 as u32,
+        VideoFormat::RGBx => DrmFourcc::Xbgr8888 as u32,
+        VideoFormat::ARGB => DrmFourcc::Bgra8888 as u32,
+        VideoFormat::xRGB => DrmFourcc::Bgrx8888 as u32,
+        VideoFormat::ABGR => DrmFourcc::Rgba8888 as u32,
+        VideoFormat::xBGR => DrmFourcc::Rgbx8888 as u32,
+        _ => 0,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use drm_fourcc::DrmFourcc;
+
+    #[test]
+    fn spa_to_drm_fourcc_all_32bit() {
+        use libspa::param::video::VideoFormat;
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::BGRA),
+            DrmFourcc::Argb8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::BGRx),
+            DrmFourcc::Xrgb8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::RGBA),
+            DrmFourcc::Abgr8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::RGBx),
+            DrmFourcc::Xbgr8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::ARGB),
+            DrmFourcc::Bgra8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::xRGB),
+            DrmFourcc::Bgrx8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::ABGR),
+            DrmFourcc::Rgba8888 as u32
+        );
+        assert_eq!(
+            spa_to_drm_fourcc(VideoFormat::xBGR),
+            DrmFourcc::Rgbx8888 as u32
+        );
+    }
+
+    #[test]
+    fn spa_to_drm_fourcc_unsupported() {
+        use libspa::param::video::VideoFormat;
+        assert_eq!(spa_to_drm_fourcc(VideoFormat::NV12), 0);
+    }
+}

src/cap_portal/logging.rs

@@ -0,0 +1,18 @@
+/// Log an actionable diagnostic when a Portal phase times out.
+///
+/// Mirrors the message format from `backend_detect.rs::log_portal_unresponsive`
+/// but additionally suggests `--no-persist` when the timeout occurred in a
+/// phase that was using a restore token.
+pub(super) fn log_portal_phase_timeout(phase: &str, used_restore_token: bool) {
+    let persist_hint = if used_restore_token {
+        " If this recurs, try: wl-webrtc --no-persist"
+    } else {
+        ""
+    };
+    tracing::error!(
+        "Portal service did not respond within timeout while {phase}. \
+         This usually means xdg-desktop-portal or xdg-desktop-portal-kde is stuck. \
+         Try: systemctl --user restart xdg-desktop-portal xdg-desktop-portal-kde, \
+         then re-run wl-webrtc.{persist_hint}"
+    );
+}

src/cap_portal/pipewire_thread.rs

@@ -0,0 +1,446 @@
+use std::os::fd::{AsRawFd, FromRawFd, OwnedFd};
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+use std::thread::{self, JoinHandle};
+
+use anyhow::Result;
+use crossbeam_channel::Sender;
+
+use super::fourcc::spa_to_drm_fourcc;
+use super::types::{PortalFormatInfo, PwCtrlEvent, PwDmaBufFrame};
+
+/// PipeWire 捕获线程的上下文数据
+///
+/// 从主线程传递给 PipeWire 捕获线程的所有必要资源。
+/// 该结构体在线程创建时一次性 move 到线程中使用。
+struct PwThreadCtx {
+    frame_tx: Sender<PwDmaBufFrame>,
+    event_tx: Sender<PwCtrlEvent>,
+    dropped: Arc<AtomicU64>,
+    shutdown_read: OwnedFd,
+    pw_fd: OwnedFd,
+    node_id: u32,
+}
+
+fn pipewire_thread(ctx: PwThreadCtx) {
+    use pipewire as pw;
+    use pw::properties::properties;
+    use pw::spa::param::video::VideoInfoRaw;
+    use pw::stream::{StreamBox, StreamFlags};
+    use std::cell::Cell;
+    use std::rc::Rc;
+
+    // 初始化 PipeWire 进程全局库。
+    //
+    // pipewire-rs 内部使用 OnceCell 保护 pw::init()，确保只调用一次。
+    // pw::deinit() 是 unsafe 且要求"进程生命周期内仅调用一次，且所有
+    // PipeWire 使用已停止"。由于 CapPortal 可被多次创建销毁，此函数
+    // 不调用 pw::deinit()——进程退出时全局状态由 OS 回收。
+    pw::init();
+
+    let PwThreadCtx {
+        frame_tx,
+        event_tx,
+        dropped,
+        shutdown_read,
+        pw_fd,
+        node_id,
+    } = ctx;
+
+    let mainloop = match pw::main_loop::MainLoopBox::new(None) {
+        Ok(ml) => ml,
+        Err(e) => {
+            if let Err(e) =
+                event_tx.try_send(PwCtrlEvent::Error(format!("MainLoop::new failed: {e}")))
+            {
+                tracing::error!("MainLoop::new failed and error channel also failed: {e}");
+            }
+            return;
+        }
+    };
+
+    let context = match pw::context::ContextBox::new(mainloop.loop_(), None) {
+        Ok(c) => c,
+        Err(e) => {
+            if let Err(e) =
+                event_tx.try_send(PwCtrlEvent::Error(format!("Context::new failed: {e}")))
+            {
+                tracing::error!("Context::new failed and error channel also failed: {e}");
+            }
+            return;
+        }
+    };
+
+    let core = match context.connect_fd(pw_fd, None) {
+        Ok(c) => c,
+        Err(e) => {
+            if let Err(e) = event_tx.try_send(PwCtrlEvent::Error(format!("connect_fd failed: {e}")))
+            {
+                tracing::error!("connect_fd failed and error channel also failed: {e}");
+            }
+            return;
+        }
+    };
+
+    // 创建 PipeWire 视频流
+    // 属性配置:
+    //   - MEDIA_TYPE = "Video": 媒体类型为视频
+    //   - MEDIA_CATEGORY = "Capture": 类别为捕获（而非回放）
+    //   - MEDIA_ROLE = "Screen": 角色为屏幕（用于策略管理）
+    let stream = match StreamBox::new(
+        &core,
+        "wl-webrtc",
+        properties! {
+            *pw::keys::MEDIA_TYPE => "Video",
+            *pw::keys::MEDIA_CATEGORY => "Capture",
+            *pw::keys::MEDIA_ROLE => "Screen",
+            *pw::keys::NODE_FORCE_QUANTUM => "512",
+        },
+    ) {
+        Ok(s) => s,
+        Err(e) => {
+            if let Err(e) =
+                event_tx.try_send(PwCtrlEvent::Error(format!("Stream::new failed: {e}")))
+            {
+                tracing::error!("Stream::new failed and error channel also failed: {e}");
+            }
+            return;
+        }
+    };
+
+    let format_info: Rc<Cell<Option<PortalFormatInfo>>> = Rc::new(Cell::new(None));
+
+    let event_tx_state = event_tx.clone();
+    let _listener = stream
+        .add_local_listener::<()>()
+        .state_changed(move |_, _, old, new| {
+            tracing::info!("PipeWire stream state: {old:?} -> {new:?}");
+            match new {
+                pw::stream::StreamState::Error(e) => {
+                    tracing::error!("PipeWire stream error: {e}");
+                    let _ = event_tx_state.try_send(PwCtrlEvent::StreamEnded);
+                }
+                pw::stream::StreamState::Unconnected => {
+                    let _ = event_tx_state.try_send(PwCtrlEvent::StreamEnded);
+                }
+                pw::stream::StreamState::Paused => {
+                    tracing::warn!("PipeWire stream paused (compositor may be switching content)");
+                }
+                pw::stream::StreamState::Streaming => {
+                    tracing::info!("PipeWire stream (re)started");
+                }
+                pw::stream::StreamState::Connecting => {}
+            }
+        })
+        // 参数变化回调（格式协商）
+        // PipeWire 在流格式协商完成后触发此回调
+        // id 为参数类型，param 包含具体的格式参数（分辨率、像素格式等）
+        .param_changed({
+            let format_info = format_info.clone();
+            let event_tx = event_tx.clone();
+            move |_, _, id, param| {
+                // 仅处理 Format 类型的参数变化
+                let Some(param) = param else { return };
+                if id != pw::spa::param::ParamType::Format.as_raw() {
+                    return;
+                }
+                // 解析视频格式信息（分辨率、像素格式、修饰符等）
+                let mut info = VideoInfoRaw::new();
+                if let Err(e) = info.parse(param) {
+                    tracing::warn!("Failed to parse video format: {e}");
+                    return;
+                }
+                let width = info.size().width;
+                let height = info.size().height;
+                // 将 SPA 视频格式转换为 DRM FourCC 格式标识符
+                let drm_format = spa_to_drm_fourcc(info.format());
+                // 获取 DRM 修饰符，描述 GPU buffer 的内存布局（如 tiling 模式）
+                let modifier = info.modifier();
+                let framerate = info.framerate();
+                let max_framerate = info.max_framerate();
+                // 保存协商后的格式信息，供 process 回调读取
+                let previous_format = format_info.get();
+                format_info.set(Some(PortalFormatInfo {
+                    width,
+                    height,
+                    drm_format,
+                    modifier,
+                }));
+                if let Some(prev) = previous_format {
+                    if width != prev.width || height != prev.height {
+                        tracing::warn!(
+                            "PipeWire dimensions changed: {}x{} (format renegotiation)",
+                            width,
+                            height
+                        );
+                        let _ = event_tx.try_send(PwCtrlEvent::FormatChanged { width, height });
+                    }
+                }
+                tracing::info!(
+                    "PipeWire format negotiated: {width}x{height}, \
+                     drm_format={drm_format:#010x}, modifier={modifier:#x}, \
+                     framerate={}/{}, max_framerate={}/{}",
+                    framerate.num,
+                    framerate.denom,
+                    max_framerate.num,
+                    max_framerate.denom,
+                );
+            }
+        })
+        // 帧处理回调 —— 这是核心的数据路径
+        // 每当 PipeWire 有新的帧数据可用时触发
+        // 关键操作: 从 buffer 中提取 DMA-BUF fd，dup 后通过 channel 发送给消费者
+        .process({
+            let format_info = format_info.clone();
+            let frame_tx = frame_tx.clone();
+            move |stream, _| {
+                // SAFETY: raw_buf ownership invariant — PipeWire's process callback
+                // contract requires that every buffer acquired via `dequeue_raw_buffer`
+                // is returned to the queue EXACTLY ONCE via `queue_raw_buffer` before
+                // the callback returns — on every exit path, success or error. Failure
+                // to requeue leaks the buffer slot and eventually stalls the stream.
+                //
+                // Audit map of this closure (verified 2026-06-28):
+                //   - null raw_buf  (dequeue returned NULL) → nothing to requeue, return.
+                //   - null spa_buf / no data / bad fd / null chunk / no format_info /
+                //     invalid dims / dup_fd < 0 → all requeue before early-return.
+                //   - success (try_send Ok / Full / Disconnected) → final requeue at end.
+                // The fd ownership is independent: dup() creates a fresh fd that lives
+                // inside PwDmaBufFrame; on try_send error the frame Drops and closes it.
+                let raw_buf = unsafe { stream.dequeue_raw_buffer() };
+                if raw_buf.is_null() {
+                    tracing::trace!("process: null raw_buf");
+                    return;
+                }
+
+                // 获取 SPA buffer 结构体，包含数据数组、元数据等
+                // SAFETY: raw_buf was checked non-null above. `pw_buffer.buffer` is a
+                // valid raw pointer for the lifetime of raw_buf (PipeWire keeps the
+                // buffer alive until we queue it back).
+                let spa_buf = unsafe { (*raw_buf).buffer };
+                if spa_buf.is_null() {
+                    tracing::trace!("process: null spa_buf");
+                    // SAFETY: raw_buf is the non-null buffer we still own; returning it.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                }
+
+                // 获取 buffer 中的数据项数量和数据指针
+                // 对于 DMA-BUF 帧，通常只有 1 个数据项（包含 fd）
+                // SAFETY: spa_buf checked non-null above; `n_datas` is a plain u32 field.
+                let n_datas = unsafe { (*spa_buf).n_datas };
+                // SAFETY: same as above; `datas` is a raw pointer field, may be null.
+                let datas_ptr = unsafe { (*spa_buf).datas };
+                if n_datas == 0 || datas_ptr.is_null() {
+                    tracing::trace!("process: no data (n_datas={n_datas})");
+                    // SAFETY: raw_buf still owned, returning it.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                }
+
+                // 从第一个数据项中获取 DMA-BUF 文件描述符
+                // 通过 libspa 的 Data 包装类型安全地访问 SPA 数据结构
+                // SAFETY: datas_ptr is non-null and n_datas > 0 (checked above). We cast
+                // to pw::spa::buffer::Data and take a shared borrow; PipeWire does not
+                // mutate the data array during a process cycle, so a shared reference
+                // for the duration of this callback is sound.
+                let data_ref: &pw::spa::buffer::Data =
+                    unsafe { &*(datas_ptr as *const pw::spa::buffer::Data) };
+                let fd = data_ref.fd();
+                if fd < 0 {
+                    tracing::trace!("process: invalid fd={fd}");
+                    // SAFETY: raw_buf still owned, returning it.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                }
+
+                if data_ref.as_raw().chunk.is_null() {
+                    tracing::trace!("process: null chunk");
+                    // SAFETY: raw_buf still owned, returning it.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                }
+                let chunk = data_ref.chunk();
+                let offset = chunk.offset() as u64;
+                let stride = chunk.stride() as u32;
+
+                // 从 SPA_META_Header 元数据中提取 PTS (显示时间戳)
+                // 遍历 buffer 的所有元数据项，查找 Header 类型的元数据
+                // PTS 可用于音视频同步和帧率控制
+                // SAFETY: spa_buf is non-null. `metas` is checked for null before
+                // iteration. We iterate `i in 0..n_metas` reading shared POD fields
+                // (type_, size, data) — PipeWire keeps the meta array immutable during
+                // a process cycle. The size guard (`meta.size >= size_of::<spa_meta_header>()`)
+                // and null-data check before reading ensure we never read past the
+                // meta's actual extent.
+                let pts: i64 = unsafe {
+                    let mut pts_val: i64 = 0;
+                    let n_metas = (*spa_buf).n_metas;
+                    let metas = (*spa_buf).metas;
+                    if !metas.is_null() {
+                        for i in 0..n_metas {
+                            let meta = &*metas.add(i as usize);
+                            if meta.type_ == libspa::sys::SPA_META_Header
+                                && meta.size as usize
+                                    >= std::mem::size_of::<libspa::sys::spa_meta_header>()
+                                && !meta.data.is_null()
+                            {
+                                let header = &*(meta.data as *const libspa::sys::spa_meta_header);
+                                pts_val = header.pts;
+                                break;
+                            }
+                        }
+                    }
+                    pts_val
+                };
+
+                // 验证格式信息已协商完成，且分辨率和格式有效
+                let Some(fmt) = format_info.get() else {
+                    // SAFETY: raw_buf still owned, returning it.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                };
+                let PortalFormatInfo {
+                    width,
+                    height,
+                    drm_format: format,
+                    modifier,
+                } = fmt;
+                if width == 0 || height == 0 || format == 0 {
+                    tracing::trace!("process: invalid dimensions {width}x{height} format={format}");
+                    // SAFETY: raw_buf still owned, returning it.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                }
+
+                // 复制 DMA-BUF 文件描述符
+                // 必须 dup，因为原始 fd 由 PipeWire 管理，我们不能持有它
+                // dup 后的 fd 由 PwDmaBufFrame 持有，生命周期独立于 PipeWire buffer
+                // SAFETY: `fd` is the open DMA-BUF fd reported by PipeWire (>= 0 checked
+                // above). libc::dup is the standard POSIX fd duplication call. The
+                // original `fd` remains owned by PipeWire (returned with raw_buf later).
+                let dup_fd = unsafe { libc::dup(fd) };
+                if dup_fd < 0 {
+                    // SAFETY: raw_buf still owned, returning it. No fd cleanup needed
+                    // because dup() failed and never returned a new fd.
+                    unsafe { stream.queue_raw_buffer(raw_buf) };
+                    return;
+                }
+
+                // 构建帧数据对象，所有必要的帧信息已收集完毕
+                // SAFETY: `dup_fd` is a freshly-dup'd open file descriptor (>= 0 checked
+                // above) and we are its sole owner. OwnedFd::from_raw_fd takes ownership
+                // and will close() it on Drop. The fd's lifecycle is independent of
+                // raw_buf: whether try_send succeeds (frame moves into the channel) or
+                // fails (Full/Disconnected — the error payload owns the frame and drops
+                // it at the end of the match arm), exactly one close() occurs per dup().
+                let frame_fd = unsafe { OwnedFd::from_raw_fd(dup_fd) };
+                let frame = PwDmaBufFrame {
+                    fd: frame_fd,
+                    offset,
+                    stride,
+                    modifier,
+                    width,
+                    height,
+                    format,
+                    pts,
+                };
+
+                match frame_tx.try_send(frame) {
+                    Ok(()) => {}
+                    Err(crossbeam_channel::TrySendError::Full(_)) => {
+                        dropped.fetch_add(1, Ordering::Relaxed);
+                    }
+                    Err(crossbeam_channel::TrySendError::Disconnected(_)) => {}
+                }
+                // SAFETY: final exactly-once requeue of raw_buf. Every path above
+                // either returned early with its own requeue, or falls through to here.
+                unsafe { stream.queue_raw_buffer(raw_buf) };
+            }
+        })
+        .register();
+
+    let mut params: [&pw::spa::pod::Pod; 0] = [];
+
+    if let Err(e) = stream.connect(
+        pw::spa::utils::Direction::Input,
+        Some(node_id),
+        StreamFlags::AUTOCONNECT | StreamFlags::MAP_BUFFERS,
+        &mut params,
+    ) {
+        if let Err(e) = event_tx.try_send(PwCtrlEvent::Error(format!("stream.connect failed: {e}")))
+        {
+            tracing::error!("stream.connect failed and error channel also failed: {e}");
+        }
+        return;
+    }
+
+    let loop_ = mainloop.loop_();
+
+    // Register the shutdown eventfd on the PipeWire loop.
+    //
+    // When CapPortal::drop writes to the eventfd, the loop wakes up and
+    // dispatches this callback on the loop thread. Because the callback
+    // only fires while mainloop.run() is blocking this thread, mainloop
+    // is guaranteed alive — eliminating the UAF that existed with the
+    // previous detached helper thread approach.
+    // 保存 mainloop 的原始指针，用于在 shutdown 回调中调用 pw_main_loop_quit
+    // 这是安全的，因为回调只在 mainloop.run() 阻塞期间执行
+    let mainloop_ptr = mainloop.as_raw_ptr();
+
+    let _shutdown_source = loop_.add_io(
+        shutdown_read,
+        libspa::support::system::IoFlags::IN,
+        move |fd| {
+            // Drain the eventfd so it doesn't re-trigger
+            let mut buf: u64 = 0;
+            // SAFETY: `fd` is the registered eventfd owned by the mainloop source; the
+            // buffer is a stack u64 of 8 bytes matching the count argument. POSIX
+            // read(2) is the standard fd-read syscall; eventfd semantics require the
+            // 8-byte buffer.
+            let _ = unsafe {
+                libc::read(
+                    fd.as_raw_fd(),
+                    &mut buf as *mut u64 as *mut _,
+                    std::mem::size_of::<u64>(),
+                )
+            };
+            // SAFETY: This callback only executes while mainloop.run() is
+            // blocking this thread, so mainloop is guaranteed alive.
+            unsafe { pipewire::sys::pw_main_loop_quit(mainloop_ptr) };
+        },
+    );
+
+    // 启动 PipeWire 主事件循环
+    // 此调用会阻塞当前线程，直到 mainloop.quit() 被调用
+    // quit() 由 shutdown eventfd 的 IO 回调触发
+    mainloop.run();
+
+    // run() returned — _shutdown_source drops first (reverse declaration order),
+    // which unregisters the callback from the loop. Then mainloop drops.
+    // No dangling raw pointers are possible.
+    // PipeWire global state is intentionally not deinitialized here — see pw::init() comment above.
+}
+
+pub(super) fn spawn_pipewire_thread(
+    frame_tx: Sender<PwDmaBufFrame>,
+    event_tx: Sender<PwCtrlEvent>,
+    dropped: Arc<AtomicU64>,
+    shutdown_read: OwnedFd,
+    pw_fd: OwnedFd,
+    node_id: u32,
+) -> Result<JoinHandle<()>> {
+    let ctx = PwThreadCtx {
+        frame_tx,
+        event_tx,
+        dropped,
+        shutdown_read,
+        pw_fd,
+        node_id,
+    };
+    thread::Builder::new()
+        .name("pipewire-capture".into())
+        .spawn(move || pipewire_thread(ctx))
+        .map_err(|e| anyhow::anyhow!("thread spawn failed: {e}"))
+}

src/cap_portal/setup.rs

@@ -0,0 +1,192 @@
+use std::os::fd::OwnedFd;
+
+use anyhow::Result;
+
+use super::logging::log_portal_phase_timeout;
+use super::token_fs::{delete_restore_token, load_restore_token, save_restore_token};
+use super::types::{PortalPhaseTimeout, PORTAL_SERVICE_TIMEOUT, PORTAL_USER_DIALOG_TIMEOUT};
+use super::CapPortal;
+
+impl CapPortal {
+    /// 通过 XDG Desktop Portal 建立屏幕录制会话
+    ///
+    /// 与桌面环境的 D-Bus 服务交互，请求用户授权屏幕录制。
+    /// 流程:
+    ///   1. 创建 Screencast 代理（D-Bus 代理）
+    ///   2. 创建 ScreenCast 会话
+    ///   3. 配置源选择参数（光标模式、显示器源、不持久化会话）
+    ///   4. 启动录制，获取流信息（包含 PipeWire node_id）
+    ///   5. 打开 PipeWire 远程连接，获取文件描述符
+    ///
+    /// 返回 (PipeWire fd, node_id)，供 PipeWire 线程连接使用
+    ///
+    /// Wraps `_setup_portal_inner` with token-aware retry: on a `TokenDependent`
+    /// timeout (phases 3 or 4 with a restore token in use) AND `no_persist ==
+    /// false`, clears the cached restore token and retries once with
+    /// `no_persist = true`.
+    pub(super) async fn setup_portal(no_persist: bool) -> Result<(OwnedFd, u32)> {
+        match Self::_setup_portal_inner(no_persist, false).await {
+            Ok(result) => Ok(result),
+            Err(e) if e.is::<PortalPhaseTimeout>() => {
+                let inner_err = e.downcast_ref::<PortalPhaseTimeout>().unwrap();
+                match inner_err {
+                    PortalPhaseTimeout::TokenDependent if !no_persist => {
+                        tracing::warn!(
+                            "Portal timed out during token-using phase. \
+                             Clearing cached restore token and retrying with fresh authorization."
+                        );
+                        delete_restore_token();
+                        Self::_setup_portal_inner(true, true).await
+                    }
+                    _ => Err(e),
+                }
+            }
+            Err(e) => Err(e),
+        }
+    }
+
+    /// Inner Portal setup with phased timeouts. See `setup_portal` for the
+    /// retry wrapper.
+    ///
+    /// `is_retry == true` disables further retry attempts (max 1 retry).
+    pub(super) async fn _setup_portal_inner(
+        no_persist: bool,
+        is_retry: bool,
+    ) -> Result<(OwnedFd, u32)> {
+        use ashpd::desktop::screencast::{
+            CursorMode, Screencast, SelectSourcesOptions, SourceType,
+        };
+        use ashpd::desktop::PersistMode;
+
+        // Phase 1: Screencast proxy (no user interaction).
+        let proxy = match tokio::time::timeout(PORTAL_SERVICE_TIMEOUT, Screencast::new()).await {
+            Ok(Ok(p)) => p,
+            Ok(Err(e)) => return Err(anyhow::anyhow!("Failed to create Screencast proxy: {e}")),
+            Err(_) => {
+                log_portal_phase_timeout("creating Screencast proxy", false);
+                return Err(PortalPhaseTimeout::Service.into());
+            }
+        };
+
+        // Phase 2: create_session (no user interaction).
+        let session = match tokio::time::timeout(
+            PORTAL_SERVICE_TIMEOUT,
+            proxy.create_session(Default::default()),
+        )
+        .await
+        {
+            Ok(Ok(s)) => s,
+            Ok(Err(e)) => return Err(anyhow::anyhow!("Failed to create ScreenCast session: {e}")),
+            Err(_) => {
+                log_portal_phase_timeout("creating session", false);
+                return Err(PortalPhaseTimeout::Service.into());
+            }
+        };
+
+        let version_supported = proxy.version() >= 4;
+
+        let (persist_mode, saved_token) = if !no_persist && version_supported {
+            let token = load_restore_token();
+            if token.is_some() {
+                if is_retry {
+                    tracing::info!("Re-attempting portal session after token clear");
+                } else {
+                    tracing::info!("Attempting to restore portal session with saved token");
+                }
+            }
+            (PersistMode::ExplicitlyRevoked, token)
+        } else {
+            (PersistMode::DoNot, None)
+        };
+
+        let mut options = SelectSourcesOptions::default()
+            .set_cursor_mode(CursorMode::Embedded)
+            .set_sources(ashpd::enumflags2::BitFlags::from(SourceType::Monitor))
+            .set_multiple(false)
+            .set_persist_mode(persist_mode);
+
+        if let Some(ref token) = saved_token {
+            options = options.set_restore_token(token.as_str());
+        }
+
+        // Phase 3: select_sources — token path is fast (no dialog); fresh
+        // authorization may pop a dialog.
+        let token_in_use = saved_token.is_some();
+        let phase3_timeout = if token_in_use {
+            PORTAL_SERVICE_TIMEOUT
+        } else {
+            PORTAL_USER_DIALOG_TIMEOUT
+        };
+        match tokio::time::timeout(phase3_timeout, proxy.select_sources(&session, options)).await {
+            Ok(Ok(_)) => {}
+            Ok(Err(e)) => return Err(anyhow::anyhow!("Screen sharing permission denied: {e}")),
+            Err(_) => {
+                log_portal_phase_timeout("selecting sources", token_in_use);
+                return Err(if token_in_use {
+                    PortalPhaseTimeout::TokenDependent
+                } else {
+                    PortalPhaseTimeout::Service
+                }
+                .into());
+            }
+        }
+
+        // Phase 4: start + response — same dialog-vs-token reasoning as phase 3.
+        let phase4_timeout = if token_in_use {
+            PORTAL_SERVICE_TIMEOUT
+        } else {
+            PORTAL_USER_DIALOG_TIMEOUT
+        };
+        let start_fut = async {
+            proxy
+                .start(&session, None, Default::default())
+                .await?
+                .response()
+        };
+        let response = match tokio::time::timeout(phase4_timeout, start_fut).await {
+            Ok(Ok(r)) => r,
+            Ok(Err(e)) => return Err(anyhow::anyhow!("ScreenCast start/response error: {e}")),
+            Err(_) => {
+                log_portal_phase_timeout("starting session", token_in_use);
+                return Err(if token_in_use {
+                    PortalPhaseTimeout::TokenDependent
+                } else {
+                    PortalPhaseTimeout::Service
+                }
+                .into());
+            }
+        };
+
+        if !no_persist && version_supported {
+            if let Some(new_token) = response.restore_token() {
+                save_restore_token(new_token);
+            }
+        }
+
+        let stream = response
+            .streams()
+            .first()
+            .ok_or_else(|| anyhow::anyhow!("No streams returned from ScreenCast"))?;
+
+        let node_id = stream.pipe_wire_node_id();
+
+        // Phase 5: open_pipe_wire_remote (no user interaction).
+        let fd = match tokio::time::timeout(
+            PORTAL_SERVICE_TIMEOUT,
+            proxy.open_pipe_wire_remote(&session, Default::default()),
+        )
+        .await
+        {
+            Ok(Ok(f)) => f,
+            Ok(Err(e)) => return Err(anyhow::anyhow!("Failed to open PipeWire remote: {e}")),
+            Err(_) => {
+                log_portal_phase_timeout("opening PipeWire remote", false);
+                return Err(PortalPhaseTimeout::Service.into());
+            }
+        };
+
+        tracing::info!("Portal session established: node_id={node_id}");
+
+        Ok((fd, node_id))
+    }
+}

src/cap_portal/token_fs.rs

@@ -0,0 +1,362 @@
+use std::path::PathBuf;
+
+pub(super) fn token_path() -> Option<PathBuf> {
+    dirs::cache_dir().map(|base| base.join("wl-webrtc").join("portal-restore-token"))
+}
+
+/// Verify that `path` is a directory owned by the current user with no group/other permissions.
+/// Rejects symlinks at the path itself (but allows the resolved target to be a real dir).
+pub(super) fn verify_secure_dir(path: &std::path::Path) -> bool {
+    use std::os::unix::fs::{MetadataExt, PermissionsExt};
+
+    match std::fs::symlink_metadata(path) {
+        Ok(meta) => {
+            if meta.file_type().is_symlink() {
+                tracing::warn!(
+                    "Token parent dir is a symlink, rejecting: {}",
+                    path.display()
+                );
+                return false;
+            }
+            // Must be a directory
+            if !meta.is_dir() {
+                tracing::warn!("Token parent path is not a directory: {}", path.display());
+                return false;
+            }
+            // Must be owned by current user
+            // SAFETY: libc::getuid has no preconditions and cannot fail; it simply
+            // returns the calling process's real user ID.
+            // SAFETY: libc::getuid has no preconditions and cannot fail.
+            if meta.uid() != unsafe { libc::getuid() } {
+                tracing::warn!(
+                    "Token parent dir not owned by current user: {}",
+                    path.display()
+                );
+                return false;
+            }
+            // No group or other permissions (mode must be 0o700 exactly within the 0o777 mask)
+            let mode = meta.permissions().mode() & 0o777;
+            if mode != 0o700 {
+                tracing::warn!(
+                    "Token parent dir has insecure permissions {:o}, expected 0700: {}",
+                    mode,
+                    path.display()
+                );
+                return false;
+            }
+            true
+        }
+        Err(e) => {
+            tracing::warn!("Failed to stat token parent dir: {e}");
+            false
+        }
+    }
+}
+
+/// Ensure the parent directory exists with restrictive permissions (0o700).
+/// Returns false if the directory could not be created or is insecure.
+pub(super) fn ensure_secure_parent(parent: &std::path::Path) -> bool {
+    use std::os::unix::fs::{DirBuilderExt, PermissionsExt};
+
+    if parent.exists() {
+        // Directory exists — try to tighten permissions, then verify.
+        // set_permissions follows symlinks, which is fine here since
+        // we verify with symlink_metadata in verify_secure_dir.
+        if let Err(e) = std::fs::set_permissions(parent, std::fs::Permissions::from_mode(0o700)) {
+            tracing::warn!("Failed to set directory permissions: {e}");
+            return false;
+        }
+        return verify_secure_dir(parent);
+    }
+
+    // Create with restrictive mode — DirBuilderExt::mode bypasses umask.
+    let mut builder = std::fs::DirBuilder::new();
+    builder.recursive(true);
+    builder.mode(0o700);
+    if let Err(e) = builder.create(parent) {
+        tracing::warn!("Failed to create token directory: {e}");
+        return false;
+    }
+
+    // Verify after creation (belt-and-suspenders)
+    verify_secure_dir(parent)
+}
+
+pub(super) fn load_restore_token() -> Option<String> {
+    load_restore_token_from(token_path()?)
+}
+
+pub(super) fn load_restore_token_from(path: PathBuf) -> Option<String> {
+    use std::os::unix::fs::{MetadataExt, PermissionsExt};
+
+    let meta = match std::fs::symlink_metadata(&path) {
+        Ok(m) => m,
+        Err(_) => return None,
+    };
+
+    if meta.file_type().is_symlink() {
+        tracing::warn!(
+            "Token file is a symlink, refusing to read: {}",
+            path.display()
+        );
+        return None;
+    }
+    if !meta.is_file() {
+        tracing::warn!("Token path is not a regular file: {}", path.display());
+        return None;
+    }
+    // SAFETY: libc::getuid has no preconditions and cannot fail.
+    if meta.uid() != unsafe { libc::getuid() } {
+        tracing::warn!("Token file not owned by current user: {}", path.display());
+        return None;
+    }
+    let mode = meta.permissions().mode() & 0o777;
+    if mode & 0o077 != 0 {
+        tracing::warn!(
+            "Token file has insecure permissions {:o}, refusing to read: {}",
+            mode,
+            path.display()
+        );
+        return None;
+    }
+
+    let token = std::fs::read_to_string(&path).ok()?;
+    let trimmed = token.trim().to_string();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+pub(super) fn save_restore_token(token: &str) {
+    let Some(path) = token_path() else {
+        tracing::warn!("No secure cache directory available, skipping token save");
+        return;
+    };
+    save_restore_token_to(token, &path);
+}
+
+pub(super) fn delete_restore_token() {
+    let Some(path) = token_path() else {
+        return;
+    };
+    match std::fs::remove_file(&path) {
+        Ok(()) => tracing::info!("Deleted stale portal restore token at {}", path.display()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+        Err(e) => tracing::warn!(
+            "Failed to delete stale restore token at {}: {e}",
+            path.display()
+        ),
+    }
+}
+
+pub(super) fn save_restore_token_to(token: &str, path: &std::path::Path) {
+    use std::fs::OpenOptions;
+    use std::io::Write;
+    use std::os::unix::fs::OpenOptionsExt;
+
+    let Some(parent) = path.parent() else {
+        tracing::warn!("Token path has no parent directory");
+        return;
+    };
+
+    if !ensure_secure_parent(parent) {
+        tracing::warn!("Parent directory is insecure, refusing to save token");
+        return;
+    }
+
+    // Use a unique temp file to prevent symlink attacks.
+    // create_new(true) guarantees exclusive creation — fails if file already exists,
+    // and does NOT follow existing symlinks.
+    let tmp_path = path.with_extension(format!("{}.tmp", std::process::id()));
+    let result = (|| -> std::io::Result<()> {
+        let mut f = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .mode(0o600)
+            .open(&tmp_path)?;
+        f.write_all(token.as_bytes())?;
+        f.sync_all()?;
+        std::fs::rename(&tmp_path, path)?;
+        Ok(())
+    })();
+    match result {
+        Ok(()) => tracing::info!("Saved portal restore token"),
+        Err(e) => {
+            let _ = std::fs::remove_file(&tmp_path);
+            tracing::warn!("Failed to save restore token: {e}");
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::os::unix::fs::PermissionsExt;
+
+    #[test]
+    fn token_path_never_uses_tmp() {
+        assert!(token_path().is_some(), "token_path should resolve on Linux");
+        let path = token_path().unwrap();
+        assert!(!path.starts_with("/tmp"), "must not fallback to /tmp");
+    }
+
+    #[test]
+    fn verify_secure_dir_rejects_wrong_permissions() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path();
+
+        // 0o700 should pass
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700)).unwrap();
+        assert!(verify_secure_dir(path));
+
+        // 0o755 should fail
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();
+        assert!(!verify_secure_dir(path));
+
+        // 0o777 should fail
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o777)).unwrap();
+        assert!(!verify_secure_dir(path));
+    }
+
+    #[test]
+    fn verify_secure_dir_rejects_non_directory() {
+        let dir = tempfile::tempdir().unwrap();
+        let file_path = dir.path().join("not-a-dir");
+        std::fs::write(&file_path, b"test").unwrap();
+        assert!(!verify_secure_dir(&file_path));
+    }
+
+    #[test]
+    fn ensure_secure_parent_creates_with_0700() {
+        let base = tempfile::tempdir().unwrap();
+        let new_dir = base.path().join("wl-test-new-dir");
+        assert!(!new_dir.exists());
+
+        assert!(ensure_secure_parent(&new_dir));
+        assert!(new_dir.is_dir());
+
+        let meta = std::fs::symlink_metadata(&new_dir).unwrap();
+        let mode = meta.permissions().mode() & 0o777;
+        assert_eq!(
+            mode, 0o700,
+            "created directory should be 0700, got {mode:o}"
+        );
+    }
+
+    #[test]
+    fn ensure_secure_parent_tightens_existing_dir() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path();
+
+        // Simulate an existing directory with loose permissions
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+        assert!(ensure_secure_parent(path));
+
+        let meta = std::fs::symlink_metadata(path).unwrap();
+        let mode = meta.permissions().mode() & 0o777;
+        assert_eq!(
+            mode, 0o700,
+            "tightened directory should be 0700, got {mode:o}"
+        );
+    }
+
+    #[test]
+    fn save_creates_file_with_0600() {
+        let dir = tempfile::tempdir().unwrap();
+        let token_path = dir.path().join("portal-restore-token");
+
+        save_restore_token_to("secret-token-123", &token_path);
+
+        assert!(token_path.exists());
+        let meta = std::fs::symlink_metadata(&token_path).unwrap();
+        let mode = meta.permissions().mode() & 0o777;
+        assert_eq!(mode, 0o600, "token file should be 0600, got {mode:o}");
+        assert_eq!(
+            std::fs::read_to_string(&token_path).unwrap(),
+            "secret-token-123"
+        );
+    }
+
+    #[test]
+    fn load_reads_secure_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let token_path = dir.path().join("portal-restore-token");
+
+        // Write a valid 0o600 token file
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut f = std::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .mode(0o600)
+            .open(&token_path)
+            .unwrap();
+        std::io::Write::write_all(&mut f, b"my-secret\n").unwrap();
+
+        let result = load_restore_token_from(token_path);
+        assert_eq!(result, Some("my-secret".to_string()));
+    }
+
+    #[test]
+    fn load_rejects_group_readable_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let token_path = dir.path().join("portal-restore-token");
+
+        // Write with 0o640 (group readable) — should be rejected
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut f = std::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .mode(0o640)
+            .open(&token_path)
+            .unwrap();
+        std::io::Write::write_all(&mut f, b"leaked-token\n").unwrap();
+
+        let result = load_restore_token_from(token_path);
+        assert!(result.is_none(), "should reject group-readable token file");
+    }
+
+    #[test]
+    fn load_rejects_world_readable_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let token_path = dir.path().join("portal-restore-token");
+
+        use std::os::unix::fs::OpenOptionsExt;
+        let mut f = std::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .mode(0o604)
+            .open(&token_path)
+            .unwrap();
+        std::io::Write::write_all(&mut f, b"leaked-token\n").unwrap();
+
+        let result = load_restore_token_from(token_path);
+        assert!(result.is_none(), "should reject world-readable token file");
+    }
+
+    #[test]
+    fn load_rejects_symlink() {
+        let dir = tempfile::tempdir().unwrap();
+        let real_path = dir.path().join("real-file");
+        let link_path = dir.path().join("portal-restore-token");
+
+        std::fs::write(&real_path, b"target-content\n").unwrap();
+        std::os::unix::fs::symlink(&real_path, &link_path).unwrap();
+
+        let result = load_restore_token_from(link_path);
+        assert!(result.is_none(), "should reject symlinked token file");
+    }
+
+    #[test]
+    fn save_then_load_roundtrip() {
+        let dir = tempfile::tempdir().unwrap();
+        let token_path = dir.path().join("portal-restore-token");
+
+        save_restore_token_to("roundtrip-token", &token_path);
+        let loaded = load_restore_token_from(token_path);
+
+        assert_eq!(loaded, Some("roundtrip-token".to_string()));
+    }
+}

src/cap_portal/types.rs

@@ -0,0 +1,79 @@
+use std::os::fd::OwnedFd;
+
+pub(super) const PORTAL_SERVICE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
+pub(super) const PORTAL_USER_DIALOG_TIMEOUT: std::time::Duration =
+    std::time::Duration::from_secs(30);
+
+/// Classification of Portal phase timeouts to drive retry behavior.
+#[derive(Debug)]
+pub(super) enum PortalPhaseTimeout {
+    /// Portal service unresponsive; not retried (user should restart service).
+    Service,
+    /// Timed out in token-dependent phase; retried once after clearing token.
+    TokenDependent,
+}
+
+impl std::fmt::Display for PortalPhaseTimeout {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Service => write!(f, "Portal phase timed out (service)"),
+            Self::TokenDependent => write!(f, "Portal phase timed out (token-dependent)"),
+        }
+    }
+}
+
+impl std::error::Error for PortalPhaseTimeout {}
+
+/// PipeWire DMA-BUF 帧数据
+///
+/// 表示从 PipeWire 流中接收到的一帧视频数据。
+/// 帧的像素数据存储在 DMA-BUF（Linux 的零拷贝 buffer 共享机制）中，
+/// 通过文件描述符 (fd) 引用，消费者通过 mmap 或 DRM 导入来访问像素数据。
+pub struct PwDmaBufFrame {
+    /// DMA-BUF 文件描述符，指向 GPU 显存中的帧缓冲区
+    pub fd: OwnedFd,
+    /// 帧数据在 DMA-BUF 中的字节偏移量
+    pub offset: u64,
+    /// 每行像素的字节跨度（可能大于 width * bpp，因为可能有对齐填充）
+    pub stride: u32,
+    /// DRM 格式修饰符，描述 buffer 的内存布局（如线性布局、tiling 等）
+    pub modifier: u64,
+    /// 帧宽度（像素）
+    pub width: u32,
+    /// 帧高度（像素）
+    pub height: u32,
+    /// DRM FourCC 格式标识符（如 BGRA、RGBA 等）
+    pub format: u32,
+    /// 显示时间戳 (PTS, Presentation Time Stamp)，单位为纳秒
+    pub pts: i64,
+}
+
+/// PipeWire-negotiated video format snapshot, stashed in a `Cell` for cross-callback
+/// sharing (format-change callback writes it; process callback reads it). The four
+/// fields are the minimal subset of `PwDmaBufFrame`'s metadata that the process
+/// callback needs to construct the frame once a buffer arrives.
+///
+/// `Copy` is required because we store it inside `Cell<Option<PortalFormatInfo>>`;
+/// `Cell` requires its contents to be `Copy` (no borrowed interior state).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PortalFormatInfo {
+    pub width: u32,
+    pub height: u32,
+    /// DRM FourCC format code (e.g. `0x34325258` for XR24 / XRGB8888).
+    pub drm_format: u32,
+    /// DRM format modifier describing buffer layout (linear, tiling, etc.).
+    pub modifier: u64,
+}
+
+/// PipeWire 控制事件枚举
+///
+/// 从 PipeWire 捕获线程发送给消费者的控制事件。
+/// 与帧数据分离，通过独立的 channel 传输，确保控制事件不被帧数据淹没。
+pub enum PwCtrlEvent {
+    /// 流已结束（PipeWire 流断开连接或进入错误状态）
+    StreamEnded,
+    /// Format/dimensions changed mid-stream
+    FormatChanged { width: u32, height: u32 },
+    /// 发生错误，包含错误描述信息
+    Error(String),
+}

src/state/dispatch/buffer.rs

@@ -0,0 +1,19 @@
+use wayland_client::protocol::wl_buffer::WlBuffer;
+use wayland_client::{Dispatch, Proxy, QueueHandle};
+
+use crate::state::{CaptureSource, State};
+
+impl<S: CaptureSource> Dispatch<WlBuffer, ()> for State<S> {
+    fn event(
+        _state: &mut Self,
+        _proxy: &WlBuffer,
+        event: <WlBuffer as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        if let wayland_client::protocol::wl_buffer::Event::Release = event {
+            tracing::trace!("WlBuffer released");
+        }
+    }
+}

src/state/dispatch/dmabuf.rs

@@ -0,0 +1,115 @@
+use std::mem;
+use std::path::PathBuf;
+
+use wayland_client::{Dispatch, Proxy, QueueHandle};
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_buffer_params_v1::{
+    Event as BufferParamsEvent, ZwpLinuxBufferParamsV1,
+};
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_feedback_v1::{
+    Event as DmabufFeedbackEvent, ZwpLinuxDmabufFeedbackV1,
+};
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_v1::{
+    Event as DmabufEvent, ZwpLinuxDmabufV1,
+};
+
+use crate::state::{CaptureSource, EncConstructionStage, InFlightSurface, State};
+
+impl<S: CaptureSource> Dispatch<ZwpLinuxDmabufV1, ()> for State<S> {
+    fn event(
+        _state: &mut Self,
+        _proxy: &ZwpLinuxDmabufV1,
+        event: <ZwpLinuxDmabufV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        match event {
+            DmabufEvent::Format { .. } => {}
+            DmabufEvent::Modifier { .. } => {}
+            _ => {}
+        }
+    }
+}
+
+impl<S: CaptureSource> Dispatch<ZwpLinuxDmabufFeedbackV1, ()> for State<S> {
+    fn event(
+        state: &mut Self,
+        _proxy: &ZwpLinuxDmabufFeedbackV1,
+        event: <ZwpLinuxDmabufFeedbackV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        match event {
+            DmabufFeedbackEvent::MainDevice { device } => {
+                if device.len() >= 8 {
+                    let dev_bytes: [u8; 8] = device[..8].try_into().unwrap_or([0u8; 8]);
+                    let dev = u64::from_ne_bytes(dev_bytes);
+                    let minor = ((dev & 0xFF) | ((dev >> 12) & 0xFFFFFF00)) as u32;
+                    let path = PathBuf::from(format!("/dev/dri/renderD{}", minor));
+                    if path.exists() {
+                        tracing::info!(
+                            "Compositor DRM device: {} (dev_t: {})",
+                            path.display(),
+                            dev
+                        );
+                        state.drm_device_from_compositor = Some(path);
+                    } else {
+                        tracing::warn!(
+                            "Compositor reported DRM device {} (dev_t: {}) but path does not exist",
+                            path.display(),
+                            dev
+                        );
+                    }
+                } else {
+                    tracing::warn!(
+                        "main_device event with unexpected data length: {}",
+                        device.len()
+                    );
+                }
+            }
+            DmabufFeedbackEvent::FormatTable { .. } => {}
+            DmabufFeedbackEvent::Done => {}
+            DmabufFeedbackEvent::TrancheDone => {}
+            DmabufFeedbackEvent::TrancheTargetDevice { .. } => {}
+            DmabufFeedbackEvent::TrancheFormats { .. } => {}
+            DmabufFeedbackEvent::TrancheFlags { .. } => {}
+            _ => {}
+        }
+    }
+}
+
+impl<S: CaptureSource> Dispatch<ZwpLinuxBufferParamsV1, ()> for State<S> {
+    fn event(
+        state: &mut Self,
+        proxy: &ZwpLinuxBufferParamsV1,
+        event: <ZwpLinuxBufferParamsV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        match event {
+            BufferParamsEvent::Created { .. } => {
+                tracing::debug!("DMA-BUF buffer created");
+            }
+            BufferParamsEvent::Failed => {
+                tracing::error!("DMA-BUF buffer creation failed");
+                let taken = mem::replace(&mut state.in_flight_surface, InFlightSurface::None);
+                match taken {
+                    InFlightSurface::CopyQueued { buffer, frame, .. } => {
+                        drop(buffer);
+                        if let EncConstructionStage::Streaming { cap, .. } = &mut state.stage {
+                            cap.on_done_with_frame(frame);
+                        }
+                    }
+                    other => {
+                        state.in_flight_surface = other;
+                    }
+                }
+                proxy.destroy();
+                state.errored = true;
+            }
+            _ => {}
+        }
+    }
+}

src/state/dispatch/mod.rs

@@ -0,0 +1,6 @@
+mod buffer;
+mod dmabuf;
+mod output_mgr;
+mod registry;
+mod screencopy;
+mod wl_output;

src/state/dispatch/output_mgr.rs

@@ -0,0 +1,109 @@
+use wayland_client::{event_created_child, Dispatch, Proxy, QueueHandle};
+use wayland_protocols::xdg::xdg_output::zv1::client::zxdg_output_manager_v1::ZxdgOutputManagerV1;
+use wayland_protocols_wlr::output_management::v1::client::zwlr_output_head_v1::{
+    self, Event as WlrHeadEvent, ZwlrOutputHeadV1,
+};
+use wayland_protocols_wlr::output_management::v1::client::zwlr_output_manager_v1::{
+    self, Event as WlrOutputManagerEvent, ZwlrOutputManagerV1,
+};
+use wayland_protocols_wlr::output_management::v1::client::zwlr_output_mode_v1::ZwlrOutputModeV1;
+
+use crate::state::{CaptureSource, EncConstructionStage, State, WlrHeadInfo};
+
+impl<S: CaptureSource> Dispatch<ZxdgOutputManagerV1, ()> for State<S> {
+    fn event(
+        _state: &mut Self,
+        _proxy: &ZxdgOutputManagerV1,
+        _event: <ZxdgOutputManagerV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+    }
+}
+
+impl<S: CaptureSource> Dispatch<ZwlrOutputManagerV1, ()> for State<S> {
+    fn event(
+        state: &mut Self,
+        _proxy: &ZwlrOutputManagerV1,
+        event: <ZwlrOutputManagerV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        match event {
+            WlrOutputManagerEvent::Head { head } => {
+                let _head: ZwlrOutputHeadV1 = head;
+                tracing::debug!("wlr output head advertised");
+            }
+            WlrOutputManagerEvent::Done { .. } => {
+                if let EncConstructionStage::ProbingOutputs {
+                    wlr_manager_done,
+                    outputs,
+                    ..
+                } = &mut state.stage
+                {
+                    *wlr_manager_done = true;
+                    let count = outputs.len();
+                    for idx in 0..count {
+                        state.try_finalize_output(idx);
+                    }
+                }
+            }
+            WlrOutputManagerEvent::Finished => {
+                tracing::warn!("zwlr_output_manager_v1::Finished received during probing");
+            }
+            _ => {}
+        }
+    }
+
+    event_created_child!(State<S>, ZwlrOutputManagerV1, [
+        zwlr_output_manager_v1::EVT_HEAD_OPCODE => (ZwlrOutputHeadV1, ()),
+    ]);
+}
+
+impl<S: CaptureSource> Dispatch<ZwlrOutputHeadV1, ()> for State<S> {
+    fn event(
+        state: &mut Self,
+        proxy: &ZwlrOutputHeadV1,
+        event: <ZwlrOutputHeadV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        match event {
+            WlrHeadEvent::Name { name } => {
+                if let EncConstructionStage::ProbingOutputs {
+                    wlr_heads,
+                    wlr_head_proxy_to_name,
+                    ..
+                } = &mut state.stage
+                {
+                    wlr_heads.entry(name.clone()).or_insert(WlrHeadInfo {});
+                    wlr_head_proxy_to_name.insert(proxy.id(), name);
+                }
+            }
+            WlrHeadEvent::Position { .. } => {}
+            WlrHeadEvent::Finished => {
+                tracing::debug!("zwlr_output_head_v1::Finished received");
+            }
+            _ => {}
+        }
+    }
+
+    event_created_child!(State<S>, ZwlrOutputHeadV1, [
+        zwlr_output_head_v1::EVT_MODE_OPCODE => (ZwlrOutputModeV1, ()),
+    ]);
+}
+
+impl<S: CaptureSource> Dispatch<ZwlrOutputModeV1, ()> for State<S> {
+    fn event(
+        _state: &mut Self,
+        _proxy: &ZwlrOutputModeV1,
+        _event: <ZwlrOutputModeV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+    }
+}

src/state/dispatch/registry.rs

@@ -0,0 +1,116 @@
+use wayland_client::globals::GlobalListContents;
+use wayland_client::protocol::wl_output::WlOutput;
+use wayland_client::protocol::wl_registry::WlRegistry;
+use wayland_client::{Dispatch, QueueHandle};
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_v1::ZwpLinuxDmabufV1;
+use wayland_protocols::xdg::xdg_output::zv1::client::zxdg_output_manager_v1::ZxdgOutputManagerV1;
+use wayland_protocols_wlr::output_management::v1::client::zwlr_output_manager_v1::ZwlrOutputManagerV1;
+use wayland_protocols_wlr::screencopy::v1::client::zwlr_screencopy_manager_v1::ZwlrScreencopyManagerV1;
+
+use crate::state::{CaptureSource, EncConstructionStage, OutputId, PartialOutputInfo, State};
+
+impl<S: CaptureSource> Dispatch<WlRegistry, GlobalListContents> for State<S> {
+    fn event(
+        state: &mut Self,
+        registry: &WlRegistry,
+        event: wayland_client::protocol::wl_registry::Event,
+        _data: &GlobalListContents,
+        _conn: &wayland_client::Connection,
+        qhandle: &QueueHandle<State<S>>,
+    ) {
+        use wayland_client::protocol::wl_registry::Event as RegistryEvent;
+
+        match event {
+            RegistryEvent::Global {
+                name,
+                interface,
+                version,
+            } => match interface.as_str() {
+                "zwlr_screencopy_manager_v1" => {
+                    let v = version.min(3);
+                    tracing::debug!("Binding zwlr_screencopy_manager_v1 v{v} (name={name})");
+                    let mgr: ZwlrScreencopyManagerV1 = registry.bind(name, v, qhandle, ());
+                    if let EncConstructionStage::ProbingOutputs {
+                        screencopy_manager, ..
+                    } = &mut state.stage
+                    {
+                        *screencopy_manager = Some(mgr);
+                    }
+                }
+                "zwp_linux_dmabuf_v1" => {
+                    let v = version.min(4);
+                    tracing::debug!("Binding zwp_linux_dmabuf_v1 v{v} (name={name})");
+                    let proxy: ZwpLinuxDmabufV1 = registry.bind(name, v, qhandle, ());
+                    if let EncConstructionStage::ProbingOutputs {
+                        dmabuf,
+                        dmabuf_feedback,
+                        ..
+                    } = &mut state.stage
+                    {
+                        *dmabuf = Some(proxy.clone());
+                        if v >= 4 {
+                            let feedback = proxy.get_default_feedback(qhandle, ());
+                            *dmabuf_feedback = Some(feedback);
+                        }
+                    }
+                }
+                "wl_output" => {
+                    let v = version.min(4);
+                    tracing::debug!("Binding wl_output v{v} (name={name})");
+                    let output: WlOutput = registry.bind(name, v, qhandle, OutputId(name));
+                    if let EncConstructionStage::ProbingOutputs {
+                        outputs,
+                        bound_outputs,
+                        output_names,
+                        xdg_output_manager,
+                        ..
+                    } = &mut state.stage
+                    {
+                        outputs.push(PartialOutputInfo::default());
+                        bound_outputs.push(output.clone());
+                        output_names.push(name);
+                        if let Some(xdg_mgr) = xdg_output_manager {
+                            let output_id = OutputId(name);
+                            xdg_mgr.get_xdg_output(&output, qhandle, output_id);
+                        }
+                    }
+                }
+                "zxdg_output_manager_v1" => {
+                    let v = version.min(3);
+                    tracing::debug!("Binding zxdg_output_manager_v1 v{v} (name={name})");
+                    let xdg_mgr: ZxdgOutputManagerV1 = registry.bind(name, v, qhandle, ());
+                    if let EncConstructionStage::ProbingOutputs {
+                        bound_outputs,
+                        xdg_output_manager,
+                        output_names,
+                        ..
+                    } = &mut state.stage
+                    {
+                        for (i, output) in bound_outputs.iter().enumerate() {
+                            let oname = output_names.get(i).copied().unwrap_or(0);
+                            let output_id = OutputId(oname);
+                            xdg_mgr.get_xdg_output(output, qhandle, output_id);
+                        }
+                        *xdg_output_manager = Some(xdg_mgr);
+                    }
+                }
+                "zwlr_output_manager_v1" => {
+                    let v = version.min(4);
+                    tracing::debug!("Binding zwlr_output_manager_v1 v{v} (name={name})");
+                    let mgr: ZwlrOutputManagerV1 = registry.bind(name, v, qhandle, ());
+                    if let EncConstructionStage::ProbingOutputs {
+                        wlr_output_manager, ..
+                    } = &mut state.stage
+                    {
+                        *wlr_output_manager = Some(mgr);
+                    }
+                }
+                _ => {}
+            },
+            RegistryEvent::GlobalRemove { name } => {
+                tracing::debug!("Global removed: name={name}");
+            }
+            _ => {}
+        }
+    }
+}

src/state/dispatch/screencopy.rs

@@ -0,0 +1,93 @@
+use wayland_client::{Dispatch, Proxy, QueueHandle};
+use wayland_protocols_wlr::screencopy::v1::client::zwlr_screencopy_frame_v1::{
+    Event as ScreencopyFrameEvent, ZwlrScreencopyFrameV1,
+};
+use wayland_protocols_wlr::screencopy::v1::client::zwlr_screencopy_manager_v1::ZwlrScreencopyManagerV1;
+
+use crate::cap_wlr_screencopy::CapWlrScreencopy;
+use crate::state::{EncConstructionStage, InFlightSurface, State};
+
+impl Dispatch<ZwlrScreencopyFrameV1, ()> for State<CapWlrScreencopy> {
+    fn event(
+        state: &mut Self,
+        proxy: &ZwlrScreencopyFrameV1,
+        event: <ZwlrScreencopyFrameV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<CapWlrScreencopy>>,
+    ) {
+        match event {
+            // SHM buffer offer — in v3 the compositor enumerates supported buffer
+            // types (buffer and/or linux_dmabuf) before buffer_done.  We only
+            // support DMA-BUF, so just log and wait for linux_dmabuf / buffer_done.
+            ScreencopyFrameEvent::Buffer { .. } => {
+                tracing::debug!("Received SHM Buffer offer — only DMA-BUF capture is supported");
+            }
+            ScreencopyFrameEvent::LinuxDmabuf {
+                format,
+                width,
+                height,
+            } => {
+                tracing::debug!("Screencopy LinuxDmabuf: format={format}, {width}x{height}");
+
+                if !matches!(state.in_flight_surface, InFlightSurface::AllocQueued) {
+                    tracing::warn!("Received LinuxDmabuf while no frame allocation was queued");
+                    return;
+                }
+
+                if matches!(state.stage, EncConstructionStage::EverythingButFmt { .. }) {
+                    state.negotiate_format(format, width, height);
+                    if state.errored {
+                        return;
+                    }
+                }
+                if let EncConstructionStage::Streaming { cap, .. } = &mut state.stage {
+                    cap.current_frame = Some(proxy.clone());
+                }
+                state.on_frame_allocd((), format, width, height);
+            }
+            // v3 terminal event: all buffer offers have been enumerated.
+            // If still AllocQueued, the compositor never sent linux_dmabuf —
+            // DMA-BUF screencopy is unsupported, so we must error out.
+            ScreencopyFrameEvent::BufferDone => {
+                if matches!(state.in_flight_surface, InFlightSurface::AllocQueued) {
+                    tracing::error!(
+                        "Compositor did not offer DMA-BUF screencopy (only SHM); \
+                         DMA-BUF capture is required"
+                    );
+                    state.in_flight_surface = InFlightSurface::None;
+                    proxy.destroy();
+                    state.errored = true;
+                }
+            }
+            ScreencopyFrameEvent::Ready {
+                tv_sec_hi,
+                tv_sec_lo,
+                tv_nsec,
+            } => {
+                let tv_sec = (tv_sec_hi as u64) << 32 | tv_sec_lo as u64;
+                let tv_usec = tv_nsec / 1000;
+                tracing::trace!("Screencopy ready: tv_sec={tv_sec}, tv_usec={tv_usec}");
+                state.on_copy_complete(tv_sec, tv_usec);
+            }
+            ScreencopyFrameEvent::Failed => {
+                tracing::error!("Screencopy frame failed");
+                state.on_copy_fail();
+            }
+            ScreencopyFrameEvent::Damage { .. } => {}
+            _ => {}
+        }
+    }
+}
+
+impl<S: crate::state::CaptureSource> Dispatch<ZwlrScreencopyManagerV1, ()> for State<S> {
+    fn event(
+        _state: &mut Self,
+        _proxy: &ZwlrScreencopyManagerV1,
+        _event: <ZwlrScreencopyManagerV1 as Proxy>::Event,
+        _data: &(),
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+    }
+}

src/state/dispatch/wl_output.rs

@@ -0,0 +1,133 @@
+use wayland_client::protocol::wl_output::WlOutput;
+use wayland_client::{Dispatch, Proxy, QueueHandle};
+use wayland_protocols::xdg::xdg_output::zv1::client::zxdg_output_v1::{
+    Event as XdgOutputEvent, ZxdgOutputV1,
+};
+
+use crate::state::{CaptureSource, EncConstructionStage, OutputId, State, Transform};
+
+impl<S: CaptureSource> Dispatch<WlOutput, OutputId> for State<S> {
+    fn event(
+        state: &mut Self,
+        _proxy: &WlOutput,
+        event: wayland_client::protocol::wl_output::Event,
+        data: &OutputId,
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        use wayland_client::protocol::wl_output::Event as OutputEvent;
+        use wayland_client::protocol::wl_output::Mode as WlMode;
+        use wayland_client::protocol::wl_output::Transform as WlTransform;
+
+        let OutputId(target_name) = data;
+        let idx = match &state.stage {
+            EncConstructionStage::ProbingOutputs { output_names, .. } => {
+                output_names.iter().position(|&n| n == *target_name)
+            }
+            _ => None,
+        };
+        let idx = match idx {
+            Some(i) => i,
+            None => return,
+        };
+
+        match event {
+            OutputEvent::Geometry { transform, .. } => {
+                let t = match transform {
+                    wayland_client::WEnum::Value(WlTransform::Normal) => Transform::Normal,
+                    wayland_client::WEnum::Value(WlTransform::_90) => Transform::Normal90,
+                    wayland_client::WEnum::Value(WlTransform::_180) => Transform::Normal180,
+                    wayland_client::WEnum::Value(WlTransform::_270) => Transform::Normal270,
+                    wayland_client::WEnum::Value(WlTransform::Flipped) => Transform::Flipped,
+                    wayland_client::WEnum::Value(WlTransform::Flipped90) => Transform::Flipped90,
+                    wayland_client::WEnum::Value(WlTransform::Flipped180) => Transform::Flipped180,
+                    wayland_client::WEnum::Value(WlTransform::Flipped270) => Transform::Flipped270,
+                    _ => Transform::Normal,
+                };
+                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
+                    if let Some(info) = outputs.get_mut(idx) {
+                        info.transform = Some(t);
+                    }
+                }
+            }
+            OutputEvent::Mode {
+                width,
+                height,
+                flags,
+                ..
+            } => {
+                let is_current = matches!(flags, wayland_client::WEnum::Value(WlMode::Current));
+                if is_current {
+                    if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
+                        if let Some(info) = outputs.get_mut(idx) {
+                            info.mode_size = Some((width, height));
+                        }
+                    }
+                }
+            }
+            OutputEvent::Done => {
+                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
+                    if let Some(info) = outputs.get_mut(idx) {
+                        info.done_count += 1;
+                        if info.done_count >= 1 {
+                            state.try_finalize_output(idx);
+                        }
+                    }
+                }
+            }
+            OutputEvent::Name { name } => {
+                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
+                    if let Some(info) = outputs.get_mut(idx) {
+                        info.wl_name = Some(name);
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+impl<S: CaptureSource> Dispatch<ZxdgOutputV1, OutputId> for State<S> {
+    fn event(
+        state: &mut Self,
+        _proxy: &ZxdgOutputV1,
+        event: <ZxdgOutputV1 as Proxy>::Event,
+        data: &OutputId,
+        _conn: &wayland_client::Connection,
+        _qhandle: &QueueHandle<State<S>>,
+    ) {
+        let target_name = data.0;
+        let idx = match &state.stage {
+            EncConstructionStage::ProbingOutputs { output_names, .. } => {
+                output_names.iter().position(|&n| n == target_name)
+            }
+            _ => None,
+        };
+        let idx = match idx {
+            Some(i) => i,
+            None => return,
+        };
+
+        match event {
+            XdgOutputEvent::Name { name } => {
+                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
+                    if let Some(info) = outputs.get_mut(idx) {
+                        info.name = Some(name);
+                    }
+                }
+            }
+            XdgOutputEvent::LogicalSize { .. } => {}
+            XdgOutputEvent::Done => {
+                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
+                    if let Some(info) = outputs.get_mut(idx) {
+                        info.done_count += 1;
+                        if info.done_count >= 1 {
+                            state.try_finalize_output(idx);
+                        }
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}

src/state/mod.rs

@@ -9,34 +9,16 @@ use std::time::Instant;
 
 use anyhow::Result;
 use wayland_client::backend::ObjectId;
-use wayland_client::globals::{GlobalList, GlobalListContents};
+use wayland_client::globals::GlobalList;
 use wayland_client::protocol::wl_buffer::WlBuffer;
 use wayland_client::protocol::wl_output::WlOutput;
-use wayland_client::protocol::wl_registry::WlRegistry;
-use wayland_client::{event_created_child, Dispatch, Proxy, QueueHandle};
-use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_buffer_params_v1::{
-    Event as BufferParamsEvent, Flags as BufferParamsFlags, ZwpLinuxBufferParamsV1,
-};
-use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_feedback_v1::{
-    Event as DmabufFeedbackEvent, ZwpLinuxDmabufFeedbackV1,
-};
-use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_v1::{
-    Event as DmabufEvent, ZwpLinuxDmabufV1,
-};
+use wayland_client::{Dispatch, QueueHandle};
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_buffer_params_v1::Flags as BufferParamsFlags;
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_feedback_v1::ZwpLinuxDmabufFeedbackV1;
+use wayland_protocols::wp::linux_dmabuf::zv1::client::zwp_linux_dmabuf_v1::ZwpLinuxDmabufV1;
 use wayland_protocols::xdg::xdg_output::zv1::client::zxdg_output_manager_v1::ZxdgOutputManagerV1;
-use wayland_protocols::xdg::xdg_output::zv1::client::zxdg_output_v1::{
-    Event as XdgOutputEvent, ZxdgOutputV1,
-};
-use wayland_protocols_wlr::output_management::v1::client::zwlr_output_head_v1::{
-    self, Event as WlrHeadEvent, ZwlrOutputHeadV1,
-};
-use wayland_protocols_wlr::output_management::v1::client::zwlr_output_manager_v1::{
-    self, Event as WlrOutputManagerEvent, ZwlrOutputManagerV1,
-};
-use wayland_protocols_wlr::output_management::v1::client::zwlr_output_mode_v1::ZwlrOutputModeV1;
-use wayland_protocols_wlr::screencopy::v1::client::zwlr_screencopy_frame_v1::{
-    Event as ScreencopyFrameEvent, ZwlrScreencopyFrameV1,
-};
+use wayland_protocols_wlr::output_management::v1::client::zwlr_output_manager_v1::ZwlrOutputManagerV1;
+use wayland_protocols_wlr::screencopy::v1::client::zwlr_screencopy_frame_v1::ZwlrScreencopyFrameV1;
 use wayland_protocols_wlr::screencopy::v1::client::zwlr_screencopy_manager_v1::ZwlrScreencopyManagerV1;
 
 use ffmpeg_next as ff;
@@ -44,12 +26,13 @@ use ffmpeg_next::ffi;
 
 use crate::args::Args;
 use crate::avhw::{AvHwDevCtx, EncState, EncodedH264Frame, SwEncState};
-use crate::cap_wlr_screencopy::CapWlrScreencopy;
 use crate::fps_limit::FpsLimit;
 use crate::stats::{FrameTimings, PipelineStats};
 use crate::transform::{transpose_if_transform_transposed, Transform};
 use crate::webrtc::WebRtcState;
 
+mod dispatch;
+
 // ---------------------------------------------------------------------------
 // CaptureSource trait
 // ---------------------------------------------------------------------------
@@ -90,7 +73,6 @@ pub struct PartialOutputInfo {
     pub done_count: u32,
 }
 
-
 /// Marker for wlr-output-management heads seen during probing; tracked by name
 /// in `EncConstructionStage::ProbingOutputs.wlr_heads`.
 // `pub(crate)` (not module-private): exposed via `EncConstructionStage::ProbingOutputs.wlr_heads`
@@ -121,7 +103,10 @@ impl StreamingEncoder {
         }
     }
 
-    fn encode_frame(&mut self, hw_frame: &ffmpeg_next::frame::Video) -> anyhow::Result<crate::avhw::EncodeStages> {
+    fn encode_frame(
+        &mut self,
+        hw_frame: &ffmpeg_next::frame::Video,
+    ) -> anyhow::Result<crate::avhw::EncodeStages> {
         match self {
             StreamingEncoder::Mp4(enc) => enc.encode_frame(hw_frame),
             StreamingEncoder::WebRtc(enc) => enc.encode_frame(hw_frame),
@@ -704,9 +689,7 @@ impl<S: CaptureSource> State<S> {
                     continue;
                 }
                 count += 1;
-                if let Err(e) = wrtc
-                    .write_h264_frame(&enc_frame.data, enc_frame.pts_ticks)
-                {
+                if let Err(e) = wrtc.write_h264_frame(&enc_frame.data, enc_frame.pts_ticks) {
                     tracing::debug!("WebRTC write frame error: {e}");
                 }
                 self.stats.record_send(0.0, None);
@@ -881,7 +864,8 @@ impl<S: CaptureSource> State<S> {
                             }
                         } else {
                             // done_count >= 1 implies transform arrived (Geometry precedes Done).
-                            if info.done_count < 1 || !wlr_manager_done || info.transform.is_none() {
+                            if info.done_count < 1 || !wlr_manager_done || info.transform.is_none()
+                            {
                                 return false;
                             }
                         }
@@ -1013,586 +997,3 @@ impl<S: CaptureSource> State<S> {
         true
     }
 }
-
-// ---------------------------------------------------------------------------
-// Dispatch<WlRegistry, GlobalListContents>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<WlRegistry, GlobalListContents> for State<S> {
-    fn event(
-        state: &mut Self,
-        registry: &WlRegistry,
-        event: wayland_client::protocol::wl_registry::Event,
-        _data: &GlobalListContents,
-        _conn: &wayland_client::Connection,
-        qhandle: &QueueHandle<State<S>>,
-    ) {
-        use wayland_client::protocol::wl_registry::Event as RegistryEvent;
-
-        match event {
-            RegistryEvent::Global {
-                name,
-                interface,
-                version,
-            } => match interface.as_str() {
-                "zwlr_screencopy_manager_v1" => {
-                    let v = version.min(3);
-                    tracing::debug!("Binding zwlr_screencopy_manager_v1 v{v} (name={name})");
-                    let mgr: ZwlrScreencopyManagerV1 = registry.bind(name, v, qhandle, ());
-                    if let EncConstructionStage::ProbingOutputs {
-                        screencopy_manager, ..
-                    } = &mut state.stage
-                    {
-                        *screencopy_manager = Some(mgr);
-                    }
-                }
-                "zwp_linux_dmabuf_v1" => {
-                    let v = version.min(4);
-                    tracing::debug!("Binding zwp_linux_dmabuf_v1 v{v} (name={name})");
-                    let proxy: ZwpLinuxDmabufV1 = registry.bind(name, v, qhandle, ());
-                    if let EncConstructionStage::ProbingOutputs {
-                        dmabuf,
-                        dmabuf_feedback,
-                        ..
-                    } = &mut state.stage
-                    {
-                        *dmabuf = Some(proxy.clone());
-                        if v >= 4 {
-                            let feedback = proxy.get_default_feedback(qhandle, ());
-                            *dmabuf_feedback = Some(feedback);
-                        }
-                    }
-                }
-                "wl_output" => {
-                    let v = version.min(4);
-                    tracing::debug!("Binding wl_output v{v} (name={name})");
-                    let output: WlOutput = registry.bind(name, v, qhandle, OutputId(name));
-                    if let EncConstructionStage::ProbingOutputs {
-                        outputs,
-                        bound_outputs,
-                        output_names,
-                        xdg_output_manager,
-                        ..
-                    } = &mut state.stage
-                    {
-                        outputs.push(PartialOutputInfo::default());
-                        bound_outputs.push(output.clone());
-                        output_names.push(name);
-                        if let Some(xdg_mgr) = xdg_output_manager {
-                            let output_id = OutputId(name);
-                            xdg_mgr.get_xdg_output(&output, qhandle, output_id);
-                        }
-                    }
-                }
-                "zxdg_output_manager_v1" => {
-                    let v = version.min(3);
-                    tracing::debug!("Binding zxdg_output_manager_v1 v{v} (name={name})");
-                    let xdg_mgr: ZxdgOutputManagerV1 = registry.bind(name, v, qhandle, ());
-                    if let EncConstructionStage::ProbingOutputs {
-                        bound_outputs,
-                        xdg_output_manager,
-                        output_names,
-                        ..
-                    } = &mut state.stage
-                    {
-                        for (i, output) in bound_outputs.iter().enumerate() {
-                            let oname = output_names.get(i).copied().unwrap_or(0);
-                            let output_id = OutputId(oname);
-                            xdg_mgr.get_xdg_output(output, qhandle, output_id);
-                        }
-                        *xdg_output_manager = Some(xdg_mgr);
-                    }
-                }
-                "zwlr_output_manager_v1" => {
-                    let v = version.min(4);
-                    tracing::debug!("Binding zwlr_output_manager_v1 v{v} (name={name})");
-                    let mgr: ZwlrOutputManagerV1 = registry.bind(name, v, qhandle, ());
-                    if let EncConstructionStage::ProbingOutputs {
-                        wlr_output_manager, ..
-                    } = &mut state.stage
-                    {
-                        *wlr_output_manager = Some(mgr);
-                    }
-                }
-                _ => {}
-            },
-            RegistryEvent::GlobalRemove { name } => {
-                tracing::debug!("Global removed: name={name}");
-            }
-            _ => {}
-        }
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<WlOutput, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<WlOutput, OutputId> for State<S> {
-    fn event(
-        state: &mut Self,
-        _proxy: &WlOutput,
-        event: wayland_client::protocol::wl_output::Event,
-        data: &OutputId,
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        use wayland_client::protocol::wl_output::Event as OutputEvent;
-        use wayland_client::protocol::wl_output::Mode as WlMode;
-        use wayland_client::protocol::wl_output::Transform as WlTransform;
-
-        let OutputId(target_name) = data;
-        let idx = match &state.stage {
-            EncConstructionStage::ProbingOutputs { output_names, .. } => {
-                output_names.iter().position(|&n| n == *target_name)
-            }
-            _ => None,
-        };
-        let idx = match idx {
-            Some(i) => i,
-            None => return,
-        };
-
-        match event {
-            OutputEvent::Geometry {
-                transform,
-                ..
-            } => {
-                let t = match transform {
-                    wayland_client::WEnum::Value(WlTransform::Normal) => Transform::Normal,
-                    wayland_client::WEnum::Value(WlTransform::_90) => Transform::Normal90,
-                    wayland_client::WEnum::Value(WlTransform::_180) => Transform::Normal180,
-                    wayland_client::WEnum::Value(WlTransform::_270) => Transform::Normal270,
-                    wayland_client::WEnum::Value(WlTransform::Flipped) => Transform::Flipped,
-                    wayland_client::WEnum::Value(WlTransform::Flipped90) => Transform::Flipped90,
-                    wayland_client::WEnum::Value(WlTransform::Flipped180) => Transform::Flipped180,
-                    wayland_client::WEnum::Value(WlTransform::Flipped270) => Transform::Flipped270,
-                    _ => Transform::Normal,
-                };
-                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
-                    if let Some(info) = outputs.get_mut(idx) {
-                        info.transform = Some(t);
-                    }
-                }
-            }
-            OutputEvent::Mode {
-                width,
-                height,
-                flags,
-                ..
-            } => {
-                let is_current = matches!(flags, wayland_client::WEnum::Value(WlMode::Current));
-                if is_current {
-                    if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
-                        if let Some(info) = outputs.get_mut(idx) {
-                            info.mode_size = Some((width, height));
-                        }
-                    }
-                }
-            }
-            OutputEvent::Done => {
-                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
-                    if let Some(info) = outputs.get_mut(idx) {
-                        info.done_count += 1;
-                        if info.done_count >= 1 {
-                            state.try_finalize_output(idx);
-                        }
-                    }
-                }
-            }
-            OutputEvent::Name { name } => {
-                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
-                    if let Some(info) = outputs.get_mut(idx) {
-                        info.wl_name = Some(name);
-                    }
-                }
-            }
-            _ => {}
-        }
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZxdgOutputV1, OutputId>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZxdgOutputV1, OutputId> for State<S> {
-    fn event(
-        state: &mut Self,
-        _proxy: &ZxdgOutputV1,
-        event: <ZxdgOutputV1 as Proxy>::Event,
-        data: &OutputId,
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        let target_name = data.0;
-        let idx = match &state.stage {
-            EncConstructionStage::ProbingOutputs { output_names, .. } => {
-                output_names.iter().position(|&n| n == target_name)
-            }
-            _ => None,
-        };
-        let idx = match idx {
-            Some(i) => i,
-            None => return,
-        };
-
-        match event {
-            XdgOutputEvent::Name { name } => {
-                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
-                    if let Some(info) = outputs.get_mut(idx) {
-                        info.name = Some(name);
-                    }
-                }
-            }
-            XdgOutputEvent::LogicalSize { .. } => {}
-            XdgOutputEvent::Done => {
-                if let EncConstructionStage::ProbingOutputs { outputs, .. } = &mut state.stage {
-                    if let Some(info) = outputs.get_mut(idx) {
-                        info.done_count += 1;
-                        if info.done_count >= 1 {
-                            state.try_finalize_output(idx);
-                        }
-                    }
-                }
-            }
-            _ => {}
-        }
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwpLinuxDmabufV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZwpLinuxDmabufV1, ()> for State<S> {
-    fn event(
-        _state: &mut Self,
-        _proxy: &ZwpLinuxDmabufV1,
-        event: <ZwpLinuxDmabufV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        match event {
-            DmabufEvent::Format { .. } => {}
-            DmabufEvent::Modifier { .. } => {}
-            _ => {}
-        }
-    }
-}
-
-impl<S: CaptureSource> Dispatch<ZwpLinuxDmabufFeedbackV1, ()> for State<S> {
-    fn event(
-        state: &mut Self,
-        _proxy: &ZwpLinuxDmabufFeedbackV1,
-        event: <ZwpLinuxDmabufFeedbackV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        match event {
-            DmabufFeedbackEvent::MainDevice { device } => {
-                if device.len() >= 8 {
-                    let dev_bytes: [u8; 8] = device[..8].try_into().unwrap_or([0u8; 8]);
-                    let dev = u64::from_ne_bytes(dev_bytes);
-                    let minor = ((dev & 0xFF) | ((dev >> 12) & 0xFFFFFF00)) as u32;
-                    let path = PathBuf::from(format!("/dev/dri/renderD{}", minor));
-                    if path.exists() {
-                        tracing::info!(
-                            "Compositor DRM device: {} (dev_t: {})",
-                            path.display(),
-                            dev
-                        );
-                        state.drm_device_from_compositor = Some(path);
-                    } else {
-                        tracing::warn!(
-                            "Compositor reported DRM device {} (dev_t: {}) but path does not exist",
-                            path.display(),
-                            dev
-                        );
-                    }
-                } else {
-                    tracing::warn!(
-                        "main_device event with unexpected data length: {}",
-                        device.len()
-                    );
-                }
-            }
-            DmabufFeedbackEvent::FormatTable { .. } => {}
-            DmabufFeedbackEvent::Done => {}
-            DmabufFeedbackEvent::TrancheDone => {}
-            DmabufFeedbackEvent::TrancheTargetDevice { .. } => {}
-            DmabufFeedbackEvent::TrancheFormats { .. } => {}
-            DmabufFeedbackEvent::TrancheFlags { .. } => {}
-            _ => {}
-        }
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwpLinuxBufferParamsV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZwpLinuxBufferParamsV1, ()> for State<S> {
-    fn event(
-        state: &mut Self,
-        proxy: &ZwpLinuxBufferParamsV1,
-        event: <ZwpLinuxBufferParamsV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        match event {
-            BufferParamsEvent::Created { .. } => {
-                tracing::debug!("DMA-BUF buffer created");
-            }
-            BufferParamsEvent::Failed => {
-                tracing::error!("DMA-BUF buffer creation failed");
-                let taken = mem::replace(&mut state.in_flight_surface, InFlightSurface::None);
-                match taken {
-                    InFlightSurface::CopyQueued { buffer, frame, .. } => {
-                        drop(buffer);
-                        if let EncConstructionStage::Streaming { cap, .. } = &mut state.stage {
-                            cap.on_done_with_frame(frame);
-                        }
-                    }
-                    other => {
-                        state.in_flight_surface = other;
-                    }
-                }
-                proxy.destroy();
-                state.errored = true;
-            }
-            _ => {}
-        }
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwlrScreencopyFrameV1, ()> for CapWlrScreencopy
-// ---------------------------------------------------------------------------
-
-impl Dispatch<ZwlrScreencopyFrameV1, ()> for State<CapWlrScreencopy> {
-    fn event(
-        state: &mut Self,
-        proxy: &ZwlrScreencopyFrameV1,
-        event: <ZwlrScreencopyFrameV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<CapWlrScreencopy>>,
-    ) {
-        match event {
-            // SHM buffer offer — in v3 the compositor enumerates supported buffer
-            // types (buffer and/or linux_dmabuf) before buffer_done.  We only
-            // support DMA-BUF, so just log and wait for linux_dmabuf / buffer_done.
-            ScreencopyFrameEvent::Buffer { .. } => {
-                tracing::debug!("Received SHM Buffer offer — only DMA-BUF capture is supported");
-            }
-            ScreencopyFrameEvent::LinuxDmabuf {
-                format,
-                width,
-                height,
-            } => {
-                tracing::debug!("Screencopy LinuxDmabuf: format={format}, {width}x{height}");
-
-                if !matches!(state.in_flight_surface, InFlightSurface::AllocQueued) {
-                    tracing::warn!("Received LinuxDmabuf while no frame allocation was queued");
-                    return;
-                }
-
-                if matches!(state.stage, EncConstructionStage::EverythingButFmt { .. }) {
-                    state.negotiate_format(format, width, height);
-                    if state.errored {
-                        return;
-                    }
-                }
-                if let EncConstructionStage::Streaming { cap, .. } = &mut state.stage {
-                    cap.current_frame = Some(proxy.clone());
-                }
-                state.on_frame_allocd((), format, width, height);
-            }
-            // v3 terminal event: all buffer offers have been enumerated.
-            // If still AllocQueued, the compositor never sent linux_dmabuf —
-            // DMA-BUF screencopy is unsupported, so we must error out.
-            ScreencopyFrameEvent::BufferDone => {
-                if matches!(state.in_flight_surface, InFlightSurface::AllocQueued) {
-                    tracing::error!(
-                        "Compositor did not offer DMA-BUF screencopy (only SHM); \
-                         DMA-BUF capture is required"
-                    );
-                    state.in_flight_surface = InFlightSurface::None;
-                    proxy.destroy();
-                    state.errored = true;
-                }
-            }
-            ScreencopyFrameEvent::Ready {
-                tv_sec_hi,
-                tv_sec_lo,
-                tv_nsec,
-            } => {
-                let tv_sec = (tv_sec_hi as u64) << 32 | tv_sec_lo as u64;
-                let tv_usec = tv_nsec / 1000;
-                tracing::trace!("Screencopy ready: tv_sec={tv_sec}, tv_usec={tv_usec}");
-                state.on_copy_complete(tv_sec, tv_usec);
-            }
-            ScreencopyFrameEvent::Failed => {
-                tracing::error!("Screencopy frame failed");
-                state.on_copy_fail();
-            }
-            ScreencopyFrameEvent::Damage { .. } => {}
-            _ => {}
-        }
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZxdgOutputManagerV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZxdgOutputManagerV1, ()> for State<S> {
-    fn event(
-        _state: &mut Self,
-        _proxy: &ZxdgOutputManagerV1,
-        _event: <ZxdgOutputManagerV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwlrOutputManagerV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZwlrOutputManagerV1, ()> for State<S> {
-    fn event(
-        state: &mut Self,
-        _proxy: &ZwlrOutputManagerV1,
-        event: <ZwlrOutputManagerV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        match event {
-            WlrOutputManagerEvent::Head { head } => {
-                let _head: ZwlrOutputHeadV1 = head;
-                tracing::debug!("wlr output head advertised");
-            }
-            WlrOutputManagerEvent::Done { .. } => {
-                if let EncConstructionStage::ProbingOutputs {
-                    wlr_manager_done,
-                    outputs,
-                    ..
-                } = &mut state.stage
-                {
-                    *wlr_manager_done = true;
-                    let count = outputs.len();
-                    for idx in 0..count {
-                        state.try_finalize_output(idx);
-                    }
-                }
-            }
-            WlrOutputManagerEvent::Finished => {
-                tracing::warn!("zwlr_output_manager_v1::Finished received during probing");
-            }
-            _ => {}
-        }
-    }
-
-    event_created_child!(State<S>, ZwlrOutputManagerV1, [
-        zwlr_output_manager_v1::EVT_HEAD_OPCODE => (ZwlrOutputHeadV1, ()),
-    ]);
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwlrOutputHeadV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZwlrOutputHeadV1, ()> for State<S> {
-    fn event(
-        state: &mut Self,
-        proxy: &ZwlrOutputHeadV1,
-        event: <ZwlrOutputHeadV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        match event {
-            WlrHeadEvent::Name { name } => {
-                if let EncConstructionStage::ProbingOutputs {
-                    wlr_heads,
-                    wlr_head_proxy_to_name,
-                    ..
-                } = &mut state.stage
-                {
-                    wlr_heads
-                        .entry(name.clone())
-                        .or_insert(WlrHeadInfo {});
-                    wlr_head_proxy_to_name.insert(proxy.id(), name);
-                }
-            }
-            WlrHeadEvent::Position { .. } => {}
-            WlrHeadEvent::Finished => {
-                tracing::debug!("zwlr_output_head_v1::Finished received");
-            }
-            _ => {}
-        }
-    }
-
-    event_created_child!(State<S>, ZwlrOutputHeadV1, [
-        zwlr_output_head_v1::EVT_MODE_OPCODE => (ZwlrOutputModeV1, ()),
-    ]);
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwlrOutputModeV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZwlrOutputModeV1, ()> for State<S> {
-    fn event(
-        _state: &mut Self,
-        _proxy: &ZwlrOutputModeV1,
-        _event: <ZwlrOutputModeV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<ZwlrScreencopyManagerV1, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<ZwlrScreencopyManagerV1, ()> for State<S> {
-    fn event(
-        _state: &mut Self,
-        _proxy: &ZwlrScreencopyManagerV1,
-        _event: <ZwlrScreencopyManagerV1 as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Dispatch<WlBuffer, ()>
-// ---------------------------------------------------------------------------
-
-impl<S: CaptureSource> Dispatch<WlBuffer, ()> for State<S> {
-    fn event(
-        _state: &mut Self,
-        _proxy: &WlBuffer,
-        event: <WlBuffer as Proxy>::Event,
-        _data: &(),
-        _conn: &wayland_client::Connection,
-        _qhandle: &QueueHandle<State<S>>,
-    ) {
-        if let wayland_client::protocol::wl_buffer::Event::Release = event {
-            tracing::trace!("WlBuffer released");
-        }
-    }
-}

src/state_portal.rs

@@ -13,13 +13,21 @@ use anyhow::{bail, Result}; // 错误处理工具
 
 use crate::args::Args; // 命令行参数
 use crate::avhw::{
-    self, BitrateCommand, CpuNv12Frame, EncodeOutcome, EncodedH264Frame, ResolutionChange,
-    SwEncEncode, SwEncImport, SwEncState,
+    self, BitrateCommand, CpuNv12Frame, ResolutionChange, SwEncEncode, SwEncImport, SwEncState,
 }; // 软件编码器状态（VAAPI 导入 + H.264 编码）
 use crate::cap_portal::{CapPortal, PwCtrlEvent, PwDmaBufFrame}; // PipeWire 屏幕采集端点
 use crate::stats::{FrameTimings, PipelineStats}; // 管道统计（帧计时、每秒快照）
 use crate::webrtc::WebRtcState; // WebRTC 信令与媒体传输
 
+mod bitrate;
+use bitrate::webrtc_startup_bitrate_bps;
+
+mod threads;
+use threads::{
+    encode_thread_loop, webrtc_thread_loop, EncodeThread, EncodeThreadTiming, WebRtcThreadChannels,
+    WebRtcThreadConfig, WebrtcThread,
+};
+
 /// 门户采集的阶段状态
 /// - WaitingForFormat: 等待接收到第一帧 DMA-BUF 以确定视频格式参数
 /// - Streaming: 已完成初始化，正在持续编码流
@@ -28,44 +36,6 @@ enum PortalStage {
     Streaming,
 }
 
-struct EncodeThreadTiming {
-    sws_us: u64,
-    encode_us: u64,
-    output_bytes: usize,
-}
-
-struct EncodeThread {
-    handle: Option<std::thread::JoinHandle<()>>,
-    input_tx: crossbeam_channel::Sender<CpuNv12Frame>,
-    timing_rx: crossbeam_channel::Receiver<EncodeThreadTiming>,
-    duplicate_count: std::sync::Arc<std::sync::atomic::AtomicU64>,
-}
-
-struct WebrtcThread {
-    handle: Option<std::thread::JoinHandle<()>>,
-    sent_gap_rx: crossbeam_channel::Receiver<(f64, Option<f64>)>,
-}
-
-/// Static configuration handed to the WebRTC sender thread. Immutable for the
-/// thread's lifetime; a resolution tier change rebuilds the whole pipeline
-/// (and spawns a new thread) rather than mutating this.
-struct WebRtcThreadConfig {
-    fps: u32,
-    enc_width: u32,
-    enc_height: u32,
-    max_bitrate: u64,
-}
-
-/// Channel endpoints owned exclusively by the WebRTC sender thread after spawn.
-/// The reverse endpoints stay with StatePortal (or the encode thread) for
-/// inbound/outbound traffic.
-struct WebRtcThreadChannels {
-    webrtc_rx: crossbeam_channel::Receiver<EncodedH264Frame>,
-    sent_gap_tx: crossbeam_channel::Sender<(f64, Option<f64>)>,
-    bitrate_tx: crossbeam_channel::Sender<BitrateCommand>,
-    resolution_tx: crossbeam_channel::Sender<BitrateCommand>,
-}
-
 /// 门户模式的主状态机
 ///
 /// 负责管理从 PipeWire 采集屏幕帧、通过 VAAPI 硬件编码的完整生命周期。
@@ -273,9 +243,7 @@ impl StatePortal {
                         bitrate_rx,
                         encoder_resolution_rx,
                     )?;
-                    let duplicate_count = std::sync::Arc::new(
-                        std::sync::atomic::AtomicU64::new(0),
-                    );
+                    let duplicate_count = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
                     let duplicate_count_for_thread = duplicate_count.clone();
                     let handle = std::thread::Builder::new()
                         .name("wl-webrtc-encode".into())
@@ -370,11 +338,13 @@ impl StatePortal {
             // capture channel depth. Oracle audit 2026-06-28: previously hardcoded
             // (0, 0), which silently zeroed two real diagnostic fields.
             let total_dropped = self.cap.dropped_count();
-            self.stats.set_pipewire_dropped(total_dropped, self.pw_dropped_prev);
+            self.stats
+                .set_pipewire_dropped(total_dropped, self.pw_dropped_prev);
             self.pw_dropped_prev = total_dropped;
             // capture queue depth is real; encoded side has no exposed depth — the
             // encoder thread publishes timings only, not a frame queue length.
-            self.stats.set_queue_depths(self.cap.capture_queue_depth(), 0);
+            self.stats
+                .set_queue_depths(self.cap.capture_queue_depth(), 0);
             if let Some(ref enc_thread) = self.enc_thread {
                 while let Ok(timing) = enc_thread.timing_rx.try_recv() {
                     self.stats.record_encode_thread(
@@ -517,9 +487,8 @@ impl StatePortal {
             // 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)
-            }?;
+            let mut vaapi_frame =
+                unsafe { avhw::import_dma_buf_to_vaapi(enc.frames_rgb().as_ptr(), &frame) }?;
 
             let import_us = t_import_start.elapsed().as_micros() as u64;
 
@@ -550,9 +519,8 @@ impl StatePortal {
         } else if let Some(import) = self.enc_import.as_mut() {
             // SAFETY: same contract as the enc branch above — frames_rgb owned by
             // 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)
-            }?;
+            let mut vaapi_frame =
+                unsafe { 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 {
                 (*vaapi_frame.as_mut_ptr()).pts = pts;
@@ -679,259 +647,6 @@ impl StatePortal {
     }
 }
 
-fn encode_thread_loop(
-    mut encode: SwEncEncode,
-    input_rx: crossbeam_channel::Receiver<CpuNv12Frame>,
-    timing_tx: crossbeam_channel::Sender<EncodeThreadTiming>,
-    duplicate_count: std::sync::Arc<std::sync::atomic::AtomicU64>,
-) {
-    loop {
-        match input_rx.recv() {
-            Ok(frame) => {
-                match encode.encode_cpu_frame(&frame) {
-                    Ok(EncodeOutcome::Encoded) => {
-                        let t = encode.take_timing();
-                        let _ = timing_tx.try_send(EncodeThreadTiming {
-                            sws_us: t.sws_us,
-                            encode_us: t.encode_us,
-                            output_bytes: t.output_bytes,
-                        });
-                    }
-                    Ok(EncodeOutcome::SkippedDuplicate) => {
-                        duplicate_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
-                    }
-                    Ok(_) => {
-                        // SkippedPaused / SkippedDisconnected — no counter needed
-                    }
-                    Err(e) => {
-                        tracing::error!("Encode thread error: {e}");
-                        break;
-                    }
-                }
-            }
-            Err(_) => {
-                tracing::info!("Encode thread input closed, flushing encoder");
-                if let Err(e) = encode.flush() {
-                    tracing::error!("Encode thread flush error: {e}");
-                }
-                break;
-            }
-        }
-    }
-    tracing::info!("Encode thread exiting");
-}
-
-fn webrtc_thread_loop(
-    mut wrtc: WebRtcState,
-    config: WebRtcThreadConfig,
-    channels: WebRtcThreadChannels,
-    paused: Arc<AtomicBool>,
-) {
-    let WebRtcThreadConfig {
-        fps,
-        enc_width,
-        enc_height,
-        max_bitrate,
-    } = config;
-    let WebRtcThreadChannels {
-        webrtc_rx,
-        sent_gap_tx,
-        bitrate_tx,
-        resolution_tx,
-    } = channels;
-    let mut frames_sent: u64 = 0;
-    let mut last_send: Option<std::time::Instant> = None;
-    let mut last_sent_bitrate: Option<u64> = None;
-    let initial_tier = (enc_width, enc_height);
-    let mut current_tier = initial_tier;
-    let mut upscale_counter = 0u32;
-    let mut last_resolution_eval = Instant::now();
-    let timeout = Duration::from_millis(1);
-
-    loop {
-        if let Err(e) = wrtc.handle_signaling() {
-            tracing::error!("WebRTC signaling error: {e}");
-            break;
-        }
-        if let Err(e) = wrtc.poll_and_feed() {
-            tracing::error!("WebRTC poll error: {e}");
-            break;
-        }
-
-        if wrtc.take_force_keyframe() {
-            let _ = bitrate_tx.try_send(BitrateCommand::ForceKeyframe);
-        }
-
-        let connected = wrtc.is_connected();
-        let was_paused = paused.load(Ordering::Relaxed);
-        let now_paused = !connected;
-        if was_paused && !now_paused {
-            tracing::info!("WebRTC client connected, resuming encoding");
-        } else if !was_paused && now_paused {
-            tracing::warn!("WebRTC client disconnected, pausing encoding");
-        }
-        paused.store(now_paused, Ordering::Relaxed);
-
-        if let Some(bwe) = wrtc.get_bwe_estimate() {
-            // #23: Cap BWE to prevent runaway bitrate escalation. Without this, BWE
-            // estimates can rise to 10+ Mbps, causing IDR bursts and PLI storms.
-            let effective_bwe = bwe.min(max_bitrate);
-            if effective_bwe != bwe {
-                tracing::debug!(
-                    bwe,
-                    effective_bwe,
-                    max_bitrate,
-                    "BWE exceeds --max-bitrate cap, clamping"
-                );
-            }
-            let bwe = effective_bwe;
-
-            let should_send = match last_sent_bitrate {
-                None => true,
-                Some(last) => {
-                    let diff = bwe.abs_diff(last);
-                    diff * 10 > last
-                }
-            };
-            if should_send {
-                let _ = bitrate_tx.try_send(BitrateCommand::UpdateBitrate { target_bps: bwe });
-                last_sent_bitrate = Some(bwe);
-            }
-
-            if last_resolution_eval.elapsed() >= Duration::from_secs(1) {
-                last_resolution_eval = Instant::now();
-                let selected = select_resolution(current_tier.0, current_tier.1, bwe, fps);
-                if selected != current_tier {
-                    current_tier = selected;
-                    upscale_counter = 0;
-                    let _ = resolution_tx.try_send(BitrateCommand::UpdateResolution {
-                        width: current_tier.0,
-                        height: current_tier.1,
-                    });
-                    wrtc.set_need_keyframe();
-                } else if let Some(next_tier) = next_upscale_tier(current_tier, initial_tier) {
-                    let needed = resolution_bitrate_bps(next_tier.0, next_tier.1, fps);
-                    if bwe > needed.saturating_mul(120) / 100 {
-                        upscale_counter = upscale_counter.saturating_add(1);
-                        if upscale_counter >= 10 {
-                            current_tier = next_tier;
-                            upscale_counter = 0;
-                            let _ = resolution_tx.try_send(BitrateCommand::UpdateResolution {
-                                width: current_tier.0,
-                                height: current_tier.1,
-                            });
-                            wrtc.set_need_keyframe();
-                        }
-                    } else {
-                        upscale_counter = 0;
-                    }
-                } else {
-                    upscale_counter = 0;
-                }
-            }
-        }
-
-        if connected {
-            while let Ok(enc_frame) = webrtc_rx.try_recv() {
-                if let Err(e) = wrtc.write_h264_frame(&enc_frame.data, enc_frame.pts_ticks) {
-                    tracing::debug!("WebRTC write frame error: {e}");
-                }
-                frames_sent = frames_sent.saturating_add(1);
-                let gap_ms = last_send
-                    .map(|l| l.elapsed().as_secs_f64() * 1000.0)
-                    .unwrap_or(0.0);
-                // Compute capture-to-send age on the sending thread so the
-                // frame_age stat stays accurate when batch-drained later.
-                let age_ms =
-                    Some(enc_frame.capture_time.elapsed().as_secs_f64() * 1000.0);
-                last_send = Some(std::time::Instant::now());
-                let _ = sent_gap_tx.try_send((gap_ms, age_ms));
-            }
-        } else {
-            while webrtc_rx.try_recv().is_ok() {}
-        }
-
-        match webrtc_rx.recv_timeout(timeout) {
-            Ok(enc_frame) => {
-                if wrtc.is_connected() {
-                    if let Err(e) = wrtc.write_h264_frame(&enc_frame.data, enc_frame.pts_ticks)
-                    {
-                        tracing::debug!("WebRTC write frame error: {e}");
-                    }
-                    frames_sent = frames_sent.saturating_add(1);
-                    let gap_ms = last_send
-                        .map(|l| l.elapsed().as_secs_f64() * 1000.0)
-                        .unwrap_or(0.0);
-                    let age_ms =
-                        Some(enc_frame.capture_time.elapsed().as_secs_f64() * 1000.0);
-                    last_send = Some(std::time::Instant::now());
-                    let _ = sent_gap_tx.try_send((gap_ms, age_ms));
-                }
-            }
-            Err(crossbeam_channel::RecvTimeoutError::Timeout) => {}
-            Err(crossbeam_channel::RecvTimeoutError::Disconnected) => {
-                tracing::info!("WebRTC channel disconnected, exiting thread");
-                return;
-            }
-        }
-    }
-
-    tracing::info!("WebRTC thread exiting");
-}
-
-const RESOLUTION_TIERS: &[(u32, u32)] = &[(2560, 1440), (1920, 1080), (1280, 720)];
-
-fn resolution_bitrate_bps(width: u32, height: u32, fps: u32) -> u64 {
-    5 * u64::from(width) * u64::from(height) * u64::from(fps) / 100
-}
-
-/// Conservative startup bitrate for WebRTC mode, tier-based by total pixel count.
-/// BWE estimate arrives within milliseconds of client connect and overrides this;
-/// the startup value only affects the first IDR. See issue #21.
-fn webrtc_startup_bitrate_bps(width: u32, height: u32) -> u64 {
-    let pixels = u64::from(width) * u64::from(height);
-    if pixels <= 1_000_000 {
-        1_000_000
-    } else if pixels <= 2_500_000 {
-        2_000_000
-    } else if pixels <= 4_500_000 {
-        4_000_000
-    } else {
-        8_000_000
-    }
-}
-
-/// Select resolution tier based on BWE estimate.
-/// Returns (width, height) for the selected tier.
-fn select_resolution(current_w: u32, current_h: u32, bwe_bps: u64, fps: u32) -> (u32, u32) {
-    let current = (current_w, current_h);
-    let current_bitrate = resolution_bitrate_bps(current_w, current_h, fps);
-    if bwe_bps >= current_bitrate.saturating_mul(60) / 100 {
-        return current;
-    }
-
-    let current_index = RESOLUTION_TIERS
-        .iter()
-        .position(|&tier| tier == current)
-        .unwrap_or_else(|| {
-            RESOLUTION_TIERS
-                .iter()
-                .position(|&(w, h)| w <= current_w && h <= current_h)
-                .unwrap_or(RESOLUTION_TIERS.len() - 1)
-        });
-    let next_index = (current_index + 1).min(RESOLUTION_TIERS.len() - 1);
-    RESOLUTION_TIERS[next_index]
-}
-
-fn next_upscale_tier(current: (u32, u32), ceiling: (u32, u32)) -> Option<(u32, u32)> {
-    let current_index = RESOLUTION_TIERS.iter().position(|&tier| tier == current)?;
-    if current_index == 0 {
-        return None;
-    }
-    let next = RESOLUTION_TIERS[current_index - 1];
-    (next.0 <= ceiling.0 && next.1 <= ceiling.1).then_some(next)
-}
-
 impl Drop for StatePortal {
     // 析构时自动调用 shutdown，确保编码器被刷新、资源被释放
     fn drop(&mut self) {
@@ -1087,48 +802,6 @@ mod tests {
         assert_eq!(result, None);
     }
 
-    #[test]
-    fn webrtc_startup_bitrate_tiers_by_pixel_count() {
-        assert_eq!(webrtc_startup_bitrate_bps(1280, 720), 1_000_000);
-        assert_eq!(webrtc_startup_bitrate_bps(1920, 1080), 2_000_000);
-        assert_eq!(webrtc_startup_bitrate_bps(2560, 1440), 4_000_000);
-        assert_eq!(webrtc_startup_bitrate_bps(3840, 2160), 8_000_000);
-    }
-
-    #[test]
-    fn select_resolution_downscales_one_tier_below_sixty_percent() {
-        let fps = 30;
-        let current = resolution_bitrate_bps(1920, 1080, fps);
-        assert_eq!(
-            select_resolution(1920, 1080, current * 59 / 100, fps),
-            (1280, 720)
-        );
-    }
-
-    #[test]
-    fn select_resolution_keeps_tier_at_sixty_percent() {
-        let fps = 30;
-        let current = resolution_bitrate_bps(1920, 1080, fps);
-        assert_eq!(
-            select_resolution(1920, 1080, current * 60 / 100, fps),
-            (1920, 1080)
-        );
-    }
-
-    #[test]
-    fn select_resolution_never_goes_below_720p() {
-        assert_eq!(select_resolution(1280, 720, 1, 30), (1280, 720));
-    }
-
-    #[test]
-    fn next_upscale_tier_respects_initial_ceiling() {
-        assert_eq!(
-            next_upscale_tier((1280, 720), (1920, 1080)),
-            Some((1920, 1080))
-        );
-        assert_eq!(next_upscale_tier((1920, 1080), (1920, 1080)), None);
-    }
-
     /// 测试：使用自定义偏移量和 stride 构建 DRM 描述符
     #[test]
     fn build_drm_descriptor_custom_offset_and_stride() {
@@ -1153,89 +826,4 @@ mod tests {
     }
 
     // ── issue #8 regression ──
-
-    #[test]
-    fn try_send_full_channel_returns_full_not_block() {
-        let (tx, rx) = crossbeam_channel::bounded::<Vec<u8>>(2);
-        tx.send(vec![1]).unwrap();
-        tx.send(vec![2]).unwrap();
-
-        assert!(matches!(
-            tx.try_send(vec![3]),
-            Err(crossbeam_channel::TrySendError::Full(_))
-        ));
-        assert_eq!(rx.len(), 2);
-    }
-
-    #[test]
-    fn try_send_after_rx_dropped_returns_disconnected() {
-        let (tx, rx) = crossbeam_channel::bounded::<Vec<u8>>(2);
-        drop(rx);
-
-        assert!(matches!(
-            tx.try_send(vec![1]),
-            Err(crossbeam_channel::TrySendError::Disconnected(_))
-        ));
-    }
-
-    // given: full bounded channel
-    // when:  rx is dropped, then try_send
-    // expect: Disconnected, not blocking
-    #[test]
-    fn shutdown_rx_drop_prevents_deadlock_on_full_channel() {
-        let (tx, rx) = crossbeam_channel::bounded::<Vec<u8>>(2);
-        tx.send(vec![1]).unwrap();
-        tx.send(vec![2]).unwrap();
-        drop(rx);
-
-        assert!(matches!(
-            tx.try_send(vec![3]),
-            Err(crossbeam_channel::TrySendError::Disconnected(_))
-        ));
-    }
-
-    // ── Task 7: Additional resolution tier edge cases ──
-
-    #[test]
-    fn select_resolution_keeps_720p_when_bwe_sufficient() {
-        let fps = 30;
-        let bitrate_720 = resolution_bitrate_bps(1280, 720, fps);
-        assert_eq!(
-            select_resolution(1280, 720, bitrate_720, fps),
-            (1280, 720)
-        );
-    }
-
-    #[test]
-    fn select_resolution_downscales_1440p_to_1080p() {
-        let fps = 30;
-        let bitrate_1440 = resolution_bitrate_bps(2560, 1440, fps);
-        assert_eq!(
-            select_resolution(2560, 1440, bitrate_1440 * 59 / 100, fps),
-            (1920, 1080)
-        );
-    }
-
-    #[test]
-    fn select_resolution_1080p_to_720p_at_very_low_bwe() {
-        let fps = 30;
-        let bitrate_1080 = resolution_bitrate_bps(1920, 1080, fps);
-        assert_eq!(
-            select_resolution(1920, 1080, bitrate_1080 / 10, fps),
-            (1280, 720)
-        );
-    }
-
-    #[test]
-    fn next_upscale_tier_from_720p_to_1080p() {
-        assert_eq!(
-            next_upscale_tier((1280, 720), (2560, 1440)),
-            Some((1920, 1080))
-        );
-    }
-
-    #[test]
-    fn next_upscale_tier_returns_none_at_highest() {
-        assert_eq!(next_upscale_tier((2560, 1440), (2560, 1440)), None);
-    }
 }

src/state_portal/bitrate.rs

@@ -0,0 +1,144 @@
+pub(super) const RESOLUTION_TIERS: &[(u32, u32)] = &[(2560, 1440), (1920, 1080), (1280, 720)];
+
+pub(super) fn resolution_bitrate_bps(width: u32, height: u32, fps: u32) -> u64 {
+    5 * u64::from(width) * u64::from(height) * u64::from(fps) / 100
+}
+
+/// Conservative startup bitrate for WebRTC mode, tier-based by total pixel count.
+/// BWE estimate arrives within milliseconds of client connect and overrides this;
+/// the startup value only affects the first IDR. See issue #21.
+pub(super) fn webrtc_startup_bitrate_bps(width: u32, height: u32) -> u64 {
+    let pixels = u64::from(width) * u64::from(height);
+    if pixels <= 1_000_000 {
+        1_000_000
+    } else if pixels <= 2_500_000 {
+        2_000_000
+    } else if pixels <= 4_500_000 {
+        4_000_000
+    } else {
+        8_000_000
+    }
+}
+
+/// Select resolution tier based on BWE estimate.
+/// Returns (width, height) for the selected tier.
+pub(super) fn select_resolution(
+    current_w: u32,
+    current_h: u32,
+    bwe_bps: u64,
+    fps: u32,
+) -> (u32, u32) {
+    let current = (current_w, current_h);
+    let current_bitrate = resolution_bitrate_bps(current_w, current_h, fps);
+    if bwe_bps >= current_bitrate.saturating_mul(60) / 100 {
+        return current;
+    }
+
+    let current_index = RESOLUTION_TIERS
+        .iter()
+        .position(|&tier| tier == current)
+        .unwrap_or_else(|| {
+            RESOLUTION_TIERS
+                .iter()
+                .position(|&(w, h)| w <= current_w && h <= current_h)
+                .unwrap_or(RESOLUTION_TIERS.len() - 1)
+        });
+    let next_index = (current_index + 1).min(RESOLUTION_TIERS.len() - 1);
+    RESOLUTION_TIERS[next_index]
+}
+
+pub(super) fn next_upscale_tier(current: (u32, u32), ceiling: (u32, u32)) -> Option<(u32, u32)> {
+    let current_index = RESOLUTION_TIERS.iter().position(|&tier| tier == current)?;
+    if current_index == 0 {
+        return None;
+    }
+    let next = RESOLUTION_TIERS[current_index - 1];
+    (next.0 <= ceiling.0 && next.1 <= ceiling.1).then_some(next)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn webrtc_startup_bitrate_tiers_by_pixel_count() {
+        assert_eq!(webrtc_startup_bitrate_bps(1280, 720), 1_000_000);
+        assert_eq!(webrtc_startup_bitrate_bps(1920, 1080), 2_000_000);
+        assert_eq!(webrtc_startup_bitrate_bps(2560, 1440), 4_000_000);
+        assert_eq!(webrtc_startup_bitrate_bps(3840, 2160), 8_000_000);
+    }
+
+    #[test]
+    fn select_resolution_downscales_one_tier_below_sixty_percent() {
+        let fps = 30;
+        let current = resolution_bitrate_bps(1920, 1080, fps);
+        assert_eq!(
+            select_resolution(1920, 1080, current * 59 / 100, fps),
+            (1280, 720)
+        );
+    }
+
+    #[test]
+    fn select_resolution_keeps_tier_at_sixty_percent() {
+        let fps = 30;
+        let current = resolution_bitrate_bps(1920, 1080, fps);
+        assert_eq!(
+            select_resolution(1920, 1080, current * 60 / 100, fps),
+            (1920, 1080)
+        );
+    }
+
+    #[test]
+    fn select_resolution_never_goes_below_720p() {
+        assert_eq!(select_resolution(1280, 720, 1, 30), (1280, 720));
+    }
+
+    #[test]
+    fn next_upscale_tier_respects_initial_ceiling() {
+        assert_eq!(
+            next_upscale_tier((1280, 720), (1920, 1080)),
+            Some((1920, 1080))
+        );
+        assert_eq!(next_upscale_tier((1920, 1080), (1920, 1080)), None);
+    }
+
+    #[test]
+    fn select_resolution_keeps_720p_when_bwe_sufficient() {
+        let fps = 30;
+        let bitrate_720 = resolution_bitrate_bps(1280, 720, fps);
+        assert_eq!(select_resolution(1280, 720, bitrate_720, fps), (1280, 720));
+    }
+
+    #[test]
+    fn select_resolution_downscales_1440p_to_1080p() {
+        let fps = 30;
+        let bitrate_1440 = resolution_bitrate_bps(2560, 1440, fps);
+        assert_eq!(
+            select_resolution(2560, 1440, bitrate_1440 * 59 / 100, fps),
+            (1920, 1080)
+        );
+    }
+
+    #[test]
+    fn select_resolution_1080p_to_720p_at_very_low_bwe() {
+        let fps = 30;
+        let bitrate_1080 = resolution_bitrate_bps(1920, 1080, fps);
+        assert_eq!(
+            select_resolution(1920, 1080, bitrate_1080 / 10, fps),
+            (1280, 720)
+        );
+    }
+
+    #[test]
+    fn next_upscale_tier_from_720p_to_1080p() {
+        assert_eq!(
+            next_upscale_tier((1280, 720), (2560, 1440)),
+            Some((1920, 1080))
+        );
+    }
+
+    #[test]
+    fn next_upscale_tier_returns_none_at_highest() {
+        assert_eq!(next_upscale_tier((2560, 1440), (2560, 1440)), None);
+    }
+}

src/state_portal/threads.rs

@@ -0,0 +1,287 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use crate::avhw::{BitrateCommand, CpuNv12Frame, EncodeOutcome, EncodedH264Frame, SwEncEncode};
+use crate::webrtc::WebRtcState;
+
+use super::bitrate::{next_upscale_tier, resolution_bitrate_bps, select_resolution};
+
+pub(super) struct EncodeThreadTiming {
+    pub(super) sws_us: u64,
+    pub(super) encode_us: u64,
+    pub(super) output_bytes: usize,
+}
+
+pub(super) struct EncodeThread {
+    pub(super) handle: Option<std::thread::JoinHandle<()>>,
+    pub(super) input_tx: crossbeam_channel::Sender<CpuNv12Frame>,
+    pub(super) timing_rx: crossbeam_channel::Receiver<EncodeThreadTiming>,
+    pub(super) duplicate_count: std::sync::Arc<std::sync::atomic::AtomicU64>,
+}
+
+pub(super) struct WebrtcThread {
+    pub(super) handle: Option<std::thread::JoinHandle<()>>,
+    pub(super) sent_gap_rx: crossbeam_channel::Receiver<(f64, Option<f64>)>,
+}
+
+/// Static configuration handed to the WebRTC sender thread. Immutable for the
+/// thread's lifetime; a resolution tier change rebuilds the whole pipeline
+/// (and spawns a new thread) rather than mutating this.
+pub(super) struct WebRtcThreadConfig {
+    pub(super) fps: u32,
+    pub(super) enc_width: u32,
+    pub(super) enc_height: u32,
+    pub(super) max_bitrate: u64,
+}
+
+/// Channel endpoints owned exclusively by the WebRTC sender thread after spawn.
+/// The reverse endpoints stay with StatePortal (or the encode thread) for
+/// inbound/outbound traffic.
+pub(super) struct WebRtcThreadChannels {
+    pub(super) webrtc_rx: crossbeam_channel::Receiver<EncodedH264Frame>,
+    pub(super) sent_gap_tx: crossbeam_channel::Sender<(f64, Option<f64>)>,
+    pub(super) bitrate_tx: crossbeam_channel::Sender<BitrateCommand>,
+    pub(super) resolution_tx: crossbeam_channel::Sender<BitrateCommand>,
+}
+
+pub(super) fn encode_thread_loop(
+    mut encode: SwEncEncode,
+    input_rx: crossbeam_channel::Receiver<CpuNv12Frame>,
+    timing_tx: crossbeam_channel::Sender<EncodeThreadTiming>,
+    duplicate_count: std::sync::Arc<std::sync::atomic::AtomicU64>,
+) {
+    loop {
+        match input_rx.recv() {
+            Ok(frame) => {
+                match encode.encode_cpu_frame(&frame) {
+                    Ok(EncodeOutcome::Encoded) => {
+                        let t = encode.take_timing();
+                        let _ = timing_tx.try_send(EncodeThreadTiming {
+                            sws_us: t.sws_us,
+                            encode_us: t.encode_us,
+                            output_bytes: t.output_bytes,
+                        });
+                    }
+                    Ok(EncodeOutcome::SkippedDuplicate) => {
+                        duplicate_count.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+                    }
+                    Ok(_) => {
+                        // SkippedPaused / SkippedDisconnected — no counter needed
+                    }
+                    Err(e) => {
+                        tracing::error!("Encode thread error: {e}");
+                        break;
+                    }
+                }
+            }
+            Err(_) => {
+                tracing::info!("Encode thread input closed, flushing encoder");
+                if let Err(e) = encode.flush() {
+                    tracing::error!("Encode thread flush error: {e}");
+                }
+                break;
+            }
+        }
+    }
+    tracing::info!("Encode thread exiting");
+}
+
+pub(super) fn webrtc_thread_loop(
+    mut wrtc: WebRtcState,
+    config: WebRtcThreadConfig,
+    channels: WebRtcThreadChannels,
+    paused: Arc<AtomicBool>,
+) {
+    let WebRtcThreadConfig {
+        fps,
+        enc_width,
+        enc_height,
+        max_bitrate,
+    } = config;
+    let WebRtcThreadChannels {
+        webrtc_rx,
+        sent_gap_tx,
+        bitrate_tx,
+        resolution_tx,
+    } = channels;
+    let mut frames_sent: u64 = 0;
+    let mut last_send: Option<std::time::Instant> = None;
+    let mut last_sent_bitrate: Option<u64> = None;
+    let initial_tier = (enc_width, enc_height);
+    let mut current_tier = initial_tier;
+    let mut upscale_counter = 0u32;
+    let mut last_resolution_eval = Instant::now();
+    let timeout = Duration::from_millis(1);
+
+    loop {
+        if let Err(e) = wrtc.handle_signaling() {
+            tracing::error!("WebRTC signaling error: {e}");
+            break;
+        }
+        if let Err(e) = wrtc.poll_and_feed() {
+            tracing::error!("WebRTC poll error: {e}");
+            break;
+        }
+
+        if wrtc.take_force_keyframe() {
+            let _ = bitrate_tx.try_send(BitrateCommand::ForceKeyframe);
+        }
+
+        let connected = wrtc.is_connected();
+        let was_paused = paused.load(Ordering::Relaxed);
+        let now_paused = !connected;
+        if was_paused && !now_paused {
+            tracing::info!("WebRTC client connected, resuming encoding");
+        } else if !was_paused && now_paused {
+            tracing::warn!("WebRTC client disconnected, pausing encoding");
+        }
+        paused.store(now_paused, Ordering::Relaxed);
+
+        if let Some(bwe) = wrtc.get_bwe_estimate() {
+            // #23: Cap BWE to prevent runaway bitrate escalation. Without this, BWE
+            // estimates can rise to 10+ Mbps, causing IDR bursts and PLI storms.
+            let effective_bwe = bwe.min(max_bitrate);
+            if effective_bwe != bwe {
+                tracing::debug!(
+                    bwe,
+                    effective_bwe,
+                    max_bitrate,
+                    "BWE exceeds --max-bitrate cap, clamping"
+                );
+            }
+            let bwe = effective_bwe;
+
+            let should_send = match last_sent_bitrate {
+                None => true,
+                Some(last) => {
+                    let diff = bwe.abs_diff(last);
+                    diff * 10 > last
+                }
+            };
+            if should_send {
+                let _ = bitrate_tx.try_send(BitrateCommand::UpdateBitrate { target_bps: bwe });
+                last_sent_bitrate = Some(bwe);
+            }
+
+            if last_resolution_eval.elapsed() >= Duration::from_secs(1) {
+                last_resolution_eval = Instant::now();
+                let selected = select_resolution(current_tier.0, current_tier.1, bwe, fps);
+                if selected != current_tier {
+                    current_tier = selected;
+                    upscale_counter = 0;
+                    let _ = resolution_tx.try_send(BitrateCommand::UpdateResolution {
+                        width: current_tier.0,
+                        height: current_tier.1,
+                    });
+                    wrtc.set_need_keyframe();
+                } else if let Some(next_tier) = next_upscale_tier(current_tier, initial_tier) {
+                    let needed = resolution_bitrate_bps(next_tier.0, next_tier.1, fps);
+                    if bwe > needed.saturating_mul(120) / 100 {
+                        upscale_counter = upscale_counter.saturating_add(1);
+                        if upscale_counter >= 10 {
+                            current_tier = next_tier;
+                            upscale_counter = 0;
+                            let _ = resolution_tx.try_send(BitrateCommand::UpdateResolution {
+                                width: current_tier.0,
+                                height: current_tier.1,
+                            });
+                            wrtc.set_need_keyframe();
+                        }
+                    } else {
+                        upscale_counter = 0;
+                    }
+                } else {
+                    upscale_counter = 0;
+                }
+            }
+        }
+
+        if connected {
+            while let Ok(enc_frame) = webrtc_rx.try_recv() {
+                if let Err(e) = wrtc.write_h264_frame(&enc_frame.data, enc_frame.pts_ticks) {
+                    tracing::debug!("WebRTC write frame error: {e}");
+                }
+                frames_sent = frames_sent.saturating_add(1);
+                let gap_ms = last_send
+                    .map(|l| l.elapsed().as_secs_f64() * 1000.0)
+                    .unwrap_or(0.0);
+                // Compute capture-to-send age on the sending thread so the
+                // frame_age stat stays accurate when batch-drained later.
+                let age_ms = Some(enc_frame.capture_time.elapsed().as_secs_f64() * 1000.0);
+                last_send = Some(std::time::Instant::now());
+                let _ = sent_gap_tx.try_send((gap_ms, age_ms));
+            }
+        } else {
+            while webrtc_rx.try_recv().is_ok() {}
+        }
+
+        match webrtc_rx.recv_timeout(timeout) {
+            Ok(enc_frame) => {
+                if wrtc.is_connected() {
+                    if let Err(e) = wrtc.write_h264_frame(&enc_frame.data, enc_frame.pts_ticks) {
+                        tracing::debug!("WebRTC write frame error: {e}");
+                    }
+                    frames_sent = frames_sent.saturating_add(1);
+                    let gap_ms = last_send
+                        .map(|l| l.elapsed().as_secs_f64() * 1000.0)
+                        .unwrap_or(0.0);
+                    let age_ms = Some(enc_frame.capture_time.elapsed().as_secs_f64() * 1000.0);
+                    last_send = Some(std::time::Instant::now());
+                    let _ = sent_gap_tx.try_send((gap_ms, age_ms));
+                }
+            }
+            Err(crossbeam_channel::RecvTimeoutError::Timeout) => {}
+            Err(crossbeam_channel::RecvTimeoutError::Disconnected) => {
+                tracing::info!("WebRTC channel disconnected, exiting thread");
+                return;
+            }
+        }
+    }
+
+    tracing::info!("WebRTC thread exiting");
+}
+
+#[cfg(test)]
+mod tests {
+
+    #[test]
+    fn try_send_full_channel_returns_full_not_block() {
+        let (tx, rx) = crossbeam_channel::bounded::<Vec<u8>>(2);
+        tx.send(vec![1]).unwrap();
+        tx.send(vec![2]).unwrap();
+
+        assert!(matches!(
+            tx.try_send(vec![3]),
+            Err(crossbeam_channel::TrySendError::Full(_))
+        ));
+        assert_eq!(rx.len(), 2);
+    }
+
+    #[test]
+    fn try_send_after_rx_dropped_returns_disconnected() {
+        let (tx, rx) = crossbeam_channel::bounded::<Vec<u8>>(2);
+        drop(rx);
+
+        assert!(matches!(
+            tx.try_send(vec![1]),
+            Err(crossbeam_channel::TrySendError::Disconnected(_))
+        ));
+    }
+
+    // given: full bounded channel
+    // when:  rx is dropped, then try_send
+    // expect: Disconnected, not blocking
+    #[test]
+    fn shutdown_rx_drop_prevents_deadlock_on_full_channel() {
+        let (tx, rx) = crossbeam_channel::bounded::<Vec<u8>>(2);
+        tx.send(vec![1]).unwrap();
+        tx.send(vec![2]).unwrap();
+        drop(rx);
+
+        assert!(matches!(
+            tx.try_send(vec![3]),
+            Err(crossbeam_channel::TrySendError::Disconnected(_))
+        ));
+    }
+}

src/stats.rs

@@ -201,7 +201,8 @@ impl PipelineStats {
     /// Update duplicate frames skipped counter (absolute value from atomic).
     /// Computes delta from previous value, like set_pipewire_dropped.
     pub fn set_duplicate_frames_skipped(&mut self, total_skipped: u64) {
-        self.duplicate_frames_skipped = total_skipped.saturating_sub(self.prev_duplicate_frames_skipped);
+        self.duplicate_frames_skipped =
+            total_skipped.saturating_sub(self.prev_duplicate_frames_skipped);
         self.prev_duplicate_frames_skipped = total_skipped;
     }
 
@@ -356,7 +357,7 @@ impl std::fmt::Display for StatsSnapshot {
         // central tendency and tail behaviour in the same glance.
         write!(
             f,
-             "elapsed={:.1}s capture_fps={:.1} encoded_fps={:.1} sent_fps={:.1} \
+            "elapsed={:.1}s capture_fps={:.1} encoded_fps={:.1} sent_fps={:.1} \
               capture_frames={} encoded_frames={} sent_frames={} \
               pw_dropped={} duplicate_frames_skipped={} \
               cap_q={} enc_q={} \

src/webrtc.rs

@@ -17,178 +17,8 @@ use str0m::{Candidate, Event, IceConnectionState, Input, Output, Rtc, RtcConfig}
 /// bursts. See issue #23.
 const FORCED_KEYFRAME_MIN_INTERVAL: Duration = Duration::from_secs(1);
 
-// ── 嵌入式 HTML 测试页面 ──────────────────────────────────────────────────
-
-const HTML_PAGE: &str = r#"<!DOCTYPE html>
-<html>
-<head><title>wl-webrtc P0</title>
-<style>body{background:#000;color:#fff;font-family:monospace;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100vh;margin:0}
-video{max-width:90vw;max-height:80vh;border:1px solid #333}
-#status{margin:12px;font-size:14px;color:#aaa}
-#debug{position:fixed;bottom:8px;left:8px;font-size:11px;color:#666;max-width:90vw;white-space:pre-wrap}
-#stats-panel{position:fixed;top:8px;right:8px;background:rgba(0,0,0,0.7);color:#0f0;font:11px monospace;padding:6px 10px;border-radius:4px;z-index:100;pointer-events:none;max-width:90vw;white-space:pre;line-height:1.5}
-</style></head>
-<body>
-<div id="status">Connecting...</div>
-<video id="video" autoplay playsinline muted></video>
-<pre id="debug"></pre>
-<div id="stats-panel"></div>
-<script>
-const status = document.getElementById('status');
-const video  = document.getElementById('video');
-const debug  = document.getElementById('debug');
-let pc       = null;
-
-const log = msg => { debug.textContent += msg + '\n'; console.log(msg); };
-
-function preferH264(sdp) {
-  const lines = sdp.split('\r\n');
-  const h264Pts = lines
-    .filter(line => line.startsWith('a=rtpmap:') && line.toUpperCase().includes('H264/90000'))
-    .map(line => line.match(/^a=rtpmap:(\d+)/)?.[1])
-    .filter(Boolean);
-  if (h264Pts.length === 0) return sdp;
-  return lines.map(line => {
-    if (!line.startsWith('m=video ')) return line;
-    const parts = line.split(' ');
-    const header = parts.slice(0, 3);
-    const pts = parts.slice(3);
-    const preferred = h264Pts.filter(pt => pts.includes(pt));
-    const rest = pts.filter(pt => !preferred.includes(pt));
-    return [...header, ...preferred, ...rest].join(' ');
-  }).join('\r\n');
-}
-
-function installStatsLogger(peer) {
-  const panel = document.getElementById('stats-panel');
-  let prev = null;
-  const intervalSecs = 1;
-
-  setInterval(() => {
-    if (peer !== pc) return;
-    peer.getStats().then(stats => {
-      let rtp = null, rtt = null, codecStr = '';
-      let freezeCount = null, totalFreezesDuration = null;
-
-      stats.forEach(report => {
-        if (report.type === 'inbound-rtp' && report.kind === 'video') rtp = report;
-        if (report.type === 'codec' && report.mimeType && report.mimeType.includes('H264'))
-          codecStr = report.mimeType + ' ' + (report.payloadType || '');
-        // candidate-pair: feature-detect 'selected' property
-        if (report.type === 'candidate-pair') {
-          const isSel = ('selected' in report) ? report.selected : report.state === 'succeeded';
-          if (isSel && typeof report.currentRoundTripTime === 'number') rtt = report.currentRoundTripTime;
-        }
-      });
-
-      // Freeze stats (feature-detect)
-      if (rtp && typeof rtp.freezeCount !== 'undefined') {
-        freezeCount = rtp.freezeCount;
-        totalFreezesDuration = rtp.totalFreezesDuration;
-      }
-
-      if (!rtp) return;
-
-      const cur = {
-        framesDecoded: rtp.framesDecoded || 0,
-        framesDropped: rtp.framesDropped || 0,
-        framesPerSecond: rtp.framesPerSecond || 0,
-        packetsLost: rtp.packetsLost || 0,
-        jitter: rtp.jitter || 0,
-        bytesReceived: rtp.bytesReceived || 0,
-        totalDecodeTime: rtp.totalDecodeTime || 0,
-        jitterBufferDelay: rtp.jitterBufferDelay || 0,
-        jitterBufferEmittedCount: rtp.jitterBufferEmittedCount || 0,
-        freezeCount: freezeCount,
-        totalFreezesDuration: totalFreezesDuration,
-        rtt: rtt,
-      };
-
-      // Raw log to debug element (backward compat)
-      log('RTP-in: decoded=' + cur.framesDecoded + ' lost=' + cur.packetsLost +
-          ' bytes=' + cur.bytesReceived + ' fps=' + cur.framesPerSecond +
-          (codecStr ? ' codec=' + codecStr : ''));
-
-      if (!prev) { prev = cur; return; }
-
-      // Compute deltas
-      const dFrames = cur.framesDecoded - prev.framesDecoded;
-      const dDropped = cur.framesDropped - prev.framesDropped;
-      const dLost = cur.packetsLost - prev.packetsLost;
-      const dBytes = cur.bytesReceived - prev.bytesReceived;
-      const dDecodeTime = cur.totalDecodeTime - prev.totalDecodeTime;
-      const dJitterBufDelay = cur.jitterBufferDelay - prev.jitterBufferDelay;
-      const dJitterBufCount = cur.jitterBufferEmittedCount - prev.jitterBufferEmittedCount;
-      const kbps = Math.round(dBytes * 8 / intervalSecs / 1000);
-      const decodeMs = dFrames > 0 ? (dDecodeTime / dFrames * 1000).toFixed(1) : '—';
-      const jitterBufMs = dJitterBufCount > 0 ? (dJitterBufDelay / dJitterBufCount * 1000).toFixed(1) : '—';
-      const jitterMs = (cur.jitter * 1000).toFixed(1);
-      const rttMs = cur.rtt !== null ? (cur.rtt * 1000).toFixed(1) : null;
-
-      let line = 'FPS:' + cur.framesPerSecond +
-        ' Decoded:' + cur.framesDecoded + '(+' + dFrames + ')' +
-        ' Dropped:' + cur.framesDropped + (dDropped > 0 ? '(+' + dDropped + ')' : '') +
-        ' Lost:' + dLost +
-        ' Jitter:' + jitterMs + 'ms' +
-        (rttMs !== null ? ' RTT:' + rttMs + 'ms' : '') +
-        ' Decode:' + decodeMs + 'ms' +
-        ' JBuf:' + jitterBufMs + 'ms';
-
-      if (freezeCount !== null) {
-        const dFreeze = cur.freezeCount - (prev.freezeCount || 0);
-        if (cur.freezeCount > 0 || dFreeze > 0)
-          line += ' Freeze:' + cur.freezeCount + '(+' + dFreeze + ')';
-      }
-
-      line += ' ' + kbps + 'kbps';
-
-      panel.textContent = line;
-      prev = cur;
-    }).catch(() => {});
-  }, intervalSecs * 1000);
-}
-
-function connect() {
-  if (pc) pc.close();
-  pc = new RTCPeerConnection();
-  const peer = pc;
-
-  peer.ontrack = e => {
-    log('ontrack: streams=' + e.streams.length + ' kind=' + e.track.kind);
-    video.srcObject = e.streams[0];
-    status.textContent = 'Track received';
-  };
-  peer.oniceconnectionstatechange = () => {
-    log('ICE: ' + peer.iceConnectionState);
-    status.textContent = 'ICE: ' + peer.iceConnectionState;
-  };
-
-  peer.addTransceiver('video', { direction: 'recvonly' });
-  installStatsLogger(peer);
-
-  peer.createOffer().then(offer => {
-      offer.sdp = preferH264(offer.sdp);
-      return peer.setLocalDescription(offer);
-    })
-    .then(() => new Promise(resolve => {
-      if (peer.iceGatheringState === 'complete') resolve();
-      else peer.onicegatheringstatechange = () => { if (peer.iceGatheringState === 'complete') resolve(); };
-    }))
-    .then(() => fetch('/sdp', { method: 'POST', body: JSON.stringify(peer.localDescription) }))
-    .then(r => { if (!r.ok) throw new Error('SDP exchange failed: ' + r.status); return r.json(); })
-    .then(answer => { if (answer.error) throw new Error(answer.error); return peer.setRemoteDescription(answer); })
-    .then(() => log('SDP answer set'))
-    .catch(e => {
-      status.textContent = 'Error: ' + e.message;
-      log('ERROR: ' + e.message + ' — retrying in 2s...');
-      console.error(e);
-      setTimeout(connect, 2000);
-    });
-}
-
-connect();
-</script>
-</body></html>"#;
+mod html_page;
+use html_page::HTML_PAGE;
 
 // ── WebRTC 状态 ───────────────────────────────────────────────────────────
 

src/webrtc/html_page.rs

@@ -0,0 +1,170 @@
+pub(super) const HTML_PAGE: &str = r#"<!DOCTYPE html>
+<html>
+<head><title>wl-webrtc P0</title>
+<style>body{background:#000;color:#fff;font-family:monospace;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100vh;margin:0}
+video{max-width:90vw;max-height:80vh;border:1px solid #333}
+#status{margin:12px;font-size:14px;color:#aaa}
+#debug{position:fixed;bottom:8px;left:8px;font-size:11px;color:#666;max-width:90vw;white-space:pre-wrap}
+#stats-panel{position:fixed;top:8px;right:8px;background:rgba(0,0,0,0.7);color:#0f0;font:11px monospace;padding:6px 10px;border-radius:4px;z-index:100;pointer-events:none;max-width:90vw;white-space:pre;line-height:1.5}
+</style></head>
+<body>
+<div id="status">Connecting...</div>
+<video id="video" autoplay playsinline muted></video>
+<pre id="debug"></pre>
+<div id="stats-panel"></div>
+<script>
+const status = document.getElementById('status');
+const video  = document.getElementById('video');
+const debug  = document.getElementById('debug');
+let pc       = null;
+
+const log = msg => { debug.textContent += msg + '\n'; console.log(msg); };
+
+function preferH264(sdp) {
+  const lines = sdp.split('\r\n');
+  const h264Pts = lines
+    .filter(line => line.startsWith('a=rtpmap:') && line.toUpperCase().includes('H264/90000'))
+    .map(line => line.match(/^a=rtpmap:(\d+)/)?.[1])
+    .filter(Boolean);
+  if (h264Pts.length === 0) return sdp;
+  return lines.map(line => {
+    if (!line.startsWith('m=video ')) return line;
+    const parts = line.split(' ');
+    const header = parts.slice(0, 3);
+    const pts = parts.slice(3);
+    const preferred = h264Pts.filter(pt => pts.includes(pt));
+    const rest = pts.filter(pt => !preferred.includes(pt));
+    return [...header, ...preferred, ...rest].join(' ');
+  }).join('\r\n');
+}
+
+function installStatsLogger(peer) {
+  const panel = document.getElementById('stats-panel');
+  let prev = null;
+  const intervalSecs = 1;
+
+  setInterval(() => {
+    if (peer !== pc) return;
+    peer.getStats().then(stats => {
+      let rtp = null, rtt = null, codecStr = '';
+      let freezeCount = null, totalFreezesDuration = null;
+
+      stats.forEach(report => {
+        if (report.type === 'inbound-rtp' && report.kind === 'video') rtp = report;
+        if (report.type === 'codec' && report.mimeType && report.mimeType.includes('H264'))
+          codecStr = report.mimeType + ' ' + (report.payloadType || '');
+        // candidate-pair: feature-detect 'selected' property
+        if (report.type === 'candidate-pair') {
+          const isSel = ('selected' in report) ? report.selected : report.state === 'succeeded';
+          if (isSel && typeof report.currentRoundTripTime === 'number') rtt = report.currentRoundTripTime;
+        }
+      });
+
+      // Freeze stats (feature-detect)
+      if (rtp && typeof rtp.freezeCount !== 'undefined') {
+        freezeCount = rtp.freezeCount;
+        totalFreezesDuration = rtp.totalFreezesDuration;
+      }
+
+      if (!rtp) return;
+
+      const cur = {
+        framesDecoded: rtp.framesDecoded || 0,
+        framesDropped: rtp.framesDropped || 0,
+        framesPerSecond: rtp.framesPerSecond || 0,
+        packetsLost: rtp.packetsLost || 0,
+        jitter: rtp.jitter || 0,
+        bytesReceived: rtp.bytesReceived || 0,
+        totalDecodeTime: rtp.totalDecodeTime || 0,
+        jitterBufferDelay: rtp.jitterBufferDelay || 0,
+        jitterBufferEmittedCount: rtp.jitterBufferEmittedCount || 0,
+        freezeCount: freezeCount,
+        totalFreezesDuration: totalFreezesDuration,
+        rtt: rtt,
+      };
+
+      // Raw log to debug element (backward compat)
+      log('RTP-in: decoded=' + cur.framesDecoded + ' lost=' + cur.packetsLost +
+          ' bytes=' + cur.bytesReceived + ' fps=' + cur.framesPerSecond +
+          (codecStr ? ' codec=' + codecStr : ''));
+
+      if (!prev) { prev = cur; return; }
+
+      // Compute deltas
+      const dFrames = cur.framesDecoded - prev.framesDecoded;
+      const dDropped = cur.framesDropped - prev.framesDropped;
+      const dLost = cur.packetsLost - prev.packetsLost;
+      const dBytes = cur.bytesReceived - prev.bytesReceived;
+      const dDecodeTime = cur.totalDecodeTime - prev.totalDecodeTime;
+      const dJitterBufDelay = cur.jitterBufferDelay - prev.jitterBufferDelay;
+      const dJitterBufCount = cur.jitterBufferEmittedCount - prev.jitterBufferEmittedCount;
+      const kbps = Math.round(dBytes * 8 / intervalSecs / 1000);
+      const decodeMs = dFrames > 0 ? (dDecodeTime / dFrames * 1000).toFixed(1) : '—';
+      const jitterBufMs = dJitterBufCount > 0 ? (dJitterBufDelay / dJitterBufCount * 1000).toFixed(1) : '—';
+      const jitterMs = (cur.jitter * 1000).toFixed(1);
+      const rttMs = cur.rtt !== null ? (cur.rtt * 1000).toFixed(1) : null;
+
+      let line = 'FPS:' + cur.framesPerSecond +
+        ' Decoded:' + cur.framesDecoded + '(+' + dFrames + ')' +
+        ' Dropped:' + cur.framesDropped + (dDropped > 0 ? '(+' + dDropped + ')' : '') +
+        ' Lost:' + dLost +
+        ' Jitter:' + jitterMs + 'ms' +
+        (rttMs !== null ? ' RTT:' + rttMs + 'ms' : '') +
+        ' Decode:' + decodeMs + 'ms' +
+        ' JBuf:' + jitterBufMs + 'ms';
+
+      if (freezeCount !== null) {
+        const dFreeze = cur.freezeCount - (prev.freezeCount || 0);
+        if (cur.freezeCount > 0 || dFreeze > 0)
+          line += ' Freeze:' + cur.freezeCount + '(+' + dFreeze + ')';
+      }
+
+      line += ' ' + kbps + 'kbps';
+
+      panel.textContent = line;
+      prev = cur;
+    }).catch(() => {});
+  }, intervalSecs * 1000);
+}
+
+function connect() {
+  if (pc) pc.close();
+  pc = new RTCPeerConnection();
+  const peer = pc;
+
+  peer.ontrack = e => {
+    log('ontrack: streams=' + e.streams.length + ' kind=' + e.track.kind);
+    video.srcObject = e.streams[0];
+    status.textContent = 'Track received';
+  };
+  peer.oniceconnectionstatechange = () => {
+    log('ICE: ' + peer.iceConnectionState);
+    status.textContent = 'ICE: ' + peer.iceConnectionState;
+  };
+
+  peer.addTransceiver('video', { direction: 'recvonly' });
+  installStatsLogger(peer);
+
+  peer.createOffer().then(offer => {
+      offer.sdp = preferH264(offer.sdp);
+      return peer.setLocalDescription(offer);
+    })
+    .then(() => new Promise(resolve => {
+      if (peer.iceGatheringState === 'complete') resolve();
+      else peer.onicegatheringstatechange = () => { if (peer.iceGatheringState === 'complete') resolve(); };
+    }))
+    .then(() => fetch('/sdp', { method: 'POST', body: JSON.stringify(peer.localDescription) }))
+    .then(r => { if (!r.ok) throw new Error('SDP exchange failed: ' + r.status); return r.json(); })
+    .then(answer => { if (answer.error) throw new Error(answer.error); return peer.setRemoteDescription(answer); })
+    .then(() => log('SDP answer set'))
+    .catch(e => {
+      status.textContent = 'Error: ' + e.message;
+      log('ERROR: ' + e.message + ' — retrying in 2s...');
+      console.error(e);
+      setTimeout(connect, 2000);
+    });
+}
+
+connect();
+</script>
+</body></html>"#;