docs(26): create gap closure plan for stems/controls render timing

Phase 26: JamTrack Polish - Plan 26-03 removes 'idle' from valid render states - Closes UAT gap: stems/controls appearing before sync - 1 plan in wave 3, depends on 26-02 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-25 22:59:46 +05:30 · 2026-02-25 22:59:46 +05:30 · 41463c9863
parent 156b1039e8
commit 41463c9863
2 changed files with 183 additions and 3 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -16,7 +16,7 @@ v1.6 addresses usability issues reported in three media features: JamTrack (load

 ## Phases

- [x] **Phase 26: JamTrack Polish** - Fix loading sequence, sizing, navigation, and cleanup ✓
+- [ ] **Phase 26: JamTrack Polish** - Fix loading sequence, sizing, navigation, and cleanup (gap closure)
 - [ ] **Phase 27: Backing Track Sync** - Enable track sync and async cleanup
 - [ ] **Phase 28: Metronome Responsiveness** - Debounce controls and cleanup timers

@ -31,11 +31,12 @@ v1.6 addresses usability issues reported in three media features: JamTrack (load
  2. JamTrack player fits properly in popup window without scrollbars
  3. "Create custom mix" button opens JamTrack editor in new tab
  4. No console warnings about leaked callbacks when closing JamTrack or navigating away
-**Plans**: 2 plans
+**Plans**: 3 plans

 Plans:
 - [x] 26-01-PLAN.md - Fix window sizing and create custom mix navigation ✓
 - [x] 26-02-PLAN.md - Add callback cleanup and defer controls rendering ✓
+- [ ] 26-03-PLAN.md - Remove 'idle' from valid render states (gap closure)

 ### Phase 27: Backing Track Sync
 **Goal**: Backing Track appears in session screen when opened
@ -68,7 +69,7 @@ Plans:

 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
-| 26. JamTrack Polish | v1.6 | 2/2 | Complete | 2026-02-25 |
+| 26. JamTrack Polish | v1.6 | 2/3 | Gap closure | 2026-02-25 |
 | 27. Backing Track Sync | v1.6 | 0/TBD | Not started | - |
 | 28. Metronome Responsiveness | v1.6 | 0/TBD | Not started | - |

--- a/.planning/phases/26-jamtrack-polish/26-03-PLAN.md
+++ b/.planning/phases/26-jamtrack-polish/26-03-PLAN.md
@ -0,0 +1,179 @@
+---
+phase: 26-jamtrack-polish
+plan: 03
+type: execute
+wave: 3
+depends_on: ["26-02"]
+files_modified:
+  - jam-ui/src/components/client/JKSessionScreen.js
+  - jam-ui/src/components/client/JKSessionJamTrackPlayer.js
+autonomous: true
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Stems only appear in session screen after JamTrack is synchronized with backend"
+    - "Player controls only appear after JamTrack is synchronized with backend"
+  artifacts:
+    - path: "jam-ui/src/components/client/JKSessionScreen.js"
+      provides: "Stems rendering gated by synchronized state only"
+      contains: "jamTrackDownloadState.state === 'synchronized'"
+    - path: "jam-ui/src/components/client/JKSessionJamTrackPlayer.js"
+      provides: "Controls rendering gated by synchronized state only"
+      contains: "downloadState.state === 'synchronized'"
+  key_links:
+    - from: "JKSessionScreen.js line 1406"
+      to: "jamTrackDownloadState.state"
+      via: "conditional rendering check"
+      pattern: "jamTrackDownloadState\\.state === 'synchronized'"
+    - from: "JKSessionJamTrackPlayer.js line 680"
+      to: "downloadState.state"
+      via: "conditional rendering check"
+      pattern: "downloadState\\.state === 'synchronized'"
+---
+
+<objective>
+Remove 'idle' from valid render states so stems and controls only appear after JamTrack is synchronized.
+
+Purpose: Fix UAT issue where stems and controls appeared immediately when JamTrack was selected, before backend processing completed. The 'idle' state means "not yet checked" but was being treated as "ready to display".
+Output: Stems and controls only render when downloadState.state === 'synchronized'.
+</objective>
+
+<execution_context>
+@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/nuwan/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/26-jamtrack-polish/26-UAT.md
+@.planning/debug/jamtrack-stems-before-sync.md
+@jam-ui/src/components/client/JKSessionScreen.js (lines 1400-1430)
+@jam-ui/src/components/client/JKSessionJamTrackPlayer.js (lines 670-690)
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Remove 'idle' from stems render condition in JKSessionScreen</name>
+  <files>jam-ui/src/components/client/JKSessionScreen.js</files>
+  <action>
+At line 1406, the render condition for JamTrack stems currently allows both 'synchronized' AND 'idle' states:
+
+```javascript
+(jamTrackDownloadState.state === 'synchronized' || jamTrackDownloadState.state === 'idle')
+```
+
+The 'idle' state is the INITIAL state when a JamTrack is first selected but before loadJamTrack() is called (which happens on Play button click). This means stems appear immediately when the user selects a JamTrack, before the backend has processed it.
+
+Change line 1406 to only check for 'synchronized':
+
+```javascript
+(jamTrackDownloadState.state === 'synchronized')
+```
+
+The full condition at line 1405-1406 should become:
+```javascript
+{selectedJamTrack && jamTrackStems.length > 0 &&
+  (jamTrackDownloadState.state === 'synchronized') && (
+```
+
+This ensures stems only appear AFTER the track is fully synchronized with the backend.
+  </action>
+  <verify>
+```bash
+grep -n "jamTrackDownloadState.state === 'synchronized'" jam-ui/src/components/client/JKSessionScreen.js | head -5
+```
+Should show the condition WITHOUT 'idle' at line 1406.
+
+Also verify 'idle' is NOT in the condition:
+```bash
+grep -n "jamTrackDownloadState.state === 'idle'" jam-ui/src/components/client/JKSessionScreen.js
+```
+Should return no matches (or matches only in unrelated code).
+  </verify>
+  <done>JKSessionScreen stems render condition only checks for 'synchronized' state, not 'idle'</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Remove 'idle' from controls render condition in JKSessionJamTrackPlayer</name>
+  <files>jam-ui/src/components/client/JKSessionJamTrackPlayer.js</files>
+  <action>
+At line 680, the render condition for player controls currently allows both 'idle' AND 'synchronized' states:
+
+```javascript
+{(downloadState.state === 'idle' || downloadState.state === 'synchronized') && !isLoadingSync && (
+```
+
+Same issue as JKSessionScreen: 'idle' is the initial state before backend sync, so controls appear prematurely.
+
+Change line 680 to only check for 'synchronized':
+
+```javascript
+{(downloadState.state === 'synchronized') && !isLoadingSync && (
+```
+
+This ensures controls only appear AFTER the track is fully synchronized with the backend. The download progress UI (lines 593-670) already handles the loading states, so the user will see:
+1. Select JamTrack -> loading indicator
+2. Download in progress -> progress bar
+3. Download complete (synchronized) -> controls appear
+  </action>
+  <verify>
+```bash
+grep -n "downloadState.state === 'synchronized'" jam-ui/src/components/client/JKSessionJamTrackPlayer.js | head -5
+```
+Should show the condition WITHOUT 'idle' at line 680.
+
+Also verify 'idle' is NOT in the controls condition:
+```bash
+grep -n "downloadState.state === 'idle'" jam-ui/src/components/client/JKSessionJamTrackPlayer.js
+```
+Should return no matches (or matches only in unrelated code like comments).
+  </verify>
+  <done>JKSessionJamTrackPlayer controls render condition only checks for 'synchronized' state, not 'idle'</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Build verification</name>
+  <files>None (verification only)</files>
+  <action>
+Run build to verify no syntax errors from the changes:
+
+```bash
+cd jam-ui && npm run build
+```
+
+Verify the changes work correctly by checking the expected behavior:
+- When user selects a JamTrack, stems should NOT appear in session screen immediately
+- Stems should only appear after the track transitions to 'synchronized' state
+- Controls in player popup should also only appear after 'synchronized' state
+  </action>
+  <verify>
+Build command exits with code 0 and no compilation errors.
+  </verify>
+  <done>Build passes with no errors, changes are syntactically correct</done>
+</task>
+
+</tasks>
+
+<verification>
+1. Build check: `cd jam-ui && npm run build` completes without errors
+2. Code verification:
+   - JKSessionScreen.js line 1406: condition is `(jamTrackDownloadState.state === 'synchronized')` WITHOUT 'idle'
+   - JKSessionJamTrackPlayer.js line 680: condition is `(downloadState.state === 'synchronized')` WITHOUT 'idle'
+3. Grep confirms no references to 'idle' in render conditions for stems/controls
+</verification>
+
+<success_criteria>
+- JKSessionScreen stems only render when jamTrackDownloadState.state === 'synchronized'
+- JKSessionJamTrackPlayer controls only render when downloadState.state === 'synchronized'
+- The word 'idle' does not appear in either render condition
+- Build passes with no errors
+- UAT gap "Controls and stems should only appear after JamTrack is synchronized" is closed
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/26-jamtrack-polish/26-03-SUMMARY.md`
+</output>