feat(windows): add viewer-only PixelPass milestone

2026-08-22 20:42:23 -04:00
parent 2f00df758d
commit ca3122b92f
16 changed files with 502 additions and 93 deletions
@@ -0,0 +1,102 @@
+# Windows support
+
+## Current milestone
+
+PixelPass on Windows is a **viewer**, not a screen-share host. It preserves the
+same viewer-side architecture used on Linux:
+
+1. parse an iroh endpoint ticket;
+2. connect to the Linux host over the existing `pixelpass/0` ALPN;
+3. expose the tunneled MPEG-TS stream on a random loopback HTTP port;
+4. emit `{"event":"connected","url":"http://127.0.0.1:..."}` when
+   `--output json` is enabled;
+5. let PeerSpeak launch VLC/mpv, or launch one from PixelPass's interactive
+   viewer prompt.
+
+No codec, container, ticket, ALPN, or JSON protocol fork was introduced for
+Windows.
+
+## Support matrix
+
+| Capability | Linux | Windows 10 |
+| --- | --- | --- |
+| View a share | Yes | Yes |
+| Headless `--output json` viewer | Yes | Yes |
+| Interactive viewer/player launch | Yes | Yes |
+| Host Wayland/X11 capture | Yes | No |
+| Host desktop/system audio | PipeWire/Pulse | No |
+| PeerSpeak voice exclusion | Yes | No |
+| PixelPass GUI | Yes (feature build) | No |
+
+Unsupported host operations fail with an explicit viewer-only error. On
+Windows, `--capabilities` reports both host-audio capability flags as `false`,
+so parent integrations cannot mistake this milestone for full hosting parity.
+
+## Build
+
+From Linux with Rust 1.95+ and MinGW-w64 installed:
+
+```sh
+rustup target add x86_64-pc-windows-gnu
+cargo build --release --target x86_64-pc-windows-gnu
+```
+
+The artifact is:
+
+```text
+target/x86_64-pc-windows-gnu/release/pixelpass.exe
+```
+
+The Windows target does not compile or link PipeWire, PulseAudio, Wayland, X11,
+or the Linux GUI stack. Keep the build headless; `--gui` is intentionally
+rejected on Windows.
+
+## Validation gates
+
+Before bundling a Windows binary with PeerSpeak:
+
+```sh
+cargo fmt -- --check
+cargo clippy --target x86_64-pc-windows-gnu -- -D warnings
+cargo test -- --test-threads=1
+cargo build --release --target x86_64-pc-windows-gnu
+```
+
+Then on an actual Windows 10 build 19045 VM:
+
+1. verify the transferred SHA-256;
+2. run `pixelpass.exe --version` and `pixelpass.exe --capabilities`;
+3. run `pixelpass.exe --doctor` with VLC or mpv installed;
+4. start a real Linux host, pass its fresh ticket to the Windows executable
+   with `--output json`, and verify the `connected` event;
+5. open the emitted loopback URL in the player and confirm moving video and
+   audio;
+6. stop the player/viewer and confirm both sides terminate cleanly.
+
+### Verified baseline
+
+On 2026-08-22 this gate passed on Windows 10 Enterprise Evaluation build 19045
+against a Wayland Linux host using software x264 at the Low preset. The Windows
+viewer emitted a loopback URL, VLC 3.0.23 rendered the live desktop, closing VLC
+terminated the viewer, and the host emitted `viewer_left` followed by
+`capture: stopped`. The final release artifact was 13,165,056 bytes with
+SHA-256:
+
+```text
+3eabd9f0dcd8565136a5c87a79470eceedd426cea5708904d7492a6fa37b3c49
+```
+
+The run deliberately declined Windows Defender's one-off public-network allow
+prompt; relay viewing succeeded without it. A packaged application should own
+an explicit, idempotent firewall rule for the final installed path instead of
+depending on that prompt.
+
+## Next Windows phases
+
+Windows hosting should be added behind a native capture boundary rather than by
+weakening the Linux implementation:
+
+1. desktop/window video capture and H.264 encode;
+2. WASAPI system-audio capture;
+3. PeerSpeak-owned voice/AEC exclusion with a fail-closed contract;
+4. dependency packaging, firewall rules, and installer upgrade coverage.