# Screen-share integration (peerspeak ↔ pixelpass)

Design decisions for surfacing pixelpass screen-sharing from inside a peerspeak
room. Locked 2026-06-06; **implemented 2026-06-06** (`src/screenshare/mod.rs` +
presence-borne ticket; tests-green, the 2-machine gossip path not yet
field-verified). peerspeak owns voice, pixelpass owns pixels — this doc is the
seam between them.

## Open questions — resolved (Discord-modelled)

- **Concurrency:** multiple simultaneous sharers, Discord-style. Sharing rides
  *presence* (`PeerState.sharing: Option<ticket>`), so each sharer shows one
  offer; no artificial one-at-a-time cap.
- **Late joiners:** yes — because sharing is presence, the existing gossip
  re-announce delivers an in-progress offer to a new joiner for free (no
  separate `ScreenShareOffer` message was needed; the doc's sketch is superseded
  by the presence-field approach).
- **Viewer limit:** not overridden — pixelpass bandwidth-measures its own safe
  cap; a full host's `viewer_refused` surfaces as a UI error.
- **UI placement:** per-peer card (🔴 Live + 👁 Watch on the sharer's card;
  🔴 Sharing badge + Stop on the self card) — the Discord "Live badge" model.
- **Player:** viewer parses `connected{url}` and opens mpv (vlc fallback),
  mirroring pixelpass's own low-latency invocation.

## Core principle: mutually optional, runtime-only coupling

**Neither tool is a Cargo dependency of the other, in either direction.**

- peerspeak works fully without pixelpass installed; the screen-share control
  just degrades (greyed / "needs pixelpass — install it").
- pixelpass works fully without peerspeak; nothing here makes it require voice.
- The integration is **runtime subprocess + a stable contract**, never a crate
  import. The contract peerspeak depends on is pixelpass's **CLI flags + JSON
  event stream**, treated as a public API.
- Keep the contract **symmetric** so the reverse direction (pixelpass launching
  peerspeak for a "call these viewers" button) stays possible later. No
  master/slave assumption.

## Chosen approach: B — auto ticket-exchange over peerspeak's gossip plane

1. User clicks **Share screen** in a peerspeak room.
2. peerspeak spawns `pixelpass --host --output json` as a child process (video
   only — see audio decision below).
3. peerspeak scrapes the `{"event":"ticket","value":"..."}` line from the
   child's **stdout** (emitted once at host startup).
4. peerspeak broadcasts a **new typed gossip message**,
   `ScreenShareOffer { from, ticket }`, over the same gossip plane that already
   carries chat + presence.
5. Each peer's peerspeak shows "**<name> is sharing — [View]**".
6. Clicking **View** spawns `pixelpass <ticket> --output json` as a viewer; it
   opens in **its own pixelpass window** (not embedded in iced).
7. When the sharer stops, peerspeak kills the host child and broadcasts a
   `ScreenShareEnded { from }` (or equivalent) so viewers' indicators clear.

Rejected: **A** (manual ticket via chat — barely integrated) and **C** (deep
embed / shared iroh identity — large, fights pixelpass's window model and the
two-tools philosophy).

## Why this is cheap

pixelpass was built to be driven as a child process:

- `--output json` exists explicitly for a front-end (its own `--gui` re-execs
  `pixelpass --host --output json` and parses the stream). See
  `pixelpass/src/common/output.rs`.
- Host emits: `ticket`, `host_info`, `viewer_joined`, `viewer_left`, `capture`,
  `viewer_refused`. Viewer emits: `connected { url }`. Host reads a `kick`
  command on **stdin**.
- **The ticket is the capability.** The data-plane host (`serve.rs`) gates
  viewers only by `max_viewers` — there is **no friends-list ACL** on the
  stream (friends is a separate control-plane/presence concept the headless CLI
  ignores). So distributing the ticket over gossip = granting room access, with
  no ACL to fight.
- pixelpass is **1 host → N viewers** (asymmetric), which maps cleanly onto
  "I share, the room watches."

## Locked sub-decisions

- **Audio: video only** on the room-launch path. Do not pass pixelpass's audio
  capture, so screen-share audio can't echo/double with peerspeak's voice mix.
- **Separate window** for the viewer (pixelpass's own), not embedded in iced.
- **Binary discovery:** look up `pixelpass` on `$PATH`; allow a config override
  for a non-standard location. Absence is a normal, handled state, not an error.

## Open questions for implementation

- **Concurrency / who can share:** one sharer at a time, or multiple
  simultaneous shares (N independent host processes + N offers + a list UI)?
- **Subprocess supervision:** how peerspeak tracks child lifetime, surfaces
  `viewer_refused` / capture failures, and cleans up on room-leave or crash
  (pixelpass has `--repair` for orphaned PipeWire state).
- **Offer lifecycle on the gossip plane:** late joiners — do we re-announce
  active shares to someone who joins mid-share?
- **UI placement:** where the Share button + incoming-offer indicators live
  across the three room layouts (3-Column / Bottom Dock / Drawer).

## Build sketch (peerspeak side, for next session)

1. New gossip message variant(s): `ScreenShareOffer`/`ScreenShareEnded` in the
   gossip wire type; bump/relax parsing compatibly.
2. A `screenshare` subprocess supervisor module (spawn host, parse JSON stdout,
   track child, kill on stop) — keep the JSON-parsing a pure testable seam.
3. `AppMessage` + state: `StartScreenShare`, `StopScreenShare`,
   `ViewShare(EndpointId)`, active-share map, "pixelpass present?" probe.
4. UI: Share button + per-peer "View" affordance; graceful disabled state when
   the binary is absent.