mal/plans/007-characterize-browser-player-flow.md

finding, catalog, impact, base_commit

finding	catalog	impact	base_commit
Characterize the browser player flow	Tests	Critical watch behavior can regress while parser tests and typecheck still pass.	0d31d46

Effort

M - add a focused DOM/browser test harness and cover the highest-risk interactions.

Risk

LOW - tests should characterize existing behavior, not change product behavior.

Confidence

HIGH - existing TypeScript tests cover helpers, while the player orchestration is largely untested.

Evidence

• static/player/main.ts:141-149 wires progress, controls, keyboard, skip, subtitles, quality, and mode behavior in one browser-only flow.
• static/player/progress.ts:65-76 persists progress through fetch and updates save state.
• static/player/episodes/complete.ts:10-28 posts completion, retries failures, and mutates UI state.
• Existing TS tests are limited to static/player/validate.test.ts and static/player/subtitles/vtt.test.ts.

Resolution Approach

Add targeted browser-player characterization tests without recreating broad flaky E2E coverage. Prefer small DOM tests under static/player that construct minimal player markup, stub fetch, navigator.sendBeacon, media element properties, timers, and window.showToast, then exercise the exported setup or lower-level modules.

Start with the highest-risk flows: initial source URL construction from mode token and quality preference, progress save on pause/scrub, completion retry behavior, and graceful handling when no playable source exists. If current modules are hard to test, introduce minimal testability seams while preserving runtime behavior.

Avoid reintroducing full Playwright infrastructure unless a lightweight DOM approach is insufficient. Keep fixtures short and readable so failures explain a specific player behavior.

Verify with bun test, bunx tsc -p tsconfig.json --noEmit, and bun run lint:ts.