Screen share 13: fluxer-core previews (#160) #239

Manually merged
charles merged 4 commits from screenshare-13-core-previews into screenshare 2026-11-12 09:48:19 +00:00
Owner

Stacked on: origin/screenshare-12-core-codec-negotiation

What

fluxer-core::voice::stream::previews (spec §3.6, §6.3 "Previews (sharer)" / "(viewer)"):

  • Sharer: while the own share is published and the privacy switch is off, ApiRequest::UploadStreamPreview { key, channel_id } at once, then every 1 s until ApiResult::StreamPreviewUploaded or 10 attempts (the original's hasUploadedOnce / initialAttempts), then every 4 min ± 60 s while another connection lists the key, otherwise a 5 s idle poll; a first viewer after the bootstrap uploads at once (the original's wake-on-demand). Privacy switch on, stop, leave or move: uploads end at once (the pending timer does nothing).
  • Viewer: streams of ui.selected_channel (own share excluded) fetched with ApiRequest::FetchStreamPreview { key }, refetched every 60 s; ApiResult::StreamPreview { key, found: false } (404) retries every 1 s for the first 10 answers; other failures retry after 60 s. UserAction::RequestStreamPreview(key) (hover) fetches unless in flight or fresh, and a hover within the fresh minute refreshes it when the minute ends. Records of ended streams are dropped.
  • preview_state(&App, &key) -> PreviewState { version, missing }; jitter(key, n) -> Duration; upload_delay(key, n); constants PREVIEW_*.
  • Privacy switch: VoiceSettings::disable_stream_previews + VoiceSettingChange::DisableStreamPreviews(bool), stored as disable_stream_previews (old files load with false).

Tests

crates/fluxer-core/tests/stream_previews.rs: the plan's 8 tests (written first, seen failing to compile, then passing). FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally. No real-device tests concern this task.

Deviations

  • jitter returns a Duration, which cannot be negative: it is 0–120 s and the delay is 4 min − 60 s + jitter (= 4 min ± 60 s). Deterministic FNV-1a + SplitMix64 over key and upload number (the store has no randomness).
  • The plan's test 404_retries_every_1s_for_10_attempts is named not_found_retries_every_1s_for_10_attempts (Rust identifiers cannot start with a digit).
  • ApiResult::StreamPreviewUploaded is a unit variant as in the Interfaces block (one share at most). No in-flight guard on uploads: each turn sends one; the runtime (Screen share 21) should serialise them.
  • Disabling the privacy switch and re-enabling it restarts the bootstrap (the original keeps the counters).
  • The privacy switch lives on VoiceSettings (machine-local, as the file list says voice/settings.rs), not in a separate privacy section; parity entries are left to Task 28/29.
  • Outside the file list: app.rs (calls reduce_previews after the selection reducer), voice/stream/{mod.rs,state.rs} (module + Streams.previews), README.md, and apps/fluxer/src/runtime.rs: a minimal 501 CLIENT_NOT_WIRED arm for the two new requests so the exhaustive match compiles, to be replaced by Screen share 21.

Closes #160

🤖 Generated with Claude Code

Stacked on: origin/screenshare-12-core-codec-negotiation ## What `fluxer-core::voice::stream::previews` (spec §3.6, §6.3 "Previews (sharer)" / "(viewer)"): - **Sharer:** while the own share is published and the privacy switch is off, `ApiRequest::UploadStreamPreview { key, channel_id }` at once, then every 1 s until `ApiResult::StreamPreviewUploaded` or 10 attempts (the original's `hasUploadedOnce` / `initialAttempts`), then every 4 min ± 60 s while another connection lists the key, otherwise a 5 s idle poll; a first viewer after the bootstrap uploads at once (the original's wake-on-demand). Privacy switch on, stop, leave or move: uploads end at once (the pending timer does nothing). - **Viewer:** streams of `ui.selected_channel` (own share excluded) fetched with `ApiRequest::FetchStreamPreview { key }`, refetched every 60 s; `ApiResult::StreamPreview { key, found: false }` (404) retries every 1 s for the first 10 answers; other failures retry after 60 s. `UserAction::RequestStreamPreview(key)` (hover) fetches unless in flight or fresh, and a hover within the fresh minute refreshes it when the minute ends. Records of ended streams are dropped. - `preview_state(&App, &key) -> PreviewState { version, missing }`; `jitter(key, n) -> Duration`; `upload_delay(key, n)`; constants `PREVIEW_*`. - Privacy switch: `VoiceSettings::disable_stream_previews` + `VoiceSettingChange::DisableStreamPreviews(bool)`, stored as `disable_stream_previews` (old files load with `false`). ## Tests `crates/fluxer-core/tests/stream_previews.rs`: the plan's 8 tests (written first, seen failing to compile, then passing). `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. No real-device tests concern this task. ## Deviations - `jitter` returns a `Duration`, which cannot be negative: it is 0–120 s and the delay is `4 min − 60 s + jitter` (= 4 min ± 60 s). Deterministic FNV-1a + SplitMix64 over key and upload number (the store has no randomness). - The plan's test `404_retries_every_1s_for_10_attempts` is named `not_found_retries_every_1s_for_10_attempts` (Rust identifiers cannot start with a digit). - `ApiResult::StreamPreviewUploaded` is a unit variant as in the Interfaces block (one share at most). No in-flight guard on uploads: each turn sends one; the runtime (Screen share 21) should serialise them. - Disabling the privacy switch and re-enabling it restarts the bootstrap (the original keeps the counters). - The privacy switch lives on `VoiceSettings` (machine-local, as the file list says `voice/settings.rs`), not in a separate privacy section; parity entries are left to Task 28/29. - Outside the file list: `app.rs` (calls `reduce_previews` after the selection reducer), `voice/stream/{mod.rs,state.rs}` (module + `Streams.previews`), `README.md`, and `apps/fluxer/src/runtime.rs`: a minimal 501 `CLIENT_NOT_WIRED` arm for the two new requests so the exhaustive match compiles, to be replaced by Screen share 21. Closes #160 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #159

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #160

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review — Screen share 13 (core previews), commit c2a4239

Scope: git diff e512205..origin/screenshare-13-core-previews (10 files).

Checks

  1. Plan tests: all 8 exist in crates/fluxer-core/tests/stream_previews.rs and assert the spec values (10 bootstrap uploads 1000 ms apart ending on first success; 4 min ± 60 s steady only with viewers, jitter deterministic and bounded; 5 s idle poll; privacy switch and stopping the share cancel the pending turn; 60 s viewer refetch for the selected channel's streams; 404 retry every 1 s for 10 answers; hover fetch then refresh). 404_retries_every_1s_for_10_attempts is renamed not_found_retries_every_1s_for_10_attempts because a Rust identifier cannot start with a digit. That rename is fine.
  2. Interfaces: ApiRequest::{UploadStreamPreview { key, channel_id }, FetchStreamPreview { key }}, ApiResult::{StreamPreviewUploaded, StreamPreview { key, found }}, UserAction::RequestStreamPreview(StreamKey), preview_state(&App, &StreamKey) -> PreviewState { version: u64, missing: bool } and jitter(&StreamKey, u64) -> Duration all exist as Task 21/22 consume them. The schedule matches the fork's StreamPreviewUploadScheduler::decide (checked in StreamPreviewUploadPolicy.ts).
  3. Invariants: no new dependency. The core holds only keys and channel ids, with no pixels, URLs or tokens. Nothing panics on server data: unparsable viewer keys watch nothing, and the hash uses wrapping arithmetic. Previews are cleared on logout through clear_streams. The runtime's 501 CLIENT_NOT_WIRED stub makes no server call.
  4. Review Focus 5 (core half): the privacy switch drops the schedule in the same reduce. The pending timer does nothing, and voice-state changes do not restart it. The requests carry no URL and no frame content. The logging half belongs to Task 21.
  5. cargo xtask ci in the review worktree: green (all steps passed; screenshot/livekit steps skipped as not enabled).

Findings

  • [minor] jitter() returns 0–120 s, and upload_delay subtracts 60 s, where the Interfaces block says "in ±60 s". Duration cannot be negative, so the offset is reasonable. The rustdoc states it, and the only consumer is upload_delay. No action needed beyond the doc.
  • [minor] The store has no in-flight guard on uploads. With an upload slower than 1 s, the bootstrap can have several uploads in flight at once. Task 21 must serialise uploads, or drop one when another is pending. Please record this as a follow-up or as a note on Task 21's issue.
  • [minor] Spec §11 puts disable_stream_previews "in the privacy section". It lives on VoiceSettings (machine-local), which matches the plan's file list (voice/settings.rs). Task 28 needs to show it under Privacy & Safety. This is not blocking.

Verdict: APPROVED (no blocking findings, local ci green).

**Independent review — Screen share 13 (core previews), commit c2a4239** Scope: `git diff e512205..origin/screenshare-13-core-previews` (10 files). **Checks** 1. Plan tests: all 8 exist in `crates/fluxer-core/tests/stream_previews.rs` and assert the spec values (10 bootstrap uploads 1000 ms apart ending on first success; 4 min ± 60 s steady only with viewers, jitter deterministic and bounded; 5 s idle poll; privacy switch and stopping the share cancel the pending turn; 60 s viewer refetch for the selected channel's streams; 404 retry every 1 s for 10 answers; hover fetch then refresh). `404_retries_every_1s_for_10_attempts` is renamed `not_found_retries_every_1s_for_10_attempts` because a Rust identifier cannot start with a digit. That rename is fine. 2. Interfaces: `ApiRequest::{UploadStreamPreview { key, channel_id }, FetchStreamPreview { key }}`, `ApiResult::{StreamPreviewUploaded, StreamPreview { key, found }}`, `UserAction::RequestStreamPreview(StreamKey)`, `preview_state(&App, &StreamKey) -> PreviewState { version: u64, missing: bool }` and `jitter(&StreamKey, u64) -> Duration` all exist as Task 21/22 consume them. The schedule matches the fork's `StreamPreviewUploadScheduler::decide` (checked in `StreamPreviewUploadPolicy.ts`). 3. Invariants: no new dependency. The core holds only keys and channel ids, with no pixels, URLs or tokens. Nothing panics on server data: unparsable viewer keys watch nothing, and the hash uses wrapping arithmetic. Previews are cleared on logout through `clear_streams`. The runtime's 501 `CLIENT_NOT_WIRED` stub makes no server call. 4. Review Focus 5 (core half): the privacy switch drops the schedule in the same reduce. The pending timer does nothing, and voice-state changes do not restart it. The requests carry no URL and no frame content. The logging half belongs to Task 21. 5. `cargo xtask ci` in the review worktree: **green** (all steps passed; screenshot/livekit steps skipped as not enabled). **Findings** - [minor] `jitter()` returns 0–120 s, and `upload_delay` subtracts 60 s, where the Interfaces block says "in ±60 s". `Duration` cannot be negative, so the offset is reasonable. The rustdoc states it, and the only consumer is `upload_delay`. No action needed beyond the doc. - [minor] The store has no in-flight guard on uploads. With an upload slower than 1 s, the bootstrap can have several uploads in flight at once. Task 21 must serialise uploads, or drop one when another is pending. Please record this as a follow-up or as a note on Task 21's issue. - [minor] Spec §11 puts `disable_stream_previews` "in the privacy section". It lives on `VoiceSettings` (machine-local), which matches the plan's file list (`voice/settings.rs`). Task 28 needs to show it under Privacy & Safety. This is not blocking. **Verdict: APPROVED** (no blocking findings, local ci green).
charles manually merged commit f98d075b60 into screenshare 2026-11-12 09:48:19 +00:00
Sign in to join this conversation.
No description provided.