rename: lumen → punktfunk, everywhere

Full project rename, decided 2026-06-10: - Crates/binaries: punktfunk-core / punktfunk-host / punktfunk-client-rs. - C ABI: punktfunk_* symbols, Punktfunk* types, include/punktfunk_core.h, PUNKTFUNK_FEATURE_QUIC guard (header regenerated; cbindgen renames updated, incl. PUNKTFUNK_BTN_*/PUNKTFUNK_AXIS_* wire constants). - Protocol: punktfunk/1 — control-plane magic LMN1 → PKF1, nonce salt lmn1 → pkf1. WIRE BREAK: clients must be rebuilt from this revision. - Env knobs: PUNKTFUNK_VIDEO_SOURCE / PUNKTFUNK_COMPOSITOR / PUNKTFUNK_ZEROCOPY / …. - Host config dir: ~/.config/punktfunk (the box's dir was migrated in place — the persistent identity is unchanged, pinned fingerprints stay valid). - Swift package: PunktfunkKit + PunktfunkCore.xcframework + PunktfunkConnection (Sources/PunktfunkClient app + tests renamed with it); build-xcframework.sh updated. - scripts/: 60-punktfunk.rules, punktfunk-host.service; OpenAPI doc regenerated. Also: scripts/headless/run-headless-kde.sh — full headless Plasma bringup. Root cause of "desktop but no apps/settings" over the stream: plasmashell launched without XDG_MENU_PREFIX=plasma-, so the launcher resolved a nonexistent applications.menu and rendered an empty menu. The script sets the complete KDE session env (menu prefix, KDE_FULL_SESSION, session version) and rebuilds ksycoca before starting plasmashell. Gate: 97/97 tests, clippy -D warnings (both feature sets), fmt, C-ABI harness PASS, zero lumen references left outside .git. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-10 13:11:59 +00:00
parent 2807976561
commit 8cceb93541
114 changed files with 1138 additions and 1078 deletions
@@ -0,0 +1,313 @@
+//! KWin virtual-output backend via the privileged `zkde_screencast_unstable_v1` Wayland
+//! protocol (the mechanism KRdp / krfb-virtualmonitor use).
+//!
+//! `stream_virtual_output(name, width, height, scale, pointer)` asks KWin to create a new output
+//! sized to exactly `width`x`height`, rendered natively (no scaling), and hands back a PipeWire
+//! node for it. The node lives on the user's default PipeWire daemon, so [`VirtualOutput::remote_fd`]
+//! is `None` and capture connects to that daemon directly.
+//!
+//! Requirements: KWin must expose the privileged `zkde_screencast` global — a real Plasma session
+//! authorizes it for its own clients; the headless test exposes it to bare clients via
+//! `KWIN_WAYLAND_NO_PERMISSION_CHECKS=1`. The compositor backend must implement
+//! `createVirtualOutput`: the **DRM backend** (any version) or the **VirtualBackend since KWin
+//! 6.5.6** (`kwin_wayland --virtual`); on `--virtual` < 6.5.6 the request fails with
+//! "Could not find output". We talk raw Wayland on `$WAYLAND_DISPLAY`, so the host must run inside
+//! the KWin session's environment.
+
+#![allow(clippy::all, dead_code, non_camel_case_types, non_snake_case, unused)]
+
+use super::{Mode, VirtualDisplay, VirtualOutput};
+use anyhow::{anyhow, bail, Context, Result};
+use std::os::fd::{AsFd, AsRawFd};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc::Sender;
+use std::sync::Arc;
+use std::thread;
+use std::time::Duration;
+use wayland_client::protocol::wl_registry::{self, WlRegistry};
+use wayland_client::{Connection, Dispatch, Proxy, QueueHandle};
+
+// Generate the client bindings for the vendored protocol XML inline (no build.rs). Path is
+// relative to CARGO_MANIFEST_DIR. See wayland-rs' "implementing a custom protocol" docs.
+#[allow(clippy::all, dead_code, non_camel_case_types, non_snake_case, unused)]
+pub mod zkde {
+    use wayland_client;
+    use wayland_client::protocol::*;
+
+    pub mod __interfaces {
+        use wayland_client::protocol::__interfaces::*;
+        wayland_scanner::generate_interfaces!("protocols/zkde-screencast-unstable-v1.xml");
+    }
+    use self::__interfaces::*;
+
+    wayland_scanner::generate_client_code!("protocols/zkde-screencast-unstable-v1.xml");
+}
+
+use zkde::zkde_screencast_stream_unstable_v1::{
+    Event as StreamEvent, ZkdeScreencastStreamUnstableV1 as ScreencastStream,
+};
+use zkde::zkde_screencast_unstable_v1::ZkdeScreencastUnstableV1 as Screencast;
+
+/// `pointer` attachment mode (the protocol enum): render the cursor into the stream so the
+/// remote sees it move with injected input.
+const POINTER_EMBEDDED: u32 = 2;
+
+/// The name we give the created output; KWin exposes it to output-management as `Virtual-<name>`.
+const VOUT_NAME: &str = "punktfunk";
+
+/// Highest interface version we drive. KWin currently advertises 5; we rely on the `created`
+/// event (deprecated only since v6) for the node id, so cap the bind at 5.
+const MAX_VERSION: u32 = 5;
+
+/// The KWin virtual-display driver. Stateless — each [`create`](VirtualDisplay::create) spins up
+/// its own Wayland connection/thread that owns the resulting output.
+pub struct KwinDisplay;
+
+impl KwinDisplay {
+    pub fn new() -> Result<Self> {
+        Ok(KwinDisplay)
+    }
+}
+
+impl VirtualDisplay for KwinDisplay {
+    fn name(&self) -> &'static str {
+        "kwin"
+    }
+
+    fn create(&mut self, mode: Mode) -> Result<VirtualOutput> {
+        let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<u32, String>>();
+        let stop = Arc::new(AtomicBool::new(false));
+        let stop_thread = stop.clone();
+        let (width, height) = (mode.width, mode.height);
+        thread::Builder::new()
+            .name("punktfunk-kwin-vout".into())
+            .spawn(move || virtual_output_thread(width, height, setup_tx, stop_thread))
+            .context("spawn KWin virtual-output thread")?;
+
+        let node_id = match setup_rx.recv_timeout(Duration::from_secs(20)) {
+            Ok(Ok(v)) => v,
+            Ok(Err(e)) => bail!("KWin virtual output failed: {e}"),
+            Err(_) => bail!("timed out creating the KWin virtual output"),
+        };
+        tracing::info!(node_id, width, height, "KWin virtual output ready");
+        // KWin creates virtual outputs at a hardcoded 60 Hz and `stream_virtual_output` has no
+        // refresh argument, so when the client wants more we install + select a custom mode
+        // (supported on virtual outputs since KWin 6.6). Done before capture connects PipeWire so
+        // the stream negotiates at the higher rate. First cut shells out to kscreen-doctor; the
+        // in-process kde_output_management_v2 client is a follow-up.
+        if mode.refresh_hz > 60 {
+            set_custom_refresh(width, height, mode.refresh_hz);
+        }
+        Ok(VirtualOutput {
+            node_id,
+            remote_fd: None,
+            preferred_mode: Some((mode.width, mode.height, mode.refresh_hz)),
+            keepalive: Box::new(StopGuard(stop)),
+        })
+    }
+}
+
+/// Best-effort: raise the just-created virtual output's refresh above KWin's default 60 Hz by
+/// installing + selecting a custom mode via `kscreen-doctor` (the output is `Virtual-<VOUT_NAME>`,
+/// refresh given in mHz). Failure leaves the source at 60 Hz — the stream still works, just capped.
+fn set_custom_refresh(width: u32, height: u32, hz: u32) {
+    let output = format!("Virtual-{VOUT_NAME}");
+    let mhz = hz.saturating_mul(1000);
+    let run = |arg: String| {
+        std::process::Command::new("kscreen-doctor")
+            .arg(arg)
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false)
+    };
+    // Add the custom mode (a fresh output has none), then select it.
+    let _ = run(format!(
+        "output.{output}.addCustomMode.{width}.{height}.{mhz}.full"
+    ));
+    if run(format!("output.{output}.mode.{width}x{height}@{hz}")) {
+        tracing::info!(output, hz, "KWin virtual output: custom refresh applied");
+    } else {
+        tracing::warn!(
+            output,
+            hz,
+            "kscreen-doctor refresh set failed — source stays 60 Hz (is kscreen-doctor installed?)"
+        );
+    }
+}
+
+/// Dropping this releases the KWin virtual output: it flips the keepalive thread's `stop`, which
+/// drops the Wayland connection and makes KWin reclaim the output.
+struct StopGuard(Arc<AtomicBool>);
+
+impl Drop for StopGuard {
+    fn drop(&mut self) {
+        self.0.store(true, Ordering::Relaxed);
+    }
+}
+
+#[derive(Default)]
+struct State {
+    screencast: Option<Screencast>,
+    node_id: Option<u32>,
+    failed: Option<String>,
+    closed: bool,
+}
+
+impl Dispatch<WlRegistry, ()> for State {
+    fn event(
+        state: &mut Self,
+        registry: &WlRegistry,
+        event: wl_registry::Event,
+        _: &(),
+        _: &Connection,
+        qh: &QueueHandle<Self>,
+    ) {
+        if let wl_registry::Event::Global {
+            name,
+            interface,
+            version,
+        } = event
+        {
+            if interface == Screencast::interface().name {
+                let v = version.min(MAX_VERSION);
+                state.screencast = Some(registry.bind::<Screencast, _, _>(name, v, qh, ()));
+            }
+        }
+    }
+}
+
+// The manager has no events.
+impl Dispatch<Screencast, ()> for State {
+    fn event(
+        _: &mut Self,
+        _: &Screencast,
+        _: zkde::zkde_screencast_unstable_v1::Event,
+        _: &(),
+        _: &Connection,
+        _: &QueueHandle<Self>,
+    ) {
+    }
+}
+
+impl Dispatch<ScreencastStream, ()> for State {
+    fn event(
+        state: &mut Self,
+        _: &ScreencastStream,
+        event: StreamEvent,
+        _: &(),
+        _: &Connection,
+        _: &QueueHandle<Self>,
+    ) {
+        match event {
+            StreamEvent::Created { node } => state.node_id = Some(node),
+            StreamEvent::Failed { error } => state.failed = Some(error),
+            StreamEvent::Closed => state.closed = true,
+            // `serial` (v6) — we use the node id from `created`, so ignore.
+            _ => {}
+        }
+    }
+}
+
+/// Worker thread: create a `width`x`height` virtual output on KWin, send its PipeWire node id
+/// back over `setup_tx`, then keep the Wayland connection alive (so the output isn't destroyed)
+/// until `stop` is set. Mirrors the portal thread's "park to keep the session alive".
+fn virtual_output_thread(
+    width: u32,
+    height: u32,
+    setup_tx: Sender<Result<u32, String>>,
+    stop: Arc<AtomicBool>,
+) {
+    if let Err(e) = run(width, height, &setup_tx, &stop) {
+        // If we never delivered a node id, report the failure to the waiting opener.
+        let _ = setup_tx.send(Err(format!("{e:#}")));
+    }
+}
+
+fn run(
+    width: u32,
+    height: u32,
+    setup_tx: &Sender<Result<u32, String>>,
+    stop: &AtomicBool,
+) -> Result<()> {
+    let conn = Connection::connect_to_env()
+        .context("connect to KWin Wayland (is WAYLAND_DISPLAY set to the KWin socket?)")?;
+    let mut queue = conn.new_event_queue();
+    let qh = queue.handle();
+    let _registry = conn.display().get_registry(&qh, ());
+
+    let mut state = State::default();
+    queue.roundtrip(&mut state).context("registry roundtrip")?;
+
+    let screencast = state.screencast.clone().ok_or_else(|| {
+        anyhow!(
+            "KWin does not expose zkde_screencast_unstable_v1 (need a real KDE session, or run \
+             KWin with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 for the headless test)"
+        )
+    })?;
+
+    // Create the virtual output sized to the client, cursor composited into the stream.
+    let stream = screencast.stream_virtual_output(
+        VOUT_NAME.to_string(),
+        width as i32,
+        height as i32,
+        1.0, // scale (logical == physical)
+        POINTER_EMBEDDED,
+        &qh,
+        (),
+    );
+    tracing::info!(
+        width,
+        height,
+        "KWin: requested virtual output; awaiting PipeWire node"
+    );
+
+    // Pump events until KWin reports the node id (or an error).
+    let node_id = loop {
+        queue
+            .blocking_dispatch(&mut state)
+            .context("wayland dispatch (awaiting created)")?;
+        if let Some(node) = state.node_id {
+            break node;
+        }
+        if let Some(e) = state.failed.take() {
+            bail!("stream_virtual_output failed: {e}");
+        }
+        if state.closed {
+            bail!("KWin closed the stream before it was created");
+        }
+    };
+    setup_tx
+        .send(Ok(node_id))
+        .map_err(|_| anyhow!("virtual-output opener went away"))?;
+
+    // Keep the connection (and thus the virtual output) alive until told to stop, observing
+    // `closed`. blocking_dispatch can't be interrupted, so poll the connection fd with a short
+    // timeout so `stop` is honored within ~200 ms.
+    while !stop.load(Ordering::Relaxed) {
+        queue
+            .dispatch_pending(&mut state)
+            .context("dispatch_pending")?;
+        if state.closed {
+            tracing::warn!("KWin closed the virtual-output stream");
+            break;
+        }
+        conn.flush().context("wayland flush")?;
+        let Some(guard) = conn.prepare_read() else {
+            continue; // events already queued — loop dispatches them
+        };
+        let mut pfd = libc::pollfd {
+            fd: conn.as_fd().as_raw_fd(),
+            events: libc::POLLIN,
+            revents: 0,
+        };
+        let r = unsafe { libc::poll(&mut pfd, 1, 200) };
+        if r > 0 && (pfd.revents & libc::POLLIN) != 0 {
+            let _ = guard.read();
+        } // else: timeout or signal — drop the guard, re-check `stop`
+    }
+
+    // Best-effort clean teardown; dropping the connection also makes KWin reclaim the output.
+    stream.close();
+    let _ = conn.flush();
+    Ok(())
+}