Piik/docs/adr/0010-cross-platform-client-runtime.md

ADR-0010: Cross-Platform App Runtime

• Status: accepted capability-provider architecture and native endpoint media boundary
• Date: 2026-09-05
• Superseded in part: items 1, 5, 7, 12 (its supervisor sentence), 13, 14, and the local-package consequence were amended in place by ADR-0012, which replaced the TypeScript server with one shared Go core.
• ADR-0013 supersedes item 8's single-output, Pion-GCC-observation-only and Browser-mediated LiveKit publisher details for the current candidate. The shared encoded-media adapter and direct Native SFU publisher preserve this ADR's participant and capability boundaries. The independent bounded control-session contract remains current; historical acceptance below does not validate the new media implementation.

Context

The Browser is the current Piik interaction surface, but it cannot own native capture, hardware encode, or reusable native sockets. A self-contained package must add those capabilities without creating another room model, signaling protocol, route controller, or UI.

Existing Piik room, admission, signaling, and routing behavior already has one TypeScript implementation. Rewriting that behavior in the Helper would make Hosted and Local deployments diverge without improving the media path.

Room authority and local media capability are independent choices. A room may come from Local, a temporary public link, or a configured Site while each participant independently uses Browser media or available App capability. Binding these choices into exclusive App modes prevents mixed Browser/Native topologies and makes a saved Site unavailable while another room source runs.

Decision

1. One shared core is the sole owner of HTTP, room authority, admission, signaling, and routing in every deployment. The local package runs that same core and the same built Browser assets with local configuration; no deployment gets a second product core. Its implementation is owned by ADR-0012.
2. The packaged product is Piik App. Its Go process is the cross-platform entry and native capability provider. It starts /health and one /control endpoint on IPv4 loopback within ports 39721 through 39730 before room- source selection and retains them until the process exits.
3. Discovery returns a per-process instanceToken. The WebSocket subprotocol echoes it so the Browser connects to the process it discovered. This value is public process identity, not authentication. The listener accepts the current Local Host origin and the one user-saved Site origin. Origin and Host validation plus the Browser's local-network permission own this boundary.
4. Loopback v9 starts with a strict hello handshake. Up to two participant control sessions may coexist; each retains its own share and media lifetime. This bounds concurrent Native work, not the shared server's room count. Ending one control session cannot end another; App exit waits for all owned sessions to retire. Health discovery reports only separately probed native capture booleans. Native Viewer receive/NAT remains available when capture or hardware encode is absent. An active control session may list local screen/window choices, request bounded previews, and own one share's generation-fenced SDP/ICE edges, including at most one loopback media bridge outside route-copy capacity; it carries no room password, Host token, Viewer grant, or route policy. The participant page owns this connection and opens it lazily for native use. The presentation lifecycle owns acquisition and retirement, including releasing unused Host control. Source replacement retains the connection; a new source or picker does not create another participant. The Browser forwards current signaling.
5. A platform package contains one Go executable carrying the same core and embedded Browser assets used by Hosted Piik. It may also carry one process-isolated capture binary and the pinned cloudflared sidecar. Those sidecars are the only supervised children and keep their bounded lifetime. Platform packaging is metadata around that entry, not another long-running wrapper or UI.
6. The system Browser remains the UI. Browser extensions, userscripts, Electron, Tauri, and resident services need new evidence before they can replace this smaller boundary. An App-opened Site stores a non-secret opt-in at that exact Browser origin, so later manually opened pages may discover the running App. Pages without that opt-in do not probe localhost or request local- network permission. Clearing Site data simply requires opening it from the App again.
7. A self-contained Local deployment serves reachable LAN peers without a central Piik service. Its explicit --link mode starts one accountless Cloudflare Quick Tunnel for the same HTTP/WebSocket surface. The App reserves the exact IPv4 listener before creating that tunnel, then applies its HTTPS origin before the server starts serving that listener. It retains the same memory RoomStore, Browser UI, Viewer grant, signaling, and route controller. The Host sends the ordinary invitation link and the Viewer needs only a Browser. Cloudflare terminates this temporary control path; WebRTC media stays P2P and uses public STUN. The link ends with the App and is not a persistent Site, SFU, or TURN fallback.
8. Browser and Native are local media adapters beneath the same authenticated participant, connection identity, copy capacity, and committed route graph. Browser-to-Browser, Native-to-Browser, and Native-to-Native edges use the same WebRTC signaling contract. Native media currently covers the Host adapter; Viewer receive/relay follows the same boundary rather than adding a second participant or route protocol. A Native Viewer accepts only a negotiated H.264/VP8 and Opus offer, forwards encoded RTP into bounded local sources, and uses the existing Browser bridge for playback; compatible child edges reuse those sources. Unsupported media or a failed native bridge falls back to the existing Browser peer. One isolated platform capture feeds one encoded source and bounded independent Pion transports, with process-loopback audio for windows or system-loopback audio for screens sharing the same PeerConnection when available. Each physical Native connection owns an independent UDP socket; discovery and media share that socket, including after ICE restart. Site and one-link P2P connections request a bounded, best-effort PCP, UPnP, or NAT-PMP mapping alongside gathering; pure LAN Local connections do not. Once ordinary STUN observes a public address, Native advertises the mapped port as one lower-priority, srflx-shaped candidate on that address. Absence or rejection leaves ordinary ICE/STUN unchanged. Native P2P quality uses Pion's transport-wide GCC estimate only after feedback and source-frame progress, comparing its target payload bitrate with the measured encoded payload supplied to that edge. The existing route evidence windows own persistence; no custom score, second adaptation policy, or queued pacer is introduced. The one loopback edge supplies Host preview and the existing Browser LiveKit publisher. It neither consumes route-copy capacity nor starts port mapping; an assigned SFU publication still consumes its existing route copy. Native code does not implement LiveKit or another representation policy. The App discovers packaged capture capability at startup. Its Host page offers the Browser's standard picker and each exact App-owned screen/window; the user must select one and the App never guesses a target. The same room quality settings select native capture size, frame rate, video/audio bitrate, and the platform encoder's quality-versus-speed hint. A live quality or source change prepares a replacement capture/encoder generation and swaps it behind the existing Pion source; room, route, and PeerConnections do not change. Windows uses Graphics Capture, Media Foundation, and WASAPI; macOS uses ScreenCaptureKit, VideoToolbox, and AudioToolbox; Linux uses the ScreenCast Portal, PipeWire, and an installed GStreamer hardware-H.264 element. These adapters end at the same bounded encoded-frame protocol and do not own WebRTC or product state. The shared Native encode is the normal path. For a persistently degraded Native sender edge, the existing quality operation may prepare an overlapping stock Browser sender from the stable local bridge; existing evidence alone decides commit or rollback, and a later operation may return to Native. No extra threshold, timer, score, route operation, or representation ladder is added. Only a consumed App-launch marker travels in the URL fragment. Exact target identity travels over loopback.
9. The App uses the system Browser as its only UI. On every launch, the current lightweight control center offers Local, public link, and Site. The Site value is stored in App configuration and remains one click on later launches; selecting Local or public link does not disable background RPC access for the saved Site. Command-line mode selectors remain automation inputs rather than the normal interface. An embedded shell requires a reproduced product failure and one comparative decision.
10. Local mode is one explicit server composition: static current assets, memory-only rooms, peer-assisted media, no SQLite or SFU, and localhost plus current LAN IPv4 origins. It uses no public discovery by default. Public-link mode adds its temporary HTTPS origin, one ordinary public STUN destination, and two bounded public survey destinations. Site mode consumes that Site's configured STUN survey. Both feed the same connection-local prediction adapter; Native additionally owns its UDP socket and best-effort port mapping.
11. One App configuration owns the optional Site origin and an optional, user-chosen Local access password. A blank value leaves the Local site open; a value gates that site through the existing SiteAccess authority. The App bootstraps a selected page through a fragment consumed before authentication; the page retains only the non-secret App opt-in at its origin. Friends use the existing room invitation grant. No App-specific room authorization system is added.
12. Local authority shutdown first ends every in-memory room through the current room-closed path, then closes signaling and HTTP. The App cancels the server context, calls that end-then-close sequence under one bounded timeout, and only then closes the public tunnel and the loopback service. It does not restart a vanished authority.
13. App assembly consumes the immutable application release from the same full Git revision and an explicit supported target. The Go binary embeds that release's built Browser assets and the package REVISION records the same revision; a revision mismatch fails rather than loading a stale private contract. App-scoped pull requests build every target and must start the assembled Local authority, pass /healthz, and stop it cleanly before the candidate is accepted.
14. The root package manifest is the single dependency contract for the Browser bundle and repository tooling. No host installs packages to run Piik, so the manifest has no runtime half, and no second App dependency list or post-install package surgery is used.

Consequences

Hosted and Local operation share one product contract and one route model. The Go runtime acts as an optional capability provider when an activated Site or Local page discovers it, but it is not a second room product. A mixed room does not expose endpoint implementation to routing policy. The runtime stays small until a proven native capability needs a protocol field. The local package presents one user entry and runs its room authority inside that same process; only the optional capture and tunnel sidecars remain supervised children, and that entry, not a compatibility protocol, owns their lifetime.

Windows gates prove loopback discovery, Local static startup, automatic Host access, LAN invitation construction, a three-Viewer Browser relay tree, two process-isolated hardware-H.264/Pion edges sharing one encoded source and decoded by Chrome, and bounded process cleanup. The native Host path uses the current Browser route; its explicit in-page window picker also passes source end, same-room reselection, and restored Viewer delivery. A remote Pion gate has received 30+ H.264 RTP packets over a selected direct srflx-to-srflx pair; this proves packet delivery, not decoded Browser video. A Windows Browser gate also receives process-loopback Opus on both native edges. A separate remote gate proves that --link generates the ordinary public invitation and carries the unchanged Viewer page and WebSocket control path, then disappears when the App exits. An isolated LiveKit gate also proves native capture through the loopback Browser bridge and the existing SFU publisher, including a live 1080p-to-480p profile change and complete cleanup. A Browser-Host-to-Native-Viewer gate additionally proves that the Viewer claims the v8 App control session and Chrome decodes the 1280x720 source; the encoded downstream edge has a separate H.264/Opus RTP integration gate. One-link Browser media and physical non-Windows capture remain separate gates. GitHub runners compile all three platform adapters. The macOS arm64 sidecar also creates a hardware-only VideoToolbox encoder and produces a constrained-baseline SPS/PPS/IDR; its ScreenCaptureKit video/audio permission, source lifecycle, static-screen recovery, and endurance still require a physical Mac. The Linux candidate probes and packages its Portal/PipeWire/GStreamer adapter, while a real desktop, hardware encoder, system audio, and lifecycle still require a physical Linux gate. Source previews remain best-effort on both platforms.

The v8 loopback gate also proves that a real Chrome receiver produces Pion transport feedback and that a non-unknown native sender-quality window reaches the existing route controller. Unknown feedback and stopped-source windows stay ineligible.

The local trust boundary is intentionally per-user: the instance token identifies the running App but is not authentication against another local process.

A physical home-router gate created and removed a UPnP mapping for an ephemeral UDP listener. The integrated native Host gate still passed capture, two-edge delivery, source restart, and cleanup with mapping enabled. The mapped port is now advertised on the observed public address; a selected mapped path across a pair that fails with STUN alone remains field evidence rather than an architectural claim.

Primary Sources

• Go child-process lifecycle
• WebRTC peer connections and signaling
• Cloudflare Quick Tunnels
• Cloudflare Tunnel WebSocket support
• RFC 6455 WebSocket Origin model
• Chrome Local Network Access
• Discord local RPC
• OBS WebSocket protocol
• LocalSend protocol
• Sunshine local Web UI
• Syncthing local GUI/API
• Native App media evidence