Text chat 57: core entrance-sound library, scopes and per-user entrance preferences (#386) #411

Manually merged
charles merged 0 commits from textchat-57-core-entrance-library into textchat 2026-11-13 06:36:44 +00:00
Owner

What this builds

The store half of the entrance-sound items of #142 (fluxer-core, plus the [voice.entrance] table in fluxer-platform's settings file).

  • voice::EntranceLibrary in Voice::entrance_library: LibraryStatus, sounds newest first, selections by scope id, pending: Option<EntranceOp>, error: Option<EntranceError>; resolve/selection follow EntranceSoundScope::fallbacks. The join-time fetch fills the library too, and the posted entrance sound now comes from resolve(EntranceSoundScope::for_voice(guild)).
  • Actions: LoadEntranceSounds (once per session, again after Failed), SetEntranceSound → PutEntranceSoundSelection (applied on EntranceSelectionSet; None clears), UploadEntranceSound (checks feature limit → quota 8 → 1 MiB → magic bytes → name ≤ 32 chars, empty → "Entrance sound"; then selects for select_for), RenameEntranceSound, DeleteEntranceSound (drops its selections), PreviewEntranceSound (entrance:<hash> key, PREVIEW_CLIP_TAG, output volume only). Server ENTRANCE_SOUND_* validation codes map to EntranceError; anything else is Server(message).
  • Listener prefs: voice::EntranceListenerPrefs in Voice::entrance_listeners, SetEntranceListenerMute / SetEntranceListenerVolume (0–200 %), entrance_gain; a muted user's entrance is never fetched; persisted in LocalSettings::entrance / [voice.entrance] (non-id keys dropped, volumes clamped, absent in old files).
  • Selector selectors::entrance_settings(app, scope, current_guild) -> EntranceSettingsModel with EntranceRow, EntranceResolved, ScopeTile.

Testing

  • New crates/fluxer-core/tests/entrance_sounds.rs (19 tests, every name in the plan's Step 1); existing tests/soundboard.rs (29, entrance playback included) still pass; fluxer-platform/tests/settings.rs::entrance_prefs_round_trip_and_old_files_load.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally.

Deviations / reviewer notes

  • Outside the Files list, minimal: crates/fluxer-core/src/app.rs passes entrance_sounds_enabled(&session) into reduce_soundboard (the upload check needs the instance limits); apps/fluxer/src/runtime.rs executes the four new ApiRequests with Task 55's ApiClient methods and lists them in perform_chat's exhaustive match (needed to compile; Task 61 owns the rest of the runtime).
  • Community overrides follow the plan (guild-list order, selectors::guild_order); the original sorts them by name.
  • One library change at a time: a new change while pending is set is ignored.
  • Upload names over 32 characters are refused (EntranceError::Name) rather than cut as deriveLibraryName does; the UI derives the name.
  • ApiRequest has no PartialEq, so the tests compare requests by Debug or matches!.

Stacked on: textchat-55-proto-api-entrance-library, textchat-56-core-soundboard-parity

Closes #386

🤖 Generated with Claude Code

## What this builds The store half of the entrance-sound items of #142 (`fluxer-core`, plus the `[voice.entrance]` table in `fluxer-platform`'s settings file). - `voice::EntranceLibrary` in `Voice::entrance_library`: `LibraryStatus`, sounds newest first, `selections` by scope id, `pending: Option<EntranceOp>`, `error: Option<EntranceError>`; `resolve`/`selection` follow `EntranceSoundScope::fallbacks`. The join-time fetch fills the library too, and the posted entrance sound now comes from `resolve(EntranceSoundScope::for_voice(guild))`. - Actions: `LoadEntranceSounds` (once per session, again after `Failed`), `SetEntranceSound` → `PutEntranceSoundSelection` (applied on `EntranceSelectionSet`; `None` clears), `UploadEntranceSound` (checks feature limit → quota 8 → 1 MiB → magic bytes → name ≤ 32 chars, empty → "Entrance sound"; then selects for `select_for`), `RenameEntranceSound`, `DeleteEntranceSound` (drops its selections), `PreviewEntranceSound` (`entrance:<hash>` key, `PREVIEW_CLIP_TAG`, output volume only). Server `ENTRANCE_SOUND_*` validation codes map to `EntranceError`; anything else is `Server(message)`. - Listener prefs: `voice::EntranceListenerPrefs` in `Voice::entrance_listeners`, `SetEntranceListenerMute` / `SetEntranceListenerVolume` (0–200 %), `entrance_gain`; a muted user's entrance is never fetched; persisted in `LocalSettings::entrance` / `[voice.entrance]` (non-id keys dropped, volumes clamped, absent in old files). - Selector `selectors::entrance_settings(app, scope, current_guild) -> EntranceSettingsModel` with `EntranceRow`, `EntranceResolved`, `ScopeTile`. ## Testing - New `crates/fluxer-core/tests/entrance_sounds.rs` (19 tests, every name in the plan's Step 1); existing `tests/soundboard.rs` (29, entrance playback included) still pass; `fluxer-platform/tests/settings.rs::entrance_prefs_round_trip_and_old_files_load`. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. ## Deviations / reviewer notes - Outside the Files list, minimal: `crates/fluxer-core/src/app.rs` passes `entrance_sounds_enabled(&session)` into `reduce_soundboard` (the upload check needs the instance limits); `apps/fluxer/src/runtime.rs` executes the four new `ApiRequest`s with Task 55's `ApiClient` methods and lists them in `perform_chat`'s exhaustive match (needed to compile; Task 61 owns the rest of the runtime). - Community overrides follow the plan (guild-list order, `selectors::guild_order`); the original sorts them by name. - One library change at a time: a new change while `pending` is set is ignored. - Upload names over 32 characters are refused (`EntranceError::Name`) rather than cut as `deriveLibraryName` does; the UI derives the name. - `ApiRequest` has no `PartialEq`, so the tests compare requests by `Debug` or `matches!`. Stacked on: textchat-55-proto-api-entrance-library, textchat-56-core-soundboard-parity Closes #386 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Request shapes from fluxer_api/src/api/user/entrance_sound/EntranceSoundController.ts:72-96
and packages/schema/src/domains/user/EntranceSoundSchemas.ts; scopes from
fluxer_app/src/features/notification/utils/EntranceSoundScopes.ts:65-74; limits from
packages/constants/src/{EntranceSoundConstants,SoundboardConstants}.ts.

Refs #384

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
entrance_sound_created.json: serializeSound of
fluxer_api/src/api/user/entrance_sound/EntranceSoundController.ts:22-34 (the 201 of the
upload at :72-96 and the 200 of the rename at :97-121).
entrance_sound_quota_reached.json: the 400 of InputValidationError.fromCode
(packages/errors/src/domains/core/InputValidationError.ts:34-36) as written by
handleLocalizedValidationErrors (packages/errors/src/domains/core/ErrorHandlers.ts:118-143,
FluxerError.toJSON spreads data at packages/errors/src/FluxerError.ts:50-56), thrown by
fluxer_api/src/api/user/entrance_sound/EntranceSoundService.ts:95.

Refs #384

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Endpoints of fluxer_api/src/api/user/entrance_sound/EntranceSoundController.ts:72-177.
The service's validation codes (EntranceSoundService.ts:95-145) are nested in a 400
INVALID_FORM_BODY; ApiError::Http now carries them as its code (error.rs, same crate).

Refs #384

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fixtures/rest is the round-trip set of fluxer-proto models; the quota-reached body is an
error, not a model, so it moves to fixtures/errors. entrance_sound_created.json joins the
round-trip and unknown-field tables as an EntranceSound.

Refs #384

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #386

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

Independent review: Text chat 57 (core-entrance-library), commit 31fecd9

Scope: git diff f3c5075..origin/textchat-57-core-entrance-library.

Tests: All 19 tests the plan names are in crates/fluxer-core/tests/entrance_sounds.rs, and entrance_prefs_round_trip_and_old_files_load is in fluxer-platform/tests/settings.rs. They assert what the plan says: 8 sounds per user, 1 MiB at the boundary and one byte over, 32 characters, "Entrance sound", the entrance:<hash> key, PREVIEW_CLIP_TAG at output volume 0.5, listener gain 1.5 x 0.5 = 0.75, the 200 % clamp, the four ENTRANCE_SOUND_* codes, guild-order overrides, and the disabled notice. No new fixtures; the tests use the fixtures Task 55 added.

Interfaces: Every name and signature in the Task 57 Interfaces block exists as written:

  • EntranceLibrary, LibraryStatus, EntranceOp, EntranceError
  • the 8 UserActions, the 4 ApiRequests and the 4 ApiResults
  • EntranceListenerPrefs::{volume, is_muted}, entrance_gain, and Voice::{entrance_library, entrance_listeners} (both pub)
  • LocalSettings::entrance: Box<EntranceListenerPrefs>
  • selectors::entrance_settings, EntranceSettingsModel, EntranceRow, EntranceResolved, ScopeTile

The runtime maps the four requests onto Task 55's ApiClient methods.

Invariants:

  • fluxer-core gains no dependency and no I/O.
  • SoundBytes only passes through the action and the effect, as the plan specifies. Its Debug prints the length only. The core keeps only the select_for scope in its requests, not the bytes.
  • Nothing is logged except CoreError strings, and there are no URLs or paths in logs.
  • [voice.entrance] round-trips. Older files load, non-id keys are dropped, and volumes are clamped without panicking.
  • Server data cannot panic the client: ids that do not parse are dropped, the sort is total, and a selection of a missing sound falls through.

Implementer's flagged points, verified:

  • Selection after an upload: EntranceSoundUploaded clears Uploading and then PUTs the selection for select_for. This matches uploadTrimmedResult, and the test covers it.
  • Code mapping: matches the plan.
  • Join fetch and settings load at the same time: the first answer clears both requests, so a late failure of the other one is ignored. Failed is set only when no other load is in flight and the status is Loading. A failed re-fetch on join leaves Loaded alone. This is correct.

Findings

  1. minor: UploadEntranceSound rejects a name over 32 characters with EntranceError::Name. The original deriveLibraryName (useEntranceSound.ts:93-98) cuts it to 32 instead, and the plan cites that function. If the UI (Task 59/60) passes a long file stem, the upload fails where the original would succeed. Either cut the name in core, or make sure the UI cuts it before sending. Not blocking: no interface or invariant is affected.
  2. minor: trimmed_name counts Unicode scalar values, while the server and the original count UTF-16 units. A name made of astral characters (for example 20 emoji) passes the check, and the server then rejects it. That error has no ENTRANCE_SOUND_* code, so it shows as Server(message). This is an edge case and degrades gracefully.
  3. note: docs/parity/settings.toml still lists section-voice_video-entrance-sound as planned. That is right for a core-only task; the UI task should update it.

CI

FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci on 31fecd9 in a clean review worktree: all steps passed (exit 0).

Verdict: APPROVED. No blocking findings, and local CI is green.

🤖 Generated with Claude Code

## Independent review: Text chat 57 (core-entrance-library), commit 31fecd9 Scope: `git diff f3c5075..origin/textchat-57-core-entrance-library`. **Tests:** All 19 tests the plan names are in `crates/fluxer-core/tests/entrance_sounds.rs`, and `entrance_prefs_round_trip_and_old_files_load` is in `fluxer-platform/tests/settings.rs`. They assert what the plan says: 8 sounds per user, 1 MiB at the boundary and one byte over, 32 characters, "Entrance sound", the `entrance:<hash>` key, `PREVIEW_CLIP_TAG` at output volume 0.5, listener gain 1.5 x 0.5 = 0.75, the 200 % clamp, the four `ENTRANCE_SOUND_*` codes, guild-order overrides, and the disabled notice. No new fixtures; the tests use the fixtures Task 55 added. **Interfaces:** Every name and signature in the Task 57 Interfaces block exists as written: - `EntranceLibrary`, `LibraryStatus`, `EntranceOp`, `EntranceError` - the 8 `UserAction`s, the 4 `ApiRequest`s and the 4 `ApiResult`s - `EntranceListenerPrefs::{volume, is_muted}`, `entrance_gain`, and `Voice::{entrance_library, entrance_listeners}` (both pub) - `LocalSettings::entrance: Box<EntranceListenerPrefs>` - `selectors::entrance_settings`, `EntranceSettingsModel`, `EntranceRow`, `EntranceResolved`, `ScopeTile` The runtime maps the four requests onto Task 55's `ApiClient` methods. **Invariants:** - fluxer-core gains no dependency and no I/O. - `SoundBytes` only passes through the action and the effect, as the plan specifies. Its `Debug` prints the length only. The core keeps only the `select_for` scope in its requests, not the bytes. - Nothing is logged except `CoreError` strings, and there are no URLs or paths in logs. - `[voice.entrance]` round-trips. Older files load, non-id keys are dropped, and volumes are clamped without panicking. - Server data cannot panic the client: ids that do not parse are dropped, the sort is total, and a selection of a missing sound falls through. **Implementer's flagged points, verified:** - Selection after an upload: `EntranceSoundUploaded` clears `Uploading` and then PUTs the selection for `select_for`. This matches `uploadTrimmedResult`, and the test covers it. - Code mapping: matches the plan. - Join fetch and settings load at the same time: the first answer clears both requests, so a late failure of the other one is ignored. `Failed` is set only when no other load is in flight and the status is `Loading`. A failed re-fetch on join leaves `Loaded` alone. This is correct. ### Findings 1. **minor**: `UploadEntranceSound` rejects a name over 32 characters with `EntranceError::Name`. The original `deriveLibraryName` (`useEntranceSound.ts:93-98`) cuts it to 32 instead, and the plan cites that function. If the UI (Task 59/60) passes a long file stem, the upload fails where the original would succeed. Either cut the name in core, or make sure the UI cuts it before sending. Not blocking: no interface or invariant is affected. 2. **minor**: `trimmed_name` counts Unicode scalar values, while the server and the original count UTF-16 units. A name made of astral characters (for example 20 emoji) passes the check, and the server then rejects it. That error has no `ENTRANCE_SOUND_*` code, so it shows as `Server(message)`. This is an edge case and degrades gracefully. 3. **note**: `docs/parity/settings.toml` still lists `section-voice_video-entrance-sound` as `planned`. That is right for a core-only task; the UI task should update it. ### CI `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` on 31fecd9 in a clean review worktree: **all steps passed** (exit 0). **Verdict: APPROVED.** No blocking findings, and local CI is green. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Owner

Independent review (second pass): Text chat 57 (core-entrance-library), HEAD 9573d82

Scope: the task's own commit 31fecd9 within git diff 02385ad..origin/textchat-57-core-entrance-library (the rest of that range is Task 55/56 merges).

1. Tests: all 20 tests the plan names exist (19 in crates/fluxer-core/tests/entrance_sounds.rs, entrance_prefs_round_trip_and_old_files_load in crates/fluxer-platform/tests/settings.rs). Each asserts what the plan says: 8-sound quota, 1 MiB size, magic-byte format, 32-char name, "Entrance sound" default, the server code → EntranceError mapping, preview at output volume under entrance:<hash> on PREVIEW_CLIP_TAG, listener volume clamped to 200, entrance_gain capped at MAX_SOUND_GAIN, tiles Global/Guilds/Dms/current guild and overrides in guild order.
2. Interfaces: EntranceLibrary, LibraryStatus, EntranceOp, EntranceError, the UserAction/ApiRequest/ApiResult variants, EntranceListenerPrefs (volume, is_muted), entrance_gain(u8, u8) -> f32, LocalSettings::entrance: Box<EntranceListenerPrefs>, and selectors::entrance_settings / EntranceSettingsModel / ScopeTile match the plan. selected_sound goes through EntranceSoundScope::fallbacks.
3. Invariants: no Cargo.toml change, so no new dependency. fluxer-core gets no upload URLs or paths. The sound bytes in UploadEntranceSound are the SoundBytes the plan's interface prescribes, as the existing soundboard upload does. Server data cannot panic the client: the settings file drops non-id keys and clamps volumes, and a scope that does not parse becomes a 400 error in the runtime, not a panic. No new fixtures, and no secrets in logs.
4. Review Focus: none of the items belongs to this task.
5. Local CI: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci on 9573d82: all steps passed (exit 0).

Findings:

  • minor: trimmed_name refuses a name over 32 characters with EntranceError::Name, while the original's deriveLibraryName cuts it to 32 (base.slice(0, 32)). It also counts chars, not UTF-16 units. The first review raised the same point. The UI task can cut the name before sending; if it does not, this needs a follow-up.
  • minor: a join-time FetchEntranceSounds answer replaces selections with the server's copy. If a selection PUT is still pending at that moment, the library shows the old selection until EntranceSelectionSet arrives. That answer then applies the change, so nothing is lost.

About the relayed request "remove the cap": this PR has several caps (MAX_SOUND_GAIN on entrance_gain, the 200 % listener clamp, and the 8-sound, 1 MiB and 32-char limits that match the server). The request does not say which one, so this review changes none of them. Charles should name the cap.

Verdict: APPROVED (0 blocking, 2 minor).

## Independent review (second pass): Text chat 57 (core-entrance-library), HEAD 9573d82 Scope: the task's own commit 31fecd9 within `git diff 02385ad..origin/textchat-57-core-entrance-library` (the rest of that range is Task 55/56 merges). **1. Tests:** all 20 tests the plan names exist (19 in `crates/fluxer-core/tests/entrance_sounds.rs`, `entrance_prefs_round_trip_and_old_files_load` in `crates/fluxer-platform/tests/settings.rs`). Each asserts what the plan says: 8-sound quota, 1 MiB size, magic-byte format, 32-char name, `"Entrance sound"` default, the server code → `EntranceError` mapping, preview at output volume under `entrance:<hash>` on `PREVIEW_CLIP_TAG`, listener volume clamped to 200, `entrance_gain` capped at `MAX_SOUND_GAIN`, tiles Global/Guilds/Dms/current guild and overrides in guild order. **2. Interfaces:** `EntranceLibrary`, `LibraryStatus`, `EntranceOp`, `EntranceError`, the `UserAction`/`ApiRequest`/`ApiResult` variants, `EntranceListenerPrefs` (`volume`, `is_muted`), `entrance_gain(u8, u8) -> f32`, `LocalSettings::entrance: Box<EntranceListenerPrefs>`, and `selectors::entrance_settings` / `EntranceSettingsModel` / `ScopeTile` match the plan. `selected_sound` goes through `EntranceSoundScope::fallbacks`. **3. Invariants:** no Cargo.toml change, so no new dependency. fluxer-core gets no upload URLs or paths. The sound bytes in `UploadEntranceSound` are the `SoundBytes` the plan's interface prescribes, as the existing soundboard upload does. Server data cannot panic the client: the settings file drops non-id keys and clamps volumes, and a scope that does not parse becomes a 400 error in the runtime, not a panic. No new fixtures, and no secrets in logs. **4. Review Focus:** none of the items belongs to this task. **5. Local CI:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` on 9573d82: all steps passed (exit 0). Findings: - **minor:** `trimmed_name` refuses a name over 32 characters with `EntranceError::Name`, while the original's `deriveLibraryName` cuts it to 32 (`base.slice(0, 32)`). It also counts chars, not UTF-16 units. The first review raised the same point. The UI task can cut the name before sending; if it does not, this needs a follow-up. - **minor:** a join-time `FetchEntranceSounds` answer replaces `selections` with the server's copy. If a selection PUT is still pending at that moment, the library shows the old selection until `EntranceSelectionSet` arrives. That answer then applies the change, so nothing is lost. About the relayed request "remove the cap": this PR has several caps (`MAX_SOUND_GAIN` on `entrance_gain`, the 200 % listener clamp, and the 8-sound, 1 MiB and 32-char limits that match the server). The request does not say which one, so this review changes none of them. Charles should name the cap. **Verdict: APPROVED** (0 blocking, 2 minor).
charles manually merged commit 5817ae684a into textchat 2026-11-13 06:36:44 +00:00
Sign in to join this conversation.
No description provided.