Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs(product): settle Browser v9 work (#218)
AAA87883748b6a0
diff --git a/docs/adr/0002-memory-resident-protected-rooms.md b/docs/adr/0002-memory-resident-protected-rooms.mdindex ff669d33..42429d10 100644--- a/docs/adr/0002-memory-resident-protected-rooms.md+++ b/docs/adr/0002-memory-resident-protected-rooms.md@@ -1,6 +1,6 @@# ADR-0002: Memory-Resident Rooms And Scoped Viewer Access-- Status: Accepted; implemented and deployed+- Status: Accepted; v8 room model implemented and deployed; v9 neutral code-only denial pending- Date: 2026-08-23## Context@@ -101,6 +101,21 @@ all code-only Viewer attempts. A valid room grant may bypass that site gate onlyfor the exact Viewer role and room. Neither a code, room password, nor Viewergrant can create a room or become Host authority.+The accepted `screener-v9` room-entry boundary adds exactly one+`ROOM_ACCESS_DENIED` result. It applies only after site access to a well-formed+code-only Viewer attempt whose expected admission rejects an unknown or expired+room, disabled code entry, an absent or incorrect room password, a full room, or+another bounded admission refusal. Every such case uses the same code, public+message, and connection-close behavior, so neither the wire nor the UI reveals+room existence or code-entry policy. The UI may offer an optional room-password+retry and tell the Viewer to use an invitation link supplied by the Host; it+does not request, discover, or mint an invitation through the server.++Exact-room grant failures remain `INVALID_TOKEN`, Host authentication retains+its independent role-specific outcomes, and unexpected internal faults remain+the generic `SERVER_ERROR`. None of those paths is folded into+`ROOM_ACCESS_DENIED`.+## Consequences- Normal operation and the 24-hour renewable-room experience require only one@@ -136,15 +151,25 @@ grant can create a room or become Host authority.storage does not. No fingerprint or server user record participates.- Raw site passwords, Host tokens, Viewer grants, and room passwords remain outof application/proxy logs and server durable storage.+- On `screener-v9`, every expected denial of a well-formed, site-authorized+ code-only attempt yields only `ROOM_ACCESS_DENIED` with the same public+ message and connection-close behavior. Tests cover unknown/expired rooms,+ disabled entry, absent/wrong passwords, full and bounded admission, while+ exact-room grant, Host-authentication, and unexpected-server-fault paths keep+ their independent typed outcomes.## Implementation Status-Current source implements this decision and has removed the old room modes,-12-digit codes, SQLite persistence, `ROOM_DATABASE_PATH`, `ROOM_TTL_SECONDS`,-and migration surface atomically on the single `screener-v8` wire. Focused source coverage spans allocation,-leases, orthogonal grant/code admission, rotate/revoke, password policy, local-profile replay, restart loss, HTTP, signaling, and browser storage privacy.-Production release `352c457` runs this `screener-v8` model. The atomic cutover,+Current source implements the v8 room, storage, and authorization core of this+decision and has removed the old room modes, 12-digit codes, SQLite persistence,+`ROOM_DATABASE_PATH`, `ROOM_TTL_SECONDS`, and migration surface atomically on+the single `screener-v8` wire. Focused source coverage spans allocation, leases,+orthogonal grant/code admission, rotate/revoke, password policy, local profile+replay, restart loss, HTTP, signaling, and browser storage privacy.+Production release `8f5b3f1` runs this `screener-v8` model. The atomic cutover,restart-loss smoke, orthogonal grant/code admission, stale-v7 rejection,no-SQLite runtime, and read-only rollback restoration checks passed; exactoperational evidence is owned by deployment and verification status.+The `ROOM_ACCESS_DENIED` boundary above is accepted for the atomic+`screener-v9` checkpoint but is not implemented in current source or deployed+in production.diff --git a/docs/adr/0004-peer-assisted-media-experiment.md b/docs/adr/0004-peer-assisted-media-experiment.mdindex e2846187..1bb84d59 100644--- a/docs/adr/0004-peer-assisted-media-experiment.md+++ b/docs/adr/0004-peer-assisted-media-experiment.md@@ -13,8 +13,8 @@ ordinary browser Viewer could relay the received screen stream to anotherViewer.This ADR records that experiment and its reusable evidence. It does not set the-current endpoint capacity, SFU topology, TURN placement, fallback sequence, or-resource accounting. ADR-0005 owns current routing invariants.+current endpoint capacity, SFU topology, server-assisted transport, fallback+sequence, or resource accounting. ADR-0005 owns current routing invariants.## Experiment@@ -37,9 +37,9 @@ bitrate, degradation-preference, codec, and screen-audio choices. Sendermutation was serialized and read back from the browser. Requested settings weretreated as ceilings and preferences, never as proof of achieved media quality.-Ordinary peer connections remained STUN-only. A TURN candidate would alter the-transport of an authorized edge, not the graph semantics or downstream edge-count.+Ordinary peer connections remained STUN-only. In the dated experiment, a TURN+candidate would have altered the transport of an authorized edge, not the graph+semantics or downstream edge count.## Evidence retained@@ -80,16 +80,17 @@ claim unsupported by measurements.## Current interpretation-Peer relay remains a useful distributed-media candidate and deployed source-contains portions of the experiment. Those portions must be evaluated against-ADR-0005's current invariants rather than carried forward wholesale.+Peer relay is part of the deployed Browser route owned by ADR-0005. This ADR+retains only the experiment evidence used to evaluate that route; its historical+policy and gates do not independently authorize current behavior.The current accepted endpoint rule is one server-authoritative downstreamcapacity for every non-server endpoint, default `2` and statically configurableas `1`, `2`, or `3`; upstream receive is free and role or user agent does not-create an exception. ADR-0005 owns the implemented Browser source for SFU/TURN-publication, subscription, transport, server admission, and migration overlap;-its production release and real-network validation remain pending.+create an exception. ADR-0005 owns the implemented and deployed Browser route+for direct/SFU publication, subscription, transport, server admission, and+migration overlap. Real heterogeneous-network and resource validation remains+open.## Consequencesdiff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex b3ede32c..c5c82aa6 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -1,8 +1,8 @@# ADR-0005: Automatic Hybrid Media Routing-- Status: Accepted; source runtime implemented and deployed+- Status: Accepted; route core implemented and deployed; v9 diagnostic delta not implemented or deployed- Date: 2026-08-20-- Last updated: 2026-08-23+- Last updated: 2026-08-24## Context@@ -220,6 +220,10 @@ second mutable graph.transport. An all-UDP-blocked network reaches a clear bounded failure; anyfuture strict-firewall transport requires its own evidence and belongs insideLiveKit rather than becoming another application candidate.+- Browser ICE connectivity checks are the authority for direct UDP reachability.+ Screener does not synthesize remote candidates, predict ports, classify NAT+ behavior, or use TCP reachability as a media-path probe. Direct exhaustion+ advances to the SFU stage inside the same operation deadline.- Endpoint sender capacity is accounted independently from server ingress/egress, SFUsubscriptions, and one bounded transition-overlap slot.Steady capacity is `1`, `2`, or `3` (default `2`); a transition may use@@ -236,6 +240,11 @@ second mutable graph.WebRTC/LiveKit adaptation inputs; they do not changeparent eligibility. Multiple bad child edges recover independently through thesame loop and naturally empty an unusable relay.+- A currently decoding exact edge remains sticky. Current-path loss, RTT,+ jitter, bitrate, resolution, FPS, freeze, and limitation evidence cannot prove+ the counterfactual quality of another parent, so Screener creates no weighted+ route score, alternative-parent probe, hysteresis loop, or periodic+ quality-driven reparenting.- Web clients derive active decoded progress from their existing periodicWebRTC/LiveKit stats sampling. One route-keyed last-progress deadline reportsthe exact edge once; it resets on route/connection change or decoded progress@@ -244,8 +253,10 @@ second mutable graph.authority.- Authoritative pause aborts the pending child operation, including its currentcandidate and reservations, keeps the active graph, suppresses decoded-frame-- stall decisions, and leaves new participants waiting. Resume wakes a fresh- reconciliation. Healthy unaffected edges remain sticky.+ stall decisions, and leaves new participants waiting. Resume normally wakes a+ fresh reconciliation; when the accepted codec transaction owns a prepared+ generation, that same room-serial owner handles Resume and settles first.+ Healthy unaffected edges remain sticky.SFU remains a bounded fallback resource with independent deployment-wideadmission. Resource exhaustion produces an explicit wait or failure; it never@@ -255,6 +266,44 @@ one waiter set. An actual SFU usage decrease drains that set once, advanceseach waiting controller's external fact, and schedules normal reconciliation;there is no periodic capacity poll or resource-specific route controller.+The accepted v9 Viewer wire adds one strict, revision-fenced `route-status`+union only for states that the existing prepare/active `route-update` cannot+express: `{ state: "waiting", reason: "sfu-admission" }` while this Viewer is+waiting on central admission, or `{ state: "failed", reason:+"route-exhausted" }` after the controller reaches its bounded terminal. It is+sent only server-to-authenticated-Viewer and carries no text, identity,+candidate, retry hint, or other topology data. Access, Host presence, signaling,+media, and autoplay remain independent presentation inputs.++The room-serial operation does not divide its per-child deadline by Viewer+count, but simultaneous joins may form a linear queue. The deployed v8+controller does not include a route-timing snapshot. The accepted v9 diagnostic+extension observes existing route events without changing the controller: for+each current child it keeps only the latest route-demand, operation-start,+current-candidate-start, first-decoded-frame, and final-outcome timing. A new+demand overwrites that child's record; authoritative share stop/replacement,+confirmed departure, and room deletion remove it.++An authenticated Host may request one snapshot only while creating the existing+user-initiated local diagnostic export. The response reads the current graph,+current operation, and latest records; the server does not push a periodic+snapshot stream, start a timer, retain an event ring, log or persist the result,+or create a second graph. Snapshot-local ordinals express parent/SFU relations+but are not participant identities and must not be treated as stable across+snapshots. Queue wait is the interval from the same route demand to operation+start and remains `null` when either event is absent.++The response uses only `direct | sfu | waiting | failed` final-route values and+the closed rejection buckets `none`, `stale`, `endpoint-capacity`,+`sfu-admission`, `candidate-failed`, `first-frame-timeout`,+`operation-deadline`, and `aborted`. It never+carries real peer, parent, session, connection or generation identity, SDP,+candidates, addresses, credentials, or raw error text, and it has no route+authority. A 20-Viewer burst reports the sample count and nearest-rank+p50/p95/max without a pass threshold before any different concurrency model or+deadline is accepted. Protocol tests must reject extra/private fields, deny the+request to Viewers, and prove departure and room-deletion cleanup.+For the single-process deployment, SFU admission is one injected authority withdeployment-wide ingress and egress counters. Enabling LiveKit requires explicitpositive safe-integer `SFU_INGRESS_CAPACITY` and `SFU_EGRESS_CAPACITY` values;@@ -305,7 +354,9 @@ heterogeneous-network and SFU media validation remains open.## Acceptance Boundary-Before a revised controller ships:+The deployed core's completed source and deployment evidence is indexed in+`docs/verification-status.md`. Any revised controller must re-pass these source+and deployment gates:- property tests cover capacity `1`, `2`, and `3`, one active upstream,acyclic and source-reachable assignments, stale generations, duplicate@@ -326,12 +377,16 @@ Before a revised controller ships:ready, relay-ingress reparent with its subtree intact, disconnected relay andnested-disconnect convergence, effective capacity `0..C` and overflow drain,SFU-fed first-child use and pause/resume;-- real-browser tests cover direct peer media, peer relay, SFU media, bounded- failure, and recovery;- deployment preflight proves the LiveKit instance is dedicated, uses`room.auto_create: false`, exposes `RoomService` only on its accepted privatecontrol origin, and can drain its managed namespace before traffic or- rollback;+ rollback.++The following external acceptance remains open without changing the deployed+core's status:++- real-browser tests cover direct peer media, peer relay, SFU media, bounded+ failure, and recovery;- measured endpoint upload and server ingress/egress prove the acceptedaccounting under normal and migration overlap; and- every exhausted path reaches a clear bounded wait or failure without leaking@@ -367,10 +422,13 @@ Positive:Negative:-- production intentionally diverges until the implemented source is released;+- one room-serial operation may create measurable queue-tail latency during a+ burst;- make-before-break consumes explicit endpoint and server reservations and mayrequire a bounded-gap cutover when no overlap slot exists; and-- real SFU and target-network evidence is still required.+- real SFU and target-network evidence is still required. The accepted v9+ diagnostic extension is not part of deployed v8 and must ship atomically with+ its single current protocol.## Relationship to other ADRsdiff --git a/docs/adr/0006-fixed-high-native-sender-canary.md b/docs/adr/0006-fixed-high-native-sender-canary.mdindex 28971002..313cb61e 100644--- a/docs/adr/0006-fixed-high-native-sender-canary.md+++ b/docs/adr/0006-fixed-high-native-sender-canary.md@@ -7,7 +7,7 @@The Draft #16/#18/#22/#23/#25/#28 ladder proved isolated WebCodecs/Pionproperties, not integration with Screener's current rooms, signaling, ordinary-browser viewers, or per-edge ICE/TURN. A native sender remains a later+browser viewers, or per-edge ICE transport. A native sender remains a lateroptimization and must not be presented as available product behavior.## Retained Boundary@@ -33,7 +33,7 @@ The sole authorized run is `no-go-unclassified`; the retained evidence andprobe limitations are recorded in the native sender research. The earliestmissing checkpoint is viewer authentication, not a proven authenticationfailure. No viewer-1 acceptance means there is no two-viewer, third-viewer-FIFO, or direct/TURN proof. The attempted native branch must not be opened or+FIFO, or direct/SFU proof. The attempted native branch must not be opened ormerged as product code from this state.## 2026-08-20 Historical Wire Checkpoint@@ -179,9 +179,9 @@ failed stage while synchronously retaining a bounded final-negative snapshot:5. Add viewer 3, prove no third edge and a host-side waiting observation whilethe viewer keeps its existing waiting state, then close viewer 1 and proveFIFO promotion plus decoding/rendering.-6. Keep this candidate STUN-only. Ordinary Native ICE never receives TURN- candidates; any selected-edge or Host-SFU TURN attempt requires its own- generation-bound gate and does not widen or block the direct-path canary.+6. Keep this candidate STUN-only. Direct failure remains inside ADR-0005's+ dedicated Host-publication/SFU-subscription boundary; the Native canary does+ not add another media transport or widen that route model.A commit-bound, short-lived evaluation artifact may package the current sourceto run these stages without a development toolchain. That artifact is not andiff --git a/docs/adr/0007-demand-driven-dual-representation-quality.md b/docs/adr/0007-demand-driven-dual-representation-quality.mdindex b1f05147..a5d52b52 100644--- a/docs/adr/0007-demand-driven-dual-representation-quality.md+++ b/docs/adr/0007-demand-driven-dual-representation-quality.md@@ -77,7 +77,7 @@ and stream generation across three stages:| Stage | Required evidence || --- | --- || A. Capture | `MediaStreamTrack.getSettings()` width, height, and frame rate |-| B. Host outbound | actual width/FPS/bitrate, target or available bitrate when present, interval encode time, `qualityLimitationReason`, RTT, loss/retransmission, selected direct/TURN route, and derived negotiated video codec/profile/parameters plus `scalabilityMode` when applicable |+| B. Host outbound | actual width/FPS/bitrate, target or available bitrate when present, interval encode time, `qualityLimitationReason`, RTT, loss/retransmission, selected direct/SFU route, and derived negotiated video codec/profile/parameters plus `scalabilityMode` when applicable || C. Viewer inbound | actual width/FPS/bitrate, loss, jitter, interval decode/drop/freeze evidence, the corresponding derived codec/profile/parameters and applicable `scalabilityMode`, and actual decode behavior |Interpretation is deliberately ordered:@@ -86,7 +86,7 @@ Interpretation is deliberately ordered:| --- | --- || Capture is already low | capture or constraint problem || Capture high, outbound low, reason `cpu` | sender encode/resource pressure |-| Capture high, outbound low, reason `bandwidth` | congestion, uplink, GCC, or TURN/path pressure |+| Capture high, outbound low, reason `bandwidth` | congestion, uplink, GCC, or current-path pressure || Outbound healthy, inbound degraded | transport or receiver-path problem || Inbound metrics healthy, image still blurry | insufficient bitrate/quantization, negotiated codec/profile/layer, or display scaling problem |@@ -284,7 +284,7 @@ Negative:always-on or on demand; otherwise the quality gate does not pass.- Native relays show packet forwarding without an added decode/encode stage.- Spoofed, stale, duplicated, or rate-excessive viewer requests have no effect.-- Controlled capture/CPU/bandwidth/TURN/receiver/display cases produce the+- Controlled capture/CPU/bandwidth/direct/SFU/receiver/display cases produce theclassifications in the evidence table without a room-wide downgrade.## Referencesdiff --git a/docs/adr/0008-window-scoped-audio-capture.md b/docs/adr/0008-window-scoped-audio-capture.mdindex 61163c57..1baf8657 100644--- a/docs/adr/0008-window-scoped-audio-capture.md+++ b/docs/adr/0008-window-scoped-audio-capture.md@@ -111,7 +111,7 @@ visual marker, while an independent voice process and notification emitdifferent markers. Require an Opus inbound track and rendered video/audio,monotonic QPC timestamps, and a bounded A/V offset; verify the unrelatedmarkers are absent and that target exit/silence stops or asks without widening-capture. SFU/TURN, second Viewer, and endurance remain follow-up gates; paired+capture. SFU/UDP, second Viewer, and endurance remain follow-up gates; pairedWGC video completion is recorded below. On 2026-08-21, 100 20-ms chunks isolated a 440 Hz target froman independent 880 Hz process by 4017.8x. Chrome 151 then received one audiotrack and 495 inbound Opus packets while video decoded/rendered 296 frames.@@ -144,10 +144,11 @@ runtime downgrade.The ZIP carries internal and external SHA-256 manifests plus exact linked Godependency license files; it is neither an installer nor a release.-## Follow-Up TODO+## Remaining Evidence Boundary-- Keep a second Viewer, SFU/TURN, endurance, and real-game A/V sync as separate- follow-ups; the one-Viewer H.264 and attributed `VideoEncode` gate passed.-- Download and run the short-lived Windows x64 evaluation artifact; keep- explicit target selection default-off. A formal release remains blocked on- the project license, signing, and its own acceptance boundary.+- A second Viewer, SFU/UDP, endurance, and real-game A/V sync remain unproven;+ the one-Viewer H.264 and attributed `VideoEncode` gate passed.+- The short-lived Windows x64 evaluation artifact is retained evidence, not an+ instruction to download or run it. Native release work remains at the bottom+ of the single project TODO ledger and still requires license, signing, and its+ own acceptance boundary.diff --git a/docs/project-memory.md b/docs/project-memory.mdindex f8c7850b..5d76c5c4 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -16,13 +16,14 @@ Last updated: 2026-08-24- One room controller reconciles allocation, child reparenting, and relay drain through the same operation. It finds one waiting Viewer or invalid edge and builds one deterministic tuple list. The operation owns its cursor, current candidate and reservations, fact version, plus one total deadline; only its current candidate may produce media. A `screener-v8` prepare names that exact child, selected transport, and server-issued candidate connection ID. A usable old edge remains until the exact candidate child decodes its first new video frame. `settleReady` synchronously commits admission before graph promotion; success commits prepare revision `P`, while failure releases resources, broadcasts rollback `R > P` from one monotonic allocator, and advances the cursor without resetting the deadline. Exhaustion retires hard-invalid, departed-parent, or overflow edges into explicit waiting but retains a healthy bootstrap edge. Bounded-gap preflights server resources, replans the untried suffix after retirement, and appends one ordinary restore candidate when it cut healthy media. A relay with a bad ingress reparents itself as a child and retains its subtree. A disconnected endpoint, or one whose effective downstream capacity falls below its current child count, accepts no excess children; its direct or overflow children enter the same operation and a disconnected endpoint is removed when childless. Authoritative pause aborts the operation, suppresses decoded-progress stall decisions, and resumes from a fresh reconciliation.- One Host publication may serve all SFU subscriptions. Its exact generation owns one ingress handle and exact Viewer subscription handles own egress; later SFU children reuse the publication, while reserved, committed, and draining handles remain charged until the managed room is deleted and proven absent. Actual SFU usage release wakes only rooms that previously lost a candidate to global admission, and SFU-fed and peer-fed endpoints use the same provisional-child transaction. Parent choice hard-filters authority, reachability, cycles, effective capacity, and producer transition, then orders by shallowest result, remaining steady sender capacity, stable join order, and peer identity; server admission is checked at the current cursor. Acyclicity and room admission bound maximum depth; depth is observed but has no separate hard cap. Healthy committed edges remain sticky: the controller repairs waiting, invalid, departed-parent, and overflow children but does not periodically rebalance the graph. Raw IP, claimed NAT type, UA, geography, all-pairs probes, weighted scores, and periodic room rebalancing are not route inputs.- Ordinary peer ICE is STUN-only, and current LiveKit media is UDP-only. Credentials, room secrets, candidate details, and diagnostic data remain private and narrowly scoped. A future strict-firewall transport requires separate evidence and must remain inside LiveKit rather than becoming another Screener route candidate.-- Browser peers use existing periodic WebRTC/LiveKit stats to maintain one exact-route decoded-progress timestamp. New frames or route/connection changes reset it; a non-paused deadline reports the edge once. Track availability, bitrate, FPS, blur, sender stats, and SFU layer remain framework or diagnostic inputs.-- Browser capture already requests available share audio by default on initial capture and source switch, with an explicit video-only warning when no audio track is returned. Screen audio offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The existing last-wins quality wire owns desired state; each endpoint serially applies and reads back current Host/relay/SFU audio senders, exposes local failures, and gives future senders the latest desired value. Opus remains fixed, and without an applied-ack wire the Host does not claim room-wide atomic convergence. These are configuration ceilings, not fidelity claims.-- Video codec selection remains `automatic | H.264 | VP8`. The accepted first switching boundary is a generation-fenced renegotiation/republish transaction while sharing is explicitly paused; unpaused hot switching is later reuse of that transaction, not an independent mechanism.+- Browser peers use existing periodic WebRTC/LiveKit stats to maintain one exact-route decoded-progress timestamp. New frames or route/connection changes reset it; a non-paused deadline reports the edge once. Track availability, bitrate, FPS, resolution, freeze, RTT, jitter, loss, sender stats, and SFU layer describe only the current path: they remain framework or diagnostic inputs and cannot prove another parent would be better.+- Browser capture already requests available share audio by default on initial capture and source switch, with an explicit video-only warning when no audio track is returned. The accepted v9 screen-audio control offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The existing last-wins quality wire owns desired state; each endpoint serially applies and reads back current Host/relay/SFU audio senders, exposes local failures, and gives future senders the latest desired value. Opus remains fixed, and without an applied-ack wire the Host does not claim room-wide atomic convergence. These are configuration ceilings, not fidelity claims.+- Video codec selection remains `automatic | H.264 | VP8`. The accepted first switching boundary is a generation-fenced renegotiation/republish transaction while sharing is explicitly paused. Preparation never resumes a user-paused share: it stops its deadline but retains the single room-serial codec owner as one bounded prepared record with no timer. The user's normal Resume atomically revalidates those exact bindings inside that owner, starts the proof deadline, and only then enables the source. Proof failure first restores authoritative pause and immediately runs bounded rollback preparation; the resulting prepared rollback has no timer and waits for the user's next normal Resume before revalidation, proof, and source enable. Unpaused hot switching is later reuse of that transaction, not an independent mechanism.+- Recommended quality remains exactly `1080p60`, `1080p30`, and `720p30`, with the middle `1080p30` as the accepted default. `480p` means only an advanced `854x480` resolution choice whose FPS and bitrate remain independently selected; it is not a fourth recommended profile.- Two distribution artifacts are accepted only after the current feature, NAT, and real-network ledger is complete. A public-server one-click deployment package installs the current application plus STUN/SFU and proxy components on a user-owned server. A Windows/macOS/Linux local package runs the Host, application server, and local state on the broadcaster's machine without source, Node, or any external Screener/network service; it keeps workable direct P2P but reports the reachability loss imposed by public ingress, TLS, gateway, NAT, or firewall limits rather than promising universal connectivity.- Current UI, presence, route labels, and diagnostics describe observed state only; they do not create route authority.- Before an explicit public-release decision, the private deployment and repository keep only the current product contract. Incompatible wire, configuration, parser, and API changes ship atomically; stale clients fail before authority, replaced compatibility surfaces are deleted, and Git history owns rollback.-- Viewer startup feedback remains on the stage until current-generation frame presentation is proven, distinguishes peer, fallback, media, autoplay, recovery, and failure phases, and keeps `Play` specific to autoplay rejection. The strict-NAT guessed-candidate idea remains an isolated emulator gate; only a pass may authorize one manually approved, kill-switched canary in an operator-owned test room with explicit consent from both endpoints and exact room/edge/generation/budget bounds.+- The accepted v9 Viewer presentation remains on the stage until current-generation frame presentation is proven, distinguishes access/Host/queue, peer, SFU, media, autoplay, recovery, and typed failure phases, and keeps `Play` specific to autoplay rejection. A failed Viewer can export its privacy-safe stage/revision/code even before connection metrics exist; an authenticated Host may request one current route/timing snapshot only when downloading diagnostics. Route decisions, queue timing, and current-path quality are diagnostic only. Browser ICE decides direct reachability; Screener does not predict ports, classify NATs, probe TCP, synthesize remote candidates, or reparent a healthy edge for speculative quality gain.## Current Source And Production@@ -32,14 +33,14 @@ Last updated: 2026-08-24- Production runs exact `8f5b3f192ddd010ca01c969008e512191312736a`, release `8f5b3f1`, wire `screener-v8`; `/opt/screener/backups/8f5b3f1-precutover-20260823T182438Z` is its verified rollback boundary.- Production implements the endpoint-cap and two-stage direct-to-SFU controller contract, admits 20 Viewers, and uses LiveKit admission of one publication ingress plus 20 subscription egress handles on a dedicated non-auto-create instance. Coturn provides STUN-only UDP 3478 with TCP/TLS and relay ranges disabled; LiveKit media uses UDP 7882.- Browser SFU subscribers reconcile eligible Host screen publications across connect/activate event ordering, participant/track arrival, and reconnect. Production LiveKit logs only warn/error, and the application service has a bounded same-host LiveKit readiness preflight.-- Production retains access controls, self-check, diagnostic export, signaling watchdog behavior, and 64/128/256 audio choices. Real heterogeneous-network and SFU media evidence remains open.+- Production retains access controls, self-check, diagnostic export, signaling watchdog behavior, and 64/128/256 audio choices. Current source still defaults to `1080p60`, has no advanced 480p resolution, disables live audio mutation, exposes scattered Viewer status/raw route errors, and carries an unused parent-edge quality-proof message. The accepted v9 cleanup and media mutations are not implemented or deployed. Real heterogeneous-network and SFU media evidence remains open.- `screener`, LiveKit, coturn, and nginx are healthy; local and public health return 200 and `screener` has `NRestarts=0`. Deployment detail is owned by [deployment](./deployment.md).- Chrome loopback, cap2/cap3, short resource, recovery, MBB, and A/V fixtures are bounded evidence only. They do not establish quality, resource limits, or product policy.## Current Priority-1. Keep this truth set and [the TODO ledger](./todo.md) concise and internally consistent.-2. Await the owner's next selection among live audio, paused video-codec switching, evidence-led H.264 diagnosis, strict-NAT emulator, connection feedback, quality-driven local reparenting research, and the remaining functional roadmap. Distribution packaging starts only after those TODOs are complete. Parallel branches may finish earlier but do not change this merge/deployment order.+1. Checkpoint this accepted Browser work against current source and production without mixing their states.+2. Implement the executable [Now ledger](./todo.md) as one atomic Browser v9 release: live audio, paused codec, unused quality-proof removal, Viewer/route diagnostics, room-entry/UI repair, and the corrected quality selection. Diagnose H.264/blur and Host background behavior from controlled evidence only. Distribution packaging starts after current functional and real-network work is settled.## Working Rulesdiff --git a/docs/research/advanced-peer-distribution.md b/docs/research/advanced-peer-distribution.mdindex c111f0cb..ffbc199f 100644--- a/docs/research/advanced-peer-distribution.md+++ b/docs/research/advanced-peer-distribution.md@@ -34,28 +34,28 @@ experience automatic, and meets the latency and queue limits below.## Cost AccountingLet `B` be one complete stream bitrate, `N` the viewer count, and `r` repair-overhead. Protocol headers, retransmission, and TURN overhead are additional.+overhead. Protocol headers and retransmission overhead are additional.| Route | Host upload | Central media traffic | Encode work || --- | ---: | ---: | --- |-| Current full-stream browser chains | at most `2B` | zero except TURN edges | host up to two encoders; every relay encodes again |-| Native full-stream RTP relay | at most `2B` | zero except TURN edges | relay zero encode; native host can share one encode |-| Two encoded-object stripe trees | about `(1+r)B` | zero except TURN edges | host one encode; relay zero encode |+| Current full-stream browser chains | at most `2B` | zero on direct peer edges; SFU legs are accounted separately | host up to two encoders; every relay encodes again |+| Native full-stream RTP relay | at most `2B` | zero on direct peer edges | relay zero encode; native host can share one encode |+| Two encoded-object stripe trees | about `(1+r)B` | zero on direct peer edges | host one encode; relay zero encode || Host publication with bounded SFU subscriptions | measured `B_pub` | per-subscriber egress; see low-server model | one publication may carry at most two active representations; physical encoder count remains measured evidence || Full central SFU/MoQ fanout | about `B` | ingress `B`, egress `N*B` | a possible bounded fallback result, never the default topology or mode |Useful last-hop traffic remains approximately `N*B`; these routes only decide-which nodes emit the copies. Exact publication/subscription, TURN-hop, and billing+which nodes emit the copies. Exact SFU publication/subscription and billingaccounting is owned by [Low-Server-Cost Media Routes](./low-server-media-routes.md).-TURN is edge transport; it is not a peer/SFU topology.## Candidate 1: Native RTP Relay-This is the nearest-term high-confidence optimization. A native helper can read+This is a retained Native research direction, not a current milestone. A+native helper can readencoded RTP from one WebRTC receiver and write the payload to at most twoindependent downstream browser PeerConnections without decoding and encodingthe video again. Each downstream edge keeps its own SSRC, pacing, RTCP,-DTLS-SRTP, ICE, and TURN behavior.+DTLS-SRTP, and ICE behavior.Draft PR [#16](https://github.com/TNTcraftHIM/Screener/pull/16) passes an earlierin-process transport oracle: one Pion v4.2.18 `TrackLocalStaticRTP.WriteRTP`@@ -64,15 +64,16 @@ sequence number, and timestamp plus binding-specific SSRCs. It contains noencoder or browsers, so it is not evidence for one physical encode, end-to-endcompatibility, feedback arbitration, congestion control, or latency.-The next Go/Pion spike is video-only VP8 at 720p30 with one browser upstream-and two unchanged browser children. It must prove:+If an owning decision reopens it, the retained Go/Pion gate is video-only VP8 at+720p30 with one browser upstream and two unchanged browser children. It must+prove:- zero relay video-encoder calls and at least 40% lower relay CPU than browserremote-track forwarding;- no more than 25 ms added p95 relay latency;- per-child bytes no more than 110% of input payload bitrate;- bounded queue age below 100 ms;-- PLI, NACK/RTX, 1% loss, one direct edge, and one TURN edge; and+- PLI, NACK/RTX, and one direct edge under both clean and 1% loss conditions; and- reparented first picture within one second after failure detection.This lowers relay compute and generational quality loss. It does not lower host@@ -119,7 +120,7 @@ and application-side picture composition.## Candidate 3: Browser Encoded ObjectsWebCodecs can encode once and expose `EncodedVideoChunk` values. WebRTC-DataChannel can carry framed chunks over peer ICE/TURN paths. This is the+DataChannel can carry framed chunks over peer ICE paths. This is thecredible pure-browser route to encoded forwarding and later two-tree striping,but it replaces the browser's RTP media receiver with application framing,pacing, a jitter buffer, keyframe requests, a WebCodecs renderer, and eventually@@ -173,7 +174,7 @@ central fallback and keep it only if, at equal quality and egress, latency orserver CPU improves at least 20% over the SFU reference and draft-version churnis isolated behind a small adapter.-## Candidate 6: Bounded Capability-Aware Local Reparenting+## Current Bounded Local Reconciliation ConclusionThis is the research basis for ADR-0005's bounded local reconciliation. Narada and Overcastdemonstrate measurement-driven overlay improvement, but neither supplies a@@ -238,7 +239,9 @@ and a four-second state reconciliation that requires three consecutivemismatches before a full reconnect. Jitsi Videobridge similarly defaults to a15-second first-transfer timeout and an eight-second inactivity limit. These arereference boundaries, not universal prescriptions. Screener's separately owned-15-second initial deadline remains a candidate pending mobile-network evidence.+15-second initial deadline is a deployed implementation value, not an accepted+experience target; mobile-network evidence may justify revisiting the one total+deadline only through ADR-0005.WebRTC/LiveKit first owns transient reconnect. A hard failure or non-pauseddecoded-frame stall wakes ADR-0005 once and seeds the exact failed@@ -254,19 +257,20 @@ The first room-1 production trace on 2026-08-20 observed two short Hostparticipants while two roots remained for roughly 4.6 seconds; all ended withclient-requested leave, no track publication survived, and neither servicerestarted. This proves LiveKit participant entry. The timing is consistent with-the current one-shot grant refresh and Peer-failback state machine, but logs do+the then-current one-shot grant refresh and recovery state machine, but logs donot prove those transitions and cannot distinguishconnect, source, video publish, sender configuration, optional audio publish, or-transport failure. The next bounded diagnostic exposes only that local enum to-the Host and deliberately keeps raw errors, URLs, tokens, candidates, and-addresses out of wire and logs.+transport failure. The accepted v9 diagnostic, which is not part of deployed+v8, exposes only a closed local stage/outcome enum to an on-demand Host snapshot+and deliberately keeps raw errors, URLs, tokens, candidates, and addresses out+of wire and logs.## Automatic Route Controller Boundary-The accepted controller preserves healthy peer edges and chooses transport per-logical edge: direct/STUN first, then exact selected TURN when authorized. A+The accepted controller preserves healthy peer edges and chooses one route per+logical edge: direct/STUN first, then the dedicated SFU/UDP path when needed. Aserver-fed ingress uses the room's single Host publication plus exact SFU-subscriptions; it is not a fixed rung inserted between every peer edge and TURN.+subscriptions; it is not a fixed rung inserted between every peer edge.Every attempt ends in bounded success, wait, or failure.Native full-stream relay and striped-object routes remain the bounded candidates@@ -275,11 +279,10 @@ into the current route model.The SFU uses one authoritative Host publication and exact per-Viewersubscriptions. SFU-fed and peer-fed endpoints use the same provisional-child-first-frame transaction. Server ingress/egress and-TURN allocations use deployment-wide admission rather than a fixed root count-or room-wide lease. The SFU/UDP and optional selected-edge TURN accounting lives in-[Low-Server-Cost Media Routes](./low-server-media-routes.md). ADR-0005 owns the-accepted behavior.+first-frame transaction. Server ingress/egress uses deployment-wide admission+rather than a fixed root count or room-wide lease. The SFU/UDP accounting lives+in [Low-Server-Cost Media Routes](./low-server-media-routes.md). ADR-0005 owns+the accepted behavior.The controller is automatic and invisible. It uses participant metadata, routerevisions, endpoint capacity, server admission, and discrete exact-edge failure;@@ -348,8 +351,6 @@ Sources checked on 2026-08-20 through 2026-08-23:observable path boundaries and the centralized low-latency alternative.- [LiveKit client 2.22 room events](https://github.com/livekit/client-sdk-js/blob/v2.22.0/src/room/Room.ts)- pinned reconnect/reconnected behavior; no implementation source was copied.-- [TURN, RFC 8656](https://www.rfc-editor.org/rfc/rfc8656.html) - per-edge relay- transport rather than a room topology.- [MOQT draft](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) and[moq-dev/moq](https://github.com/moq-dev/moq) - core MIT/Apache-2.0; its OBSplugin is separately GPL-2.0-or-later and remains study-only.diff --git a/docs/research/browser-screen-audio-quality.md b/docs/research/browser-screen-audio-quality.mdindex e7c0bb8e..e2a8b4a0 100644--- a/docs/research/browser-screen-audio-quality.md+++ b/docs/research/browser-screen-audio-quality.md@@ -6,9 +6,11 @@ Status: peer and SFU routes already use stereo and a 128 kbps default, but usersstill report speech-gated movie/game audio, including on a phone connecteddirectly through the SFU. Current Chromium web `getDisplayMedia()` defaults tolocal speech processing unless the request disables it. The source request is-explicit, and Share advanced settings now provide bounded 64/128/256 kbps-sender ceilings across P2P, browser relay, and SFU. Target-device audible proof-remains open.+explicit. Current v8 exposes bounded 64/128/256 kbps choices before sharing and+applies the selected ceiling when each P2P, browser-relay, or SFU sender is+created; it does not mutate an already-active sender. Accepted v9 live mutation+and applied readback are not implemented or deployed. Target-device audible+proof remains open.## Scope And Decision@@ -46,18 +48,19 @@ stereo music in a 64--128 kbps sweet spot, and LiveKit 2.22.0 names 128 kbps`musicHighQualityStereo`. Requested, applied, negotiated, and observed statesremain separate.-The advanced panel is named Share advanced settings. The 64/128/256 choice is-a sender `maxBitrate` ceiling on the existing Opus path, so it can change during-an active share through serialized `getParameters()`/`setParameters()` updates-and readback; it does not require audio codec renegotiation. The existing wire-distributes a last-wins desired profile; each endpoint applies it locally, keeps-media and the old applied ceiling on failure, and does not claim room-wide-convergence without a remote applied acknowledgement. On the declared-Chrome/Edge screen-audio Host baseline, pinned LiveKit 2.22.0 can update the-existing audio sender without republish. Firefox's initial publish path may also-write the preset into Opus fmtp, so a sender-only increase is not claimed there-until real readback and receive evidence pass. A future microphone/voice feature-remains a separate track and processing path with its own+The advanced panel is named Share advanced settings. Current v8 stores the+64/128/256 choice and applies that sender `maxBitrate` ceiling on the existing+Opus path when it creates a sender; changing the choice during an active share+does not update an existing sender. Accepted v9, which is not implemented or+deployed, serializes `getParameters()`/`setParameters()` updates and readback,+keeps media and the old applied ceiling on failure, and does not claim room-wide+convergence without a remote applied acknowledgement. This does not require+audio codec renegotiation. On the declared Chrome/Edge screen-audio Host+baseline, pinned LiveKit 2.22.0 can update an existing audio sender without+republish. Firefox's initial publish path may also write the preset into Opus+fmtp, so a sender-only increase is not claimed there until real readback and+receive evidence pass. A future microphone/voice feature remains a separate+track and processing path with its ownAEC/noise-suppression/DTX contract. It must not turn movie or game audio into avoice-processed source.@@ -340,9 +343,8 @@ browser congestion control:are distinct repair mechanisms; retaining one neither proves, replaces nordisables the other, and no FEC switch is exposed or reimplemented.-Applying the receive preference in every browser answer covers direct P2P,-browser-relay children and selected-edge TURN because TURN changes the ICE-transport, not the peer SDP contract. SFU uses the equivalent SDK contract.+Applying the receive preference in every browser answer covers direct P2P and+browser-relay children. SFU uses the equivalent SDK contract.An SFU-only change is not acceptable: moving between peer and SFU routes wouldotherwise change channel behavior. Native/Pion sender routes retain their ownexplicit encoded-track contract and need a focused compatibility check before@@ -425,7 +427,7 @@ protected-content silence, and WASAPI device/service errors report`unavailable`/`silent` and stop or ask. The implementation never widens towhole-system loopback. The first acceptance smoke is one direct Viewer with aknown target tone/visual marker and independent voice/notification markers;-SFU/TURN, a second Viewer, endurance, and native WGC video replacement remain+SFU/UDP, a second Viewer, endurance, and native WGC video replacement remainlater gates.### Retained P1 Result (2026-08-21)@@ -444,7 +446,7 @@ audio track and 495 inbound Opus packets while video decoded/rendered 296frames. There was no fatal or encoder error. The sole failed assertion was theexisting generic Pion two-second outbound snapshot, which also missed freshdeltas in earlier video loopbacks. This is functional evidence, not packaging,-real-game sync, second-Viewer, SFU/TURN, or endurance evidence.+real-game sync, second-Viewer, SFU/UDP, or endurance evidence.Run one bounded matrix rather than a full route Cartesian product: exactproduction and current `main` on Windows Chrome/Edge for tab/window/monitor,@@ -452,9 +454,9 @@ audio selected/unselected, and a simultaneous voice call; then the nativecandidate on current Windows 11 with game parent and child audio, an independentvoice process, notifications, no render stream, and process restart. Windows 10records the explicit unsupported/unresolved result rather than a fake fallback.-Direct is the primary route; one browser-relay and one-SFU-subscription audio check cover route preservation. Test exact selected-edge-TURN and Host-SFU TURN transport as separate authorized connectivity gates.+Direct is the primary route; one browser-relay and one SFU-subscription audio+check cover route preservation. Ordinary peer ICE remains STUN-only and current+SFU media remains UDP-only; this audio matrix does not add a transport path.Correlate capture settings, negotiated codec/derived fmtp,actual outbound/inbound bitrate, loss, jitter, concealment, jitter buffer, andA/V playout timing using a distinguishable stereo fixture plus game/film audio.@@ -462,11 +464,13 @@ A/V playout timing using a distinguishable stereo fixture plus game/film audio.## UI And Voice BoundaryShare advanced settings offers exactly 64/128/256 kbps and defaults to 128.-The choice can change during the active share. P2P, browser relay, and SFU-senders read the latest desired profile and keep endpoint-local applied-readback rather than claiming one room-wide applied commit. It remains a sender-ceiling, not a guaranteed or constant bitrate. Do not expose sample rate,-channel count, codec, DTX, RED, FEC, an arbitrary slider, or a second audio+Current v8 applies the selected choice before sharing and to any newly created+P2P, browser-relay, or SFU sender; it does not live-update an active sender.+Accepted v9 live mutation is not implemented or deployed. That extension reads+the latest desired profile into each sender and keeps endpoint-local applied+readback rather than claiming one room-wide applied commit. The setting remains+a sender ceiling, not a guaranteed or constant bitrate. Do not expose sample+rate, channel count, codec, DTX, RED, FEC, an arbitrary slider, or a second audioadaptation loop.If microphone voice enters scope, treat it as a separate source/track with andiff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.mdindex 847c1880..f49faea8 100644--- a/docs/research/low-server-media-routes.md+++ b/docs/research/low-server-media-routes.md@@ -11,24 +11,24 @@## Current Transport ConclusionScreener's application route ladder is only direct/STUN peer followed by the-dedicated LiveKit SFU over UDP. The selected peer-edge/Host-ingress TURN/UDP-candidate is rejected: when outbound UDP can reach a public server, SFU/UDP-covers the product's bounded central fallback while one Host publication serves-multiple Viewers; when all outbound UDP is blocked, TURN/UDP adds no reachability.-The extra credential issuer, route tuple, logical-allocation ledger, relay-only-rebuild, configuration, UI, deployment, and test surfaces have no remaining-consumer that justifies their whole-system cost.--This conclusion does not claim that the TURN standard has no use. WebRTC-requires TURN support for endpoint-dependent NAT combinations, and LiveKit can-offer ICE/TCP or TURN/TLS for strict firewalls. Screener currently accepts a-smaller UDP-only boundary and fails clearly when it is unreachable. If real-target-network evidence later requires broader coverage, transport selection-belongs inside LiveKit rather than becoming a third Screener route class. The-pinned LiveKit 1.13.5 configuration exposes `rtc.tcp_port`, external TURN, and-embedded TURN/TLS as framework capabilities; none is enabled by this decision.--Primary sources checked 2026-08-24: [WebRTC transports, RFC+dedicated LiveKit SFU over UDP. One Host publication can serve multiple exact+Viewer subscriptions, so this remains a bounded central fallback rather than an+always-SFU topology. When all outbound UDP is blocked, both accepted paths end+in a clear bounded failure. Screener configures no TURN, ICE/TCP, media TCP, or+TLS-relayed media path.++WebRTC and LiveKit expose broader framework transport capabilities, but those+capabilities do not authorize another Screener route. Any future strict-firewall+coverage requires real target-network evidence and a new accepted decision, and+must remain inside LiveKit rather than become a third application route class.+The pinned LiveKit 1.13.5 configuration exposes `rtc.tcp_port`, external TURN,+and embedded TURN/TLS; none is enabled by the current product contract.++Primary sources checked 2026-08-24: [ICE, RFC+8445](https://www.rfc-editor.org/rfc/rfc8445.html), [NAT traversal and port+prediction, RFC 5128](https://www.rfc-editor.org/rfc/rfc5128.html#section-5.2),+[Experimental NAT behavior discovery, RFC+5780](https://www.rfc-editor.org/rfc/rfc5780.html), [WebRTC transports, RFC8835](https://www.rfc-editor.org/rfc/rfc8835.html), [LiveKit connectionreliability](https://docs.livekit.io/intro/basics/connect/), [LiveKit self-hosteddeployment](https://docs.livekit.io/transport/self-hosting/deployment/), and the@@ -49,8 +49,8 @@ re-encoding closed that browser-relay candidate. Native sender work remained aseparate research track. ClosedPR #12's explicit whole-room SFU mode is superseded. ADR-0005 and merged PR #17own the automatic cross-mode controller. Production first enabled it only for-room `1` and later removed that rollout boundary. The deployed release observed-participant entry but did not retain media. On 2026-08-21, a latest-source run+room `1` and later removed that rollout boundary. That first room-`1` release+observed participant entry but did not retain media. On 2026-08-21, a latest-source runforced the first direct edge to fail and then passed one local SFU/UDP root withChrome 151, LiveKit 1.13.5, and pinned client 2.22.0. LiveKit produced two senderRIDs in `q,h` order; Screener's former `q,f` guard caused the Host publisher to@@ -58,8 +58,10 @@ fail closed at `sender-config`. After correcting that contract, Viewer inboundpackets and decoded/rendered frames increased, endpoint edges stayed bounded,and both clients left cleanly. TURN did not participate in that first run. Alater exact-source canary against the then-production media tuple proved the-historical Host-ingress selected relay described below. Both are functional, not-performance, evidence; public-room and browser-diversity validation remain open.+historical Host-ingress selected relay described below. The current `8f5b3f1`+production canary subsequently committed two SFU assignments and decoded+1920x1080 video. These are functional, not performance, evidence; heterogeneous+networks, mobile, resources, and endurance remain open.## Token-Free SFU Standby Prewarm@@ -126,7 +128,7 @@ only by its actual committed children and those edges are already counted inwhere a publisher leg separately uses TURN, retain host upload`B_pub`, TURN ingress `B_pub`, TURN egress `B_pub`, and SFU ingress `B_pub` asdistinct interface/service traffic. Any separately TURN-relayed LiveKit-subscription or controller-selected peer edge adds TURN ingress and egress equal+subscription or historical selected-edge peer leg adds TURN ingress and egress equalto that leg's measured bitrate. These are one logical useful payload copy butreal physical hops, so NIC, service, and billing counters must never be folded.SFU@@ -195,12 +197,16 @@ supports one fresh, generation-bound P2P opportunity after a discrete networkchange or explicit reconnect; it does not support periodic probing, a carrier"kept channel" assumption, or a universal hard-NAT traversal claim.-### Deployable Browser-First Priorities+### Real-Network Measurement Inputs++These are isolated measurement inputs for the accepted real-network ledger, not+authority to change production DNS, firewall, STUN count, or route behavior.**1. Dual-stack Web, STUN, and SFU**-- Smallest change: publish working `AAAA` records, bind every public endpoint on- IPv6, and open the same bounded UDP paths. Browser ICE already gathers and+- Measurement setup: on an operator-owned isolated deployment, publish working+ `AAAA` records, bind every public endpoint on IPv6, and open the same bounded+ UDP paths. Browser ICE already gathers andintermixes IPv4/IPv6 candidates; do not add application candidate ordering.Product code can remain unchanged; any retained evidence is only a sanitizedselected-address-family enum tied to the existing opaque generation.@@ -216,9 +222,10 @@ change or explicit reconnect; it does not support periodic probing, a carrier**2. Exactly two independent-destination STUN servers**-- Smallest change: set the existing `STUN_URLS` list to two URLs. Current server- code already accepts the list and sends both URLs in one ICE server entry.- Existing schema capacity for eight URLs is not a product recommendation.+- Measurement setup: use an isolated `STUN_URLS` list with two independent+ destinations. Current server code already accepts the list and sends both+ URLs in one ICE server entry. Existing schema capacity for eight URLs is not a+ product recommendation or production change.- Dependency: each URL must resolve to a different public destination IP;separate failure domains and dual-stack coverage are preferable. Currentlibwebrtc tests show that equal observed mappings are deduplicated while two@@ -232,67 +239,26 @@ change or explicit reconnect; it does not support periodic probing, a carrier- Stop line: two STUN destinations improve address-family/failure diversity andcan expose mapping differences in an owned canary; they do not reveal themapping that a peer destination will receive and do not solve two endpoint-- dependent mappers. Do not add a third server or a NAT classifier without a- measured failure that the second server fixes.--**3. SFU-to-P2P recovery**--- WebRTC/LiveKit first owns network change and reconnect. Only an exact hard- failure or non-paused decoded-frame stall wakes the room reconciliation used- for every child.-- The existing SFU edge remains active when usable. One P2P candidate receives- standard ICE checks and commits only after its child decodes the first new- frame; failure releases it and preserves SFU.-- No polling loop, periodic probing, or second route controller- is authorized. Capacity and server admission use ADR-0005.--### Isolated Bounded Guessed-Candidate Spike--WebRTC does not expose raw UDP, but the WebRTC API lets the application signal a-remote ICE candidate and call `addIceCandidate()`. An owned experiment can-therefore inject a small, explicitly capped set of nearby-remote-port candidate guesses for one edge generation and let the browser ICE-agents send authenticated connectivity checks. The initial harness ceiling of-eight guesses across both endpoints is a safety fixture to bound abuse and ICE-work, not a product constant or evidence that eight is optimal. This is bounded-port prediction, not the birthday-paradox technique proposed for native peers-with hundreds of sockets and probes.--RFC 5780 behavior discovery is Experimental, requires a STUN server that-supports alternate addresses, observes only current behavior toward those test-destinations, and explicitly does not replace ICE. It may help an owned emulator-confirm that a mapping pattern exists, but route decisions must still use actual-operating connectivity and media evidence. A NAT label or two observed ports do-not authorize a guessed production path.--- Current status: zero product or production integration and not yet eligible- for a production canary. Use an isolated test page or harness and- a sequential endpoint-dependent NAT emulator fixture. Reuse existing candidate- signaling and ICE generations; do not mutate SDP or create a second production- protocol.-- Dependency: two controlled STUN destination IPs, a deterministic owned NAT- emulator, the same ICE base/socket across observations and peer checks, an- allowlisted test room, and a hard maximum of eight extra candidate guesses in- total across both endpoints per edge generation. No guessed address, candidate- string, or SDP may be retained.-- Acceptance: ordinary ICE must deterministically fail direct connection in the- emulator; then the bounded variant must reach decoded media within the current- 15-second route window in at least 90 of 100 runs on the exact stable Chrome- and Firefox releases recorded in the matrix, with no more than eight injected- guesses in total and no candidate-error or resource-growth regression. Actual- connectivity-check packets may exceed eight because guesses pair with local- candidates and ICE retransmits checks; the candidate budget is not a packet- budget. Safari is measured separately before any product decision. Only an- emulator pass permits one manually approved canary in an operator-owned test- room. Both endpoints must explicitly consent, and the canary must be default-off- behind a kill switch and bound to one exact room, logical edge, ICE generation,- deadline, and aggregate candidate budget. It is still not general production- evidence.-- Stop line: reject the candidate if it needs raw sockets, extra peer- connections, browser-specific SDP rewriting, more than eight total guesses,- unbounded retries, a longer black-screen deadline, or fails the two-engine- repeatability gate. A failure closes this candidate in favor of bounded- SFU/UDP; it does not justify a native sender by itself.+ dependent mappers. Do not add a third server or a NAT classifier; neither is+ part of the accepted Browser route model.++### Ordinary-Browser ICE Boundary++Browser ICE connectivity checks are the only accepted direct UDP reachability+authority. RFC 8445 already tests authenticated candidate pairs and produces an+actually usable nominated pair; a TCP connection, a claimed NAT label, or two+STUN observations cannot predict whether that UDP media pair is reachable.+RFC 5128 also limits port prediction to favorable mapping behavior and notes+that randomized or multi-level mappings defeat it. RFC 5780 is Experimental,+observes behavior only toward its STUN destinations, and explicitly does not+replace ICE.++Screener therefore does not synthesize remote candidates, guess adjacent ports,+classify NAT behavior, or probe TCP reachability. Direct ICE exhaustion advances+to SFU/UDP within the existing total operation deadline; when all UDP is blocked,+both accepted paths end in a clear bounded failure. This preserves one candidate+model and avoids adding mappings, ICE/DTLS work, abuse surface, or magic guess+budgets that ordinary browser APIs cannot make reliable.### Ordinary-Browser Hard Boundaries@@ -324,33 +290,40 @@ not authorize a guessed production path.The shared acceptance matrix remains EIM/EIM, one endpoint-dependent mapper,two endpoint-dependent mappers including cellular-to-cellular, all UDP blocked,-and a Wi-Fi-to-cellular change. Record only sanitized route kind, address family,-generation, time to first decoded frame, loss, RTT, bitrate, and SFU bytes. Keep-credentials short-lived and generation-scoped and retain ingress/egress caps.+and a Wi-Fi-to-cellular change. It measures ordinary ICE/STUN, SFU/UDP, and clear+failure without injecting candidates. Record only sanitized route kind, address+family, generation, queue/candidate/first-frame timing, loss, RTT, bitrate, and+SFU bytes. Keep credentials short-lived and generation-scoped and retain+ingress/egress caps.-## Privacy-Safe ICE Evidence Candidate+## Privacy-Safe Route Diagnostic BoundaryStart with locally retained, redacted `webrtc-internals` as manual ground truth.-Only then may one exact allowlisted room record, without changing its route:--- selected local/remote candidate type and protocol plus local- `relayProtocol`;-- selected address family reduced locally to `ipv4|ipv6`, without retaining the- source address;-- `iceGatheringState`, `iceConnectionState`, and `connectionState` transitions- with monotonic event-derived establishment duration;-- `selectedCandidatePairChanges` when implemented, reported only as a delta- from the current opaque connection/ICE-restart generation baseline;-- RTT, loss, and actual/available bitrate for the selected RTP-bound path; and-- `icecandidateerror.errorCode` bucketed as- `3xx|4xx|5xx|6xx|701|other`.--Never retain raw `errorText`, address, port, URL, candidate strings, SDP, or-device/network identifiers. Stats members may be absent, and the pair-change-counter is transport-lifetime state, so events and generation baselines prevent-old connection or ICE-restart history from being attributed to a new route.-Use opaque generations only. This is a bounded diagnostic manifest, not a-backend telemetry schema or controller input.+The deployed v8 product already has a user-initiated local stats export; it does+not have the accepted v9 route-timing snapshot. V9 may observe only existing+join, route-demand, operation-start, candidate-start, first-decoded-frame,+settle, share-stop, departure, and room-delete events. It keeps one latest+timing/outcome record per current child; a new demand overwrites that record,+and authoritative share stop/replacement, confirmed departure, or room deletion+removes it. It creates no timer, event ring, backend telemetry stream, or route+input.++Only an authenticated Host's explicit local-export action may request one+current snapshot. The response projects the current graph, current operation,+and latest records through snapshot-local ordinals that are not participant+identities. It includes relative queue/candidate/first-frame timing, operation+reason/stage/cursor, and final route `direct | sfu | waiting | failed`. A current+candidate may expose only the closed rejection bucket `none`, `stale`,+`endpoint-capacity`, `sfu-admission`, `candidate-failed`,+`first-frame-timeout`, `operation-deadline`, or `aborted`. Queue wait is measured+from route demand to operation start. Missing timing remains `null`; no consumer+reconstructs past events from the current graph.++Never retain or emit raw `errorText`, address, port, URL, candidate strings,+SDP, credentials, display name, or real peer/parent/session/connection/generation+identity. The server does not log, persist, or periodically push the snapshot,+and Viewers cannot request it. Current-path ICE/RTP stats remain local to the+page that owns the connection and have no route authority.### Local Diagnostic Export Boundary@@ -391,31 +364,23 @@ one controller-selected authenticated TURN/UDP rebuild before failure. Thatordering and accounting are historical implementation evidence, not currentroute authority.-STUN/ICE discovers and checks paths. RFC 8656 TURN allocates a relayed address-and continuously carries media when selected; it is not a handshake helper or-topology. Ordinary PCs do not gather relay candidates, so healthy paths consume-no idle allocation. Exact-room, complete-tuple, current-generation and one-use-controller gates prevent participant-wide or process-wide rollout.--Coturn validates a REST bearer's HMAC and expiry, not the originating room,-peer edge, revision, parent, or connection generation. Application issuance and-both endpoint rebuilds therefore must revalidate the controller's current edge-identity and consume the attempt on success, failure, expiry, or generation-change. This is application selected-edge enforcement plus TTL, fanout, and-quota containment, not coturn-side cryptographic edge binding. The failed-built-in alternative and retained standards evidence are in+The historical candidate relied on RFC 8656 TURN allocation carrying media+rather than acting as a handshake helper or topology. It kept ordinary PCs+STUN-only and used exact-room, complete-tuple, generation, and one-use gates to+contain its isolated rollout. Those gates describe the measured candidate only;+they do not authorize a current transport.++At that checkpoint, coturn validated bearer HMAC and expiry but not Screener's+room, edge, revision, parent, or connection identity. The application therefore+bound issuance and both endpoint rebuilds to the candidate's exact identity and+consumed the attempt on success, failure, expiry, or generation change. The+failed built-in alternative and retained standards evidence are in[Built-In Peer ICE TURN Candidate](./built-in-peer-ice-turn.md).-Pinned LiveKit 1.13.5 can advertise authenticated TURN to LiveKit participants,-but that separate ICE domain covers publisher/subscriber connections to the-SFU, not ordinary peer PCs. Selected-edge coturn uses independent configuration-and credentials. LiveKit TURN cannot rescue an unavailable SFU; the application-controller selects whether independent coturn may rebuild one failed peer edge.--Pinned client 2.22.0 accepts a per-connect `rtcConfig`; its engine retains-explicit ICE servers when constructing the publisher PeerConnection. A selected-Host ingress can therefore supply only its coturn server plus relay policy-without advertising that credential to ordinary peer PCs.+Pinned LiveKit 1.13.5 and client 2.22.0 exposed TURN and per-connect `rtcConfig`+capabilities used to explain the historical Host-ingress experiment. That+separate ICE domain and its coturn credential were never authority for ordinary+peer PCs and are not part of the current product route.Ordinary peer ICE remains STUN-only. Both the participant-wide and selected-edgeTURN candidates are rejected product paths; their canary evidence remains below@@ -427,7 +392,7 @@ instances rather than a process-wide old-release compatibility branch. HTTPS/WSS### Historical Host-Ingress Functional Evidence-On 2026-08-21 the tracked standalone gate reused the production selected-edge+On 2026-08-21 the tracked standalone gate reused the then-production selected-edgetuple parser and credential issuer, supplied the short-lived credential only toan isolated loopback Chrome page, and returned a sanitized result: one UDP relaycandidate and an otherwise non-blocking `701` error bucket. No URL, username,@@ -435,7 +400,7 @@ credential, candidate address, or raw error text was emitted or persisted.The canonical Chrome 151 product canary then used exact deployed Web source`16f6eab27bdfb1c15cdbd814a35864f4f18be767` in a local Screener room while-connecting to the production LiveKit 1.13.5 and coturn tuple. After direct media+connecting to the then-production LiveKit 1.13.5 and coturn tuple. After direct mediaand active SFU media, a temporary DEV-only hook failed the refreshed publisheronce; the normal application failure path requested `host-sfu-ingress` and thehook was removed after the run. The relay-policy publisher had only a TURN@@ -457,17 +422,16 @@ TURN-only server set, `relayProtocol`, and transmitted media together; thenot latency, quality, capacity, expiry, mobile, resource, or bandwidth behavior.Coturn 4.17.2 documents `stun-only` as ignoring TURN requests and provides`no-tcp` and `no-tls`; it marks `no-dtls` deprecated, so the tracked temporary-template does not use that switch. The shared production host instead retains its old-authenticated-relay daemon and TCP/UDP 3478 plus UDP 49152-49251 rules. The-rejected participant-wide candidate advertised no TURN credential, and that-historical post-canary audit found zero allocations. This baseline is not the-later selected-edge functional evidence above.--No public port is selected by this decision. LiveKit documents ICE/UDP mux as-optional and its pinned sample recommends a multi-port UDP mux range at least-as wide as the CPU count for performance. Embedded TURN/UDP defaults to 3478.-The current nginx template has no HTTP/3 listener, but that fact alone does not-prove one UDP port is the best production layout.+template did not use that switch. At that dated checkpoint, the shared host+still retained an authenticated-relay daemon and TCP/UDP 3478 plus UDP+49152-49251 rules. Current production instead runs coturn as STUN-only UDP 3478+and LiveKit media on UDP 7882, with coturn TCP/TLS and relay ranges disabled.+The historical participant-wide canary advertised no TURN credential and its+post-canary audit found zero allocations.++That historical candidate selected no new public port. LiveKit's optional+ICE/UDP mux, multi-port sample, and embedded TURN defaults are framework facts,+not current Screener deployment recommendations.For `K` equal-representation first-level deliveries that cannot use direct media:@@ -486,7 +450,9 @@ benchmarks and the Jitsi profiling breakdown establish capacity and componentcategories only. Different machines and implementations cannot support auniversal relay/SFU CPU ratio or a claimed fixed percentage saving.-One bounded exact-room gate owns rollout evidence:+### Current Direct/SFU External Acceptance++One bounded exact-room gate owns the still-open direct/SFU evidence:1. On the same host and NIC, measure LiveKit SFU UDP at 8 and 12 Mbps with onepublication and one, two, and twenty subscriptions. Record CPU seconds/GiB,@@ -584,27 +550,6 @@ example benchmark cannot supply Screener defaults. A later multi-processScreener deployment needs a shared atomic ledger; independent process-localcounters would not be deployment-wide admission.-## Deployment-Wide TURN Admission--Selected TURN needs its own deployment admission because coturn REST credentials-authenticate a bounded bearer but do not enforce Screener's room, edge, session,-revision, or connection identity. The current single-process boundary is one-O(1) logical-allocation ledger with an explicit positive safe-integer capacity-and no default. Each exact `peer-selected` transport and Host-SFU ingress-transport reserves one unit before credential issuance; reserved, committed, and-draining authorizations remain charged until the application releases that exact-identity. Independent edges may therefore coexist without a room-wide lease-rule, while exhaustion returns to the existing bounded fallback path.--Coturn exposes no application control-plane operation that deletes and reads-back one exact Screener allocation. The logical ledger therefore does not claim-physical allocation drain proof. Short credential TTL plus coturn `user-quota`-and `total-quota` bound allocations that outlive a logical authorization or an-application restart. A restarted single process starts a new logical owner and-cannot reconstruct the old in-memory ledger; a multi-process or stronger-cross-restart claim would require a shared atomic owner or a coturn control-contract and is outside this wave.-## Route Screening| Route | Where copies are emitted | Endpoint cost | Evidence status |@@ -613,8 +558,8 @@ contract and is outside this wave.| Bounded browser relay DAG | Host and each Web relay emit at most the configured endpoint cap | Ordinary browser, but every relay decodes and re-encodes and adds a hop | Source and production admit up to 20; the local 20-Viewer smoke passed, while heterogeneous networks remain open || Native shared-encode host | Host targets one encode for standard WebRTC edges | libwebrtc public-API proxy risk spike, with Pion as fallback | Research evidence; still pays per-edge upload || Native volunteer encoded-RTP relay | Each volunteer forwards one encoded copy | Native install, RTP/RTCP forwarding, packaging, and opt-in relay policy | Research only; no current product authorization |-| SFU service | SFU emits authorized subscription copies | Service pays bounded egress; an authoritative Host publisher supplies media | Source topology/admission are deployed; real LiveKit media and network validation remain open |-| SFU fallback | SFU emits authorized copies | Additional central ingress and egress cost | Accepted resource-admission input; validate the bounded path at release |+| SFU service | SFU emits authorized subscription copies | Service pays bounded egress; an authoritative Host publisher supplies media | Source topology/admission are deployed and a controlled production canary decoded media; heterogeneous-network and resource validation remains open |+| SFU fallback | SFU emits authorized copies | Additional central ingress and egress cost | Deployed bounded path; real heterogeneous-network and resource acceptance remains open || SVC plus multiple trees | Peers emit striped layer copies across several trees | Layer scheduling, reassembly, redundancy, and more churn state | Separate conditional spike; target endpoint upload near `B` || Network coding | Peers or servers emit coded blocks | Generations, buffering, decoding, integrity, and a custom media plane | Trace/FEC spike only; optimize loss recovery, not clean bandwidth || MoQ | Publishers and MoQ relays emit object copies | New transport, packaging, player, relay, and auth stack | Optional central-fallback benchmark; still pays server egress |diff --git a/docs/research/native-shared-encode-sender.md b/docs/research/native-shared-encode-sender.mdindex 809d9348..a26159ff 100644--- a/docs/research/native-shared-encode-sender.md+++ b/docs/research/native-shared-encode-sender.md@@ -27,7 +27,7 @@ described as one hardware or physical encode.The preferred first experiment is a standalone Windows C++ sender using a fixedlibwebrtc revision. It keeps libwebrtc's mature PeerConnection, RTP/RTCP, pacing,-NACK/RTX, DTLS-SRTP, ICE, and TURN behavior on each edge. Electron is not part of+NACK/RTX, DTLS-SRTP, and ICE behavior on each edge. Electron is not part ofthe media experiment; it can only wrap a proven helper later.## Minimal Risk Spike@@ -346,8 +346,8 @@ memory, latency, quality, and upload measurements. A third host edge, customRTP/SRTP, or a custom congestion-control framework remains out of scope. The#28 minimum-of-two policy is also out of scope for product code; retaining itsevidence does not retain its policy. Ordinary Web and Native peer ICE stays-STUN-only; optional selected-edge TURN follows the shared controller only after-SFU/UDP fails and needs its own bounded transport gate.+STUN-only. The sole application fallback remains ADR-0005's Host publication+with exact SFU/UDP subscriptions; Native research adds no transport candidate.## Primary Sources And License Boundarydiff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.mdindex 9dbf20ac..a4f90eea 100644--- a/docs/research/peer-assisted-media.md+++ b/docs/research/peer-assisted-media.md@@ -6,7 +6,8 @@the earlier resource/quality gate remains eight- Status: historical evidence plus the deployed bounded controller;accepted ADR-0005 owns automatic peer/SFU routing. Production later removed- the room-`1` rollout boundary; retained SFU media remains unverified.+ the room-`1` rollout boundary and a controlled canary decoded SFU media;+ heterogeneous-network, mobile, resource, and endurance evidence remains open.This document owns dated measurements and implementation evidence. Currentcapacity and routing authority live in [ADR-0005](../adr/0005-automatic-hybrid-media-routing.md)@@ -20,24 +21,25 @@ evidence rather than current capacity policy. The accepted path uses standardWebRTC media, one active upstream per Viewer, a bounded acyclic peer graph, andone uniform non-server outbound capacity `C` configured as `1`, `2`, or `3`.Host publication and peer children consume physical sender slots under-ADR-0005; SFU/TURN server resources use separate admission.+ADR-0005; SFU server resources use separate admission.This path reuses WebRTC capture, codec negotiation, RTP, NACK/PLI/RTX, congestion-control, jitter buffering, ICE, STUN, DTLS-SRTP, and browser rendering. An-exact controller-authorized logical edge may also use selected TURN. Its-cost is unavoidable in ordinary browsers: every relay decodes and re-encodes+control, jitter buffering, ICE, STUN, DTLS-SRTP, and browser rendering. Ordinary+peer edges are STUN-only; direct exhaustion may instead select the dedicated+SFU/UDP path. The peer-relay cost is unavoidable in ordinary browsers: every relay decodes and re-encodesthe screen stream. The first spike measures whether that cost is acceptable; itdoes not hide it or claim shared encoding.-The accepted controller preserves healthy direct/peer UDP edges. Exact selected-TURN may replace an authorized logical edge transport; one Host publication and-per-Viewer SFU subscriptions provide server-fed ingress when selected by the+The accepted controller preserves healthy direct/peer UDP edges. One Host+publication and per-Viewer SFU subscriptions provide server-fed ingress when selected by thesame bounded controller. Direct P2P remains thesimplest path while a healthy endpoint sender slot is available; later Viewersmay be assigned to peers automatically. ADR-0005 makes SFU capacity part of the flagshiptarget while retaining peer descendants. The first production rollout used a-room-`1` exact smoke; participant entry was observed, but retained SFU media-remained unverified. Production later removed that room boundary.+room-`1` exact smoke and observed only participant entry. Production later+removed that room boundary; a controlled current-release canary subsequently+committed two SFU assignments and decoded 1920x1080 video. That does not close+the real-network or resource matrix.## What Browsers Can Share@@ -143,7 +145,7 @@ DataChannel avoids relay re-encoding, but the application must define:- decoder reset and generation changes; and- explicit failure when the codec or feature set is unsupported.-DataChannel still provides ICE/TURN traversal, DTLS protection, SCTP+DataChannel still provides ICE traversal, DTLS protection, SCTPfragmentation, partial reliability, and association-level congestion control.RFC 8831 warns that a large message can monopolize an SCTP association whenmessage interleaving is unavailable and recommends limiting messages to 16 KB@@ -195,8 +197,8 @@ Sources:The signaling server remains the topology authority. The source candidate usesa sticky, bounded DAG selected by one breadth-first walk. Here, one media edge-means one downstream `RTCPeerConnection` carrying the shared stream; a later-controller-selected TURN rebuild does not change the edge count.+ means one downstream `RTCPeerConnection` carrying the shared stream; a+ framework connection rebuild does not change the logical edge count.- the historical experiment gave the host and every ordinary Web viewer capacityfor at most two children;@@ -220,10 +222,11 @@ experiment rather than something hidden by a scheduler. Ordinary Web clientsuse the same capacity without UA or visibility classification; mobile devicesremain non-blocking compatibility observations.-Per-edge ICE remains independent. Ordinary peer edges are STUN-only; the-controller may select authenticated TURN for an exact logical edge transport or-the single Host-SFU ingress under the accepted route model. Peer assistance therefore reduces normal server media-traffic but cannot promise zero server traffic in restrictive networks.+Per-edge ICE remains independent. Ordinary peer edges are STUN-only; after the+direct stage is exhausted, the same controller may select the room's single Host+publication and an exact SFU/UDP subscription. Peer assistance therefore reduces+normal server media traffic but cannot promise zero server traffic in restrictive+networks.## Implemented Bounded Quality Coordination@@ -233,10 +236,12 @@ integer 15-60 fps, integer 2-12 Mbps, and the three standard degradationpreferences; missing, extra, or out-of-range fields fail schema validation.The three visible presets are recommendations rather than wire IDs. The serverstores the latest complete object in a room-count-bounded in-memory map,-defaults to 1080p60 at 8 Mbps with clarity-first priority, includes it in+currently defaults to 1080p60 at 8 Mbps with balanced priority, includes it inpeer-assisted authenticated snapshots, and broadcasts host changes to onlineviewers. The value survives a stopped share, is removed with the room, and is-not written to SQLite. Ordinary P2P authentication remains unchanged and+not persisted. The accepted next default is the existing 1080p30 recommendation;+advanced `480p` adds only an 854x480 resolution value, not a fourth preset.+Ordinary P2P authentication remains unchanged andsetting-control messages are forbidden in that mode.After peer-assisted authentication, the host reasserts its local selection@@ -372,9 +377,9 @@ downstream capacity `C`:- each non-server parent has at most approximately `C * B` ordinary downstreamupload, plus transport overhead;- aggregate viewer delivery still requires approximately `N * B` across hosts,- relays, and any TURN paths; and-- signaling/STUN carry negligible media traffic, while a TURN path still incurs- relay ingress and egress for that edge.+ relays, and SFU paths; and+- signaling/STUN carry negligible media traffic, while an SFU path incurs+ bounded publication ingress and subscription egress.Peer assistance distributes traffic; it does not eliminate it. The productkeeps topology automatic and invisible while the server enforces the configured@@ -471,8 +476,9 @@ All hard gates must pass:statistics are expected to show a new outbound RTP encoder at every hop; itsencode time, CPU/GPU cost, and `qualityLimitationReason` are recorded ratherthan mislabeled as shared encoding.-3. Excluding explicitly selected TURN edges, application-server media ingress- and egress remains zero. Host and relay upload stay within 20% of+3. Under that dated gate, excluding its explicitly selected TURN edges,+ application-server media ingress and egress remains zero. Host and relay+ upload stay within 20% of`childCount * B`.4. First picture is at most 3 seconds, decoded 60 fps does not remain below 50for more than 5 seconds without an explicit failure, and depth-three p95@@ -501,8 +507,9 @@ fallbacks.Passing these historical gates proved only that a second design phase wasjustified. ADR-0005 subsequently accepted the bounded controller; production-first ran a room-`1` smoke and later removed that rollout boundary. Retained SFU-media and broader audio/A-V verification remain open. The+first ran a room-`1` smoke and later removed that rollout boundary. A controlled+current-release canary decoded two SFU assignments; heterogeneous-network,+resource, and broader audio/A-V verification remain open. Thenative host shared-encode sender is a separate planned phase regardless of thisexperiment's result and is not implemented here.@@ -546,11 +553,8 @@ statistics, is not logged, and is limited by the server to at most one responseper socket per second. The watchdog itself does not close or rebuild media,emit `route-failed`, or change route authority. Ordinary P2P and a duplicatesame-revision SFU authority keep their healthy media while the new socket-reauthenticates. An existing `peer-selected` TURN lease remains deliberately-bound to both authenticated sessions: replacing either session invalidates that-exceptional transport and leaves recovery to the existing bounded route path.-Relaxing or carrying that security authority is a separate routing/protocol-change, not part of signaling liveness detection.+reauthenticates. The watchdog does not create or carry media-transport+authority; route and SFU lifecycle remain owned by ADR-0005.## License Boundarydiff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex f1f7a249..bcd7b9ef 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -32,9 +32,32 @@ on 2024-05-22; the commit says it had already been disabled for several yearsand was not maintained. Current Chromium behavior must therefore not bedescribed as automatically detecting game motion and forcing a 720p cap.-## Production Degradation Report--On 2026-08-19 production `769de201f7cc` was reported to become severely blurry+## Route Quality Authority++Current-path WebRTC stats can diagnose loss, RTT, jitter, bitrate, resolution,+FPS, freeze, encode/decode work, and limitation reason, but they cannot prove the+counterfactual quality of an unconnected parent. RFC 8836 assigns real-time+congestion adaptation to the media transport. The Overcast, Narada, and NICE+overlay algorithms require active measurements, periodic reevaluation,+thresholds, or additional overlay state; those mechanisms conflict with+Screener's one event-driven reconciliation loop, one room-serial child+operation, and sticky healthy edges.++Screener therefore does not compute a weighted route score, probe alternative+parents, or reparent a currently decoding edge for bitrate, resolution, FPS,+freeze ratio, RTT, jitter, loss, or limitation evidence. Only a hard+`failed/closed` connection or the existing non-paused decoded-frame stall makes+the exact edge invalid. The existing `parent-edge-quality-evidence` message has+no route consumer and should be deleted rather than given a threshold-based+meaning. Primary sources checked 2026-08-24: [RFC+8836](https://www.rfc-editor.org/rfc/rfc8836.html),+[Overcast](https://www.usenix.org/legacy/publications/library/proceedings/osdi2000/full_papers/jannotti/jannotti_html/index.html),+[Narada](https://www.cs.cmu.edu/~srini/papers/papers/2002-Chu-jsac/2002-Chu-jsac.pdf),+and [NICE](https://conferences.sigcomm.org/sigcomm/2002/papers/appmulti.pdf).++## 2026-08-19 Then-Production Degradation Report++The then-production release `769de201f7cc` was reported to become severely blurrywhile the host repeatedly showed a sustained native`qualityLimitationReason=bandwidth`, despite one capable viewer on the same LANand the UI showing direct P2P. This is a user report, not yet an instrumented@@ -61,7 +84,7 @@ Use this as the first A+B/C reproduction before any route change or dual-layerpublication:1. Reproduce one wired LAN/direct viewer first, then Wi-Fi, two/three viewers,- and forced TURN, using the same high-motion scene for 60 to 90 seconds.+ and SFU/UDP, using the same high-motion scene for 60 to 90 seconds.2. In one window record A capture; B actual/target/available outbound bitrate,dimensions/FPS, codec, encode cost, loss/RTT/retransmission, selected path,limitation, and PC/track generations; and C inbound decode/drop/freeze.@@ -131,15 +154,33 @@ the application policy without those measurements. LiveKit's pinned clientalso contains an SDP start-bitrate mitigation for initial video blur, butScreener's accepted boundary forbids adding application SDP bitrate hacks.-The same production release is also reported to reduce game-stream frame rate-and consume noticeable Host resources. That report applies only to deployed-`769de201f7cc`, not automatically to the newer diagnostics on `main`. The Web+The same release was also reported to reduce game-stream frame rate and+consume noticeable Host resources. That report applies only to+`769de201f7cc`, not to current production or automatically to the newer+diagnostics on `main`. The Websender creates one independent `RTCRtpSender` per viewer and has no cross-PCshared-encoder guarantee; its muted local preview creates no media edge orserver traffic but may still consume compositor/GPU work. Compare the exactrelease and current `main` under one fixture, with preview on/off as a separatebinary intervention.+Desktop background diagnosis must also separate three independent variables:+Host document foreground/occluded/minimized state, captured source+foreground/occluded/minimized state, and local preview play/pause. Record+document visibility/focus, capture-track `muted`/`readyState`, actual codec,+capture/outbound/inbound FPS and bitrate, resolution, frames, encode time, and+limitation reason. The Screen Capture specification does not expose a page+keepalive contract; Screen Wake Lock is released when its document is no longer+visible, and browser page lifecycle may freeze JavaScript. Do not add fake+activity or keepalive timers. If the capture source or browser/OS suppresses+frames while minimized, record that standard capability boundary before any+packaged Host work. Primary sources checked 2026-08-24: [Screen+Capture](https://www.w3.org/TR/screen-capture/), [Screen Wake+Lock](https://www.w3.org/TR/screen-wake-lock/), [Page Lifecycle+API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api), and+[Chromium desktop capture+implementation](https://chromium.googlesource.com/chromium/src/+/master/content/browser/media/capture/desktop_capture_device.cc).+## SFU Profile Lifecycle And Publisher EvidenceA 2026-08-21 report says that selecting fluid preference on an SFU path could@@ -201,11 +242,20 @@ a same-kind source. Mature WebRTC code such as Jitsi follows a codec preferencechange with renegotiation, while pinned LiveKit changes publication codec throughits publish/republish lifecycle. Screener therefore starts with a paused-sharetransaction: fence the request by codec/media generation, serialize it with-route mutation, renegotiate the frozen still-current peer/relay targets, and-republish the SFU generation when present. A zero-target share only saves the-future preference. Because paused tracks cannot prove decoded progress, proof-occurs on resume; failure pauses again and runs a bounded old-preference-rollback. Passing an empty codec list restores default browser preferences.+route mutation, boundedly renegotiate the frozen still-current peer/relay+targets, and republish the SFU generation when present. Preparation never+resumes an explicitly paused share. When preparation settles, it stops only the+running preparation deadline: one room-serial codec mutation owner remains as+bounded in-memory prepared state, holds no timer while paused, and excludes+route mutation. The user's ordinary Resume is handled inside that same owner. It+atomically revalidates the exact frozen bindings, starts the decoded-progress+proof deadline, and only then enables the source. A zero-target share saves the+future preference and commits without media proof. If forward proof fails, the+owner first restores authoritative paused state and then runs bounded+old-preference rollback preparation. A prepared rollback again holds no timer+and waits for the user's next ordinary Resume to start its decoded proof; no+transaction path resumes the share automatically. Passing an empty codec list+restores default browser preferences.This is a deliberate paused bounded-gap path. Unpaused make-before-break is alater extension rather than a second codec mechanism.@@ -320,7 +370,7 @@ Product inference from those facts: use the following ordered classification:| --- | --- || Capture low | capture or constraints || Capture high; outbound low; `cpu` | encoder/resource pressure |-| Capture high; outbound low; `bandwidth` | GCC, uplink, or TURN/path pressure |+| Capture high; outbound low; `bandwidth` | GCC, uplink, or current-path pressure || Outbound healthy; inbound low | transport or receiver path || Inbound healthy; image visibly blurry | bitrate/quantization, codec, or display scaling |@@ -377,9 +427,11 @@ one unambiguous encoding. Current quality settings do not request a mode, sothe requested value remains null and a browser-reported default is not calleda mismatch; multiple encodings remain unknown. Inbound stats provide no currentstandard `scalabilityMode` source, so C does not carry a null-only placeholder.-The shared `HIGH+LOW` publication remains unimplemented,-and browser support remains subject to the controlled matrix. Physically-stopping an unused `LOW` is a resource optimization rather than a prerequisite.+The current SFU publisher already configures the shared ordered `q,h`+`HIGH+LOW` publication. Real LiveKit per-subscriber BWE downshift/recovery,+hardware and game-resource cost, and heterogeneous-network behavior remain open+acceptance evidence. Physically stopping an unused `LOW` is a resource+optimization rather than a prerequisite.Official W3C text checked 2026-08-19 defines names ending in `Id` as stats-objectreferences. In particular, outbound [`mediaSourceId`](https://www.w3.org/TR/webrtc-stats/#dom-rtcoutboundrtpstreamstats-mediasourceid)@@ -655,7 +707,7 @@ latency, CPU, and memory conflict and must be balanced. Its native encodertuning and hardware integration are not available to a browser-only sender andmust not be presented as settings this project already has.-## Current Policy+## Current V8 And Accepted V9 PolicyThe three user-visible profiles remain ceilings rather than promised rates:@@ -665,10 +717,13 @@ The three user-visible profiles remain ceilings rather than promised rates:| 1080p30 | 1920x1080 at 30 fps | 5 Mbps || 720p30 | 1280x720 at 30 fps | 3 Mbps |-The middle profile is an explicit manual 1080p30 ceiling: choosing it trades a-60 fps ceiling for a 1080p capture bound. LiveKit currently uses the same-1080p30 at 5 Mbps screen-share preset, but neither preset guarantees the emitted-resolution, frame rate, or bitrate.+Current v8 defaults to `1080p60`; accepted v9 changes the default to the middle+`1080p30` ceiling. Choosing it trades a 60 fps ceiling for a 1080p capture bound.+The recommended set remains exactly the three profiles above. Accepted v9 adds+`480p` only as an advanced `854x480` resolution whose frame rate and bitrate are+selected independently, not as a fourth profile or preset ID. LiveKit currently+uses the same 1080p30 at 5 Mbps screen-share preset, but neither preset+guarantees the emitted resolution, frame rate, or bitrate.- Initial capture supplies `ideal` and `max` bounds for resolution and framerate; the actual result is read back from `MediaStreamTrack.getSettings()`.@@ -680,14 +735,16 @@ resolution, frame rate, or bitrate.and `maintain-framerate` choices. None promises an emitted resolution or rate.- `maxBitrate` and `maxFramerate` are ceilings. They are neither minimums nortarget guarantees, and the project does not use SDP bitrate hacks.-- The folded “advanced video” panel accepts only 720p/1080p/1440p, integer- 15-60 fps, 2-12 Mbps, the three preferences, and Automatic/H.264/VP8. The- first codec-switch product boundary is a generation-fenced renegotiation and- SFU republish while sharing is explicitly paused; pause or `replaceTrack()`- alone does not switch codec. The panel is now Share advanced settings and- also offers live-switchable 64/128/256 kbps audio sender ceilings, default- 128, on the existing Opus path. Display capture does- not standardize channel-count or sample-rate control. The peer receive+- The current v8 Share advanced settings panel accepts only+ 720p/1080p/1440p, integer 15-60 fps, 2-12 Mbps, the three preferences, and+ Automatic/H.264/VP8. Its 64/128/256 kbps audio ceiling, default 128, is+ selected before sharing and applied when senders are created; v8 locks audio+ mutation during an active share. Accepted v9 adds advanced `854x480` and+ live-switchable audio ceilings on the existing Opus path. The first+ codec-switch product boundary is a generation-fenced renegotiation and SFU+ republish while sharing is explicitly paused; pause or `replaceTrack()` alone+ does not switch codec. Display capture does not standardize channel-count or+ sample-rate control. The peer receivecontract permits Opus `stereo=1;maxaveragebitrate=256000`, paired with pinnedLiveKit's explicit high-quality stereo/forceStereo option; the selected senderceiling remains separate from negotiated and observed bitrate.@@ -745,7 +802,7 @@ Use the same static UI scene and deterministic high-motion game scene at720p30, 1080p30, and 1080p60. Correlate A capture, B outbound, and C inbound atthe same interval. Record actual dimensions/FPS/bitrate, limitation reason,codec, encoder implementation, interval encode/decode cost, drops/freezes,-jitter, RTT, loss/retransmission, selected direct/TURN path, and host CPU/GPU.+jitter, RTT, loss/retransmission, selected direct/SFU path, and host CPU/GPU.A live profile change must preserve peer connection IDs, avoid a second sourceprompt, and visibly converge to the requested bounds.diff --git a/docs/research/webrtc-p2p-screen-sharing.md b/docs/research/webrtc-p2p-screen-sharing.mdindex 3ea3ed6f..d40bf291 100644--- a/docs/research/webrtc-p2p-screen-sharing.md+++ b/docs/research/webrtc-p2p-screen-sharing.md@@ -4,7 +4,7 @@- 移动端采集与 Viewer 投屏能力复核:2026-08-21- selected candidate 地址隐私语义复核:2026-08-22- 目标场景:一名玩家向少量熟人私密分享,观看者可用手机/桌面浏览器加入,低延迟,尽量不消耗媒体服务器带宽-- 结论状态:本文记录已部署 PoC 的 P2P/coturn 基线。ADR-0005 与[低服务器成本媒体路由](./low-server-media-routes.md)已取代本文早期“每条 peer edge 必带 TURN”的旗舰建议;生产后续移除了 room `1` 边界,ordinary ICE 仍为 STUN-only,selected-edge TURN 已配置但尚未完成真实媒体验收+- 结论状态:本文保留早期 PoC 的可行性证据;当前 Browser source 与 production 只使用 direct/STUN peer 和 LiveKit SFU/UDP,Screener 不配置 TURN 或媒体 TCP。当前路由权威见 ADR-0005。本文是可行性与历史证据,不定义当前路由策略;当前约束见[ADR-0005](../adr/0005-automatic-hybrid-media-routing.md) 与 [TODO 台账](../todo.md)。@@ -19,18 +19,18 @@| |+---- ICE + STUN 尝试直接 UDP WebRTC ----------+|- +---- logical edge: direct/STUN -> exact selected TURN transport- +---- source/ingress fallback: one Host publication -> SFU subscriptions+ +---- logical edge: direct/STUN peer ----------------++ +---- fallback: one Host publication -> SFU subscriptions-当前自动模型由 ADR-0005 持有:健康 direct/peer 边保持 sticky;selected TURN 只替换 exact logical edge 的 transport;需要 server-fed ingress 时由一份 Host publication 服务精确授权的 SFU subscriptions。每条路径受端点发送容量、独立 server admission、generation 和 bounded failure 共同约束。Browser source 已实现该模型;production release 与真实网络验收边界由 current status、TODO 和 verification ledger 持有。+当前自动模型由 ADR-0005 持有:健康 direct/peer 边保持 sticky;direct 阶段耗尽后,同一有界 operation 复用或建立一份 Host publication 并为 exact Viewer 建立 SFU subscription。每条路径受端点发送容量、独立 server admission、generation 和 bounded failure 共同约束。Browser source 与 production 已实现该模型;真实网络验收边界由 current status、TODO 和 verification ledger 持有。系统必须无感完成拓扑分配、恢复和必要迁移;大规模公开分享仍直接使用现有直播服务。```“让画面跑起来”难度不高;“像 Discord/TeamSpeak 一样在不同 GPU、浏览器、NAT、运营商和弱网中都保持清晰、60 fps、低延迟”难度高。建议把产品分层:-- 原型:Web、P2P、STUN、TURN,验证小范围多观看者;当前产品接入上限为 20,发布前仍需完成 20-Viewer Browser smoke。-- 可用 MVP:房间鉴权、短期 TURN 凭据、质量降档、ICE restart、统计与 30 分钟稳定性测试。-- 产品化:Electron 分享端、Web/移动观看端、Windows 应用音频、硬件编码诊断和区域化 TURN。+- 当前 Browser 产品:Web、P2P/STUN 与专用 SFU/UDP,接入上限为 20;本地 20-Viewer Browser smoke 已证明控制面和容量边界,真实公网质量仍需验收。+- 可用边界:房间鉴权、自动路由、质量上限、ICE/LiveKit recovery、统计与明确的有界失败。+- 后续产品化:在当前功能和真实网络证据完成后交付公网服务器包与完全自包含的本地 Host-server 包;Native Host 是最低优先级增强。- Discord 级:原生捕获/编码引擎、多个捕获后端、GPU 零复制、进程树音频、广泛兼容与持续遥测,属于长期工程。## 竞品事实@@ -38,7 +38,7 @@| 产品 | 已公开的可靠事实 | 对本项目的含义 || --- | --- | --- || Discord Go Live | 使用 WebRTC,但媒体发往 Discord RTC Worker 后再转发给观看者;官方明确这是为了路由控制和隐藏用户 IP。桌面端有原生 C++ media engine、自研捕获/编码、多后端回退和硬件编码。 | Discord 的稳定性并不是纯 P2P 或纯浏览器免费获得的。它是未来质量上限参考,不是首版拓扑参考。 |-| TeamSpeak 6 | 官方技术回复说明用 WebRTC/ICE 做 P2P 屏幕分享;Windows 在 DX、Windows Game Capture 与传统捕获路径间选择。2026-04 官方称其 `turn.*` 主机实际仅启用 STUN,server-side SFU 仍在开发。 | 与当前目标接近,也解释了 direct-only/STUN-only 的部分可达风险;Screener 保持 direct/peer 优先,由同一 controller 为 exact edge 选择 TURN transport 或 Host-publication/SFU subscription。 |+| TeamSpeak 6 | 官方技术回复说明用 WebRTC/ICE 做 P2P 屏幕分享;Windows 在 DX、Windows Game Capture 与传统捕获路径间选择。2026-04 官方称其 `turn.*` 主机实际仅启用 STUN,server-side SFU 仍在开发。 | 与当前目标接近,也解释了 direct-only/STUN-only 的部分可达风险;Screener 保持 direct/peer 优先,并用同一 controller 选择 direct 或 Host-publication/SFU subscription。 || KOOK / Oopz | 官方 SDK 清单只足以证明屏幕分享接入声网相关能力,没有公开具体媒体拓扑。 | 可以参考交互,不能把它们写成已经证实的 P2P 或 SFU 案例。 |来源:@@ -59,9 +59,9 @@- STUN 让客户端发现公网映射并产生 server-reflexive candidate。它不承载媒体,也不能保证穿过所有 NAT。- ICE 测试 host、server-reflexive、peer-reflexive 和 relay candidates,并选择可工作的候选对。Trickle ICE 可以减少建连等待。- TURN 在无法直连时转发完整媒体流,是 NAT 组件中真正产生高带宽成本的部分。-- 当前 controller 保持健康 direct/peer UDP 边;ordinary peer 只接收 STUN。selected TURN 只替换 exact logical edge 的 transport,Host 无 direct first-level path 时可用于唯一 Host-SFU publication;server-fed Viewer 使用该 publication 的精确 SFU subscription。每个尝试都受当前 generation、端点容量、server admission 和 bounded failure 约束。+- 当前 controller 保持健康 direct/peer UDP 边;ordinary peer 只接收 STUN。direct 阶段耗尽后,server-fed Viewer 使用唯一 Host publication 的精确 SFU subscription。每个尝试都受当前 generation、端点容量、server admission 和 bounded failure 约束。-不存在适用于所有用户的权威“P2P 直连率”。CGNAT、endpoint-dependent mapping、校园/企业防火墙、移动网络、IPv6 和地区运营商都会改变结果。首版必须通过 `getStats()` 统计自己的 `host/srflx/prflx/relay` 比例,而不是引用未经验证的行业百分比。+不存在适用于所有用户的权威“P2P 直连率”。CGNAT、endpoint-dependent mapping、校园/企业防火墙、移动网络、IPv6 和地区运营商都会改变结果。真实网络验收必须分别记录 direct 的实际 `host/srflx/prflx` candidate type 与 SFU route kind,而不是引用未经验证的行业百分比。### 为什么会“有人能看,有人看不了”@@ -70,12 +70,12 @@ ICE 是按分享者与每一名观看者的网络组合独立选路,而不是当前边界如下:1. 将 direct UDP 设为最高优先级,成功者保持零媒体服务器路径。-2. Ordinary peer ICE 为 STUN-only;controller 只为已选定的 logical edge 授予 selected TURN transport,或在需要 server-fed ingress 时授权当前 Host publication 的 SFU subscription,不能用固定全局梯级代替逐 edge 决策。-3. 通过统计确认最终选中的 candidate pair;LiveKit participant TURN 与 selected-edge coturn 分别记录,不能从应用计时顺序推断路径。+2. Ordinary peer ICE 为 STUN-only;controller 在 direct 阶段耗尽后,按 server admission 授权当前 Host publication 的 SFU subscription,不能用固定全局梯级代替逐 edge 决策。+3. 通过统计确认 direct 的 selected candidate pair 或 SFU/UDP 媒体;不能从应用计时顺序推断路径。4. 网络切换或候选对失效时执行 ICE restart,超时后重建该 peer connection。-5. 在 UI 和诊断中区分“直连”“服务器中继”“正在恢复”和明确失败原因。+5. 在 UI 和诊断中区分“直连”“SFU fallback”“正在恢复”和明确失败原因。-这种混合房间里,一名观看者走 TURN/UDP 不会迫使其他观看者也中继;被中继的 WebRTC 媒体仍由端点间 DTLS-SRTP 加密。+这种混合房间里,一名观看者走 SFU/UDP 不会迫使其他观看者也进入 SFU;direct 与 SFU 路径分别保持自己的 WebRTC 安全边界。来源:@@ -118,16 +118,16 @@ IETF 对 mesh/SFU 的拓扑说明见 [RFC 7667](https://www.rfc-editor.org/rfc/r当前 source 与 production 边界:-- 生产已移除 exact-room allowlist,所有房间由 bounded peer-assisted/SFU controller 自动路由;ordinary peer 仍使用 STUN-only ICE。-- Production `9461e20` 默认允许八名观看者且只接受 1 至 16;当前 source 接受最多 20。该数值只控制接入,不代表 1:20 已通过性能验收;route release 仍需记录实际 sender、应用 CPU/内存与 SFU/TURN 用量。-- 每条 ordinary peer 链路独立使用 STUN-only ICE;只有控制器选中的 exact logical edge 或 Host-SFU ingress 才会获得短期 TURN credential。-- Exact release `9461e20` 的所有房间在 peer recovery 与 alternate parent 耗尽后可准备最多两个 SFU/UDP roots;这是已部署事实,不是当前 source 的固定 root 数。当前 source 使用一份 Host publication 和精确 Viewer subscriptions,尚未发布。+- 所有房间由 bounded peer-assisted/SFU controller 自动路由;ordinary peer 使用 STUN-only ICE。+- Current source 与 production 接受最多 20 名 Viewer。该数值只控制接入,不代表 1:20 已通过公网性能验收;真实矩阵仍需记录实际 sender、应用 CPU/内存与 SFU 用量。+- 每条 ordinary peer 链路独立使用 STUN-only ICE;direct 阶段耗尽后,同一 operation 可选择唯一 Host publication 的精确 SFU subscription。+- Current source 与 production 使用一份 Host publication 和精确 Viewer subscriptions,没有固定 SFU root 数或房间级 lease。- 桌面和手机观看者使用同一个 Web 播放端;分享者不要求朋友安装完整客户端。-当前接受的非服务器 endpoint downstream 默认值为二,并允许部署静态配置为一、二或三;分享端及 Viewer 遵守同一规则。ADR-0004 的可删除实验验证第三名及后续 Viewer 可由客户端转发;ADR-0005 定义一份 Host publication、逐 Viewer SFU subscription、exact selected TURN edge transport 与独立 server admission,当前 Browser source 已收敛为一个自动 controller。生产发布、真实 SFU/TURN、移动端和异构网络验收仍未完成;已关闭 PR #12 的显式整房 SFU 模式不再是当前方案。超过小房间上限时仍建议使用外部直播服务。观察项包括:+当前接受的非服务器 endpoint downstream 默认值为二,并允许部署静态配置为一、二或三;分享端及 Viewer 遵守同一规则。ADR-0004 的可删除实验验证第三名及后续 Viewer 可由客户端转发;ADR-0005 定义一份 Host publication、逐 Viewer SFU subscription 与独立 server admission,当前 Browser source 与 production 已收敛为一个自动 controller。真实 SFU、移动端和异构网络验收仍未完成;已关闭 PR #12 的显式整房 SFU 模式不再是当前方案。超过小房间上限时仍建议使用外部直播服务。观察项包括:- 正常工作负载持续超过实测可承载的 P2P 人数。-- 当前 logical edge 的 direct/STUN transport 失败;controller 可为同一 edge 选择 selected TURN,或在 logical ingress 需要 server-fed source 时选择当前 Host publication 的 SFU subscription。+- 当前 logical edge 的 direct/STUN transport 失败;controller 可在需要 server-fed source 时选择当前 Host publication 的 SFU subscription。- 分享者上行安全余量不足。- 分享者因 CPU/encoder 限制降质。- 产品开始要求隐藏好友之间的 IP。@@ -226,7 +226,7 @@ Google Cast `MediaInfo` 的 `contentUrl` 会被用作 media URL,缺失时 `con被当作 media URL;当前 P2P Viewer 持有的是进程内 `MediaStream`,没有可供电视 fetch的 URL。为它新增转码、HLS/Web Receiver 或私有协议会改变服务器媒体成本和安全边界,当前不做。投屏只属于-Viewer 本地播放输出;无论是否启用,现有 upstream PeerConnection、TURN/SFU/peer+Viewer 本地播放输出;无论是否启用,现有 upstream PeerConnection、SFU/peerroute、Host fanout 和其他 Viewer 均不变。未来只在浏览器发布说明或实现明确支持 live `MediaStream` wireless playback 后重开@@ -292,7 +292,7 @@ W3C TAG 的 capability URL 指南指出 URL 仍会出现在地址栏、历史、来源(访问于 2026-08-19):[RFC 3986 section 3.5](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5)、[WHATWG WebSockets](https://websockets.spec.whatwg.org/#the-websocket-interface)、[RFC 6455](https://www.rfc-editor.org/rfc/rfc6455.html)、[RFC 6750 section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3)、[W3C Referrer Policy](https://www.w3.org/TR/referrer-policy/)、[W3C TAG Capability URLs](https://www.w3.org/TR/capability-urls/)、[HTML Web Storage](https://html.spec.whatwg.org/multipage/webstorage.html)、[Web Cryptography Level 2](https://www.w3.org/TR/WebCryptoAPI/)、[Node.js Crypto](https://nodejs.org/api/crypto.html) 与 [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)。-WebRTC 媒体本身使用 DTLS-SRTP 加密,但 direct P2P 仍可能让这组可信好友看到彼此网络地址。若房间政策要求完全隐藏 endpoint IP,ordinary direct/peer 不能满足,应使用明确的中央媒体路径或拒绝该连接;selected TURN 只隐藏获授权 edge 的 direct candidate,不是全房隐私开关。+WebRTC 媒体本身使用 DTLS-SRTP 加密,但 direct P2P 仍可能让这组可信好友看到彼此网络地址。若房间政策要求完全隐藏 endpoint IP,ordinary direct/peer 不能满足,应使用明确的中央媒体路径或拒绝该连接;当前产品不提供全房隐藏 endpoint IP 的独立策略开关。## 编解码策略@@ -321,20 +321,20 @@ WebRTC 媒体本身使用 DTLS-SRTP 加密,但 direct P2P 仍可能让这组- `qualityLimitationReason` 和各原因累计时长- jitter buffer delay、decode time 和 total packet send delay-`RTCIceCandidateStats.protocol` 是内部候选传输字段;只有本地 relay candidate 的 `relayProtocol` 才能确认本端到 TURN 的实际传输。规范不向远端暴露 `relayProtocol`,所以不能从 `remoteCandidate.protocol` 推断远端 TURN 传输。当前详情以 `P2P`/`SFU fallback` 表示媒体方式,直连只显示实际 `protocol`,relay 先显示 `TURN`,仅本地 relay 再附加 `/UDP` 等实际值;candidate type 单列为候选路径,不为补齐远端字段扩展信令或遥测。W3C Stats 规定远端 candidate `address` 默认可为 `null`,浏览器也可按隐私策略过滤;诊断 UI 因此只读取当前本地 report 中由 media transport、`selectedCandidatePairId`、`localCandidateId`/`remoteCandidateId` 精确关联的地址与端口,缺失就保持未知,不解析 SDP 补值,也不上传、记录或持久化。+`RTCIceCandidateStats.protocol` 是内部候选传输字段;在通用 WebRTC 中,只有本地 relay candidate 的 `relayProtocol` 才能确认本端到 TURN 的实际传输,规范不向远端暴露该值。Screener 当前不配置 TURN,因此当前详情只以 `P2P`/`SFU fallback` 表示媒体方式,并显示浏览器对实际 current path 暴露的 `protocol` 与 candidate type;不合成 TURN 标签或补齐远端传输。W3C Stats 规定远端 candidate `address` 默认可为 `null`,浏览器也可按隐私策略过滤;诊断 UI 因此只读取当前本地 report 中由 media transport、`selectedCandidatePairId`、`localCandidateId`/`remoteCandidateId` 精确关联的地址与端口,缺失就保持未知,不解析 SDP 补值,也不上传、记录或持久化。WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件,并使用画面时间码或高速摄像机测量玻璃到玻璃延迟。60 fps 的单帧周期是 16.7 ms,端到端延迟还包含采集等待、编码、单程网络、jitter buffer、解码和显示。-建议目标:受控 direct/RTT <= 40 ms/丢包 <= 1% 时 p50 <= 150 ms、p95 <= 250 ms;区域 SFU/UDP root p95 <= 350 ms,可选 TURN 单独测量。先测量,再决定原生优化。+建议目标:受控 direct/RTT <= 40 ms/丢包 <= 1% 时 p50 <= 150 ms、p95 <= 250 ms;区域 SFU/UDP root p95 <= 350 ms。先测量,再决定原生优化。## 安全与成本防护-- WebRTC 使用 DTLS-SRTP。TURN 只能看到加密后的媒体包,但仍能看到地址、房间时序和流量元数据。+- WebRTC 使用 DTLS-SRTP;当前 SFU 在服务器上终止其两侧的 DTLS-SRTP,因此 operator 可接触媒体和流量元数据。- P2P 会让房间内双方得知网络地址。熟人首版可以接受,陌生人房间不能默认接受。-- TURN 必须使用短期凭据、速率限制、每用户/房间配额和出口告警,不能提供匿名公共 relay。+- SFU credential 必须短期、精确绑定当前授权和代次,并受独立 ingress/egress admission 约束。- site access password 控制建房/Host role 和 code-only 尝试,不能替代 room-scoped grant 或可选逐房间 Viewer 密码;`open` room code 明确不提供隐私。这些入口都不改变媒体 fanout/egress 上限。- raw Viewer grant 与 Host token 等同访问凭据:服务器当前进程只保存摘要,禁止日志/遥测/错误/Referrer/持久存储明文。显示名、room-scoped peer 后缀和 IP 诊断均不参与授权。-- 如果未来使用 SFU 且要求服务器看不到内容,再评估 SFrame/WebRTC Encoded Transform 和群组密钥管理。+- 如果未来要求 SFU operator 看不到内容,再评估 SFrame/WebRTC Encoded Transform 和群组密钥管理;当前不得宣称应用 E2EE。## 参考代码优先级@@ -345,18 +345,18 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件| [Tailchat Meeting](https://github.com/msgbyte/tailchat-meeting) | React 捕获生命周期与会议产品交互参考 | Apache-2.0,但媒体基于 mediasoup/SFU,不能作为当前 P2P 拓扑底座 | [ScreenShare.ts](https://github.com/msgbyte/tailchat-meeting/blob/master/app/src/features/ScreenShare.ts)、[media.ts](https://github.com/msgbyte/tailchat-meeting/blob/master/packages/sdk/src/client/media.ts) || [WebRTC samples](https://github.com/webrtc/samples) | 官方浏览器 API 最小示例 | BSD 风格。用于理解 API,不是产品框架 | [getDisplayMedia](https://github.com/webrtc/samples/tree/gh-pages/src/content/getusermedia/getdisplaymedia)、[peer connection examples](https://github.com/webrtc/samples/tree/gh-pages/src/content/peerconnection) || [PeerJS](https://github.com/peers/peerjs) | 快速 P2P 原型与简单信令抽象 | MIT。原型快,但产品最终可能需要直接控制 RTCPeerConnection 和统计 | [PeerJS server](https://github.com/peers/peerjs-server) |-| [coturn](https://github.com/coturn/coturn) | 当前 STUN 服务与未来 selected-edge TURN | BSD-3-Clause。STUN 当前必需,TURN 仅按异常 edge 可选 | [turnserver 文档](https://github.com/coturn/coturn/blob/master/README.turnserver)、[Docker](https://github.com/coturn/coturn/blob/master/docker/coturn/README.md) |+| [coturn](https://github.com/coturn/coturn) | 当前 STUN-only 服务 | BSD-3-Clause。当前只启用 UDP STUN,不分配媒体 relay | [turnserver 文档](https://github.com/coturn/coturn/blob/master/README.turnserver)、[Docker](https://github.com/coturn/coturn/blob/master/docker/coturn/README.md) || [Peer Calls](https://github.com/peer-calls/peer-calls) | 同一应用中的 mesh/SFU 双模式 | Apache-2.0;维护速度较慢,适合参考而非首选底座 | [mesh.go](https://github.com/peer-calls/peer-calls/blob/master/server/mesh.go)、[sfu.go](https://github.com/peer-calls/peer-calls/blob/master/server/sfu.go)、[iceauth.go](https://github.com/peer-calls/peer-calls/blob/master/server/iceauth.go) |-| [Broadcast Box](https://github.com/Glimesh/broadcast-box) | 未来专用一对多 SFU,WHIP 推流/WHEP 播放 | MIT。比会议型 SFU 更贴近单路广播 | [Broadcast.tsx](https://github.com/Glimesh/broadcast-box/blob/main/web/src/components/broadcast/Broadcast.tsx)、[simple watcher](https://github.com/Glimesh/broadcast-box/blob/main/examples/simple-watcher.html) |-| [LiveKit](https://github.com/livekit/livekit) | 生产级区域 SFU、SDK、内置 TURN、鉴权 | Apache-2.0。未来需要稳定 SFU 时的首选完整底座 | [屏幕共享](https://docs.livekit.io/transport/media/screenshare/)、[turn.go](https://github.com/livekit/livekit/blob/master/pkg/service/turn.go) |+| [Broadcast Box](https://github.com/Glimesh/broadcast-box) | 外部一对多 SFU、WHIP 推流/WHEP 播放参考 | MIT。只作单路广播研究对照,不替换当前 LiveKit route | [Broadcast.tsx](https://github.com/Glimesh/broadcast-box/blob/main/web/src/components/broadcast/Broadcast.tsx)、[simple watcher](https://github.com/Glimesh/broadcast-box/blob/main/examples/simple-watcher.html) |+| [LiveKit](https://github.com/livekit/livekit) | 当前专用 SFU、SDK 与鉴权底座 | Apache-2.0。Screener 当前只启用 LiveKit SFU/UDP;框架的其他 transport capability 不构成产品授权 | [屏幕共享](https://docs.livekit.io/transport/media/screenshare/)、[turn.go](https://github.com/livekit/livekit/blob/master/pkg/service/turn.go) || [mediasoup](https://github.com/versatica/mediasoup) | 强定制低层 SFU | ISC。自由度高,但房间、信令、鉴权、TURN 和 UI 都需自建 | [mediasoup demo](https://github.com/versatica/mediasoup-demo) || [Valve GameNetworkingSockets](https://github.com/ValveSoftware/GameNetworkingSockets) | Photon/Steam 式控制面与 P2P NAT 模型参考,不是媒体引擎 | BSD-3-Clause。其 P2P 文档同样要求信令、ICE/STUN 和 relay fallback | [README_P2P](https://github.com/ValveSoftware/GameNetworkingSockets/blob/master/README_P2P.md)、[test_p2p.cpp](https://github.com/ValveSoftware/GameNetworkingSockets/blob/master/tests/test_p2p.cpp) |不建议新项目以休眠的 `ion-sfu` 为底座。Janus 和 Galene 均可用,但分别偏底层网关和完整会议系统,不如上述项目贴合当前边界。-## 2026-08-18 实施基线复核+## Historical 2026-08-18 Implementation Baseline-进入 PoC 实现前再次核对当前官方版本和参考代码:+进入当时的 PoC 实现前曾核对以下官方版本和参考代码。TURN 条目只记录已放弃的 2026-08-18 baseline,不定义当前配置、实现或 roadmap:- 本机原 Node 20 已结束维护;当前实现基线改为 Node 24 LTS。Vite 8 要求 Node `^20.19.0 || >=22.12.0`,仓库应通过 `engines`、`.node-version` 和 CI 固定受支持运行时。- 使用 React + TypeScript 的官方 Vite SPA 模板,不引入 SSR 或全栈框架。生产环境不能使用 `vite preview`,由同一个 Node HTTP 服务提供静态构建、房间 API 与 WebSocket。@@ -387,9 +387,9 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件| 阶段 | 难度 | 预估 | 交付物 || --- | --- | --- | --- |-| 技术原型 | 低到中 | 3 至 7 个工作日 | Web 选源、逐观看者 P2P、基础信令、STUN/TURN、统计面板 |-| 可给朋友使用的 MVP | 中 | 4 至 8 周 | 私密房间、短期 TURN 凭据、质量档位、断线恢复、音频提示、测试矩阵和部署 |-| 稳定产品化 | 高 | 2 至 4 个月以上 | Electron 分享端、应用音频、硬编诊断、多地区 TURN、遥测、升级/安全/兼容处理 |+| 技术原型 | 低到中 | 3 至 7 个工作日 | Web 选源、逐观看者 P2P、基础信令、STUN、统计面板 |+| 可给朋友使用的 MVP | 中 | 4 至 8 周 | 私密房间、专用 SFU fallback、质量档位、断线恢复、音频提示、测试矩阵和部署 |+| 稳定产品化 | 高 | 2 至 4 个月以上 | 原生分享端、应用音频、硬编诊断、SFU 容量与真实网络验收、升级/安全/兼容处理 || Discord 级跨平台体验 | 很高 | 多人持续工程 | 原生 media engine、多捕获后端、GPU 零复制、广泛硬件与网络优化、SFU/E2EE |最大的未知不是信令服务,而是浏览器是否在目标 GPU 上复用硬件编码、用户真实 P2P 直连率、香港/内地/海外路由和应用音频需求。第一里程碑应是一个带完整统计的原型和真实朋友网络测试,而不是先设计大规模后端。@@ -398,7 +398,7 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件1. 首版坚持 P2P-first,但明确只服务一名 Host 加最多 20 名 Viewer;20-Viewer smoke 只验证 admission、控制面和资源上界,不把它写成任意公网画质或持续性能承诺。2. Web 先行,目标 Windows Chrome/Edge;把 1080p60 写成 best effort,同时提供降档。-3. 保留 ordinary STUN-only 配置。Controller 对 exact logical edge 先验证 direct/STUN,再按 ADR-0005 选择短期 authenticated selected TURN;需要 server-fed ingress 时复用唯一 Host publication 和精确 SFU subscription,Host-SFU ingress 本身也可经 selected TURN。coturn 只验证 credential 与 expiry,room/edge/revision 必须由应用重验。+3. 保留 ordinary STUN-only 配置。Controller 对 exact logical edge 先验证 direct/STUN;需要 server-fed ingress 时复用唯一 Host publication 和精确 SFU subscription。Screener 不配置 TURN、ICE/TCP 或媒体 TCP。4. 观看端优先做成免安装响应式 Web;分享端先 Web 验证,再按捕获/音频实测升级 Electron。5. 产品代码优先直接使用浏览器 WebRTC API;借鉴 MiroTalk BRO 和 Screego,不在许可证未定前直接 fork GPL/AGPL 代码。6. 每个非服务器端点使用部署权威 outbound capacity `C in {1,2,3}`,默认二;peer child 与 Host publication 消耗 sender slot,上游接收不计数。分配、恢复和 server admission 由 ADR-0005 统一约束,不从一次历史 fanout 测量推导产品上限。diff --git a/docs/session-handoff.md b/docs/session-handoff.mdindex 6b732295..3e5d14c3 100644--- a/docs/session-handoff.md+++ b/docs/session-handoff.md@@ -43,6 +43,16 @@ Current high-signal boundary:open/password/disabled code entry. Current source and production use thesingle `screener-v8` wire and no SQLite runtime; exact rollback artifacts areowned by the deployment document.+- The owner authorized one atomic Browser v9 Now ledger. Accepted but not yet+ implemented work includes live audio mutation, paused codec switching, typed+ Viewer presentation, Host-on-demand route diagnostics, neutral room-code denial, responsive entry controls, a+ default `1080p30` recommendation, and `480p` only as an advanced 854x480+ resolution. Production remains exact v8 release `8f5b3f1` until a later+ verified deployment; do not report any of this batch as implemented or live.+- Ordinary browser ICE owns direct reachability. Do not build port prediction,+ guessed candidates, NAT classification, TCP probes, quality scores, or+ quality-driven reparenting. Current-path quality is diagnostic; a healthy+ decoded edge remains sticky.- docs/maintenance.md owns the reusable mechanism-simplification review. SQLiteis its reference case because the bounded restart-experience loss did notjustify the persistence surface; accepting that tradeoff changed the contract,@@ -55,7 +65,7 @@ Current high-signal boundary:material. Do not merge or delete them until their unique changes, references,and reparse/junction safety are checked against current main.-First report back with: current branch/HEAD, dirty-file scope, accepted versus-implemented versus deployed room/route state, and the next authorized TODO. Then-follow the latest owner instruction without reviving stale agent or branch facts.+Follow the current ledger in order, checkpoint accepted truth before dependent+implementation, and report each verified integration/deployment boundary without+reviving stale agent or branch facts.```diff --git a/docs/status.md b/docs/status.mdindex c8e3a407..63f24c5d 100644--- a/docs/status.md+++ b/docs/status.md@@ -21,28 +21,28 @@ This is the current execution index. Git history owns completed timelines; [veri- Current source also implements explicit no-default SFU ingress/egress capacities and exact `reserved | committed | draining` accounting. The listener owner reconciles its dedicated non-auto-create LiveKit namespace before serving, creates each generation before token issuance, releases only after delete-plus-absence proof, and reclaims Host-offline generations through bounded exact-participant checks. Ordinary peer ICE is STUN-only and the sole application fallback is SFU/UDP; stale TURN environment keys fail startup.- Current source implements automatic P2P-first routing with one active upstream, an acyclic source-reachable graph, an exact prepare tuple, first-decoded-frame make-before-break, strict rollback revision, and bounded wait or failure.- One event-driven controller owns the committed graph and at most one room-serial child operation. The operation owns one deterministic candidate list/cursor, one current candidate and reservations, fact version, and one total deadline split only across direct and SFU stages. Failed candidates are operation-local; exhaustion retires invalid/overflow edges but retains healthy bootstrap media. Bounded-gap preflights resources, replans the remaining suffix, and restores a healthy retired edge through one final ordinary candidate. Admission commits synchronously before graph promotion; release uses the resource-set difference and room disposal returns all resources. One Host publication serves exact Viewer subscription handles, and actual global SFU release wakes registered waiting rooms.-- Parent selection is deterministic rather than random or score-based: hard eligibility filters, then shallowest result, remaining sender capacity, stable join order, and peer identity. When a departed Host root frees a Host slot, a new or reparable child prefers that shallower Host result over another root's free slot; healthy old edges remain sticky and the controller does not periodically rebalance the whole graph. The exact candidate child's first new decoded frame is the only application media-ready event. Moderate bitrate, FPS, or visual degradation remains with stock WebRTC/LiveKit adaptation and diagnostics; only hard connection failure or a non-paused decoded-frame stall invalidates a route edge. Quality-driven local reparenting and topology evidence are accepted research/TODO work, not current behavior.+- Parent selection is deterministic rather than random or score-based: hard eligibility filters, then shallowest result, remaining sender capacity, stable join order, and peer identity. When a departed Host root frees a Host slot, a new or reparable child prefers that shallower Host result over another root's free slot; healthy old edges remain sticky and the controller does not periodically rebalance the whole graph. The exact candidate child's first new decoded frame is the only application media-ready event. Moderate bitrate, FPS, resolution, loss, or visual degradation remains with stock WebRTC/LiveKit adaptation and diagnostics; only hard connection failure or a non-paused decoded-frame stall invalidates a route edge. Current-path stats do not authorize quality-driven reparenting.- The direct-to-SFU source passed repository typecheck, all 531 Web tests in 41 files, and client/server production builds. Focused tests cover the direct-stage wake, Host-full virtual SFU bootstrap without a premature route error, SFU reuse, and a departed-root scenario in which new demand uses the freed Host slot without moving healthy descendants. No Native/executable suite or heterogeneous-network media run was performed.- Browser initial capture and source switching already request available share audio through one shared capture boundary and visibly retain video-only sharing when no audio track is returned.-- Live 64/128/256 audio-ceiling mutation and paused-share video codec switching are accepted but not yet implemented on canonical `main`. H.264 startup blur/low-FPS reports remain an evidence-led diagnosis, not a presumed codec defect. Public-server and fully local distribution packages are later work after the functional, NAT, and real-network ledger is complete.+- Live 64/128/256 audio-ceiling mutation and paused-share video codec switching are accepted but not yet implemented on canonical `main`. Current source still defaults to `1080p60`, lacks advanced 480p, renders Viewer state from scattered free text, and carries an unused parent-edge quality-proof message. The accepted v9 cleanup changes the default to `1080p30`, adds only advanced `854x480`, introduces typed Viewer failure/route timing, and deletes that unused message; none of v9 is implemented or deployed. H.264 startup blur/low-FPS reports remain an evidence-led diagnosis, not a presumed codec defect.- Current source and production implement one process-memory RoomStore with random four-digit codes, a default 24-hour dormant lease, exact-Host resume, restart loss, local Host preference replay, independent token invitations and `open | password | disabled` code entry, and no SQLite runtime. The Host UI separates the invitation, room-code entry policy, password, grant update, and grant revoke controls.## Current Milestone-1. Release live audio-ceiling mutation and paused-share codec switching on the deployed generation/transition boundary.-2. Reproduce the H.264 startup report before any codec-specific repair, research quality-driven local reparenting, and build the strict-NAT emulator gate before any manually approved canary in an operator-owned test room.-3. Add first-frame-driven Viewer connection stages, then finish the remaining accepted functional and real-network work.+1. Build one atomic Browser v9 release: implement live audio-ceiling mutation and paused-share codec switching, then remove the unused quality-proof wire, add first-frame/typed-failure Viewer presentation and privacy-safe on-demand route diagnostics, repair room entry/UI, set the default to `1080p30`, and add `480p` only to advanced resolution. Do not deploy a protocol subset.+2. Reproduce the dated H.264/blur report and current Host background report before any mechanism change.+3. Finish standard ICE/SFU real-network acceptance. Browser port prediction, NAT classification, TCP probing, and quality-driven reparenting are outside the accepted route model.## Active Boundaries- `fix/configurable-relay-cap` is an old, incomplete draft and must not be merged as-is.- 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 entry, sharing controls, ID lifetime, storage semantics, v8 stale-client rejection, restart loss, and rollback restoration are aligned between current source and production.+- Room lifetime, authorization/storage semantics, v8 stale-client rejection, restart loss, and rollback restoration are aligned between current source and production. The room-entry presentation and responsive-control changes listed above are accepted v9 work, not current behavior.- Real SFU recovery, heterogeneous networks, mobile lifecycle, audio/A-V device behavior, and endurance/resource measurements remain external acceptance evidence, not blockers for unrelated reversible work.## Current HoldThe Browser route, SFU subscription reconciliation, two-stage deadline, direct-to-SFU transport,-and memory-room slices are deployed. There is no active P0/P1 hold; wait for the owner to select the-next TODO rather than beginning live-media, Native/executable, or broad repository cleanup.+and memory-room slices are deployed. There is no active P0/P1 hold. The owner authorized the current+Browser TODO sequence; Native/executable work and broad repository cleanup remain outside it.diff --git a/docs/todo.md b/docs/todo.mdindex ef687289..f2a137a3 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -7,22 +7,21 @@ Only items in **Now** are executable after their stated decision gate. A branch## Now1. **Switch screen-audio ceilings live.** Keep Opus fixed and serialize 64/128/256 kbps desired profile updates across every current Host, relay, and SFU audio sender. Each endpoint uses fresh `getParameters()`/`setParameters()` readback, ignores stale completions, retains media plus its prior applied value on failure, and applies the latest desired value to future edges. Do not add a remote applied-ack protocol or claim room-wide atomic convergence in this slice.-2. **Switch video codec while paused.** Serialize the change with route mutation, freeze exact current route/media bindings, hold new joins, renegotiate P2P/relay and republish SFU while paused, then verify actual codec plus decoded frames on resume. A binding invalidated by leave or hard route failure exits this proof set and waits for routing to rebuild from the final committed preference after the bounded codec transaction settles. On failure pause again and perform bounded rollback; rollback proves the prior preference was reapplied plus a newly negotiated actual codec and decoded progress, not literal equality with the old actual codec. Zero targets update only the future-edge preference. Reset `automatic` with empty codec preferences. This is a paused bounded-gap transaction; unpaused make-before-break is a later extension.-3. **Diagnose the production H.264/blur report.** Reproduce exact release `769de201f7cc` against the deployed route release on the same Host/browser/driver/game and one wired direct Viewer, changing one variable at a time. Implement a codec-specific repair only if codec/encoder evidence identifies it; otherwise fix the proven capture, sender, BWE, or lifecycle cause.+2. **Switch video codec while paused.** Serialize the change with route mutation, freeze exact current route/media bindings, hold new joins, and boundedly renegotiate P2P/relay plus republish SFU while paused. Preparation must not resume a share the user explicitly paused: after it settles, stop the deadline but retain the single room-serial codec owner as one bounded prepared record with no timer. The user's normal Resume first atomically revalidates those bindings in that owner, starts the decoded-frame proof deadline, and only then enables the source. A binding invalidated by leave or hard route failure exits this proof set and waits for routing to rebuild after the transaction settles. Preparation failure remains paused; proof failure first restores authoritative pause and performs bounded rollback preparation, whose proof waits for the user's next Resume. Rollback proves the prior preference was reapplied plus a newly negotiated actual codec and decoded progress, not literal equality with the old actual codec. No path auto-resumes. Zero targets update only the future-edge preference. Reset `automatic` with empty codec preferences. This is a paused bounded-gap transaction; unpaused make-before-break is a later extension.+3. **Diagnose the dated H.264/blur report.** Reproduce the 2026-08-19 then-production release `769de201f7cc` against current `main` on the same Host/browser/driver/game and one wired direct Viewer, changing one variable at a time. Implement a codec-specific repair only if codec/encoder evidence identifies it; otherwise fix the proven capture, sender, BWE, or lifecycle cause.4. **Diagnose desktop Host background/minimized performance.** On the same machine, dynamic scene, direct Viewer, browser, and fresh share, compare foreground, occluded, minimized, and hidden states while separately verifying actual negotiated VP8/H.264. Correlate capture settings/FPS, frames captured/encoded/sent/decoded, bitrate, `qualityLimitationReason`, encode time, browser/game CPU and GPU, and the existing local-preview pause boundary. Treat browser scheduling/throttling and codec effects as hypotheses until measured. Do not spoof page activity, add keepalive timers, or misuse Wake Lock; if current Chrome/Edge cannot preserve the accepted Host behavior through standard Web APIs, record that capability boundary before considering the packaged/native Host.-5. **Gate the strict-NAT guessed-candidate experiment.** Build only the isolated endpoint-dependent NAT emulator and browser harness first. Standard ICE must fail in the owned fixture, and every guessed candidate must remain inside the existing direct-stage share rather than extending the room operation. The capped set must pass the documented repeatability, privacy, cleanup, and total-deadline gates in stable Chrome and Firefox, while fallback remains unchanged. Only then may one manually approved, operator-owned test room run a default-off, kill-switched canary with explicit consent from both endpoints and exact room/edge/ICE-generation/deadline/aggregate-budget bounds; failure closes the candidate. Do not ship guessed candidates to ordinary rooms or infer NAT type from IP, UA, carrier, or two STUN observations.-6. **Make Viewer connection progress and failure recovery explicit.** Derive one stable stage from existing access, Host presence, route, peer/SFU, media, autoplay, recovery, and bounded-failure state. Keep the overlay until a composited current-generation frame, show `Play` only for actual autoplay rejection, preserve a still-valid old frame during recovery, and expose retry only through the bounded controller. Use one Chinese user-facing vocabulary and map server restart/room loss, Host stop, Host signaling loss with healthy media, Host crash/offline, route exhaustion, SFU admission, autoplay, and stale-client refresh to distinct actionable presentations without exposing private topology identifiers. A failed mobile page must retain privacy-safe stage/revision/code buckets for diagnostic export instead of collapsing everything into `No usable media route is available`. Measure the existing token-free SFU prewarm and route stages before adding another connection mechanism.-7. **Clarify malformed and unusable room entry without enumeration.** Reject non-four-digit input locally with a direct format message. For a well-formed code that cannot be admitted, stop automatically implying that a password is required; show one neutral result covering an unknown room, disabled code entry, wrong/absent password, or bounded admission failure, and offer an optional password retry plus the invitation-link path. Keep `open` rooms direct and do not expose room existence or code-entry policy through distinct server errors.-8. **Refine recommended quality presets.** Change the default recommended profile to the middle `1080p30` option and add one fully specified 480p preset only after its exact resolution, frame rate, and bitrate ceiling are accepted. Update capture constraints, current/future peer/relay/SFU sender settings, local preference/default selection, readback, and tests together; do not add a label that leaves old sender parameters active.-9. **Finish the room-code entry UI as one responsive control.** Preserve the invitation-link controls that are already direct, but redesign the code-only policy/password area to match the compact work surface instead of a nested form panel. Keep the `Start sharing` and `Join room` action rows at stable dimensions when disclosure content opens; prove desktop/mobile wrapping, focus, password and disabled states, and no horizontal overflow before integrating the retained UI candidate.-10. **Research quality-driven local reparenting without room-wide churn.** First measure exact child-edge decoded progress, freeze ratio, RTT, jitter, loss, received bitrate, resolution, FPS, and sender/receiver limitation evidence against the desired room profile. Compare standards/framework algorithms and primary literature for hysteresis, make-before-break handoff, application-layer multicast repair, and local cost/benefit decisions. Any accepted mechanism must be event-driven, exact-edge scoped, bounded by the existing room-serial operation, and resistant to oscillation; it must not infer parent-wide quality from one child, use a weighted room score, or periodically rebalance healthy subtrees. Separately prove the current deterministic rule: after a Host root leaves, a waiting or orphaned child prefers the newly free shallower Host slot, while already healthy descendants remain sticky. Add privacy-safe route-decision snapshots before diagnosing another live room because production currently cannot reconstruct a room such as `3793` after the fact.+5. **Remove the unused parent-edge quality-proof surface.** Delete the client reporter, protocol message, server dispatch/ack flag, benchmark sender, and tests whose only purpose is the unconsumed `parent-edge-quality-evidence` message. Keep the existing exact Viewer evidence generation/session gate used by diagnostics. Do not replace the deleted magic packet/loss thresholds with another score, probe, blacklist, or route input.+6. **Make Viewer connection progress, failure recovery, and route timing explicit.** Derive one stable stage from existing access, Host presence, route, peer/SFU, media, autoplay, recovery, and bounded-failure state. Keep the overlay until a composited current-generation frame, show `Play` only for actual autoplay rejection, preserve a still-valid old frame during recovery, and expose retry only through the bounded controller. Use one Chinese user-facing vocabulary and typed failures for server restart/room loss, Host stop, Host signaling loss with healthy media, Host crash/offline, route exhaustion, SFU admission, autoplay, and stale-client refresh without exposing private topology identifiers. A failed mobile page must retain privacy-safe stage/revision/code buckets even with zero connection metrics. When the authenticated Host downloads diagnostics, request one current route snapshot containing only each current child's latest demand, queue wait, candidate start, first decoded frame, final route, and closed outcome bucket; do not continuously push it or retain an event history. Use a 20-Viewer burst to report sample count, raw sorted durations, and nearest-rank p50/p95/max before changing the single room-serial operation or its total deadline.+7. **Clarify malformed and unusable room entry without enumeration.** Reject non-four-digit input locally with a direct format message. For a well-formed code that cannot be admitted, stop automatically implying that a password is required; show one `ROOM_ACCESS_DENIED` result covering an unknown/expired room, disabled code entry, wrong/absent password, room full, or bounded admission failure. Offer an optional password retry and tell the Viewer to use the invitation link supplied by the Host; do not imply that the server can provide one. Keep `open` rooms direct and do not expose room existence or code-entry policy through distinct errors.+8. **Refine quality selection.** Keep exactly three recommended profiles: `1080p60`, `1080p30`, and `720p30`. Change the default recommended profile to the middle `1080p30` option. Add `480p` (`854x480`) only to the advanced resolution selector; advanced frame rate and bitrate remain independently selected, and no `480p` recommended profile or preset ID is added. Update capture constraints, current/future peer/relay/SFU sender settings, the current-page initial desired state, readback, and tests together; do not persist quality selection or add a label that leaves old sender parameters active.+9. **Finish the room-code entry UI as one responsive control.** Preserve the invitation-link controls that are already direct, but redesign the code-only policy/password area to match the compact work surface instead of a nested form panel. The fixed action row contains only `Start sharing`, its divider, and `Join room`; disclosure is a following sibling and cannot participate in action-row sizing. Prove stable button rectangles, desktop/mobile wrapping, focus, password and disabled states, and no horizontal overflow before integrating the retained UI candidate.## Accepted Later RoadmapThese items are real product work, ordered after the current release boundary; they are not permission to resume an old branch wholesale.1. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari device matrices for autoplay gesture, foreground/background audio, foreground video recovery, lock/page reclamation, rotation, Wi-Fi/cellular migration, and an assigned relay's outbound-media survival or controller failover across those transitions. Preserve the same media element and current reconnect path; do not promise background video composition, background relay continuity, or unsupported lock-screen behavior.-2. **Real network acceptance.** Measure standard ICE/STUN, IPv4/IPv6, independent STUN destinations, SFU ingress/subscription, and bounded failure across representative NATs and mobile networks. Include an all-UDP-blocked case to measure the current explicit failure boundary. Browser port prediction remains experiment-only until its emulator and allowlisted-canary gates pass; raw-IP ranking and a room-wide quality score remain out of scope. Parent choice uses exact edge evidence and the accepted route controller.+2. **Real network acceptance.** Measure standard ICE/STUN, IPv4/IPv6, independent STUN destinations, SFU ingress/subscription, and bounded failure across representative NATs and mobile networks. Include an all-UDP-blocked case to measure the current explicit failure boundary. Browser pages do not predict ports, classify NATs, probe TCP reachability, or synthesize remote ICE candidates; raw-IP ranking and a room-wide quality score remain out of scope. Parent choice uses the accepted route controller, while current-path local stats and exact Viewer quality evidence remain diagnostic only.3. **Platform output only when real.** Revisit AirPlay/Cast only when a target browser and physical receiver prove the live `MediaStream` contract. System mirroring remains external; no placeholder button, custom receiver, or server transcode is scheduled.4. **Public-server one-click deployment package.** After every current functional and real-network item is settled, package the exact application, STUN/SFU, reverse proxy, secrets, health checks and rollback flow for a user-owned public server. Require real domain/TLS/firewall/capacity inputs and never ship credentials or call a partial deployment ready.5. **Fully local one-click Host-server package.** Package Windows/macOS/Linux Host capture, the exact application server and local state without requiring source, Node or any external Screener/STUN/SFU/tunnel/relay service. Preserve usable direct P2P and use the completed NAT/network evidence to maximize reachability, while reporting public-origin, gateway, NAT and firewall limits truthfully; loopback/LAN success is not universal Internet success.@@ -35,7 +34,6 @@ These items are real product work, ordered after the current release boundary; t| Deployed or retained item | Decision || --- | --- || #169 connection self-check | Keep, revise, or remove the user-facing pre-share probe. Do not extend it automatically. |-| #171 diagnostic JSON export | Confirm a support workflow or remove the extra surface. || #181 selected-pair response counter | Keep as local observation or remove; it has no route authority. || #182 signaling watchdog | Confirm Host and mobile/background session semantics before calling it complete. |@@ -45,7 +43,7 @@ These decisions are not permission to continue old branches, and current deploym- 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. The isolated strict-NAT harness authorizes no product path until its gate passes; raw-IP ranking, AirPlay/Cast receivers, and mobile background guarantees are not implied by the current implementation batch.+- 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.- Real heterogeneous-network SFU, mobile lifecycle, audio/A-V device, and endurance/resource acceptance are scheduled at the relevant release boundary.## Candidate Handlingdiff --git a/docs/verification-status.md b/docs/verification-status.mdindex c41db43c..bc8ce98a 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -35,13 +35,13 @@ Capacity and routing entries below describe the exact tested source or release o## Open Proof Boundaries-- Routing: verify current-release initial ingress, exact candidate first-frame commit and rollback, `peer-selected` expiry/failure, 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.+- Routing: verify current-release initial ingress, exact candidate first-frame commit and 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.- Relay resources: source and production expose the authenticated `1/2/3` endpoint-cap boundary, and the 20-Viewer loopback observed maximum Host and relay active-media edges of two at cap `2`. CPU/GPU/upload and heterogeneous-network measurements remain diagnostics, not authority to change the contract.- Room scale: source and production admit 20 Viewers plus one Host, and focused plus local Browser convergence evidence covers that bound. 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.- Audio: verify the 64/128/256 kbps Share settings, negotiated/observed bitrate, audible music quality, route changes, and game A/V synchronization. Bitrate settings are ceilings, not quality proof.-- Observability: the UI and local stats plumbing are deployed, including identity-bound relayed-detail retention and export freshness guards, but target-browser availability and actual values remain unverified for Host SFU sender evidence, codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, A/V playout/jitter/concealment, selected candidate endpoints, and bounded same-pair STUN-response observation. These fields diagnose and have no recovery authority; they do not by themselves prove hardware encode, synchronization quality, or route quality.+- Observability: the v8 UI and local stats/export plumbing are deployed, including identity-bound relayed-detail retention and export freshness guards, but target-browser availability and actual values remain unverified for Host SFU sender evidence, codec/fmtp and encoder implementation/power efficiency, media-source and encoded FPS, A/V playout/jitter/concealment, selected candidate endpoints, and bounded same-pair STUN-response observation. The accepted v9 Viewer stage and on-demand Host route snapshot are not implemented or deployed. All of these fields diagnose and have no recovery authority; they do not by themselves prove hardware encode, synchronization quality, or route quality.- Mobile: Android/iOS remain Viewer-only. Autoplay, rotation, iOS lock-screen/page reclamation, background reconnection, and network changes need device evidence. AirPlay/system mirroring is Viewer-local output, not a portable in-app WebRTC output contract.- Native: ADR-0006 has one-Viewer evidence only. Viewer2/FIFO, hardware diversity, endurance, downloaded-package/public-host, game A/V, and browser diversity remain open.- Access and operations: v8 production preflight/postflight, atomic environment/unit replacement, stale-v7 rejection, restart-wide room loss, password-profile creation, grant/code orthogonality, rotate/revoke, no-SQLite runtime, and exact current journal/nginx sentinel checks passed. Three historical rotated nginx access logs containing the current site secret in old `/r/...` request paths were deleted, and all remaining plain/gzip nginx logs plus Screener/LiveKit journals rescanned with zero site-secret hit. Headful same-browser preference replay and the isolated VM/IP clean-port matrix remain open; shared-IP smoke cannot approve them.diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index 90a70432..93341e03 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -2,7 +2,7 @@## 2026-08-18 14:45-状态:首个 PoC 基线及其已接受扩展的当前设计。Production 普通 peer ICE 保持 STUN-only,并已部署自动 route controller;完整 assisted-route 语义由 ADR-0005 持有,运行时迁移尚未部署。精确 deployed behavior 只由 deployment 文档记录。+状态:首个 PoC 基线及其已接受扩展的当前设计。Production 普通 peer ICE 保持 STUN-only,并已部署 ADR-0005 的完整 Browser route controller 与易失房间模型。下一 Browser v9 与 live-media mutation 已接受但尚未实现或部署;精确 deployed behavior 只由 deployment 文档记录。## 目标与边界@@ -108,7 +108,7 @@ Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-access cookie 是否有效;连接后五秒内第一条消息必须是当前单一 wire 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 site access。Viewer 消息携带 room、role、clientId,以及 exact-room Viewer grant 或当前 code-only password attempt。成功的 `authenticated` 快照始终携带部署最终值 `endpointMediaCopyCapacity: 1|2|3`;普通模式的服务端 admission 只向 Host 激活稳定加入顺序中的至多该数量 Viewer,并在离开后提升等待者,双方信令只允许 active child。Browser Host 与 Viewer 严格校验该值,房间 `maxViewers` 只约束观看者总 admission。Native/executable sender 停留在旧 wire 并在 authority 前拒绝。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。-主要消息:+下表先列 current v8 已实现消息,再以 `v9` 明示 accepted delta;实现分片可以排序,但 server 与 Browser assets 只发布一个完整 v9 wire,不存在中间协议:| 方向 | 消息 | 作用 || --- | --- | --- |@@ -122,10 +122,13 @@ WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-| viewer -> host | `answer` / `candidate` | 只能回给本房间分享者 || viewer -> host | `restart-request` | 以 `rebuild` 标志请求 ICE restart 或完整重建该 peer || host -> server | `stop-sharing` | 结束当前发布、清理本轮连接并让观看者等待;不删除房间或使邀请失效 |+| server -> viewer | `route-status` | v9 strict union 只允许 `{ revision, state: "waiting", reason: "sfu-admission" }` 或 `{ revision, state: "failed", reason: "route-exhausted" }`;只补充现有 `route-update` 无法表达的 SFU admission waiting 与 bounded route exhaustion,不携带 raw text、identity、candidate 或 retry hint |+| host -> server -> host | `request-route-diagnostic` / `route-diagnostic-snapshot` | v9 仅在 authenticated Host 点击下载诊断时请求并返回一份当前快照;不连续推送、不参与 route authority |+| host/viewer -> server | codec transition apply/proof | v9 精确绑定 share/codec generation 与 frozen media binding,独立于 `route-ready` 和 Viewer quality evidence |Zod 在服务边界拒绝未知类型、超长字符串、非法 SDP/candidate 结构和越权目标。服务端根据已认证会话决定路由:观看者不能给另一名观看者发信令,分享者也不能向本房间以外的 peerId 发送。-当前唯一 source wire 是 `screener-v8`,不做版本协商、旧 parser、双写或 translator。任何旧页面或 executable sender 的首条消息在角色进入 room lookup 前得到同一个 fatal refresh 终态并停止自动重连。缺失、过期、跨房、已 rotate 或 revoked 的当前 Viewer grant 使用同一个通用“邀请无效或已失效”结果,不区分房间不存在与凭据错误。+当前唯一 source wire 是 `screener-v8`,不做版本协商、旧 parser、双写或 translator。任何旧页面或 executable sender 的首条消息在角色进入 room lookup 前得到同一个 fatal refresh 终态并停止自动重连。缺失、过期、跨房、已 rotate 或 revoked 的当前 Viewer grant 使用同一个通用“邀请无效或已失效”结果,不区分房间不存在与凭据错误。Accepted v9 对已通过 site access 的 well-formed code-only 预期拒绝只发 `ROOM_ACCESS_DENIED`:unknown/expired room、disabled policy、absent/wrong password、room full 与其他已知有界 admission refusal 使用同一 code、公开文案和 close 行为。Grant 继续使用 `INVALID_TOKEN`,Host 鉴权保持独立,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。## WebRTC 协商@@ -153,11 +156,11 @@ Zod 在服务边界拒绝未知类型、超长字符串、非法 SDP/candidate| 1080p30 | 1920x1080、30 fps | 5 Mbps/peer || 720p30 | 1280x720、30 fps | 3 Mbps/peer |-浏览器可返回更低设置,界面以 `track.getSettings()` 显示实际捕获结果。Current source 保留有界手动质量控制:视频 track 使用 `contentHint = "motion"`,返回的音频 track 使用 `contentHint = "music"`;二者都是内容提示而不是 codec 或质量档位。三档推荐质量与折叠高级区初始值统一采用 `degradationPreference = "balanced"`,并允许显式选择 clarity-first 或 fluid。“分享高级设置”将视频设置限制为 720p/1080p/1440p、15 至 60 整数 FPS、2 至 12 Mbps、三种 degradation preference,以及 `自动 | H.264 | VP8`;同时提供离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling。音频 ceiling 可在直播中串行更新;视频 codec 首先支持在分享显式暂停时事务化切换。它们只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率、声道或硬编。+浏览器可返回更低设置,界面以 `track.getSettings()` 显示实际捕获结果。推荐区始终只有表中的三档并默认选择中档 `1080p30`;高级分辨率额外提供 `480p`(854x480)、720p、1080p 与 1440p,FPS 继续独立接受 15 至 60 整数,码率继续独立接受 2 至 12 Mbps,因此不建立第四个推荐档或 `480p` preset ID。视频 track 使用 `contentHint = "motion"`,返回的音频 track 使用 `contentHint = "music"`;二者都是内容提示而不是 codec 或质量档位。三档推荐质量与折叠高级区初始值统一采用 `degradationPreference = "balanced"`,并允许显式选择 clarity-first 或 fluid。“分享高级设置”同时提供 `自动 | H.264 | VP8` 和离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling。音频 ceiling 可在直播中串行更新;视频 codec 首先支持在分享显式暂停时事务化切换。它们只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率、声道或硬编。每次 `setParameters()` 都必须从当次 `getParameters()` 派生更新,然后读回 requested/applied `maxBitrate`、`maxFramerate`、`scaleResolutionDownBy` 和 degradation preference。浏览器负责具体降级,实际结果由 stats 观测;拒绝或浏览器改写必须进入可见状态,不能只写 `console.warn`。-Web 视频端不做视频 SDP munging。`automatic` 以空 `setCodecPreferences([])` 恢复 P2P 浏览器默认且不覆盖 LiveKit 默认 codec;显式 H.264/VP8 在首个 offer/publication 前应用,P2P 与 browser relay 仍保留完整 browser codec/repair 回退列表,SFU 始终保持 `backupCodec: false`。暂停时的 codec 切换使用单调 codec-negotiation generation,并和 route mutation 串行:冻结 exact current route/media binding target,新 join 等待、leave 从 target 移除;P2P/relay 在暂停中显式重新 offer/answer,SFU 以新 publication generation republish。恢复 source 后,每名 target 从实际 inbound RTP stats 与 decoded-frame counter 生成专用 codec-transition proof;proof 精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation 与 codec-negotiation generation,不复用 Viewer quality evidence,也不改变 route authority。leave、hard failure 或 binding generation 变化会移除该 target 并把仍在线 Viewer 置为 `route-wait`;bounded codec transaction 先以剩余 target settle 并释放 route lock,随后 controller 使用最终 committed preference 恢复该 Viewer,防止 codec/route 互等。服务端只在全部 still-current target 的 actual codec 与 decoded progress 成立后提交 desired codec。失败立即重新暂停并按旧 preference 开启有界 rollback generation;rollback 证明 P2P 空/有序 preference 或 SFU fresh publish options 已恢复,并从新协商代次取得 actual inbound codec 与 decoded progress,不要求 actual codec 与旧观测字面相同。回滚失败则保持暂停和明确错误。零 target 只更新 future-edge desired codec。该 slice 是 paused bounded-gap mutation,不声称 make-before-break;`replaceTrack()` 或暂停本身不改变 codec,未暂停热切换后续复用同一事务。实际 outbound codec/profile、encoder implementation 与 stats 是结果真相;浏览器支持 H.264 不证明命中硬编。AV1 仍不得仅凭压缩率推断默认启用。唯一获准的 Web SDP 变换是下述 Viewer answer 的 Opus stereo receive preference,不得借此扩展视频码率、codec 或通用 munging。+Web 视频端不做视频 SDP munging。`automatic` 以空 `setCodecPreferences([])` 恢复 P2P 浏览器默认且不覆盖 LiveKit 默认 codec;显式 H.264/VP8 在首个 offer/publication 前应用,P2P 与 browser relay 仍保留完整 browser codec/repair 回退列表,SFU 始终保持 `backupCodec: false`。暂停时的 codec 切换使用单调 codec-negotiation generation,并和 route mutation 串行:冻结 exact current route/media binding target,新 join 按 pause 语义等待、leave 从 target 移除;P2P/relay 在暂停中以独立总 deadline 显式重新 offer/answer,SFU 以新 publication generation republish。Preparation 成功后只停止 preparation deadline;同一个 room-serial codec mutation owner 保留一个内存有界的 prepared generation,暂停期间无 timer并排斥 route mutation,绝不擅自恢复用户主动暂停的分享。Host 的正常 Resume 动作先在该 owner 内原子重验 frozen bindings,启动 proof deadline 后才启用 source。每名 still-current target 从实际 inbound RTP stats 与 decoded-frame counter 生成专用 codec-transition proof;proof 精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation 与 codec-negotiation generation,不复用 Viewer quality evidence,也不改变 route authority。leave、hard failure 或 binding generation 变化会移除该 target并把仍在线 Viewer置为 `route-wait`;事务以剩余 target settle 后释放 owner,controller 再使用最终 committed preference 恢复该 Viewer。服务端只在全部 still-current target 的 actual codec 与 decoded progress 成立后提交 desired codec。Preparation failure 保持暂停并运行有界 old-preference rollback preparation;forward proof failure 先重新进入权威 paused,再运行 rollback preparation。Rollback prepared state 保留同一 owner且无 timer,等待用户下一次正常 Resume 后重验、启动 rollback proof deadline并启用 source;proof 证明 P2P 空/有序 preference 或 SFU fresh publish options 已恢复,并从新协商代次取得 actual inbound codec 与 decoded progress,不要求 actual codec 与旧观测字面相同。回滚失败保持暂停和明确错误,任何路径都不自动 Resume。stop/share replacement/room delete 清除 prepared state;零 target 只更新 future-edge desired codec。该 slice 是 paused bounded-gap mutation,不声称 make-before-break;`replaceTrack()` 或暂停本身不改变 codec,未暂停热切换后续复用同一事务。实际 outbound codec/profile、encoder implementation 与 stats 是结果真相;浏览器支持 H.264 不证明命中硬编。AV1 仍不得仅凭压缩率推断默认启用。唯一获准的 Web SDP 变换是下述 Viewer answer 的 Opus stereo receive preference,不得借此扩展视频码率、codec 或通用 munging。Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`autoGainControl` 和 `voiceIsolation`,并以 `channelCount: { ideal: 2 }` 偏好双声道;这是当前 Chrome/Edge Host 基线的实现契约,用于避开网页 `getDisplayMedia()` 默认的语音处理和单声道 APM 候选,不宣称跨浏览器保证,也不固定采样率。所有值都是非强制 post-selection preference;不使用 `exact`、`min` 或 `advanced`。若 `getAudioTracks()` 为空,分享者界面必须显示“当前来源没有可共享音频”。Web 端同时传入 `windowAudio: "window"` 与 `systemAudio: "include"`:窗口选项请求该窗口/应用音频,整个屏幕选项允许用户勾选系统音频;标签页使用浏览器自身的标签页音频选择。浏览器可以忽略这些约束或 picker hints,且没有对应的标准来源类型读回,因此 UI 不额外推断或标注来源。系统音频由用户显式选择,可能包含语音或通知;video-only 始终可用。@@ -169,9 +172,9 @@ Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`直播中切换质量不重新打开选源器:对当前视频 track 调用 `applyConstraints()`,再更新所有现有 sender 的参数;新加入、重建的 relay sender 和启用的 SFU publisher 使用同一权威设置。失败时保留当前分享并给出状态,不以重建整个房间补偿。临时暂停禁用当前 capture stream 的全部音视频 tracks;Host 通过当前 share generation 更新现有 `host-status`,`authenticated` 快照携带当前暂停位,Viewer 在舞台显示“分享者已暂停”。晚加入和信令重连从快照恢复,恢复、停止、新分享或会话替换清除旧状态;不得把 track mute、黑帧或网络停顿推断成主动暂停。房间与连接保持不变,恢复时重新启用同一批 tracks。-Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeerConnection` 或额外媒体边,也不产生 SFU/应用服务器出口。预览仍可能有本地合成、缩放和 GPU 显示成本;在同一动态场景对预览开/关采集 Host CPU、GPU、encode time 和实际 FPS。只有稳定收益且捕获、编码和远端画面不变时,才把直播后的默认动态预览改为静止缩略图或隐藏并允许按需展开;隐藏预览绝不停止 capture track 或 sender encode。+Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeerConnection` 或额外媒体边,也不产生 SFU/应用服务器出口。预览仍可能有本地合成、缩放和 GPU 显示成本;在同一动态场景对预览开/关采集 Host CPU、GPU、encode time 和实际 FPS。后台性能诊断必须把 Host 页面前台/遮挡/最小化、被捕获 source 前台/遮挡/最小化以及 preview 播放/暂停分成独立变量,并关联 document visibility/focus、track mute/readyState 与 capture/outbound/inbound stats。页面 timer、伪活跃和 Screen Wake Lock 都不构成屏幕捕获保活方案;若标准浏览器无法维持目标行为,应记录平台能力边界而不是制造第二套 lifecycle。只有稳定收益且捕获、编码和远端画面不变时,才把直播后的默认动态预览改为静止缩略图或隐藏并允许按需展开;隐藏预览绝不停止 capture track 或 sender encode。-部署版 `769de201f7cc` 的模糊、游戏低帧、持续 `bandwidth` 提示和 Host 刷新恢复都只作为同一 release 的用户报告。首轮复现必须在相同机器、Chrome/Edge、驱动、游戏场景和单个有线 direct Viewer 上对照该 release 与最新 `main`。生命周期实验固定 `automatic`,每个独立 affected baseline 只运行 observe、受影响 `HostPeer` rebuild、capture replace、Host reload 或 preview cycle 中一个动作;codec A/B 另以全新 Host/share/PeerConnection 会话分别请求 automatic/H.264/VP8 并校验 actual codec。质量判断只使用同一 generation 且时间重叠的 capture A、sender B、Viewer C 窗口;stats identity poll 不推进采样 accumulator,可选 encoder 字段缺失保持 unknown。若实际 codec/encoder 不变而 BWE/发送恢复,则下调 codec 根因优先级;只有编码成本异常时才进入受控 codec repair。+2026-08-19 当时生产 release `769de201f7cc` 的模糊、游戏低帧、持续 `bandwidth` 提示和 Host 刷新恢复都只作为该 release 的用户报告;当前生产已是 `8f5b3f1`。首轮复现必须在相同机器、Chrome/Edge、驱动、游戏场景和单个有线 direct Viewer 上对照该历史 release 与最新 `main`。生命周期实验固定 `automatic`,每个独立 affected baseline 只运行 observe、受影响 `HostPeer` rebuild、capture replace、Host reload 或 preview cycle 中一个动作;codec A/B 另以全新 Host/share/PeerConnection 会话分别请求 automatic/H.264/VP8 并校验 actual codec。质量判断只使用同一 generation 且时间重叠的 capture A、sender B、Viewer C 窗口;stats identity poll 不推进采样 accumulator,可选 encoder 字段缺失保持 unknown。若实际 codec/encoder 不变而 BWE/发送恢复,则下调 codec 根因优先级;只有编码成本异常时才进入受控 codec repair。`track.getSettings()` 中存在的 EC/NS/AGC/voice-isolation、`channelCount` 和 `sampleRate` 只能作为当前捕获观测;缺失字段保持未知,Opus 协商仍是独立事实。每个 Web Host 或浏览器 relay 的实际音频 sender 在首次绑定和换源后通过标准 `RTCRtpSender.setParameters()` 请求并读回当前 64/128/256 kbps ceiling;这只是上限,浏览器 WebRTC 拥塞控制仍可降低实际流量,不新增应用层音频降级器。128 kbps 保持默认,因为 RFC 7587 将 20 ms full-band stereo music 的建议区间列为 64--128 kbps,pinned LiveKit 2.22.0 也把 128 kbps 命名为 `musicHighQualityStereo`;256 kbps 是用户显式选择的较高上限,不是质量保证。Peer answer 声明 `stereo=1;maxaveragebitrate=256000`,让同一接收协商覆盖所有三档,实际 sender ceiling 仍由所选档位约束;普通 PC synthetic 不用于标定参数、听感或性能。@@ -267,6 +270,8 @@ media-proof 和 bounded-recovery 不变量的 scoped code 与 tests。每两秒在本地采集一次 `getStats()`。首版不上传原始统计。折叠详情可在产生该连接的本机显示 selected local/remote candidate 的 `address`/`port`,但浏览器未暴露时保持未知;地址不得进入信令、Viewer C、日志、诊断导出、持久化或路由/质量决策。在 peer 边中它只是当前连接端点,在 SFU 边中通常是 SFU 端点,不能标成参与者的权威公网 IP。+v9 在 authenticated Host 点击下载诊断时发送一次 `request-route-diagnostic`;服务端当场返回严格 Host-only 的 `route-diagnostic-snapshot`,不连续推送。每个 current child 只保留 latest demand timestamp、operation/candidate start、first-frame/final outcome;新的 route demand 覆盖该 child 的旧 record,confirmed departure 与 room delete 立即删除,且不增加 timer、事件环或第二张 graph。`queueWaitMs` 只从同一个 current demand 到其 room-serial operation start计算;没有权威 demand timestamp 就是 `null`。Serializer 为本次导出分配 snapshot-local opaque ordinal,用它表达 current parent/SFU 关系、effective capacity、child count、current operation reason/stage/cursor/candidate count与相对 timing;`finalRoute` 只允许 `direct | sfu | waiting | failed`,`rejectionBucket` 只允许 `none | stale | endpoint-capacity | sfu-admission | candidate-failed | first-frame-timeout | operation-deadline | aborted`。Ordinal 不是身份或稳定 ID。Snapshot 不包含 room code、display name、真实 peer/session/connection/generation、地址、URL、SDP、token、raw error或 planner 曾过滤的 parent,不形成路由输入或前台第二套状态。Viewer 的 schema v2 只携带自身 stage、粗粒度 revision、typed failure、signal/Host state、route kind 与 current-frame proof,即使 connection list为空也可下载;未鉴权 `ROOM_ACCESS_DENIED` 分支只含 stage/code,不含 Host、route、revision或timing。+Host 与 relay Viewer 复用同一个纯 presentation reducer 保存远端 `ViewerQualityEvidence`。代际 identity 是 exact route identity(room/share、viewer/parent、assignment/connection、route revision 和当前可用的 media-binding generation,及适用时 publication generation);只有同 identity 且 sequence 严格递增才可承接旧字段,其他输入从新 evidence 重建。每个非空 metric 保存自己的本地观测时间并在五秒边界清空,页面 timer 总是指向最早边界;整块详情不因某个采样缺字段而卸载。`new`/`connecting`/`disconnected` 保留同 identity shell 但立即标为非 fresh,`failed`/`closed` 或 route identity 变化清空。任何依赖当前状态的消费者只读取 fresh presentation;该层不新增 wire 字段或服务端 route authority。质量诊断必须能按顺序区分:捕获源设置、sender 实际参数、CPU 或带宽 `qualityLimitationReason`、当前 peer/SFU 路径、outbound 与 inbound 差异,以及接收端 dropped/freeze。当前有界实现显示 sender 参数的 requested/applied 读回;同一个非 `none` 原生 `qualityLimitationReason` 连续出现三个采样周期后显示单条原因提示,原因变化、缺失或恢复为 `none` 即重新计数。这只是去抖后的观察,不组合评分、不触发调档或迁移。完整跨路径分类仍由后续真实矩阵验收;首轮使用浏览器 WebRTC internals 导出和一份脱敏 run manifest,不新增服务端遥测。@@ -287,20 +292,29 @@ Host 与 relay Viewer 复用同一个纯 presentation reducer 保存远端 `View首屏就是工具,不做营销页。视觉采用中性深灰工作台,绿色表示 direct、琥珀色表示 relay/警告、红色表示失败,避免单一蓝紫色主题;浏览器 favicon 复用页头 `MonitorUp` 的深绿底、绿色显示器和上行箭头语言。-- 访问入口:未鉴权根路径、`/join` 和 code-only `/r/{code}` 显示“站点访问”与“站点口令”,未知路径只显示“无法访问”。有效 `/r/{code}#v={grant}` 直接进入;其余 Viewer 通过 site access 后按 `open/password/disabled` 直接进入、看到“加入房间 / 房间密码”或得到中性拒绝。已有有效 site-access cookie 不重复显示整站验证;站点口令和房间密码不共享输入值或授权状态。无效、过期、错误密码或满员只显示通用拒绝,不泄露房间存在性或 policy。-- 分享者根页面:顶部显示“{分享者显示名} 的屏幕”和房间状态,并在标题旁显示可单独复制的紧凑四位房间号;Viewer 同一位置显示权威 Host 名称,不再在标题下重复。主区域保持稳定的 16:9 舞台。未发布、已停止或可恢复错误状态时,舞台内以同等尺寸和权重显示“开始分享”和“加入房间”,中间只用“或”与分隔线表达发送/接收;前者直接开始现有分享流程,后者作为 disclosure 在当前舞台内、紧邻触发按钮就地展开共享的房间码表单,提交后才导航到 `/r/{code}`。按钮同步 `aria-expanded`/`aria-controls`,展开后输入获得焦点,DOM 与焦点顺序保持触发器后接表单;窄屏允许表单换到动作行下方,不产生横向滚动。不增加首页、向导或拓扑选择。直播时舞台显示本地预览及独立全屏图标,底部保留停止、同步暂停音视频、质量档位,以及职责分离的“复制邀请链接”“复制房间号”“房间号加入:开放/密码/关闭”“更新邀请”“撤销邀请”控制;熟悉动作使用 lucide 图标、直接标签和 tooltip,不用一个含糊的“分享”菜单混装。主分享动作始终复制含 grant 的邀请链接。页面失焦仅暂停本地 video element,并在舞台提示“本地预览已暂停,分享仍在继续”;媒体暂停则禁用 capture stream 轨道,两者都保留现有连接。-- `/join`:保留为可直接访问的回退入口,并复用同一个四位房间码表单;通过 site access 后输入 `1000..9999` 并进入 `/r/{code}`,后续行为由房间 code-only policy 决定。+- 访问入口:未鉴权根路径、`/join` 和合法 code-only `/r/{code}` 显示“站点访问”与“站点口令”;malformed `/r/...` 直接显示房间号必须是 `1000..9999` 四位数字,其他未知路径只显示“无法访问”。有效 `/r/{code}#v={grant}` 直接进入;其余 Viewer 通过 site access 后以 code-only 方式进入或得到同一个 `ROOM_ACCESS_DENIED`。well-formed code 被拒绝时默认不展开密码、不暗示房间存在或需要密码,只提供“输入房间密码”动作并提示“使用分享者提供的邀请链接”;产品不向服务器索取链接。已有有效 site-access cookie 不重复显示整站验证;站点口令和房间密码不共享输入值或授权状态。+- 分享者根页面:顶部显示“{分享者显示名} 的屏幕”和房间状态,并在标题旁显示可单独复制的紧凑四位房间号;Viewer 同一位置显示权威 Host 名称,不再在标题下重复。主区域保持稳定的 16:9 舞台。未发布、已停止或可恢复错误状态时,舞台内以同等尺寸和权重显示“开始分享”和“加入房间”,中间只用“或”与分隔线表达发送/接收;固定 action row 只能包含这两个按钮及分隔,disclosure 是紧随其后的 sibling,不得参与 action-row track sizing。前者直接开始现有分享流程,后者在当前舞台内展开共享的房间码表单,提交后才导航到 `/r/{code}`。按钮同步 `aria-expanded`/`aria-controls`,展开后输入获得焦点,DOM 与焦点顺序保持触发器后接表单;窄屏允许 disclosure 自己换行,不改变两个 action 的矩形或产生横向滚动。不增加首页、向导或拓扑选择。直播时舞台显示本地预览及独立全屏图标,底部保留停止、同步暂停音视频、质量档位,以及职责分离的“复制邀请链接”“复制房间号”“房间号加入:开放/密码/关闭”“更新邀请”“撤销邀请”控制;熟悉动作使用 lucide 图标、直接标签和 tooltip,不用一个含糊的“分享”菜单混装。主分享动作始终复制含 grant 的邀请链接。页面失焦仅暂停本地 video element,并在舞台提示“本地预览已暂停,分享仍在继续”;媒体暂停则禁用 capture stream 轨道,两者都保留现有连接。+- `/join`:保留为可直接访问的回退入口,并复用同一个四位房间码表单;一个纯 route parser 返回 `host | join | viewer | malformed-room | unknown`,只把精确 `/r/{1000..9999}` 当成 Viewer route。输入保留用户原文,`inputMode="numeric"` 只提示软键盘,提交时由共享 schema 拒绝而不是 `trim`、删除非数字或接受 Unicode 数字。通过 site access 后输入合法 code 并进入 `/r/{code}`,后续行为由 code-only admission 决定。- `/r/{code}` 观看者:首次解析合法 fragment grant 后立即清理地址栏并直达;仅有 code 时先通过 site access,再按 `open/password/disabled` policy 进入。鉴权后主区域最大化远端视频,标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制;Host 主动暂停时复用视频舞台遮罩显示“分享者已暂停”,恢复后立即移除。视频舞台用单一派生 presentation reducer 合成 access、Host presence、route prepare/active、peer/SFU connection、remote track、首个 composited frame、autoplay rejection 和 bounded failure。支持时用 `requestVideoFrameCallback()` 确认第一帧已提交,旧浏览器回退到当前代 decoded-frame delta 与 video readiness;`playing`、track object 或 ICE `connected` 单独都不足以结束占位层。连接阶段占用固定布局且不显示虚假百分比,播放按钮只处理实际 autoplay rejection,失败重试只调用现有有界 controller 入口。- 首帧观察绑定当前 assignment/connection/media-binding generation 以及适用的 publication generation;`srcObject` 或 route identity 变化立即使旧回调和旧 decoded baseline 失效,迟到回调不能把新路线标成已播放。- 移动端:视频保持稳定宽高比,控制与状态移到视频下方,任何文字和按钮不得溢出或遮挡。两端默认显示紧凑在线 roster;Viewer 端复用同一权威 participant snapshot,只列出当前 Viewer(含本机)并在新 snapshot 到达时整体替换,停止分享仅移除已离线 Host,鉴权失效、房间关闭或页面卸载则清空。Host 与 Viewer 的本机显示名在界面中统一标为“昵称”,默认只读,铅笔按钮紧贴昵称并只切换当前控件的输入、保存和取消,唯一名称仅显示名称,重名时才追加 room-scoped `peerId` 短后缀。一个不持久化的“显示连接详情”复选框按页展开媒体方式、传输协议、候选路径、浏览器实际暴露的本地/远端候选地址、codec、RTT、RTP 丢包率、编解码耗时及逐边统计;地址与端口只从当前页面 `RTCPeerConnection.getStats()` 精确关联的 selected pair 读取,浏览器隐藏或缺失任一字段就不显示,且不进入质量证据、信令、服务端、日志或持久化。真实连接失败、音频缺失、持续画质受限和需要用户动作的告警始终可见。显示名/roster 不进入 access credential 或服务器持久状态。-用户可见的非直播状态使用稳定、真实的阶段词:分享端使用“已停止分享”;观看端使用“等待开始分享”“正在分配线路”“正在建立 P2P”“正在连接备用线路”“正在接收画面”“需要点击播放”“正在恢复连接”或明确失败。阶段只描述当前用户可感知动作,不暴露房间寿命、媒体代次、parent identity 或内部迁移步骤。`room-closed` 显示“房间已关闭”或“房间已过期”,不得误写成“分享已结束”。+用户可见的非直播状态使用稳定、真实的阶段词:分享端使用“已停止分享”;观看端使用“等待开始分享”“正在分配线路”“正在建立 P2P”“正在连接备用线路”“正在接收画面”“需要点击播放”“正在恢复连接”或明确失败。阶段只描述当前用户可感知动作,不暴露房间寿命、媒体代次、parent identity 或内部迁移步骤。`room-closed` 显示“房间已关闭”或“房间已过期”,不得误写成“分享已结束”。服务端 raw `message` 永不直接渲染;单一纯 reducer 按下表优先级把 typed current-generation fact 派生为文案、遮罩、保留画面和动作,较旧 revision/generation 输入直接丢弃:++| 优先级 | 权威输入 | 展示与动作 |+| ---: | --- | --- |+| 1 | stale client、room closed/expired/lost、`ROOM_ACCESS_DENIED` | 阻塞终态;只显示对应刷新、可选密码或使用 Host 邀请的动作,不显示 route retry |+| 2 | Host authoritative pause | 保留仍属于 current binding 的最后画面并显示“分享者已暂停”;等待 Host,不显示 retry |+| 3 | 同一 current media identity 的 `play()` 仅因 `NotAllowedError` 被拒绝 | 不要求先有 frame proof,立即显示唯一主动作 `Play`;点击后播放成功只清除 autoplay block,仍须等 current-generation frame proof 才撤遮罩,其他播放异常使用 typed failure |+| 4 | current binding 已有 composited frame | 去掉阻塞层;若 signaling 恢复中但媒体仍健康,只显示非阻塞提示且不清空画面 |+| 5 | route terminal failure、Host stopped/offline | 只有仍 current 且已证明的旧画面可保留;否则阻塞。仅 route/controller 明确允许时显示 bounded retry |+| 6 | SFU capacity wait、peer/SFU prepare、已绑定但未证明首帧、尚无 assignment | 依次显示备用线路等待、建立线路、接收画面或分配线路;无 `Play`、无虚假百分比 |Token-free SFU standby prewarm 保持可选且不创建 participant、publication、subscription 或 route authority。它只提前加载 pinned SDK 并调用官方 `prepareConnection()`;是否缩短公网首帧由阶段时间戳验证,失败时继续既有冷路径。-按钮使用 `lucide-react` 图标并提供可访问名称和 tooltip。动态状态区域固定最小尺寸,避免连接状态变化导致布局跳动。320、375 与 390 CSS px 下两个首屏动作仍须同排等宽、文字不溢出且触控高度至少 44 px;展开详情不遮挡视频或引入横向滚动。+按钮使用 `lucide-react` 图标并提供可访问名称和 tooltip。动态状态区域固定最小尺寸,避免连接状态变化导致布局跳动。在 1440、1024、780、520、390、375 与 320 CSS px 下,closed/open/validation-error 三种 disclosure 状态的两个首屏 action 都须同排等宽、触控高度至少 44 px且前后 `getBoundingClientRect()` 尺寸不变;输入获得焦点,文字不溢出,详情不遮挡视频且 `scrollWidth <= clientWidth`。观看端使用原生 `range` 展示 `0%` 至 `100%`,并把归一化值直接写入当前 `<video>.volume`;它不进入 WebRTC sender、信令、房间状态或 `localStorage`。React 页面状态跨 `srcObject` 替换、换父和 ICE 恢复保留;页面刷新后恢复默认值。静音按钮只切换本地 `muted`,并保留上次非零音量;拖到零自动静音,从零调高或直接取消静音时恢复可听状态。该控件不作为音频码率、声道、采样率或来源隔离设置。@@ -322,12 +336,13 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio- RoomStore 的四位空闲码随机分配/释放、活动分享免过期、dormant lease/续租、Host token/Viewer grant 摘要验证、`open/password/disabled` 正交 policy、grant 到期/跨房拒绝、rotate/revoke 强撤销、Viewer 上限和超额拒绝;- 进程重启后 room state 全空、旧 Host/grant/password fail closed、释放号码复用时旧 grant 仍失败;`ROOM_LEASE_SECONDS` 的默认/边界与 `MAX_ROOMS <= 9000` 校验,已删除的 `ROOM_DATABASE_PATH`/`ROOM_TTL_SECONDS` fail-fast;- STUN UDP URL 严格校验、生产 STUN 必需、LiveKit tuple 完整性/TTL/secret 独立性、当前 route/session/revision/connection generation guard,以及 ordinary peer、未授权房间和 Native 的 STUN-only isolation;LiveKit `sfu-config` 保持独立边界;-- 单一 `screener-v8` 信令 literal、任意旧客户端 mismatch 的一次性刷新终态,以及协议非法 JSON、未知消息、错误方向、跨房间目标和 payload 限制;+- 下一不兼容实现 checkpoint 的单一 `screener-v9` 信令 literal、任意旧客户端 mismatch 的一次性刷新终态,以及协议非法 JSON、未知消息、错误方向、跨房间目标和 payload 限制;v9 原子删除无消费者的 parent-edge quality proof,加入 paused codec transaction proof、`ROOM_ACCESS_DENIED`、typed Viewer route failure 与 Host-only 按需脱敏 route snapshot,不保留 v8 parser、writer 或别名;`qualityProfileIdSchema` 保持三档不变,只有 `qualityResolutionSchema` 增加 `480p`,`DEFAULT_QUALITY_SETTINGS` 改为 1080p30;- 质量协议的 host 授权、严格字段与数值范围、last-wins、当前/未来 relay、已配置 SFU 和普通 P2P wire 兼容;sender 的四字段 requested/applied 读回、拒绝与持续受限提示;screen audio SDP helper 覆盖 CRLF、existing/missing fmtp、unknown key preservation、幂等、payload number、rejected/non-audio,以及 empty/no-Opus/ambiguous/parser 异常原对象 fallback,`ViewerPeer` 覆盖 initial/restart/rebuild 时同一结果的 local/signaling 一致性,SFU publisher 精确断言 high-quality stereo/forceStereo/DTX 且不覆盖 RED;-- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 `open/password/disabled`。覆盖原子创建 profile、同浏览器重建偏好、fragment/sessionStorage/replaceState、无 site access 的 code-only 统一拒绝、通过 site access 后的 open/password/disabled 行为、raw grant/密码不进入 URL/日志/服务端持久状态,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;+- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 `open/password/disabled`。覆盖原子创建 profile、同浏览器重建偏好、fragment/sessionStorage/replaceState、无 site access 的 code-only 统一拒绝、unknown/expired/disabled/wrong-or-absent-password/full code-only 使用完全相同的 `ROOM_ACCESS_DENIED` code/文案/close、grant 与 Host 的独立错误、raw grant/密码不进入 URL/日志/服务端持久状态,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;- 客户端策略与 stats 解析:会话替换不重连,ordinary ICE 与 LiveKit protocol 分离;- route planner property tests:候选输入乱序仍产生相同 list,健康边 sticky,硬过滤拒绝 stale/cycle/effective-capacity/unadmitted parent,优先结果深度和剩余容量并稳定打破平局;失败候选清理后 cursor 前进且总 deadline 不重置;-- Viewer stage reducer:peer/SFU prepare、remote track 无首帧、首个 composited frame、autoplay rejection、恢复和 bounded failure 不互相冒充,动态状态不改变布局或 route authority;+- Viewer stage reducer:按上表覆盖 access/Host/queue、peer/SFU prepare、remote track 无首帧、首个 composited frame、autoplay rejection、健康媒体上的 signaling recovery、Host stop/offline 和 bounded failure;stale revision不能覆盖 current frame,raw server message不能进入 UI,零连接失败仍可导出 allowlisted stage/revision/code bucket;+- route parser 覆盖 `/r/`、三位/五位、`0000`、ASCII 字母、Unicode 数字、额外 path segment、合法 query/hash 与 exact `1000..9999`,且 malformed 输入不发起鉴权;Host-only diagnostic request 拒绝 Viewer,schema 拒绝额外/raw/private 字段,departure/room delete清除 latest timing,zero-connection Viewer export仍成立;- TypeScript 类型检查、Vite production build 和仓库 hygiene。人工矩阵:@@ -335,10 +350,9 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio- 同机双标签页与同 LAN direct;- 真实跨网络、同房间 direct/peer UDP + SFU/UDP root;- CGNAT、双 NAT、移动热点和普通家宽下按 accepted route model 验证 direct/peer、SFU/UDP、恢复和 bounded failure;记录 RSS/CPU/latency 与 RX/TX/loss。人为封锁全部 UDP 时仍必须有界明确失败。旧 production release 留在独立实例作为回滚,不在同进程保留旧 transport;-- guessed-candidate 只先在 owned endpoint-dependent NAT emulator 中运行 ordinary-ICE failure 与 bounded-candidate A/B;没有通过双浏览器重复性、首帧 deadline、privacy 和 cleanup gate 时不得进入任何 production room,通过后也只在一个人工批准的 operator-owned test room 运行一次 canary,并要求双方 endpoint 显式同意、default-off kill switch 以及 exact room/edge/ICE-generation/deadline/aggregate-budget 约束;- Windows Chrome/Edge 的 tab/window/monitor 音轨有/无、同时语音通话和 video-only;一个可区分左右声道的 fixture 只验证 Web P2P 与 SFU 的 channel correctness、协商 fmtp 和 route switch 后持久 `MediaStream`,不做听感/性能标定;Windows 11 原生候选另测 game process tree、通知、无渲染流与进程重启,Windows 10 记录明确不支持/未解决;- Android Chrome 与 iOS Safari 的播放手势、旋转、前后台和网络切换;-- 一名分享者、20 名观看者先运行 bounded smoke,记录路由深度、首帧、sender 数、应用 CPU/内存和 SFU 用量;端点 `C=1/2/3` 分开解释。30 分钟异构公网 endurance 仍是后续质量证据,不阻止已经有界失败的 20-Viewer admission。+- 一名分享者、20 名观看者先运行 bounded smoke,记录路由深度、queue wait、candidate start、first decoded frame、final route、sender 数、应用 CPU/内存和 SFU 用量,并报告 current-child sample/pending count、原始排序时长与 nearest-rank p50/p95/max;端点 `C=1/2/3` 分开解释。未接受产品体验上限前不把观测值变成新的 magic timeout。30 分钟异构公网 endurance 仍是后续质量证据,不阻止已经有界失败的 20-Viewer admission。- 真实桌面 Chrome 对 balanced 与 clarity 做控制传播和连接身份 smoke;该项只证明直播中应用与不重建,不代替清晰度、负载或公网矩阵。真实矩阵未完成前,状态文档必须把这些列为待验证,而不是把设计目标写成产品能力。@@ -350,12 +364,13 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio3. 完成屏幕捕获、逐观看者 PeerConnection、观看播放和手动质量档。4. 完成连接恢复和 stats 面板,并保持 ordinary peer 的 STUN-only snapshot。5. 在 endpoint cap/accounting 与 SFU lifecycle 边界上,以单一 Browser wire 完成 route controller convergence:一个 event-driven reconcile 和一个 room-serial candidate 统一处理 deterministic allocation、child reparent 和 relay drain;该 wave 独立可回滚。-6. 路由边界合入后依次落 live screen-audio ceiling 和 paused video-codec transaction;随后做 H.264 根因诊断与 strict-NAT emulator gate,门禁通过才允许 allowlisted canary。-7. 加入 first-frame-driven Viewer connection stages;随后把房间收敛为四位随机码、易失租约、正交 code/grant access 和本地 Host creation profile,并原子删除 SQLite 双模式。-8. 当前发布只验收 Web Host、Viewer 和 browser relay。Native sender、capture helper 与 shared-encode executable 排在整体 roadmap 最后,不参与当前构建、路由验收或发布。-9. 当前功能、NAT 与真实网络 TODO 完成后,再分别设计和交付公网服务器一键部署包与完全不依赖外部服务的本地 Host-server 包。+6. 已部署路由与易失房间边界保持不变;在同一个尚未部署的 Browser v9 checkpoint 中依次实现 live screen-audio ceiling 和 paused video-codec transaction。+7. 在该 checkpoint 中删除未消费的 parent-edge quality proof,加入 first-frame-driven Viewer stage/typed failure、按需脱敏 route timing、无枚举房间准入结果,并把默认推荐档改为 1080p30、只在高级分辨率增加 480p;全部 v9 protocol source 一起原子部署,不发布中间 wire 子集。+8. 对 H.264/模糊与 Host 后台性能只做受控根因诊断;标准 ICE/SFU 按真实异构网络验收,不增加 guessed candidate、NAT classifier、TCP probe 或 quality-driven reparent。+9. 当前发布只验收 Web Host、Viewer 和 browser relay。Native sender、capture helper 与 shared-encode executable 排在整体 roadmap 最后,不参与当前构建、路由验收或发布。+10. 当前功能与真实网络 TODO 完成后,再分别设计和交付公网服务器一键部署包与完全不依赖外部服务的本地 Host-server 包。-生产当前运行 `screener-v8` room/route release `8f5b3f1`。内部不兼容 wire/schema 原子切换,Git commit 与部署备份承担回滚,不保留兼容实现。+生产当前运行 `screener-v8` room/route release `8f5b3f1`;上述 v9 是 accepted design,尚未实现或部署。内部不兼容 wire/schema 原子切换,Git commit 与部署备份承担回滚,不保留兼容实现。任何一步只实现当前消费者需要的接口。不得为未来账号、第三种媒体拓扑或原生 sender 预建抽象层。diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index e5d113a5..51050cad 100644--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"@@ -26,13 +26,13 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- 一对多观看:每个房间允许一名 Host 和最多 `20` 名 authenticated Viewer;房间 admission 与端点下游容量、SFU admission 分别配置,超额加入必须明确拒绝。观看人数不从 endpoint cap 推导,20-Viewer smoke 只证明控制面与资源上界,不是任意网络质量声明。- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。服务端在每次 `authenticated` 权威快照中返回最终 `endpointMediaCopyCapacity`;普通非 peer-assisted 模式也只授权稳定加入顺序中的至多 `C` 个 Host child,超额 Viewer 保持入房等待并在槽位释放后提升,信令不能绕过该集合。Browser Host 与 Viewer 严格校验该值并用它约束稳态 assignment;并行产生媒体的 candidate 必须持有唯一 `TransitionOverlapSlot`,active+pending 物理 copy 只可达到 `min(C + 1, 3)` 并在 commit/abort 后释放。`C=3` 满载时必须先收到 active bounded-gap retirement 再 prepare,绝不产生第四份 copy。SFU subscriber egress 由独立 server admission 记账。当前不兼容房间合同以单一 release 原子升级;缺失/非法 cap、旧 wire 与 executable sender都在取得room/route authority前fail closed。- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。Host 已满且首次需要 SFU 时,同一 reconcile 将 affected Host direct child(若无则稳定顺序中最新的 connected Host direct child)作为本次 child operation,创建唯一 Host publication 并把该 child 变为首个 SFU subscriber,subtree 不动;publication 取代释放的 Host peer slot,下一次扫描再处理原受限 Viewer,不建立 bootstrap 状态机。-- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的完整顺序只有保持或尝试 direct/STUN peers,再复用或建立 direct-ingress Host publication/SFU subscription。Screener 不配置 TURN、ICE/TCP、media TCP 或 TLS-relayed media;当前 LiveKit 也保持 UDP-only。未来若真实严格防火墙矩阵证明需要另一种传输,必须把它作为 LiveKit 内部能力重新决策,不能增加第三种应用 route candidate。LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target;HTTPS/WSS 继续独立使用 TLS/TCP。-- 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接;视频 codec 首个可交付切换边界是在分享已显式暂停时执行有界重协商,未暂停热切换是后续复用同一事务的扩展。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。+- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。浏览器 ICE connectivity checks 是 direct UDP 可达性的权威;Screener 不合成 remote candidate、不预测端口、不分类 NAT,也不使用 TCP 探测推断 UDP 媒体可达性。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,direct 阶段耗尽后在同一 operation deadline 内进入 SFU/UDP,全部可用路径耗尽后明确等待或失败。已接受的完整顺序只有保持或尝试 direct/STUN peers,再复用或建立 direct-ingress Host publication/SFU subscription。Screener 不配置 TURN、ICE/TCP、media TCP 或 TLS-relayed media;当前 LiveKit 也保持 UDP-only。未来若真实严格防火墙矩阵证明需要另一种传输,必须把它作为 LiveKit 内部能力重新决策,不能增加第三种应用 route candidate。LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target;HTTPS/WSS 继续独立使用 TLS/TCP。+- 质量控制:推荐档位始终只有 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档,默认选择中档 `1080p30`。高级设置的分辨率选项增加 `480p`(854x480),其 FPS 与码率仍由高级控件独立选择;不增加 `480p` 推荐档、preset ID 或固定的 480p FPS/码率组合。三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接;视频 codec 首个可交付切换边界是在分享已显式暂停时执行有界重协商,未暂停热切换是后续复用同一事务的扩展。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先使用 pinned LiveKit 的标准两层 screen-share simulcast,让内建 per-subscriber BWE 独立降层和恢复,Screener 不实现媒体层 selector。应用只诊断实际接收层、硬件编码、游戏性能、资源和上传;SFU 自动降层不改变拓扑。`LOW` 停编只是资源优化,active representation/layer 硬上限为二且不随 viewer 增长。当前 Web P2P simulcast 与 Web/LiveKit SVC 不能证明跨 direct/peer 共享编码或可移植硬件路径;全部标准路径失败后才考虑 custom/native dual encode。-- 路由失效输入:应用不推断 parent-wide 质量,也不计算综合分数。当前 authenticated child 只在 PeerConnection `failed/closed`,或非权威暂停时现有 periodic stats 在统一 deadline 内没有新 decoded frame 时,使自己的 exact edge 失效并唤醒同一个 reconcile。decoded progress 只保存 route-keyed `lastDecodedAt`,route/connection变化或新帧重置、暂停抑制,同一 edge只报告一次,不增加轮询器。该 operation 把失败的 `parent + transport` tuple 在当前 fact version 直接视为已尝试,先选择其他 direct parent;同一 parent 只有换用另一 transport 时才可在本次继续,新的外部事实才允许原 tuple 重新进入。Track availability、低码率、低 FPS、模糊、sender/viewer stats 与 SFU layer只用于stock WebRTC/LiveKit恢复和诊断。relay自身ingress失效时,它作为child换父并保留subtree;disconnect或effective downstream capacity降低只让direct/overflow children逐个走同一事务。+- 路由失效输入:应用不推断 parent-wide 质量,也不计算综合分数。当前 authenticated child 只在 PeerConnection `failed/closed`,或非权威暂停时现有 periodic stats 在统一 deadline 内没有新 decoded frame 时,使自己的 exact edge 失效并唤醒同一个 reconcile。decoded progress 只保存 route-keyed `lastDecodedAt`,route/connection变化或新帧重置、暂停抑制,同一 edge只报告一次,不增加轮询器。该 operation 把失败的 exact direct parent 在当前 fact version 直接视为已尝试,先选择其他 direct parent,再进入有界 SFU suffix;新的外部事实才允许原 direct tuple 重新进入。Track availability、低码率、低 FPS、模糊、sender/viewer stats 与 SFU layer只用于stock WebRTC/LiveKit恢复和诊断。relay自身ingress失效时,它作为child换父并保留subtree;disconnect或effective downstream capacity降低只让direct/overflow children逐个走同一事务。- 断线恢复:临时网络变化先交给 WebRTC/LiveKit 的 ICE、consent、重连和流状态。Direct edge 可在 exact current parent/child sessions 内采用 framework rebuild 的新 connection ID而不改变topology。应用只在上述exact edge失效后运行一次有界reconcile;任一步成功即停止。候选耗尽时hard-invalid、confirmed-departed或overflow edge被退休并进入明确waiting,healthy bootstrap edge保留。所有异步结果受authenticated session、share generation、base/pending route revision与candidate connection identity约束,未受影响分支保持sticky。权威暂停abort未提交candidate、保留active graph、抑制stall,并在resume后重新reconcile。-- 同一 operation 的一个总 deadline 只按实际存在的 `direct | sfu` 语义阶段等分,不配置每个 candidate 的 magic timeout。阶段内的硬失败继续推进 cursor;silent ICE 到达 direct 阶段边界时跳过剩余 direct tuple,必须把派生份额留给 SFU。任何 strict-NAT guessed candidate 以后也只能处于 direct 阶段,不能延长总 deadline。-- 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、RTP 丢包率、抖动、码率、帧率、编码耗时和受限原因。候选与错误的 wire、日志和导出只使用[低服务器成本媒体路由](./research/low-server-media-routes.md)的脱敏字段和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText` 或网络标识。只有创建该 `RTCPeerConnection` 的本机可在折叠详情中显示浏览器对 selected local/remote candidate 实际暴露的地址与端口;该值不上传、不持久化、不用于地理/NAT 推断,缺失或被隐私保护时显示未知。+- 同一 operation 的一个总 deadline 只按实际存在的 `direct | sfu` 语义阶段等分,不配置每个 candidate 的 magic timeout。阶段内的硬失败继续推进 cursor;silent ICE 到达 direct 阶段边界时跳过剩余 direct tuple,必须把派生份额留给 SFU。20 名 Viewer 同时加入时,每名 child 的 operation deadline 不会被人数除分,但单一 room-serial operation 可能形成线性排队尾延迟;在接受另一种并发模型前,只测量 queue wait、candidate start、first decoded frame 与 final route 的 p50/p95/max,不用 NAT 猜测、TCP probe 或 magic timeout 绕过排队。+- 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、RTP 丢包率、抖动、码率、帧率、编码耗时和受限原因。候选、route decision、队列时序与错误的 wire、日志和导出使用封闭 schema 和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText`、真实 peer/parent/session/connection identity 或网络标识。失败前没有 connection metrics 的 Viewer 仍可导出自身 stage、粗粒度 revision bucket 和 typed failure code;未鉴权 access denial 只导出 stage 与 `ROOM_ACCESS_DENIED`。只有 authenticated Host 点击下载诊断时才向服务端请求一份当前 route snapshot:每次导出使用 snapshot-local opaque ordinal 表达当前 parent 关系,只携带当前 operation 与每个 current child 的 latest demand、queue/candidate/first-frame timing 和 closed outcome enum。Ordinal 不是身份或稳定 ID;服务端不连续推送、不保留事件环或第二张权威图,confirmed departure 与 room delete 立即清除对应 timing。只有创建该 `RTCPeerConnection` 的本机可在折叠详情中显示浏览器对 selected local/remote candidate 实际暴露的地址与端口;该值不上传、不持久化、不用于地理/NAT 推断,缺失或被隐私保护时显示未知。- 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;Host 的 Viewer 卡片只把本机连接或当前接收证据称为“已连接”,其余状态保持中性的“线路分配中”或具体连接状态,不把 active assignment 当作连接成功。展开连接详情也只在当前媒体证据成立后显示媒体方式:direct peer使用绿色`P2P`,SFU使用黄色`SFU fallback`。尚未连接时不预告 P2P、SFU 或未知 ICE,只保留中性状态。Host/Peer 上下游仍只在独立的权威拓扑视图中展示。传输协议、候选路径、RTT、视频/音频 RTP 区间丢包率、实际编解码器、音频区间码率/jitter 和视频编码耗时等技术详情由一个明确的“显示连接详情”开关展开。远端 Viewer evidence 的详情 shell 在同一 viewer/parent/connection/route identity 内保持稳定;非空字段从各自最后一次实际观测起精确保留五秒,`connecting`/`disconnected` 只降为非 fresh,`failed`/`closed`、identity/session/share/route 变化或非单调 sequence 则清空/换代。非 fresh evidence 不得继续证明“已连接”或被其他 current-state 消费者使用。音频 codec MIME、RTP clock、channels 与 fmtp 只能来自当前 RTP 对象引用的 `RTCCodecStats`,缺失即未知;`opus/48000/2` 不得写成 48 kHz 音源或实际立体声。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限或需要用户操作的告警。- 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}` 和 `/join` 必须先持有效站点 cookie,之后才检查 `open | password | disabled` code-only policy。失败统一且不得泄露房间是否存在或 policy;建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、JWT、服务端 session Map 或通用 logout。- 房间级观看授权:新房间总是生成含 256-bit 随机量、限时且可撤销的 room-scoped Viewer grant;服务端内存只保存完整 grant 的 SHA-256 摘要。到期阻止以后鉴权/重连,但不为已鉴权 Viewer 设置踢出定时器;即时清退使用 rotate/revoke。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续。code-only 入口独立采用 `open | password | disabled`,默认 `open` 且无房间密码;所有 code-only 尝试先通过站点访问。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可独立 rotate/revoke grant 或改变 code-only policy;授权变化必须先提交新的内存代次,再清除 Viewer grace/路由、终止旧代次信令和媒体并断开受影响 Viewer。@@ -42,11 +42,11 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- 公网服务器一键部署包:在用户自有的公网服务器上一键部署当前 Web/信令应用、易失房间状态和所需 STUN/SFU/反向代理组件,复用唯一配置、secret、路由、健康检查和回滚合同。它不是托管服务,不能内置真实凭据或跳过域名、TLS、防火墙、端口、容量和回滚预检。- 本地自包含一键包:提供 Windows、macOS 和 Linux 可分发的桌面包,在分享者电脑上同时运行 Host、当前 Web/信令应用服务器和本地状态,朋友继续通过普通浏览器邀请观看。安装后启动不要求源码 checkout、Node 或任何外部 Screener、STUN、SFU、隧道或 relay 服务;它尽力使用本机可达入口和 direct P2P,但必须明确报告公网入口、可信 HTTPS/WSS、网关映射或 NAT 路径缺失,不能承诺任意 CGNAT/严格防火墙必通。两种分发包都排在当前功能、路由、NAT 和真实网络 TODO 完成之后。-- 独立房间入口:合法 `/r/{code}#v={grant}` 邀请直接进入对应房间;没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,再按房间 `open | password | disabled` policy 直接进入、要求房间密码或中性拒绝。有效 site-access cookie 只跳过第一步,两类密码不得复用或互相替代。Host 可设置、轮换或移除房间观看密码;密码接受 1 至 64 个可见 ASCII 字符,异步 scrypt 全局最多执行 2 个、等待 16 个派生。Host 可把房间密码保存在同源本地创建偏好中;它不得进入 URL、cookie、日志或服务端持久存储。不存在、错误密码、队满和正确密码后的满房都返回通用结果。+- 独立房间入口:合法 `/r/{code}#v={grant}` 邀请直接进入对应房间;没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,再提交 code-only 尝试。`open` 且可准入时直接进入;其余预期拒绝统一为 `ROOM_ACCESS_DENIED`,不得先披露 `password | disabled` policy。有效 site-access cookie 只跳过第一步,两类密码不得复用或互相替代。Host 可设置、轮换或移除房间观看密码;密码接受 1 至 64 个可见 ASCII 字符,异步 scrypt 全局最多执行 2 个、等待 16 个派生。Host 可把房间密码保存在同源本地创建偏好中;它不得进入 URL、cookie、日志或服务端持久存储。未知或过期房间、disabled policy、缺失/错误密码、队满和其他已知有界 admission refusal 都返回相同 code、公开文案和 close 行为。- 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,每个房间使用一个服务端 route controller,独占 committed graph、一个 pending child operation 和 event-driven reconcile。运行时只增加一个串行pump、一个operation deadline timer与typed resource lifecycle task,不维护另一份graph。operation持有candidate list/cursor、一个current candidate/资源预留、fact version和一个总deadline。committed graph必须无环、source-reachable,且每名Viewer同时至多一个active upstream。加入、容量变化、节点离开、exact edge `failed/closed`,以及非暂停decoded-frame stall都只唤醒同一个reconcile;其余健康分支保持sticky。候选按当前身份、source reachability、无环、effective capacity与sender transition硬过滤,再按结果深度、剩余sender slots、稳定加入顺序和peer identity排序;因此 Host root退出后新释放的Host槽位比已有root的更深槽位优先,但健康旧边不因周期性平衡而迁移。server admission在执行当前cursor时独立reserve。candidate child首帧ready触发`settleReady(commitAdmissionSync)`,成功prepare `P`提交active `P`;失败释放资源并用同一monotonic allocator广播`R>P` rollback,cursor推进但总deadline不重置。bounded-gap先preflight server resource,再retire producer、按新graph重算未尝试suffix,并在切断healthy edge时追加一个普通restore candidate。relay自身ingress失效时作为child换父并保留subtree;relay disconnect/cap降低让overflow children逐个走同一事务,childless后删除。房间admission和无环约束最大深度,不设独立hard cap。普通peer始终STUN-only,SFU使用独立admission。-- 观看端连接反馈:Viewer 舞台从鉴权到首帧使用一个由现有权威状态推导的稳定阶段反馈,至少区分等待分享、分配线路、建立 P2P、连接备用线路、等待首帧、浏览器阻止自动播放、恢复连接和有界失败。阶段不是进度百分比,也不产生 route authority;只有当前 video element 实际提交首帧后才显示正在播放。播放按钮只在 `play()` 因自动播放策略被拒绝时稳定出现,连接中不得忽隐忽现;明确失败后才提供一次受现有 controller 约束的重试入口。make-before-break 或仍有可见旧帧时保留画面并叠加恢复状态,不为显示反馈主动清空健康 media element。-- 质量控制扩展:推荐档位仍是默认入口;“分享高级设置”只允许 720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好、`自动 | H.264 | VP8` 编码选择,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;初始值采用 `balanced`、`automatic` 与 128 kbps。视频档位和音频档位在直播中显式应用;音频变更只更新固定 Opus 路径的 sender ceiling,不是 codec 切换。所有当前及以后建立的 Web Host、Browser relay 与 SFU sender 都读取最新 desired 档位,并各自在 fresh sender parameters 上应用和读回 endpoint-local applied 值;实际码率仍由浏览器拥塞控制和 stats 决定。Peer 只在唯一明确的 active Opus audio 上做结构化、幂等的 Viewer answer `stereo=1;maxaveragebitrate=256000` 变换,使同一接收上限覆盖三档;非目标形态或 parser/writer 异常必须原样保留浏览器 answer,不得阻断可继续的 mono/video edge。不得用宽泛字符串/正则改 SDP,也不得改写浏览器协商的 FEC。SFU 将三档映射到 pinned SDK 的 music stereo preset 或显式 256 kbps ceiling,统一保留 `forceStereo = true`、`dtx = false` 与 pinned room default `red = true`。不得暴露任意码率、声道、采样率、audio codec、stereo、DTX、RED 或 FEC 控件;256 kbps 只是显式较高上限,不是无损、高保真或最低码率保证。实际质量持续低于所选上限时必须显示可解释的限制原因;在真实拥塞、编码器和接收端证据完成前,不把任一组合称为“完美平衡”。未来 microphone voice 若进入范围,必须是独立 track/处理链,不能把 AEC/降噪/DTX 套到电影或游戏音频。+- 观看端连接反馈:Viewer 舞台从鉴权到首帧使用一个由现有权威状态推导的稳定阶段反馈,至少区分等待分享、分配线路、建立 P2P、连接备用线路、等待首帧、浏览器阻止自动播放、恢复连接和有界失败。阶段不是进度百分比,也不产生 route authority;只有当前 video element 实际提交首帧后才显示正在播放。播放按钮只在 `play()` 因自动播放策略被拒绝时稳定出现,连接中不得忽隐忽现;明确失败后才提供一次受现有 controller 约束的重试入口。make-before-break 或仍有可见旧帧时保留画面并叠加恢复状态,不为显示反馈主动清空健康 media element。Accepted v9 的服务端补充消息是 strict、current-revision-fenced `route-status` union,且只允许 `waiting/sfu-admission` 与 `failed/route-exhausted` 两种配对;它不携带 raw text、身份、candidate 或 retry hint,prepare/active、access、Host、signal、media 与 autoplay 继续由各自权威输入派生。+- 质量控制扩展:推荐档位仍是默认入口且只保留 1080p60/1080p30/720p30 三档,当前页面初始 desired state 选择 1080p30 且不写 `localStorage`;“分享高级设置”允许 480p(854x480)/720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好、`自动 | H.264 | VP8` 编码选择,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;480p 不形成推荐档或固定 FPS/码率组合,初始值采用 `balanced`、`automatic` 与 128 kbps。视频档位和音频档位在直播中显式应用;音频变更只更新固定 Opus 路径的 sender ceiling,不是 codec 切换。所有当前及以后建立的 Web Host、Browser relay 与 SFU sender 都读取最新 desired 档位,并各自在 fresh sender parameters 上应用和读回 endpoint-local applied 值;实际码率仍由浏览器拥塞控制和 stats 决定。Peer 只在唯一明确的 active Opus audio 上做结构化、幂等的 Viewer answer `stereo=1;maxaveragebitrate=256000` 变换,使同一接收上限覆盖三档;非目标形态或 parser/writer 异常必须原样保留浏览器 answer,不得阻断可继续的 mono/video edge。不得用宽泛字符串/正则改 SDP,也不得改写浏览器协商的 FEC。SFU 将三档映射到 pinned SDK 的 music stereo preset 或显式 256 kbps ceiling,统一保留 `forceStereo = true`、`dtx = false` 与 pinned room default `red = true`。不得暴露任意码率、声道、采样率、audio codec、stereo、DTX、RED 或 FEC 控件;256 kbps 只是显式较高上限,不是无损、高保真或最低码率保证。实际质量持续低于所选上限时必须显示可解释的限制原因;在真实拥塞、编码器和接收端证据完成前,不把任一组合称为“完美平衡”。未来 microphone voice 若进入范围,必须是独立 track/处理链,不能把 AEC/降噪/DTX 套到电影或游戏音频。- SFU 质量设置生命周期:直播中修改档位时,浏览器 sender 的 applied readback、LiveKit `LocalVideoTrack` 保存的 degradation preference、track restart options 与 `LocalTrackPublication` 的 republish options 必须作为同一次串行操作更新;任一步失败恢复旧 sender 与旧 SDK 保存态,旧 publication generation 不得回写当前状态。LiveKit full reconnect/republish 不得恢复初次发布的旧偏好。该修复不改变 codec、码率上限、层数或路由,也不能单独解释即时低帧。- 本地预览性能候选:在相同动态场景中 A/B 测量 Host 动态预览开/关的 CPU、GPU、encode time 和实际 FPS。只有稳定收益且捕获、编码和远端画面不受影响时,才允许直播开始后默认显示静止缩略图或隐藏动态预览并提供按需展开;未测前不宣称收益。- Peer-assisted 媒体路径:所有非服务器 endpoint 都受同一个服务端权威稳态 outbound media-copy capacity 约束,默认 `2` 且可静态配置为 `1`、`2` 或 `3`;peer child 与 Host publication 都按实际发送副本计数。每名 Viewer 任一时刻只有一个 active upstream,活动媒体图保持无环;只在离散事件中做有界分配或换父。浏览器把收到的标准 remote track 加入独立下游 `RTCPeerConnection` 时会逐跳解码并分别重编码,必须测量而不能称为 shared encode。服务端只在有界房间内存中保存严格校验的质量设置,不写入持久存储。@@ -58,7 +58,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。- Windows 应用音频:Windows 11 Native sender 使用本地 opaque window target 绑定 HWND、PID 与进程创建时间,只捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。- 受限网络边界:当前媒体只使用 ordinary direct/STUN UDP 与 LiveKit SFU/UDP;全 UDP 封锁、只允许标准 HTTPS 出站等网络在有界窗口后明确失败。不得用 TCP 探测、客户端声称的 NAT 类型或另一套应用 route candidate 猜测可达性。若真实矩阵证明该失败边界需要扩展,先比较 LiveKit 内建 ICE/TCP 或其内部安全 relay transport,并另行接受安全、端口、延迟和部署合同。-- Web 编码选择:分享高级设置提供 `自动 | H.264 | VP8`,默认自动使用浏览器/LiveKit 协商;首次分享前直接应用,分享中只在 Host 已显式暂停后允许切换。暂停切换与 route mutation 串行,使用 generation-fenced P2P/relay 重协商和 SFU republish;恢复播放后才以实际 codec 与 decoded-frame progress 验证,失败重新暂停并有界回滚。P2P/浏览器 relay 保留完整 repair 与其他 codec 回退列表,SFU 保持 `backupCodec = false`,不维护第二套应用编码链。实际 codec/profile、encoder implementation 与 stats 是结果真相;H.264 可选不等于浏览器必走硬编,AV1 仍不得仅凭压缩率推断默认启用。+- Web 编码选择:分享高级设置提供 `自动 | H.264 | VP8`,默认自动使用浏览器/LiveKit 协商;首次分享前直接应用,分享中只在 Host 已显式暂停后允许切换。暂停切换与 route mutation 串行,使用 generation-fenced P2P/relay 重协商和 SFU republish;preparation 不得自动恢复用户暂停,只有用户正常 Resume 后才以实际 codec 与 decoded-frame progress 验证,失败保持暂停并有界回滚。P2P/浏览器 relay 保留完整 repair 与其他 codec 回退列表,SFU 保持 `backupCodec = false`,不维护第二套应用编码链。实际 codec/profile、encoder implementation 与 stats 是结果真相;H.264 可选不等于浏览器必走硬编,AV1 仍不得仅凭压缩率推断默认启用。### P2 - 可选功能@@ -101,8 +101,8 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given 应用以 production 模式启动但 `SITE_ACCESS_PASSWORD` 缺失,或配置仍提供已删除的 `ACCESS_PASSWORD`、`ROOM_DATABASE_PATH`、`ROOM_TTL_SECONDS`,When 应用启动,Then 配置校验明确失败,而不是兼容旧 gate、旧持久化模式或公开建房。- Given production site access secret 短于 8 bytes、长于 128 bytes 或含非可见 ASCII,When 新 release 启动,Then 必须 fail-fast。Given 同一来源连续提交错误 secret,When 超过 deployment `limit_req` 的 `5r/m`、`burst=5 nodelay` 边界,Then nginx 返回不含凭据的通用限频结果;允许请求的错误值仍使用常量时间比较和统一鉴权失败,limiter 只使用 nginx 内存且不新增 IP 持久化/日志字段。- Given 新建房间,When 服务端返回邀请并由 Host/Viewer 客户端读取,Then grant 含 256-bit 随机量、只授权该房间 Viewer、只在该页面会话的 room-scoped `sessionStorage` 留存,并在首次读取后从地址栏移除;HTTP request-target、WebSocket URL、Referrer、cookie、`localStorage`、服务端持久存储、日志和错误均不包含 grant。-- Given 默认新房,When 已通过站点访问的 Viewer 只输入四位房间码,Then 无房间密码即可在现有 Viewer/连接/egress 上限内加入,同时 Host 的主分享动作仍复制独立的 token-bearing link。Given code-only policy 为 `password` 或 `disabled`,Then 分别要求正确房间密码或中性拒绝;grant 路径保持独立。-- Given Viewer 只有 site access cookie、另一个房间的 grant、缺失/过期 grant 且 code-only policy 不允许,或自行把 role 改为 Host,When 首条信令鉴权到达,Then 返回同一通用无效结果且不泄露房间存在性;不能建房、发布、跨房或绕过 Host token。+- Given 本地输入不是 `1000..9999` 的四位房间码,When 用户提交或直接访问 malformed `/r/...`,Then 客户端保留原输入并直接提示“四位数字”,不发起房间鉴权、不静默删除字符。Given 默认新房,When 已通过站点访问的 Viewer 只输入合法房间码,Then 无房间密码即可在现有 Viewer/连接/egress 上限内加入,同时 Host 的主分享动作仍复制独立的 token-bearing link。+- Given 已通过 site access 的 well-formed code-only 尝试对应未知/过期房间、disabled policy、缺失/错误密码、满房或其他已知有界 admission refusal,When 首条信令鉴权到达,Then 服务端返回唯一 v9 `ROOM_ACCESS_DENIED`,同一公开文案和 close 行为不得泄露房间存在性或 policy;UI 不自动断言“需要密码”,只允许可选密码重试并提示使用 Host 提供的邀请链接,不向服务器索取链接。Given grant 无效,Then 继续使用通用 `INVALID_TOKEN`;Host 鉴权保持独立错误,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。Given Viewer 持另一个房间的 grant、缺失/过期 grant 或自行把 role 改为 Host,Then 不能建房、发布、跨房或绕过 Host token。- Given Host rotate/revoke Viewer grant,When 新内存摘要和 authorization generation 提交,Then 服务端清除 Viewer grace/路由,命令 Viewer 关闭接收 PC/媒体并让每个 Host/relay/SFU upstream owner 关闭对应旧代次媒体边,最后关闭旧 Viewer socket;rotate 返回一次新 grant,revoke 锁定 grant 路径,code-only policy 保持独立。- Given Host 同源本地偏好保存了 `open | password | disabled` 和可选房间密码,When 服务器重启后该 Host 下一次显式开始分享,Then 客户端清除失效 ownership、创建新四位房间并原子重放偏好;新的 Host token 和 grant 替换旧值。Given 换浏览器、换设备或清理站点数据,Then 不恢复这些偏好或所有权。- Given 应用进程重启,When 旧 Host、Viewer 或 code-only 链接再次访问,Then 所有旧房间、租约、摘要、密码 verifier 和参与者均已丢弃并 fail closed;运行时不读取数据库、迁移旧 schema 或恢复旧号码。@@ -118,7 +118,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given 新路线正在准备,When exact candidate child 尚未解码出第一帧新画面,Then 可用旧路线保持权威;首帧后只原子提交该 candidate,失败或统一 deadline 到期销毁候选并保留或恢复旧路线。- Given 所有 direct 与 SFU 媒体路径耗尽,When 有界连接窗口结束,Then 界面显示通用等待或连接失败,不静默黑屏、不长时间假连接,也不尝试未授权路径。SFU 的精确 path order 和 resource accounting 按 ADR-0005 验证。- Given 同一 committed graph 和候选集合以不同枚举顺序输入 controller,When 新 Viewer 加入或 exact failed edge 触发换父,Then 硬过滤结果相同,选择稳定落到最浅且分配后剩余容量最多的合格 parent,并以加入顺序和 peer identity 打破平局;健康 current edge 不因出现更优候选而迁移。Given 第一候选 ICE 或首帧失败,Then controller 先幂等清理该候选再尝试下一候选,且不会启动 all-pairs probe;若候选创建了受管 SFU room,其 server capacity 在删除并证明 room 不存在前仍计费。-- Given owned endpoint-dependent NAT emulator 中 ordinary ICE 可重复失败,When isolated guessed-candidate harness 运行,Then 只有满足[低服务器成本媒体路由](./research/low-server-media-routes.md)的 candidate budget、双浏览器重复性、首帧 deadline、隐私和 cleanup gate 才可继续。门禁前 ordinary room 不接收 guessed candidate;门禁后也只允许一个人工批准的 operator-owned test room,在双方 endpoint 显式同意、default-off kill switch 以及 exact room/edge/ICE-generation/deadline/aggregate-budget 约束下运行 canary。任何失败都关闭该候选并保留现有 SFU fallback。+- Given 任意 ordinary Browser direct edge,When 浏览器 ICE checks 成功或 direct 阶段耗尽,Then 应用分别采用该实际可达 peer path 或在同一总 deadline 内进入 SFU/UDP;不得合成 remote candidate、预测端口、上报 NAT 类型或用 TCP 可达性替代 UDP ICE 结果。Given 所有 UDP 均被阻止,Then direct 与 SFU 都在有界窗口内结束并显示明确失败。### 浏览器与移动端观看@@ -135,8 +135,8 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Browser Host 或任一 Browser Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,角色、浏览器和 UA 不改变 `C`;每个 `authenticated` 快照都携带同一个 `C`,并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。When 当前房间合同上线,Then server 与 Browser assets 在同一 release 原子升级,缺失或越界的 `C`、旧 wire 与 executable sender 都在房间授权前得到明确 mismatch,且 `C=3` 满载 Host 在取得会产生第四份 endpoint media copy 的 publication/token 前明确等待或失败。- Given peer-assisted 路径分别运行 1、5、10、20 名观看者,When 用户加入、容量释放、节点离开、重鉴权或当前 edge 失效,Then 服务端只为新 Viewer、等待 Viewer 或失去 parent 的 subtree root 选择一个 active parent;每名 Viewer 同时至多一个 active upstream,活动图无环,其余健康边保持 sticky。没有可用 parent 时明确等待或拒绝,不主动重平衡或引入常驻多源媒体。-- Given 一个 Host root 退出并释放 Host sender slot,When 新 Viewer 加入或一个失父 child 进入同一 reconcile,Then 候选按结果深度优先,选择 Host 而不是另一 root 的更深空槽;已健康挂在另一 root 下的旧 child 不被周期性搬动。Given 需要判断历史房间为何形成某一拓扑,Then 只使用脱敏、代次绑定的 route-decision snapshot,不从当前拓扑反推已经丢失的事件。-- Given 一名分享者和 20 名观看者,When 运行 bounded browser smoke,Then 全部 Viewer 取得明确媒体或 bounded wait/failure,非服务器端点不超过 `C`,并记录 route depth、首帧时间、实际 sender 数、应用服务器 CPU/内存以及 SFU 用量。该 smoke 验证 admission、控制面效能和资源上界,不单独证明任意公网画质或 30 分钟 endurance。+- Given 一个 Host root 退出并释放 Host sender slot,When 新 Viewer 加入或一个失父 child 进入同一 reconcile,Then 候选按结果深度优先,选择 Host 而不是另一 root 的更深空槽;已健康挂在另一 root 下的旧 child 不被周期性搬动。Given authenticated Host 点击下载诊断,Then 服务端按需生成一份 current route snapshot,用 snapshot-local opaque ordinal 表达当前 parent 关系,并只包含 current operation reason/stage/cursor、每个 current child 的 latest demand/queue/candidate/first-frame timing 与封闭 outcome enum;该 ordinal 不是稳定身份,snapshot 不反推丢失事件、不记录 planner 过滤过的 parent、不包含 raw identity/address/error,也不参与 route。Given Viewer 请求房间级 snapshot,Then 服务端拒绝。+- Given 一名分享者和 20 名观看者,When 运行 bounded browser smoke,Then 全部 Viewer 取得明确媒体或 bounded wait/failure,非服务器端点不超过 `C`,并记录 route depth、首帧时间、实际 sender 数、应用服务器 CPU/内存以及 SFU 用量。诊断汇总报告 20 个 current-child 样本数、pending 数、每项原始排序时长和 nearest-rank p50/p95/max,不设通过阈值;confirmed departure 和 room delete 后对应 timing 必须消失。该 smoke 验证 admission、控制面效能和资源上界,不单独证明任意公网画质或 30 分钟 endurance。- Given candidate 改变房间 admission 默认值或上限,When 在目标数量与代表性路径上运行规定时长并注入 relay departure、重连和一个弱路径,Then 每名观看者持续解码、每个非服务器端点不超过配置容量、深度与故障半径有界、未受影响 subtree 不迁移,并记录端点与中央服务的 CPU、GPU、内存、上行、出口、帧率、丢包率、冻结和恢复;任一门槛失败时不得切换默认值。- Given peer-assisted host 鉴权或直播中连续修改质量设置,When 服务端校验其分辨率、FPS、码率和偏好,Then 只有 host 的完整有界设置被接受,last-wins 地应用到当前和以后建立的 relay child sender 以及启用的 SFU publisher;越界、缺字段和多余字段被拒绝,普通 P2P 的鉴权 wire 不新增该字段且不接受同步消息。- Given 标准浏览器把收到的 remote track 直接加入下游 `RTCPeerConnection`,When 检查 relay 统计和 libwebrtc 路径,Then 明确记录新的 outbound encoder、编码耗时和 CPU/GPU 限制,不把它当作 encoded forwarding 或 shared encode 成果。@@ -151,14 +151,14 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given 用户选择任一推荐档位或高级质量参数,When 接收端实际分辨率、帧率或码率持续显著低于该目标,Then 诊断数据能区分采集约束、发送编码、带宽/拥塞、当前 peer/SFU 路径和接收端限制;产品不得只改变档位标签却继续隐藏实际降级。- Given 一个健康 SFU leaf 和一个受控弱 SFU leaf 都以 `HIGH` ceiling 订阅,When 内建 LiveKit BWE 运行,Then 弱 leaf 自动使用唯一共享 `LOW` 并在恢复后回到 `HIGH`,健康 leaf 不受影响,且 Screener 没有实现媒体层 selector;direct/peer 继续使用各自的 stock WebRTC GCC。- Given 当前 Viewer 的 exact edge 进入 `failed/closed`,或在非权威暂停时超过统一 deadline 没有新 decoded frame,When 服务端确认 authenticated child、share generation、active revision 与 connection identity 仍匹配,Then 只把该 child 送入同一个 reserve/prepare/first-frame/commit-or-abort 事务;低码率、低 FPS、模糊和 SFU layer 只进入诊断。-- Given 当前 edge 仍在解码但分辨率、FPS、码率、freeze ratio、RTT、jitter、loss 或 limitation evidence 持续影响观感,When 评估是否自动换父,Then 当前产品只诊断而不迁移。任何后续质量驱动机制必须先用标准/框架算法与论文证据定义 exact-child 的可比较收益、最小观测窗、hysteresis/cooldown、旧边首帧前保留和最大尝试预算;不得把一个 child 的弱路径推断为 parent-wide 质量、定期重排健康 subtree 或用不透明全房加权分数。+- Given 当前 edge 仍在解码但分辨率、FPS、码率、freeze ratio、RTT、jitter、loss 或 limitation evidence 持续影响观感,When 评估是否自动换父,Then 当前产品只诊断而不迁移:现有路径证据不能证明未连接 parent 的反事实质量,WebRTC/LiveKit 继续拥有拥塞适应,应用不建立 alternative-parent probe、hysteresis/cooldown、加权分数或周期性重排。- Given 同一 Viewer 同时是某人的 child 和其他人的 parent,When 自身 ingress 失效,Then 它作为 child 换父、在新 ingress 首帧提交前保留可用旧 edge,并保持 subtree。Given endpoint disconnect 或 `effectiveDownstreamCapacity` 降低,Then controller 只保留稳定顺序内可容纳的 children,并将 deterministic overflow children 逐个送入同一事务;childless 后删除 disconnected relay。-- Given 当前分享权威 paused,When 新 Viewer 加入、edge 失效或已有 child operation 尚未提交,Then abort 整个 pending operation 及其 current candidate/预留、保留 active graph、让新 Viewer waiting,并且不因没有 decoded frame 触发恢复;resume 后从当前 graph 重新 reconcile。+- Given 当前分享权威 paused,When 新 Viewer 加入、edge 失效或已有 child operation 尚未提交,Then abort 整个 pending route operation 及其 current candidate/预留、保留 active graph、让新 Viewer waiting,并且不因没有 decoded frame 触发恢复。普通 resume 从当前 graph 重新 reconcile;若存在 prepared codec owner,则 Resume 必须先在该唯一 room-serial owner 内重验 frozen bindings、启动 proof deadline 并启用 source,codec settle 后才处理积压 route reconcile。- Given exactly-two publication 的实测 encoder/CPU/GPU 或上传成本超过游戏预算,或没有合格 hardware/power-efficient 路径,When 评估该候选,Then 保留健康路径并明确显示弱路径降级或不可用,不得退回全房间最低目标或静默软件编码;若 supported sender cohort 无法以常驻或按需方式提供共享 `LOW`,Then 质量验收失败,必须优化编码路径或明确标记不支持。- Given 同一时刻采集、host outbound 与 viewer inbound 证据,When 进行根因分类,Then 关联派生后的实际协商视频 codec/profile/parameters、适用时的 `scalabilityMode` 与真实解码表现,依次区分 Capture 低、Capture 高但 outbound 因 CPU 低、Capture 高但 outbound 因 bandwidth 低、outbound 正常但 inbound 低、以及 inbound 正常但肉眼模糊五类;不用 UA 或设备型号代替运行时证据,也不上传 raw SDP。- Given Viewer 发送低档请求,When 请求未鉴权、过频、重复、过期或没有匹配的 sender/viewer 统计,Then 请求不改变表示或路径状态;有效请求也只能作为交叉验证输入。- Given 受控 RTT/丢包测试条件,When 连续分享高动态游戏画面 30 分钟,Then 延迟、帧率与丢帧达到上述目标,且没有不可恢复的冻结。-- Given 部署版出现游戏低帧、持续 `bandwidth` 限制或只有 Host 刷新才能恢复,When 归因该报告,Then 用同一机器、浏览器、驱动、游戏场景和单个有线 direct Viewer 对照精确 release `769de201f7cc` 与最新 `main`。每次从独立重新确认的 affected state 只执行 `observe`、重建该 `HostPeer`、替换 capture、Host reload 或本地预览 cycle 中一个动作;codec A/B 另用新的 Host/share/PeerConnection 分别请求 `automatic/H.264/VP8` 并校验实际 codec,不把 codec 变更混入生命周期动作。记录 capture A、sender B、Viewer C 的同代重叠窗口、游戏 FPS、CPU 与进程级 GPU encode;可选 encoder implementation/power-efficient 字段缺失只记 unknown,不能把部署版报告直接归为最新代码或 H.264 缺陷。+- Given 2026-08-19 当时生产 release `769de201f7cc` 出现游戏低帧、持续 `bandwidth` 限制或只有 Host 刷新才能恢复,When 归因该历史报告,Then 用同一机器、浏览器、驱动、游戏场景和单个有线 direct Viewer 对照该精确 release 与最新 `main`。每次从独立重新确认的 affected state 只执行 `observe`、重建该 `HostPeer`、替换 capture、Host reload 或本地预览 cycle 中一个动作;codec A/B 另用新的 Host/share/PeerConnection 分别请求 `automatic/H.264/VP8` 并校验实际 codec,不把 codec 变更混入生命周期动作。记录 capture A、sender B、Viewer C 的同代重叠窗口、游戏 FPS、CPU 与进程级 GPU encode;可选 encoder implementation/power-efficient 字段缺失只记 unknown,不能把当时生产报告直接归为当前代码或 H.264 缺陷。- Given 分享过程中切换 Wi-Fi/有线网络,When ICE 连接失败,Then 客户端触发 ICE restart,并在成功或超时后给出明确状态。- Given 当前路径仍可播放且控制器准备迁移 logical parent 或替换 transport,When 候选路径拥有模型授权的 overlap 资源,Then 旧路径保持权威,直到 exact candidate child 解码出第一帧新画面后才原子提交;ICE `connected` 单独不能触发切换。- Given 候选没有准入资源,或 provisional 路径失败、超时、代次过期、参与者变化、房间停止、权限撤销或 session 被替换,When 本次机会结束,Then 原路径和未受影响 branches 继续工作,临时资源被销毁,重试遵守模型定义的有界策略。@@ -168,7 +168,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap- Given Web Host 或浏览器 relay 建立或替换分享音轨,When 对实际音频 sender 应用发送参数,Then 从当次 `getParameters()` 派生所选 `encodings[0].maxBitrate = 64000 | 128000 | 256000`、调用 `setParameters()` 并立即读回,旧配置缺失时按 128000 处理;Given Web Viewer 为含唯一有效 audio/Opus payload 的 offer 生成 answer,Then 用结构化 SDP parser 只 upsert 该 payload 的 `stereo=1` 与 `maxaveragebitrate=256000`,并把同一个结果用于 `setLocalDescription()` 和 signaling。首次连接、ICE restart、同 parent rebuild 和 relay child 都适用;空 SDP、无/歧义 Opus、多个有效 audio、重复目标参数、畸形 fmtp 或 parse/write 异常必须按对象 identity 返回浏览器原 answer 并继续,不能发送部分修改或静默冒充 stereo/实际码率。只有实际 `setLocalDescription()` 失败才进入既有连接错误路径。`sprop-stereo` 与 `usedtx` 不新增,其他 fmtp/FEC/session/media 字段逐项保留。- Given 通过 SFU 发布分享音轨,When 构建 LiveKit 2.22.0 publish options,Then 64 kbps 使用 `AudioPresets.musicStereo`、128 kbps 使用 `AudioPresets.musicHighQualityStereo`、256 kbps 使用同等结构的显式 sender ceiling,三档都设置 `forceStereo = true` 与 `dtx = false`,且不覆盖 pinned room default `red = true`;验收同时核对 SDK 选项、applied ceiling、当前 RTP codec/fmtp 与 stats 实际码率,不能从 preset 名称或 `opus/48000/2` 单独推断实际声道内容。- Given 分享正在直播或暂停且 Host 选择新的 64/128/256 kbps 音频档位,When 当前 profile mutation 串行执行,Then 服务端以 last-wins 保存并广播最新 desired profile,每个当前 Host、relay 与 SFU audio sender 从 fresh `getParameters()` 派生 `setParameters()` 并立即 readback,过期 completion 不得覆盖新值;以后创建的 sender 使用最新 desired profile。单个端点应用失败时保留媒体与其旧 applied 值、显示可见告警并允许后续更新或重建重试,不得谎称全房已收敛。当前 applied readback 保持 endpoint-local;没有显式回执 wire 就不宣称跨端点原子提交。该操作不改变 Opus、route revision、media-binding generation 或 publication generation,也不创建第二个音频控制环。当前 screen-audio Host 基线是 Chrome/Edge;其他浏览器只有实际 sender readback 成功时才算支持。-- Given 分享已显式暂停且 Host 选择 `自动 | H.264 | VP8` 的不同值,When 执行首个视频 codec 切换闭环,Then 为该请求分配单调 codec-negotiation generation,并与 room route mutation 串行;事务开始时冻结 exact current route/media binding target,离开的 Viewer 从 target 移除,新加入者等待事务结束。暂停期间对 target 的 P2P/relay path 完成显式 offer/answer 重协商,并对 SFU 路径完成新的 publication generation/republish;选择 `automatic` 时以空 codec preference 恢复浏览器默认。暂停帧不能充当媒体证明:恢复 source 后,每名 still-current target 发送一个只属于 codec transaction 的 proof,精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation、codec-negotiation generation、实际 inbound codec 与 decoded-frame baseline/delta;该 proof 不进入路由失效判断。若 leave、hard failure 或任何 exact binding 变化使 target 失效,服务端把它移出本事务并标为 `route-wait`,codec 事务在 deadline 内以剩余 target settle 后释放 route lock,controller 再用最终 committed preference 为仍在线 Viewer 恢复路径。只有服务端校验全部仍在 target 内的 proof 后才提交 desired codec。失败时立即重新暂停,按旧 preference 开启有界 rollback generation;rollback 必须证明旧 preference 已重新应用(P2P 空/有序 preference 或 SFU fresh publish options),并由新协商代次报告实际 inbound codec 与 decoded-frame progress,不要求 actual codec 字面等于历史值。回滚失败则保持暂停并显示明确失败,不允许 stale generation 恢复播放。零 current Viewer 或事务中全部离开时直接提交 future-edge desired codec,无需伪造 frame proof。`pause`、`replaceTrack()` 或仅调用 `setCodecPreferences()` 均不能冒充已完成切换;本 slice 是明确的 paused bounded-gap 事务,未暂停 MBB 热切换留作后续扩展。+- Given 分享已显式暂停且 Host 选择 `自动 | H.264 | VP8` 的不同值,When 执行首个视频 codec 切换闭环,Then 为该请求分配单调 codec-negotiation generation,并与 room route mutation 串行;事务开始时冻结 exact current route/media binding target,离开的 Viewer 从 target 移除,新加入者按既有 pause 语义等待。暂停期间在独立有界 preparation deadline 内对 target 的 P2P/relay path 完成显式 offer/answer 重协商,并对 SFU 路径完成新的 publication generation/republish;选择 `automatic` 时以空 codec preference 恢复浏览器默认。Preparation 完成不得擅自恢复用户主动暂停的分享:停止 preparation deadline,但继续由同一个 room-serial codec mutation owner 持有一个 bounded prepared generation,暂停期间不运行 timer并排斥 route mutation。Host 的正常 Resume 必须先在该 owner 内原子重验全部 frozen binding;仍精确匹配时启动 proof deadline,然后才启用 source。暂停帧不能充当媒体证明:用户恢复 source 后,每名 still-current target 发送一个只属于 codec transaction 的 proof,精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation、codec-negotiation generation、实际 inbound codec 与 decoded-frame baseline/delta;该 proof 不进入路由失效判断。若 leave、hard failure 或任何 exact binding 变化使 target 失效,服务端把它移出本事务并标为 `route-wait`,codec 事务以剩余 target settle 后释放 owner,controller 再用最终 committed preference 为仍在线 Viewer 恢复路径。只有服务端校验全部 still-current proof 后才提交 desired codec。Preparation failure 保持暂停并开启有界 old-preference rollback preparation;forward proof failure 则先重新进入服务端权威 paused,再执行同一 rollback preparation。Rollback prepared state继续占有同一 owner、无 timer,并等待用户下一次正常 Resume 后重验 binding、启动 rollback proof deadline、再启用 source;rollback 证明旧 preference 已重新应用(P2P 空/有序 preference 或 SFU fresh publish options)以及新协商代次的 actual inbound codec 与 decoded progress,不要求 actual codec 字面等于历史值。回滚失败保持暂停并显示明确失败;任何路径都不自动 Resume,不允许 stale generation 恢复播放。停止分享、替换 share generation 或删除房间清除 prepared state。零 current Viewer 或事务中全部离开时直接提交 future-edge desired codec,无需伪造 frame proof。`pause`、`replaceTrack()` 或仅调用 `setCodecPreferences()` 均不能冒充已完成切换;本 slice 是明确的 paused bounded-gap 事务,未暂停 MBB 热切换留作后续扩展。- Given 浏览器返回屏幕音轨,When 产品展示音频状态或未来连接详情,Then 只能把存在性、浏览器实际返回的 track settings、实际协商 codec/fmtp 和实际流量分别标为捕获、协商或观测事实;字段缺失必须显示为未知,且不得从 Opus 的 `48000/2` RTP 声明推断源采样率或实际 stereo。- Given Web 或后续 native sender 分享电影/视频音频,When 进行产品验收,Then 必须用独立 A/B/C 证据关联 capture audio track/settings、实际 negotiated codec/fmtp、outbound/inbound 实际码率、loss、jitter、concealment、jitter-buffer 与 A/V sync;P2P、浏览器 relay 与 SFU route switch 保持同一持久 Viewer `MediaStream`/媒体元素和 stereo 协商,不新增独立 audio element 或 Web Audio 时钟边界。native sender 必须通过该音质和同步矩阵,且不得把 audio `maxBitrate` ceiling 当作提质证明。- Given 分享者同时运行语音软件,When 选择仅分享游戏声音,Then supported Windows 11 native sender 只保留目标游戏及其子进程的渲染音频,观众、通知和其他应用声音不得进入分享;浏览器 system audio 无法满足时必须允许 video-only 或明确告知其可能包含语音/通知,不能用 AEC、降噪或来源标签伪称已隔离。