Read AGENTS.md and CONTRIBUTING.md first, house rules live there.
Web player contributions
Constraints
- Vanilla JS modules, no framework, no build step. Files under
web/src/are served as-is by the API (/web). web/src/services/AudioService.jspicks the playback path and owns the file-source swap.services/audio/MsePipeline.jsis the bounded MSE (audio/mpeg) state machine,services/audio/BlockLoader.jsthe blob fallback where MSE mp3 is unsupported (Firefox). Any playback change must keep both paths working.- Long-session behavior matters: the bounded buffer exists because unbounded MSE appends crashed ~10 min in. Don't reintroduce unbounded growth.
- A finished MSE stream swaps to the full server-side file so scrubbing and true duration work (
canSwapToFileSource/swapToFileSource). Swaps only fire at existing discontinuities: end of playback, pause, seek, and read-along activation when no duration is known yet (ReadAlong.js). Don't trigger one mid-playback.
Standard patterns
- Popup menus (
role="menu") get full keyboard support: ArrowUp/Down walk items with wrap, Escape closes and restores focus to the trigger,focusoutcloses when focus leaves, first item focused when opened via keyboard. Reference implementations: markup inweb/index.html(#cast-menuis apopover="manual",#download-menuishidden-toggled), handlers inVoiceSelector.jsandApp.js. New menus copy that shape. - File downloads go through
App.triggerDownload(url, name), don't hand-roll anchor clicks. - Outside-click dismissal uses
closeOnOutsidePressfromdismiss.js. - Fire-and-forget promises still need a
.catchthat surfaces viashowStatus. - Settings checkboxes copy
.autoplay-toggle(player.css, plus its mobile media-query override): no:hoversplit, no per-controlaccent-color,:rootin base.css sets it. - Services take request values as arguments (
buildRequestBody(..., responseFormat)). Read a control once in the caller, don't re-query it inside the service.
Testing
- Unit:
npm run test:web(node test runner). New test files go inweb/tests/unit/and must be imported fromweb/tests/unit/index.test.mjs, it's a manual registry. - E2e:
npm run test:e2e(Playwright againstweb/tests/e2e/fixtures/static-server.mjson port 4173, auto-started by the config). Stub the two startup calls withmockApi(page)fromfixtures/mock-api.mjs, no TTS backend needed. CI runs unit and e2e on bundled Chromium. - Bundled Chromium has no mp3 codec, so real MSE playback needs system Chrome: launch with
channel: 'chrome'and skip when it's unavailable, CI has only bundled Chromium.long-playback.spec.mjsmocksMediaSourceinstead. - For manual testing against a real backend, the cpu and gpu compose files already mount
web/over the image's copy, edits are live per request. rocm needs the mount added. - Before committing, check the change against modern-web-guidance for current HTML/CSS/JS and accesibility patterns.