docs: web comments say what the app does, not how it came to be (#6277)
Rewrites the web app's comments to rule 32. Task, milestone, rule and spec ids are gone; regression stories are restated as the trap they guard (public auth routes, the menu's stopPropagation, universal loads under adapter-static, metric deltas with their margin). Flutter and Tauri mentions now name the Android app or a native shell, operator quotes and dates are dropped, and one library's counts no longer appear outside test fixtures. Verified with a TypeScript-scanner token comparison (template literals and regex literals re-scanned): only comment text changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,13 +1,12 @@
|
||||
// Audio loader seam. Today: returns the server-relative stream URL
|
||||
// directly. In the future Tauri shell, the loader can be swapped to
|
||||
// return blob URLs backed by a Rust-side cache (mirroring the Flutter
|
||||
// drift+LockCachingAudioSource pattern), without touching the player UI.
|
||||
// Audio loader seam: returns the server-relative stream URL directly. A
|
||||
// native shell can swap the loader to return blob URLs backed by its own
|
||||
// cache, without touching the player UI.
|
||||
//
|
||||
// Two operations:
|
||||
// - resolve(track) — returns the URL the <audio> element should src.
|
||||
// - prefetch(track) — hint that a track will be needed soon. Default
|
||||
// no-op (the browser handles it via the prefetch <audio> element);
|
||||
// Tauri can warm its native cache here.
|
||||
// a native shell can warm its cache here.
|
||||
|
||||
import type { TrackRef } from '#lib/api/types.js';
|
||||
|
||||
|
||||
@@ -17,22 +17,19 @@ import type { PlayStartedResponse, EventOkResponse } from '#lib/api/types.js';
|
||||
// - pagehide with a live row → navigator.sendBeacon a play_ended with
|
||||
// the last position. The server's rule still classifies skip-vs-not.
|
||||
//
|
||||
// Earlier shape made the skip-vs-ended call client-side via a "within 3s
|
||||
// of duration" rule, which left the server's threshold dead code and
|
||||
// treated every "next" tap as a skip even after most of the track played.
|
||||
// Backflow of the Android fix (commit d82e744d, 2026-06-01); see Scribe
|
||||
// task 519. Flutter client is deprecated and not updated.
|
||||
// The skip-vs-ended call is the server's, as on Android: a client-side
|
||||
// "within 3s of duration" rule would leave the server's threshold dead and
|
||||
// treat every "next" tap as a skip even after most of the track played.
|
||||
|
||||
export function useEventsDispatcher(): void {
|
||||
let openPlayEventId: string | null = null;
|
||||
let openTrackId: string | null = null;
|
||||
// openLastPositionMs tracks the *open row's* track and is updated
|
||||
// ONLY while that track is current — so a track change (which
|
||||
// synchronously resets the store's position to 0 and duration to 0)
|
||||
// can't clobber it before the close branch reads it. This is the
|
||||
// #426 race fix. The pagehide + natural-end branches can read
|
||||
// player.position directly because their current track is still the
|
||||
// open one at fire time.
|
||||
// openLastPositionMs tracks the *open row's* track and is updated ONLY while
|
||||
// that track is current — so a track change (which synchronously resets the
|
||||
// store's position to 0 and duration to 0) can't clobber it before the close
|
||||
// branch reads it. The pagehide + natural-end branches can read
|
||||
// player.position directly because their current track is still the open one
|
||||
// at fire time.
|
||||
let openLastPositionMs = 0;
|
||||
let prevTrackId: string | null = null;
|
||||
let prevState: string | null = null;
|
||||
@@ -121,11 +118,11 @@ export function useEventsDispatcher(): void {
|
||||
type: 'play_started',
|
||||
track_id: trackId,
|
||||
client_id: clientId,
|
||||
// #415: tag the play with the system playlist it came from
|
||||
// Tag the play with the system playlist it came from
|
||||
// (null for library / user-playlist / radio) so the server
|
||||
// can advance that playlist's rotation.
|
||||
source: player.queueSource ?? undefined,
|
||||
// #1551: device class for context conditioning. The web app is a
|
||||
// Device class for context conditioning. The web app is a
|
||||
// browser session, so it reports 'web'.
|
||||
device_class: 'web'
|
||||
});
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// Loudness normalization math for the web player (M464 #4999). Pure, so the
|
||||
// Loudness normalization math for the web player. Pure, so the
|
||||
// rules are tested without an <audio> element or an AudioContext.
|
||||
|
||||
import type { NormalizationPrefs, ReplayGain } from '#lib/api/normalization.js';
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// The web player's gain stage (M464 #4999). A cut is applied through the
|
||||
// The web player's gain stage. A cut is applied through the
|
||||
// element's own volume. A boost needs Web Audio, because element.volume
|
||||
// stops at 1: the element is routed through a GainNode and a
|
||||
// DynamicsCompressor, which acts as a limiter when the user picked one.
|
||||
@@ -6,8 +6,8 @@
|
||||
// Routing is permanent once made (createMediaElementSource cannot be
|
||||
// undone), and a context that is not running plays nothing. So the graph is
|
||||
// built only when a track actually wants a boost, and only once a context
|
||||
// has been confirmed running. Until then a boost plays at unity, which is
|
||||
// what the track sounded like before leveling existed.
|
||||
// has been confirmed running. Until then a boost plays at unity: the track
|
||||
// as it sounds unleveled.
|
||||
|
||||
import { SvelteMap } from 'svelte/reactivity';
|
||||
import { getReplayGain, type ReplayGain } from '#lib/api/normalization.js';
|
||||
@@ -137,7 +137,7 @@ export async function ensureGraph(el: HTMLAudioElement): Promise<void> {
|
||||
|
||||
// iOS suspends Web Audio when the screen locks, and a routed element goes
|
||||
// silent with it, so iOS never gets the graph. It ignores element.volume
|
||||
// too, so leveling there waits for the server's leveled stream (#5001).
|
||||
// too, so leveling there waits for the server's leveled stream.
|
||||
function isIOS(): boolean {
|
||||
const n = navigator;
|
||||
return /iPad|iPhone|iPod/.test(n.userAgent) || (n.platform === 'MacIntel' && n.maxTouchPoints > 1);
|
||||
|
||||
@@ -70,26 +70,26 @@ let _queueDrawerOpen = $state(false);
|
||||
// saved position after metadata loads.
|
||||
let _pendingRestorePosition: number | null = null;
|
||||
|
||||
// M4c: track when the queue was seeded by a radio call so we can
|
||||
// Track when the queue was seeded by a radio call so we can
|
||||
// auto-refresh at 80% consumption. Cleared when the user enqueues
|
||||
// from a non-radio source.
|
||||
let _radioSeedId = $state<string | null>(null);
|
||||
let _radioRefreshInFlight = false;
|
||||
|
||||
// #415: which system playlist (if any) this queue was seeded from.
|
||||
// Which system playlist (if any) this queue was seeded from.
|
||||
// 'for_you' | 'discover' | null. Read by the events dispatcher so
|
||||
// play_started carries `source` and the play counts against that
|
||||
// playlist's rotation. Re-set on every playQueue (a fresh non-system
|
||||
// queue clears it).
|
||||
let _queueSource = $state<string | null>(null);
|
||||
|
||||
// Track B (#968): consecutive load failures since the last successful
|
||||
// Consecutive load failures since the last successful
|
||||
// 'playing'. A bad track auto-advances instead of dead-ending; the streak
|
||||
// (capped against queue length) stops a fully-unplayable queue from
|
||||
// looping forever. Reset on a successful play and on a fresh playQueue.
|
||||
let _failureStreak = 0;
|
||||
|
||||
// Track B (#968): when a queue is seeded from a refreshable source (a system
|
||||
// When a queue is seeded from a refreshable source (a system
|
||||
// playlist or radio), the seeder hands us a closure that re-pulls the fresh
|
||||
// snapshot. On total failure (whole queue unplayable — likely a stale tab
|
||||
// left open across the daily rebuild) we call it once to self-heal before
|
||||
@@ -123,7 +123,7 @@ export function registerAudioEl(el: HTMLAudioElement | null): void {
|
||||
_audioEl = el;
|
||||
}
|
||||
|
||||
// #5418: a missing file can't stream, so it never enters the queue. Returns
|
||||
// A missing file can't stream, so it never enters the queue. Returns
|
||||
// the same array when nothing is missing.
|
||||
function playable(tracks: TrackRef[]): TrackRef[] {
|
||||
return tracks.some((t) => t.unavailable) ? tracks.filter((t) => !t.unavailable) : tracks;
|
||||
@@ -138,12 +138,12 @@ export function playQueue(
|
||||
refetch?: () => Promise<TrackRef[]>;
|
||||
} = {},
|
||||
): void {
|
||||
_radioSeedId = null; // M4c: non-radio enqueue clears the radio refresh state
|
||||
// #415: a fresh queue resets the system-playlist source. Set only
|
||||
_radioSeedId = null; // Non-radio enqueue clears the radio refresh state
|
||||
// A fresh queue resets the system-playlist source. Set only
|
||||
// when seeded from a system playlist (server already returned the
|
||||
// rotation-aware order, so no client shuffle in that path).
|
||||
_queueSource = opts.source ?? null;
|
||||
// #968: a fresh play replaces the self-heal closure + resets its budget.
|
||||
// A fresh play replaces the self-heal closure + resets its budget.
|
||||
_queueRefetch = opts.refetch ?? null;
|
||||
_selfHealAttempts = 0;
|
||||
// Start on the chosen track's place in the playable list; if the chosen
|
||||
@@ -184,8 +184,8 @@ export function playQueue(
|
||||
|
||||
export function togglePlay(): void {
|
||||
if (_queue.length === 0) return;
|
||||
// "Intent to play" (loading + playing) → paused. Anything else → loading (user
|
||||
// wants to play; audio will catch up).
|
||||
// "Intent to play" (loading + playing) → paused. Anything else → loading
|
||||
// (user wants to play; audio will catch up).
|
||||
if (_state === 'playing' || _state === 'loading') {
|
||||
_state = 'paused';
|
||||
} else {
|
||||
@@ -340,7 +340,7 @@ export function reportStateFromAudio(
|
||||
}
|
||||
}
|
||||
|
||||
// Track B (#968): a single failed track must not strand the player on the
|
||||
// A single failed track must not strand the player on the
|
||||
// "Try again" dead-end. Advance past it; only surface the error once the
|
||||
// whole queue has proven unplayable — every track failed, or we reached the
|
||||
// end with nothing playable. The streak cap (vs queue length) stops a
|
||||
@@ -362,7 +362,7 @@ function handleLoadFailure(detail?: string): void {
|
||||
_error = detail ?? 'Playback failed.';
|
||||
}
|
||||
|
||||
// #968: re-pull a stale refreshable queue. Returns true if a self-heal was
|
||||
// Re-pull a stale refreshable queue. Returns true if a self-heal was
|
||||
// started (caller must not dead-end). Bounded to one attempt per exhaustion
|
||||
// (reset on the next successful play) so a still-broken refresh can't loop.
|
||||
function trySelfHeal(): boolean {
|
||||
@@ -411,12 +411,12 @@ export function enqueueTrack(t: TrackRef): void {
|
||||
}
|
||||
|
||||
/**
|
||||
* M7 #372: insert a track immediately after the currently-playing one
|
||||
* Insert a track immediately after the currently-playing one
|
||||
* so it plays next. If the queue is empty, behaves like enqueueTrack
|
||||
* and starts the queue with this track at index 0.
|
||||
*/
|
||||
export function playNext(t: TrackRef): void {
|
||||
_radioSeedId = null; // M4c: any user-driven enqueue clears the radio refresh state
|
||||
_radioSeedId = null; // Any user-driven enqueue clears the radio refresh state
|
||||
if (t.unavailable) return;
|
||||
if (_queue.length === 0) {
|
||||
_queue = [t];
|
||||
@@ -461,10 +461,10 @@ async function fetchRadioTracks(seedTrackId: string): Promise<TrackRef[]> {
|
||||
export async function playRadio(seedTrackId: string): Promise<void> {
|
||||
const tracks = await fetchRadioTracks(seedTrackId);
|
||||
if (tracks.length === 0) return;
|
||||
// #968: hand the player a self-heal closure so a fully-stale radio queue
|
||||
// Hand the player a self-heal closure so a fully-stale radio queue
|
||||
// re-seeds from the same track instead of dead-ending.
|
||||
playQueue(tracks, 0, { refetch: () => fetchRadioTracks(seedTrackId) });
|
||||
_radioSeedId = seedTrackId; // M4c: set AFTER playQueue (which clears it)
|
||||
_radioSeedId = seedTrackId; // Set AFTER playQueue (which clears it)
|
||||
}
|
||||
|
||||
export function moveQueueItem(from: number, to: number): void {
|
||||
@@ -577,7 +577,7 @@ export function consumePendingRestorePosition(): number | null {
|
||||
return p;
|
||||
}
|
||||
|
||||
// M4c: auto-refresh radio queue when 80% consumed.
|
||||
// Auto-refresh radio queue when 80% consumed.
|
||||
// Fires whenever the consumption ratio crosses 80% AND the queue was
|
||||
// seeded by playRadio() AND no refresh is currently in-flight.
|
||||
$effect.root(() => {
|
||||
@@ -590,7 +590,7 @@ $effect.root(() => {
|
||||
|
||||
_radioRefreshInFlight = true;
|
||||
const seed = _radioSeedId;
|
||||
// Drift #554: cap the exclude list so a multi-hour radio session
|
||||
// Cap the exclude list so a multi-hour radio session
|
||||
// doesn't grow the query string past common 8KB limits and start
|
||||
// 414-ing /api/radio. The .catch() below would silently swallow
|
||||
// that failure and the player would stop topping up — a dead
|
||||
@@ -625,7 +625,7 @@ $effect.root(() => {
|
||||
});
|
||||
});
|
||||
|
||||
// Session-end teardown (#375): auth signals via sessionEnd; player
|
||||
// Session-end teardown: auth signals via sessionEnd; player
|
||||
// owns the player-specific cleanup (clear persisted queue for the
|
||||
// outgoing user, reset in-memory queue, close drawer) without auth
|
||||
// having to import any player APIs.
|
||||
@@ -641,10 +641,9 @@ $effect.root(() => {
|
||||
});
|
||||
});
|
||||
|
||||
// Persistence (M7 #364): split-effect shape. Queue/index changes write
|
||||
// immediately (rare, user-driven); position changes throttle to once
|
||||
// per 5s during steady playback. See spec section "Persistence write
|
||||
// effect" for the alternative debounce shape.
|
||||
// Persistence: split-effect shape. Queue/index changes write immediately
|
||||
// (rare, user-driven); position changes throttle to once per 5s during
|
||||
// steady playback.
|
||||
$effect.root(() => {
|
||||
let lastPositionWriteAt = 0;
|
||||
|
||||
|
||||
@@ -40,7 +40,8 @@ function track(id: string, dur = 180): TrackRef {
|
||||
|
||||
beforeEach(() => {
|
||||
localStorage.clear();
|
||||
// Reset state by starting with an empty queue (playQueue([]) leaves queue=[], index=0).
|
||||
// Reset state by starting with an empty queue (playQueue([]) leaves queue=[],
|
||||
// index=0).
|
||||
playQueue([]);
|
||||
closeQueueDrawer();
|
||||
setVolume(1);
|
||||
@@ -73,12 +74,13 @@ describe('player store — basic actions', () => {
|
||||
expect(player.state).toBe('idle'); // still idle with empty queue
|
||||
|
||||
playQueue([track('1')]);
|
||||
// After playQueue we're in 'loading'; togglePlay should not advance without an audio event.
|
||||
// But togglePlay from 'loading' should set the intent to play anyway — tested via report later.
|
||||
// Here, simulate the paused state:
|
||||
// After playQueue we're in 'loading'; togglePlay should not advance without
|
||||
// an audio event. But togglePlay from 'loading' should set the intent to
|
||||
// play anyway — tested via report later. Here, simulate the paused state:
|
||||
reportTimeUpdate(0);
|
||||
// manually put us in paused state by calling togglePlay twice isn't clean; set via the state-report API in Task 2.
|
||||
// Instead, test the simpler case: playQueue then togglePlay = still 'loading' (intent is to play).
|
||||
// manually put us in paused state by calling togglePlay twice isn't clean;
|
||||
// set via the state-report API in Task 2. Instead, test the simpler case:
|
||||
// playQueue then togglePlay = still 'loading' (intent is to play).
|
||||
togglePlay(); // from 'loading' — inverts intent; store moves to 'paused' intent
|
||||
expect(player.state).toBe('paused');
|
||||
togglePlay(); // from 'paused' — moves to 'loading' (re-play intent)
|
||||
@@ -185,8 +187,8 @@ describe('player store — shuffle + repeat + audio reports', () => {
|
||||
});
|
||||
|
||||
test('toggleShuffle randomizes queue[index+1..end], leaves current and earlier alone', () => {
|
||||
// Deterministic RNG: always returns 0 so Fisher-Yates swaps each i with i itself → no change.
|
||||
// Flip to always 0.999 to force swaps.
|
||||
// Deterministic RNG: always returns 0 so Fisher-Yates swaps each i with i
|
||||
// itself → no change. Flip to always 0.999 to force swaps.
|
||||
const seq = [0.999, 0.999, 0.999, 0.999, 0.999];
|
||||
let i = 0;
|
||||
__setShuffleRng(() => seq[i++ % seq.length]);
|
||||
@@ -199,9 +201,10 @@ describe('player store — shuffle + repeat + audio reports', () => {
|
||||
// Index 0 and 1 preserved:
|
||||
expect(player.queue[0].id).toBe('1');
|
||||
expect(player.queue[1].id).toBe('2');
|
||||
// Index 2..4 reordered: because RNG = 0.999 always, Math.floor(rng() * (j+1)) === j for each,
|
||||
// so swaps are with self — queue is unchanged. So validate that the IDs 3/4/5 are still the
|
||||
// tail set, in any order, to tolerate future RNG semantics.
|
||||
// Index 2..4 reordered: because RNG = 0.999 always, Math.floor(rng() *
|
||||
// (j+1)) === j for each, so swaps are with self — queue is unchanged. So
|
||||
// validate that the IDs 3/4/5 are still the tail set, in any order, to
|
||||
// tolerate future RNG semantics.
|
||||
const tailIds = [player.queue[2].id, player.queue[3].id, player.queue[4].id].sort();
|
||||
expect(tailIds).toEqual(['3', '4', '5']);
|
||||
|
||||
@@ -399,7 +402,7 @@ describe('player store — enqueue + playRadio', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// #5418: a missing file can't stream, so no entry point lets one into the queue.
|
||||
// A missing file can't stream, so no entry point lets one into the queue.
|
||||
describe('missing files stay out of the queue', () => {
|
||||
const gone = (id: string) => ({ ...track(id), unavailable: true });
|
||||
|
||||
@@ -487,7 +490,8 @@ describe('M4c radio auto-refresh at 80%', () => {
|
||||
const apiGet = vi.spyOn(client.api, 'get').mockResolvedValueOnce({ tracks: initial });
|
||||
await playRadio('seed');
|
||||
apiGet.mockClear();
|
||||
// Refresh response: 5 tracks where the first is the seed (will be stripped).
|
||||
// Refresh response: 5 tracks where the first is the seed (will be
|
||||
// stripped).
|
||||
const refreshTracks = [track('seed'), track('n1'), track('n2'), track('n3'), track('n4')];
|
||||
apiGet.mockResolvedValueOnce({ tracks: refreshTracks });
|
||||
skipNext(); skipNext(); skipNext(); // index = 3 (80%)
|
||||
|
||||
Reference in New Issue
Block a user