Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs(project): defer Host background diagnosis
AAA6e4374b9754f
diff --git a/docs/project-memory.md b/docs/project-memory.mdindex f937debf..627840d3 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -39,9 +39,11 @@ Last updated: 2026-08-24## Current Priority-1. Finish the desktop Host background/minimized diagnosis on exact production with a real game/replay and separate direct Viewer, then diagnose the screen-audio `1 kbps` readout and physically validate live audio ceilings. A bounded current-Chrome Browser `getDisplayMedia()` WPF-window same-machine loopback did not observe an immediate Host-page lifecycle drop and therefore authorizes no keepalive or other Browser workaround.+1. Diagnose the screen-audio `1 kbps` readout and physically validate live audio ceilings.2. Then physically validate exact direct, browser-relay, and SFU codec behavior on deployed Browser v11, refine the invitation UI, and finish real-network route acceptance. Browser VP8 hardware acceleration and mobile Viewer lifecycle remain Accepted Later; Native/executable, distribution, and repository-wide simplification remain later phases.+The desktop Host background/minimized report is deferred until it reproduces on current production with a real game and synchronized media plus CPU/GPU evidence. The bounded current-Chrome screening found no immediate Host-page lifecycle drop, and removal of the old harmful `contentHint = "motion"` remains a plausible confound rather than a proven background fix. Mobile Viewer playback and assigned-relay survival remain a separate lifecycle gate.+## Working Rules- Generic task authority, scope, smallest-correct implementation, and current-result delivery are owned by the repo-tracked [`stop-that-shit` skill](../.agents/skills/stop-that-shit/SKILL.md); repository-specific truth and execution rules remain in `AGENTS.md` and `CONTRIBUTING.md`.diff --git a/docs/research/browser-background-capture.md b/docs/research/browser-background-capture.mdindex f62a01ce..01e7c88a 100644--- a/docs/research/browser-background-capture.md+++ b/docs/research/browser-background-capture.md@@ -3,9 +3,9 @@- Research date: 2026-08-24- Scope: desktop Chrome/Edge Web Host capture while the Host page isunfocused, occluded, backgrounded, or minimized-- Status: one bounded current-browser screening did not observe an immediate- Host-page background drop; the reported real-game case remains unreproduced- and unattributed, and no new fix is accepted, implemented, or deployed+- Status: deferred until a current-production real-game reproduction exists;+ one bounded current-browser screening did not observe an immediate Host-page+ background drop, and no new fix is accepted, implemented, or deployed## Current Conclusion@@ -62,6 +62,14 @@ background report had the same cause. The physical baseline must thereforestart from current production rather than carrying the old report forward as acurrent regression.+This investigation is deferred. It reopens only if the report+reproduces on current production with a continuously changing real game and+synchronized capture, send, receive, decode, CPU, and GPU evidence. Removing the+old harmful `motion` hint may have removed a confounding quality defect, but it+is not established as a background-lifecycle fix. Mobile Viewer background+playback and assigned-relay survival remain a separate browser/OS lifecycle+gate and do not inherit this desktop Host result.+## Current Source BoundaryThe no-video-hint review baseline isdiff --git a/docs/status.md b/docs/status.mdindex bb9eae31..a37c3fb4 100644--- a/docs/status.md+++ b/docs/status.md@@ -27,15 +27,15 @@ This is the current execution index. Git history owns completed timelines; [veri## Current Milestone-1. Finish the Host background/minimized diagnosis on exact production with a real game/replay and separate direct Viewer. A bounded current-Chrome Browser `getDisplayMedia()` WPF-window same-machine loopback did not observe an immediate page-lifecycle drop, so no workaround is established; the reported workload still needs synchronized capture, send, receive, decode, CPU, and GPU evidence.-2. Diagnose the reported screen-audio `1 kbps` readout and physically validate live audio ceilings.-3. Physically verify the deployed `screener-v11` fixed-VP8/no-video-hint direct, browser-relay, and SFU paths from actual codec, capture, outbound, and decoded stats.-4. Refine the Host invitation controls without changing grant semantics implicitly.-5. Finish representative ICE/STUN/SFU acceptance including mobile networks. Browser port prediction, NAT classification, TCP probing, fake page keepalive, and quality-driven reparenting remain outside the accepted model.+1. Diagnose the reported screen-audio `1 kbps` readout and physically validate live audio ceilings.+2. Physically verify the deployed `screener-v11` fixed-VP8/no-video-hint direct, browser-relay, and SFU paths from actual codec, capture, outbound, and decoded stats.+3. Refine the Host invitation controls without changing grant semantics implicitly.+4. Finish representative ICE/STUN/SFU acceptance including mobile networks. Browser port prediction, NAT classification, TCP probing, fake page keepalive, and quality-driven reparenting remain outside the accepted model.## Active Boundaries- `fix/configurable-relay-cap` is an old, incomplete draft and must not be merged as-is.+- The desktop Host background/minimized report is deferred until a current-production real-game reproduction supplies synchronized media and CPU/GPU evidence. Mobile Viewer background playback and relay survival remain a separate Accepted Later lifecycle gate.- Open PR #192 and the Native stack are evidence/research, not pending product releases. Native senders, capture helpers, shared-encode executables, and their test binaries are outside the current Browser milestone and are not built or run.- Deployed surfaces and retained candidates that still need product decisions are indexed only in [the TODO ledger](./todo.md); do not extend or roll them back automatically.- Room lifetime, authorization/storage semantics, restart loss, entry/presentation, and the Browser v11 contract are aligned between source and production. This application-only cutover reused unchanged infrastructure and configuration and does not maintain a full rollback/configuration backup; any future infrastructure or irreversible-state change requires recovery scoped to the surfaces it actually changes.diff --git a/docs/todo.md b/docs/todo.mdindex 61aee1d1..66d5cccf 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -6,11 +6,10 @@ Only items in **Now** are executable after their stated decision gate. A branch## Now-1. **Finish the real-game Host background/minimized diagnosis.** A bounded Chrome Browser `getDisplayMedia()` capture of a changing WPF window with one same-machine loopback receiver did not observe an immediate Host-page lifecycle drop; this does not close the reported case. On exact production with a continuously changing real game or replay and a separate direct wired Viewer, compare foreground, occluded/unfocused, hidden-tab, and minimized Host states while the captured source stays visible. Correlate RTCStats-timestamped capture, encode, send, receive, decode, browser/game CPU and GPU, and the existing local-preview pause boundary; record energy settings and inspect discard state only outside timed windows. Do not spoof page activity, add keepalive timers, misuse Wake Lock, or carry the old `contentHint = "motion"` release forward as current evidence. If current Chrome/Edge cannot preserve the accepted Host behavior through standard Web APIs, record that capability boundary before considering the packaged/native Host.-2. **Diagnose and physically validate live screen audio.** First reproduce the Host diagnostic remaining at `1 kbps` after switching the shared source, and distinguish stale/reset statistics from an actual RTP bitrate problem. The app already requests audio and supplies system/window audio hints; record the selected surface, returned audio track, sender/receiver counters, and audible result because the browser owns the picker and may still return video only. Then switch the 64/128/256 kbps ceilings across direct, browser-relay, and SFU paths, create a new edge, and switch source while checking route continuity and A/V synchronization. Do not infer fidelity or room-wide atomic convergence from configuration alone.-3. **Physically validate fixed Browser VP8 with no video hint.** Production exact deployed application/runtime revision `679fe3e7af634309322bea83b316641f51ad3d09`, release `679fe3e`, already runs the strict v11 wire, VP8-only direct/browser-relay offers, VP8 SFU publication with no backup codec, unset video `contentHint`, and no codec UI/state/wire. Confirm actual codec, capture, outbound, and decoded stats on direct, browser-relay, and SFU paths; deployment postflight alone does not close this gate.-4. **Redesign the Host invitation controls.** Replace the current raw-link-heavy block with a compact copy-first layout while preserving the accepted copy-link, copy-room-code, code-entry policy, rotate, and revoke actions. Keep the credential out of logs and request URLs; changing the copied credential length is blocked on the explicit product decision below.-5. **Finish real-network route acceptance.** Measure standard ICE/STUN direct paths, peer relay, SFU ingress/subscription, exact first-frame commit and rollback, relay-ingress repair with subtree retention, disconnect/capacity drain, Pause/Resume, and bounded explicit failure across representative IPv4/IPv6 NATs and mobile networks. Include an all-UDP-blocked case to establish the current failure boundary. Do not add port prediction, NAT classification, TCP probes, guessed candidates, route scores, or quality-driven reparenting.+1. **Diagnose and physically validate live screen audio.** First reproduce the Host diagnostic remaining at `1 kbps` after switching the shared source, and distinguish stale/reset statistics from an actual RTP bitrate problem. The app already requests audio and supplies system/window audio hints; record the selected surface, returned audio track, sender/receiver counters, and audible result because the browser owns the picker and may still return video only. Then switch the 64/128/256 kbps ceilings across direct, browser-relay, and SFU paths, create a new edge, and switch source while checking route continuity and A/V synchronization. Do not infer fidelity or room-wide atomic convergence from configuration alone.+2. **Physically validate fixed Browser VP8 with no video hint.** Production exact deployed application/runtime revision `679fe3e7af634309322bea83b316641f51ad3d09`, release `679fe3e`, already runs the strict v11 wire, VP8-only direct/browser-relay offers, VP8 SFU publication with no backup codec, unset video `contentHint`, and no codec UI/state/wire. Confirm actual codec, capture, outbound, and decoded stats on direct, browser-relay, and SFU paths; deployment postflight alone does not close this gate.+3. **Redesign the Host invitation controls.** Replace the current raw-link-heavy block with a compact copy-first layout while preserving the accepted copy-link, copy-room-code, code-entry policy, rotate, and revoke actions. Keep the credential out of logs and request URLs; changing the copied credential length is blocked on the explicit product decision below.+4. **Finish real-network route acceptance.** Measure standard ICE/STUN direct paths, peer relay, SFU ingress/subscription, exact first-frame commit and rollback, relay-ingress repair with subtree retention, disconnect/capacity drain, Pause/Resume, and bounded explicit failure across representative IPv4/IPv6 NATs and mobile networks. Include an all-UDP-blocked case to establish the current failure boundary. Do not add port prediction, NAT classification, TCP probes, guessed candidates, route scores, or quality-driven reparenting.## Accepted Later Roadmap@@ -40,6 +39,7 @@ These decisions are not permission to continue old branches, and current deploym## Evidence And Later Work+- The desktop Host background/minimized report is deferred after a bounded current-Chrome screening found no immediate Host-page lifecycle drop and the old `contentHint = "motion"` release remained a plausible confound. Reopen it only with a reproducible current-production real-game case and synchronized capture/send/receive/decode plus CPU/GPU evidence. This does not close or advance the separate Mobile Viewer lifecycle item, whose background playback and assigned-relay survival depend on mobile browser and OS lifecycle behavior.- Open PR #192 measures synthetic flash/tone timing; it is not an A/V correction feature.- The Native PR stack #16/#18/#22/#23/#25/#28 and related fanout branches are one research program, not six product TODOs.- Cap3, resource, route-recovery, Viewer-MBB, signaling-blackhole, Host-generation, SFU-shaping, NAT, mobile, and endurance artifacts remain bounded evidence. Merge or retain them only when a current decision consumes them. Raw-IP ranking, port prediction, NAT classification, AirPlay/Cast receivers, and mobile background guarantees are not implied by the current implementation batch.diff --git a/docs/verification-status.md b/docs/verification-status.mdindex 0eb58cd4..52f94d98 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -31,7 +31,7 @@ Capacity and routing entries below describe the exact tested source or release o- Routing: exact v10 local direct loopback remains historical evidence for admission-20 initial ingress and exact-candidate first-frame commit timing on that source. Current v11 production still needs physical direct, browser-relay, and SFU codec verification, together with route rollback, direct-stage exhaustion and SFU admission, relay-ingress reparent with subtree retention, disconnect/effective-capacity drain, pause/resume, and bounded failure on real browser/media paths. Silent control partitions may wait 30 to 60 seconds for heartbeat detection before the default five-second grace; a non-paused decoded-frame stall may invalidate only that exact child edge.- Quality: production startup blur remains unclassified. One same-`balanced` local A/B retained route/PC/SSRC/track while 720p rose to 1080p, but natural ramp prevents causal, production, or SFU conclusions. Correlate Host capture/encode/send with Viewer receive/decode before changing policy.-- Host background: the current-Chrome Browser `getDisplayMedia()` WPF-window screening did not observe an immediate hidden/minimized Host-page media drop. The reported game case still requires exact production, a continuously changing real game or replay, a separate direct wired Viewer, synchronized capture/outbound/inbound plus CPU/GPU evidence, and repeated focused/unfocused/hidden/minimized windows. Current evidence authorizes no keepalive, Wake Lock, timer, codec switch, route change, or Native fallback.+- Host background: deferred until the report reproduces on exact production with a continuously changing real game or replay, a separate direct wired Viewer, synchronized capture/outbound/inbound plus CPU/GPU evidence, and repeated focused/unfocused/hidden/minimized windows. The current-Chrome Browser `getDisplayMedia()` WPF-window screening did not observe an immediate Host-page media drop, and the old harmful `contentHint = "motion"` release remains a plausible confound rather than a proven background cause. Current evidence authorizes no keepalive, Wake Lock, timer, codec switch, route change, or Native fallback.- Relay resources: current v11 source and production expose the authenticated `1/2/3` endpoint-cap boundary, and retained v10 local loopback evidence covers 20 Viewers at cap `2` only for that source. CPU/GPU/upload and heterogeneous-network measurements remain diagnostics, not authority to change the contract.- Room scale: current source and production admit 20 Viewers plus one Host, and the retained v10 local Browser convergence gate covers that bound on direct loopback. A real public-network 1:20 session, quality, and sustained resource matrix remain open.- SFU: production uses one Host publication with exact Viewer subscriptions and no fixed root-count or room-wide lease rule. Real LiveKit lifecycle/JWT replay, shaped packet-flow, BWE downshift/recovery, resource use, and SFU-fed first-child evidence remain open. Use Linux `tc` or an authorized public canary for per-leaf shaping, never CDP throttling.