Circular Minimized Music Player Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Replace the current mini-bar approach with a true circular minimized music player state that preserves playback, survives instant-navigation page transitions, resets on full refresh, and visually matches all three theme modes.
Architecture: Reuse the existing persistent music player component and session-scoped state, but change minimized mode from a reduced rectangular bar into a dedicated circular floating control. The circle shows playback state visually and restores the full player on click. Theme-specific styling is handled in CSS with focused overrides for default, flashlight, and minecraft modes.
Tech Stack: MkDocs Material, vanilla JavaScript, CSS, session-scoped in-memory state, existing music player DOM
Task 1: Replace minimized bar behavior with circular minimized state
Files:
- Modify: docs/javascripts/music-player.js
- Modify: docs/stylesheets/music-player.css
Step 1: Write the failing test
Manual failing criteria: - minimized state still looks like a shrunken rectangular player - minimized state is not visually distinct enough from expanded state - minimized state does not communicate playback state clearly
Step 2: Run verification to confirm failure
Check current implementation and confirm: - minimized mode remains bar-like - visual difference from expanded player is insufficient
Expected: FAIL.
Step 3: Write minimal implementation
- Keep the existing minimize toggle control and session state source
- Change minimized mode styling so the player becomes a compact circular control
- In minimized state:
- hide full player layout
- keep only circular shell and playback-state indicator
- clicking the circle restores the player
- Preserve playback logic and current session persistence across instant navigation
- Preserve refresh-reset behavior (expanded on full refresh)
Step 4: Run verification to confirm it passes
Expected: - minimized player becomes a true small circle - playback continues normally - click restores expanded player - page transitions preserve minimized state within session
Step 5: Commit
git add docs/javascripts/music-player.js docs/stylesheets/music-player.css
git commit -m "feat: replace mini bar with circular minimized music player"
Task 2: Add clear playback-state visualization to minimized circle
Files:
- Modify: docs/javascripts/music-player.js
- Modify: docs/stylesheets/music-player.css
Step 1: Write the failing test
Manual failing criteria: - minimized circle does not clearly show whether music is playing or paused - state feedback is too subtle or ambiguous
Step 2: Run verification to confirm failure
Expected: FAIL.
Step 3: Write minimal implementation
- In minimized state show distinct visual playback status:
- paused → obvious play icon
- playing → animated visual state (e.g. pulsing/rotating indicator)
- Avoid adding complex new controls beyond what is necessary
- Keep restored player behavior unchanged
Step 4: Run verification to confirm it passes
Expected: - user can tell at a glance whether playback is active - animation remains lightweight and visually clean
Step 5: Commit
git add docs/javascripts/music-player.js docs/stylesheets/music-player.css
git commit -m "feat: show animated playback state in minimized player"
Task 3: Theme-adapt the minimized circle for default, flashlight, and minecraft modes
Files:
- Modify: docs/stylesheets/music-player.css
- Modify: docs/stylesheets/minecraft-theme.css
- Possibly modify: docs/stylesheets/extra.css if flashlight/default mode override placement is clearer there
Step 1: Write the failing test
Manual failing criteria: - minimized control still looks pink/glass-only in minecraft mode - minimized control does not visually fit flashlight mode - theme transitions leave the minimized control mismatched or hard to read
Step 2: Run verification to confirm failure
Expected: FAIL because theme-specific minimized treatment is incomplete.
Step 3: Write minimal implementation
- Default mode: soft glass circular floating control
- Flashlight mode: darker, higher-contrast circular control
- Minecraft mode: pixel-style control matching existing minecraft UI language; avoid pink glass styling
- Ensure icon/readability/hover states are appropriate in all three themes
Step 4: Run verification to confirm it passes
Expected: - minimized state visually belongs to each theme - minecraft mode no longer looks like a pink glass control - no readability or click-target issue appears
Step 5: Commit
git add docs/stylesheets/music-player.css docs/stylesheets/minecraft-theme.css docs/stylesheets/extra.css
git commit -m "feat: theme-match minimized music player across modes"
Task 4: Verify no regression in playback, drag, and restore behavior
Files: - Verify only unless regression found
Step 1: Write failing verification checklist
Failure conditions: - player can no longer drag correctly when expanded - minimized player cannot restore - playback button state desynchronizes from audio state - minimized state breaks on page transition or theme switch
Step 2: Run verification
Manual checks: - play / pause music - minimize / restore - switch theme modes - navigate between pages with instant navigation - refresh page and confirm expanded default returns - drag expanded player after restore
Step 3: Minimal implementation if needed
Only fix regressions caused by Tasks 1-3. No unrelated cleanup.
Step 4: Re-run verification
Expected: new circular minimized mode works without breaking existing player behavior.
Step 5: Commit
git add <only files changed during regression fix>
git commit -m "fix: preserve player behavior after circular minimized mode"
Plan complete and saved to docs/plans/2026-03-10-circular-mini-player-plan.md. Two execution options:
1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints
Which approach?