docs: next-goals roadmap (KDE reliability → options → mic → Bazzite → touch → UHID DualSense)

Research-grounded sequence + per-goal approach/effort. Decisions: start with KDE startup
reliability; Bazzite via COPR RPM then bootc image; commit to full UHID DualSense.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/roadmap.md

@@ -0,0 +1,77 @@
+# punktfunk roadmap — next goals
+
+Decided 2026-06-10 (research-grounded; see commit history). Sequence:
+**KDE reliability → client compositor options → mic passthrough → Bazzite COPR RPM (then
+bootc) → touch → full UHID DualSense → iOS.**
+
+## 1. Reliable headless KDE/compositor spawning *(in progress)*
+
+Startup is a chain of timing-sensitive handoffs with no readiness checks — each is a blind
+`sleep`, one-shot timeout, or silent fire-and-forget that fails into a black screen.
+
+- **Phase 1 (S):** replace `run-headless-kde.sh`'s blind `sleep 2` with an active readiness
+  wait (kwin socket + `wl_display` roundtrip + `zkde_screencast` global advertised +
+  KWIN_PID alive); add a `punktfunk-host probe-compositor` subcommand (reuses kwin.rs's
+  registry roundtrip); move the portal restart to *after* readiness and precede it with
+  `systemctl --user import-environment` + `dbus-update-activation-environment` (the missing
+  env import — the Sway script does this, the KDE one doesn't).
+- **Phase 2 (M):** bounded retry-with-backoff around `vd.create()` + first-frame
+  (permanent vs transient); a PipeWire negotiation watchdog with zero-copy→CPU auto-fallback
+  ("no PipeWire frame within 10s" → recovery or precise diagnosis); fix `set_custom_refresh`
+  to wait for the output, read back the active mode, reconcile encoder fps; harden gamescope
+  node discovery + detect the known-bad-gamescope signature; graceful PipeWire-thread stop.
+- **Phase 3 (L):** supervised systemd user session (kwin + portal + host) with the readiness
+  probe as an `ExecStartPost` gate, `Restart=on-failure`.
+
+## 2. Offer available compositors in the client *(M)*
+
+Host enumerates which backends are actually available (binary present + version OK:
+gamescope ≥3.16.22, KWin ≥6.5.6, gnome-shell, sway), advertises the list in the punktfunk/1
+Welcome + a mgmt-API field; client sends its pick in the Hello; host honors it per session.
+Picker in the Apple client + web console.
+
+## 3. Bazzite / install on other devices *(decision: COPR RPM → bootc)*
+
+Bazzite already ships gamescope + PipeWire + the NVIDIA driver (incl. `libnvidia-encode`);
+it's Fedora-atomic and the community installs Sunshine via COPR rpm-ostree — the analog.
+
+- **M-Bazzite-1:** a **COPR RPM** (primary) — binary + `60-punktfunk.rules` (→
+  `/usr/lib/udev/rules.d`) + systemd `--user` unit + `host.env.example`; `Requires` the
+  NVENC ffmpeg-libs Bazzite already pulls; links host `libcuda`/`libnvidia-encode` directly.
+  Install = `rpm-ostree install` + reboot + add to `input`/`render`. Default backend =
+  Bazzite's already-present **gamescope** (minimal session plumbing).
+- **M-Bazzite-2:** wrap the RPM in a **bootc/OCI image layer** (`FROM
+  ghcr.io/ublue-os/bazzite-nvidia:stable`) for the appliance/"just rebase" experience.
+- Flatpak only later as an explicitly-degraded convenience build (sandbox fights
+  zero-copy NVENC/dmabuf/uinput).
+
+## 4. Mic passthrough — client mic → host input device *(S+M)*
+
+The exact mirror of the host→client desktop-audio path. A PipeWire virtual source apps can
+select = a `pw_stream` with `Direction::Output` + `media.class=Audio/Source`.
+
+- New `0xCB` MIC_AUDIO datagram (mirror of `0xC9`) + `NativeClient::send_audio` + ABI
+  `punktfunk_send_audio`.
+- `audio/source_linux.rs` — near-copy of the capture file, Direction::Output, fed from a
+  jitter buffer (silence-fill underrun, Opus PLC).
+- Host `mic_thread` (Opus decode → ring → source); teardown RAII, set `node.dont-reconnect`.
+- Apple capture (AVAudioEngine → Opus). **Opt-in + paired-only** (a remote mic is a privacy
+  surface). punktfunk/1-only.
+
+## 5. Touch + rich DualSense *(decision: commit to full UHID DualSense)*
+
+- **Touch (M):** `reis` already exposes `ei_touchscreen` — add Touch InputKinds + wire
+  `ei::Touchscreen` in `inject/libei.rs` (reuse the abs-pointer region mapping). Multi-touch
+  on KWin/Mutter; single-pointer fallback elsewhere.
+- **Rich DualSense (XL, committed):** uinput can't carry HID output reports. Use **UHID** +
+  the kernel `hid-playstation` driver (the inputtino/Wolf approach): present a genuine
+  DualSense (real report descriptor, vendor 054C/0CE6, BT mode + CRC32) so games drive LED +
+  adaptive triggers + touchpad + gyro; forward `UHID_OUTPUT` (LED color, trigger effects) to
+  the client's `GCDualSense*` APIs. Needs a variable-length gamepad/touch event family
+  (the fixed 18-byte InputEvent can't hold touchpad/motion), per-client controller-type
+  negotiation, and a `/dev/uhid` udev rule. Phase after touch + a protocol-growth step.
+
+## 6. iOS/iPadOS → tvOS *(deferred)*
+
+PunktfunkKit is already platform-shared; iOS needs the `UIViewRepresentable` presenter twin
++ touch capture (#5) + UI. tvOS later.