fix(26): orchestrator corrections - update planning docs

.planning/phases/26-jamtrack-polish/26-03-PLAN.md

@@ -14,7 +14,11 @@ 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"
+    - "Already-synchronized JamTracks show stems/controls immediately without waiting"
   artifacts:
+    - path: "jam-ui/src/components/client/JKSessionScreen.js"
+      provides: "handleJamTrackSelect calls checkJamTrackSync before dispatching UI state"
+      contains: "checkJamTrackSync"
     - path: "jam-ui/src/components/client/JKSessionScreen.js"
       provides: "Stems rendering gated by synchronized state only"
       contains: "jamTrackDownloadState.state === 'synchronized'"
@@ -22,6 +26,10 @@ must_haves:
       provides: "Controls rendering gated by synchronized state only"
       contains: "downloadState.state === 'synchronized'"
   key_links:
+    - from: "handleJamTrackSelect"
+      to: "checkJamTrackSync thunk"
+      via: "dispatch call before setting UI state"
+      pattern: "dispatch\\(checkJamTrackSync"
     - from: "JKSessionScreen.js line 1406"
       to: "jamTrackDownloadState.state"
       via: "conditional rendering check"
@@ -33,10 +41,14 @@ must_haves:
 ---
 
 <objective>
-Remove 'idle' from valid render states so stems and controls only appear after JamTrack is synchronized.
+Fix UAT issue where stems and controls appear before 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".
+Two-part fix:
-Output: Stems and controls only render when downloadState.state === 'synchronized'.
+1. Call checkJamTrackSync in handleJamTrackSelect BEFORE dispatching UI state - this transitions downloadState from 'idle' to 'synchronized' (for cached tracks) or keeps it 'idle' (for non-synced tracks)
+2. Remove 'idle' from render conditions - only 'synchronized' shows UI
+
+Purpose: Ensure stems and controls only appear AFTER backend confirms the track is ready, while allowing already-synchronized tracks to appear immediately.
+Output: Proper loading sequence: select → check sync → (download if needed) → show UI.
 </objective>
 
 <execution_context>
@@ -50,14 +62,90 @@ Output: Stems and controls only render when downloadState.state === 'synchronize
 @.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/JKSessionScreen.js (lines 1165-1190, 1400-1430)
 @jam-ui/src/components/client/JKSessionJamTrackPlayer.js (lines 670-690)
+@jam-ui/src/store/features/mediaSlice.js (checkJamTrackSync thunk)
 </context>
 
 <tasks>
 
 <task type="auto">
-  <name>Task 1: Remove 'idle' from stems render condition in JKSessionScreen</name>
+  <name>Task 1: Call checkJamTrackSync in handleJamTrackSelect before dispatching UI state</name>
+  <files>jam-ui/src/components/client/JKSessionScreen.js</files>
+  <action>
+The root cause is that handleJamTrackSelect (lines 1165-1190) dispatches UI state immediately without calling checkJamTrackSync. This means downloadState.state remains 'idle' (initial state) and never transitions to 'synchronized'.
+
+**Step 1: Add checkJamTrackSync to the imports**
+
+Find the mediaSlice imports (around line 40-60) and add checkJamTrackSync:
+
+```javascript
+import {
+  // ... existing imports ...
+  checkJamTrackSync,  // Add this
+} from '../../store/features/mediaSlice';
+```
+
+**Step 2: Modify handleJamTrackSelect to call checkJamTrackSync first**
+
+Replace lines 1165-1190 with:
+
+```javascript
+const handleJamTrackSelect = async (jamTrack) => {
+  try {
+    // Fetch jam track details with stems
+    const response = await getJamTrack({ id: jamTrack.id });
+    const jamTrackWithStems = await response.json();
+
+    // Check sync state BEFORE dispatching UI state
+    // This transitions downloadState from 'idle' to 'synchronized' (if already synced)
+    // or keeps it 'idle' (if download needed)
+    const syncResult = await dispatch(checkJamTrackSync({
+      jamTrack: jamTrackWithStems,
+      jamClient
+    })).unwrap();
+
+    // Set the selected jam track and stems (for display on session screen)
+    dispatch(setSelectedJamTrack(jamTrackWithStems));
+    dispatch(setJamTrackStems(jamTrackWithStems.tracks || []));
+
+    // Open the JamTrack player popup (with full data needed for player)
+    dispatch(setJamTrackData({
+      jamTrack: jamTrackWithStems,
+      session: currentSession,
+      currentUser: currentUser
+    }));
+
+    // Show appropriate message based on sync state
+    if (syncResult.isSynchronized) {
+      toast.success(`Loaded JamTrack: ${jamTrackWithStems.name}`);
+    } else {
+      toast.info(`Loading JamTrack: ${jamTrackWithStems.name}...`);
+    }
+  } catch (error) {
+    toast.error('Failed to load JamTrack');
+  }
+};
+```
+
+The key change is calling `checkJamTrackSync` BEFORE dispatching `setSelectedJamTrack` and `setJamTrackStems`. This ensures:
+- For already-synced tracks: downloadState transitions from 'idle' to 'synchronized' → stems render immediately
+- For non-synced tracks: downloadState stays 'idle' → stems don't render until download completes
+  </action>
+  <verify>
+```bash
+# Verify checkJamTrackSync is imported
+grep -n "checkJamTrackSync" jam-ui/src/components/client/JKSessionScreen.js | head -3
+
+# Verify it's called in handleJamTrackSelect
+grep -A5 "const handleJamTrackSelect" jam-ui/src/components/client/JKSessionScreen.js | grep -q "checkJamTrackSync" && echo "checkJamTrackSync called in handleJamTrackSelect"
+```
+  </verify>
+  <done>handleJamTrackSelect calls checkJamTrackSync before dispatching UI state, ensuring downloadState transitions from 'idle' to appropriate state</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: 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:
@@ -66,7 +154,9 @@ At line 1406, the render condition for JamTrack stems currently allows both 'syn
 (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.
+Now that Task 1 ensures checkJamTrackSync is called before UI state is set, we can safely remove 'idle' from the condition. The flow will be:
+- Already-synced tracks: checkJamTrackSync → state='synchronized' → stems render
+- Non-synced tracks: checkJamTrackSync → state='idle' → stems hidden until download completes
 
 Change line 1406 to only check for 'synchronized':
 
@@ -79,64 +169,54 @@ The full condition at line 1405-1406 should become:
 {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
+# Verify condition no longer includes 'idle'
-```
+grep -n "jamTrackDownloadState.state === 'synchronized'" jam-ui/src/components/client/JKSessionScreen.js | grep -v idle
-Should show the condition WITHOUT 'idle' at line 1406.
 
-Also verify 'idle' is NOT in the condition:
+# Verify 'idle' is NOT in the stems render condition
-```bash
+grep -n "jamTrackDownloadState.state === 'idle'" jam-ui/src/components/client/JKSessionScreen.js || echo "No 'idle' check found - correct"
-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>
+  <name>Task 3: 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:
+At line 680 (or nearby), 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 to only check for 'synchronized':
-
-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
+1. Select JamTrack → checkJamTrackSync runs
-2. Download in progress -> progress bar
+2. If not synced: loading indicator → download progress → controls appear
-3. Download complete (synchronized) -> controls appear
+3. If already synced: controls appear immediately
   </action>
   <verify>
 ```bash
-grep -n "downloadState.state === 'synchronized'" jam-ui/src/components/client/JKSessionJamTrackPlayer.js | head -5
+# Verify condition no longer includes 'idle'
-```
+grep -n "downloadState.state === 'synchronized'" jam-ui/src/components/client/JKSessionJamTrackPlayer.js | head -3
-Should show the condition WITHOUT 'idle' at line 680.
 
-Also verify 'idle' is NOT in the controls condition:
+# Verify 'idle' is NOT in the controls render condition
-```bash
+grep -n "downloadState.state === 'idle'" jam-ui/src/components/client/JKSessionJamTrackPlayer.js || echo "No 'idle' check found - correct"
-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>
+  <name>Task 4: Build verification</name>
   <files>None (verification only)</files>
   <action>
 Run build to verify no syntax errors from the changes:
@@ -145,10 +225,12 @@ Run build to verify no syntax errors from the changes:
 cd jam-ui && npm run build
 ```
 
-Verify the changes work correctly by checking the expected behavior:
+The expected behavior after all changes:
-- When user selects a JamTrack, stems should NOT appear in session screen immediately
+1. User selects JamTrack
-- Stems should only appear after the track transitions to 'synchronized' state
+2. handleJamTrackSelect fetches data and calls checkJamTrackSync
-- Controls in player popup should also only appear after 'synchronized' state
+3. If already synchronized: downloadState='synchronized' → stems render immediately
+4. If not synchronized: downloadState='idle' → stems hidden, user sees loading
+5. When download completes: downloadState='synchronized' → stems appear
   </action>
   <verify>
 Build command exits with code 0 and no compilation errors.
@@ -161,15 +243,19 @@ Build command exits with code 0 and no compilation errors.
 <verification>
 1. Build check: `cd jam-ui && npm run build` completes without errors
 2. Code verification:
+   - JKSessionScreen.js imports checkJamTrackSync
+   - handleJamTrackSelect calls checkJamTrackSync BEFORE dispatching setSelectedJamTrack
    - 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>
+- handleJamTrackSelect calls checkJamTrackSync before dispatching UI state
 - 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
+- Already-synchronized JamTracks show stems/controls immediately (checkJamTrackSync returns synchronized)
+- Non-synchronized JamTracks don't show stems/controls until download completes
 - Build passes with no errors
 - UAT gap "Controls and stems should only appear after JamTrack is synchronized" is closed
 </success_criteria>

.planning/phases/26-jamtrack-polish/26-04-PLAN.md

@@ -0,0 +1,156 @@
+---
+phase: 26-jamtrack-polish
+plan: 04
+type: execute
+wave: 4
+depends_on: ["26-03"]
+files_modified:
+  - jam-ui/src/components/client/JKSessionScreen.js
+autonomous: true
+gap_closure: true
+
+must_haves:
+  truths:
+    - "User sees loading/progress indicators while JamTrack is being processed"
+    - "Non-synchronized JamTracks trigger the download flow automatically"
+    - "Already-synchronized JamTracks show controls immediately"
+  artifacts:
+    - path: "jam-ui/src/components/client/JKSessionScreen.js"
+      provides: "handleJamTrackSelect calls loadJamTrack when track is not synchronized"
+      contains: "loadJamTrack"
+  key_links:
+    - from: "handleJamTrackSelect"
+      to: "loadJamTrack thunk"
+      via: "dispatch call when syncResult.isSynchronized is false"
+      pattern: "dispatch\\(loadJamTrack"
+---
+
+<objective>
+Fix empty JamTrack player by triggering loadJamTrack when track is not synchronized.
+
+Problem: After plan 26-03, when checkJamTrackSync returns isSynchronized=false, the state stays 'idle'. The download banner only shows for 'checking/packaging/downloading/keying' states, and controls only show for 'synchronized'. With 'idle' state, nothing renders.
+
+Fix: If syncResult.isSynchronized is false, call loadJamTrack to start the download flow. This transitions state through 'checking' → 'packaging' → 'downloading' → 'keying' → 'synchronized', showing progress UI along the way.
+
+Output: JamTrack player shows proper loading progress for non-synchronized tracks.
+</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
+@jam-ui/src/components/client/JKSessionScreen.js (lines 1166-1204)
+@jam-ui/src/store/features/mediaSlice.js (loadJamTrack thunk)
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Call loadJamTrack when track is not synchronized</name>
+  <files>jam-ui/src/components/client/JKSessionScreen.js</files>
+  <action>
+In handleJamTrackSelect (around line 1166-1204), after checkJamTrackSync returns:
+- If `syncResult.isSynchronized` is true: show success toast (current behavior)
+- If `syncResult.isSynchronized` is false: call loadJamTrack to start download flow
+
+**Step 1: Import loadJamTrack**
+
+Check if loadJamTrack is already imported from mediaSlice (it may be). If not, add it to the imports.
+
+**Step 2: Modify handleJamTrackSelect**
+
+`loadJamTrack` is already available from `useMediaActions()` hook (line 153). It just takes the jamTrack object.
+
+Change the sync result handling (around lines 1194-1199) from:
+
+```javascript
+// Show appropriate message based on sync state
+if (syncResult.isSynchronized) {
+  toast.success(`Loaded JamTrack: ${jamTrackWithStems.name}`);
+} else {
+  toast.info(`Loading JamTrack: ${jamTrackWithStems.name}...`);
+}
+```
+
+To:
+
+```javascript
+// Handle sync result
+if (syncResult.isSynchronized) {
+  // Already synchronized - show success
+  toast.success(`Loaded JamTrack: ${jamTrackWithStems.name}`);
+} else {
+  // Not synchronized - start download flow
+  // This will transition state through checking → packaging → downloading → keying → synchronized
+  toast.info(`Loading JamTrack: ${jamTrackWithStems.name}...`);
+  loadJamTrack(jamTrackWithStems);
+}
+```
+
+Note: `loadJamTrack` is already destructured from `useMediaActions()` at line 153, so no additional imports are needed.
+  </action>
+  <verify>
+```bash
+# Verify loadJamTrack is imported
+grep -n "loadJamTrack" jam-ui/src/components/client/JKSessionScreen.js | head -5
+
+# Verify it's called in handleJamTrackSelect
+grep -A20 "const handleJamTrackSelect" jam-ui/src/components/client/JKSessionScreen.js | grep "loadJamTrack"
+```
+  </verify>
+  <done>handleJamTrackSelect calls loadJamTrack when track is not synchronized, triggering the download flow</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: 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
+```
+
+If build fails due to infrastructure issues (Node.js version, node-sass), verify syntax via babel parser instead.
+
+Expected behavior after fix:
+1. User selects non-synchronized JamTrack
+2. handleJamTrackSelect calls checkJamTrackSync → returns isSynchronized=false
+3. loadJamTrack is dispatched → state transitions to 'checking' (or 'packaging')
+4. Player opens and shows download banner: "Checking sync status..." or "Your JamTrack is currently being created..."
+5. Progress continues through 'packaging' → 'downloading' → 'keying' → 'synchronized'
+6. Once 'synchronized', controls appear
+  </action>
+  <verify>
+Build command exits with code 0 and no compilation errors, or babel parser confirms syntax is correct.
+  </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 imports loadJamTrack
+   - handleJamTrackSelect dispatches loadJamTrack when syncResult.isSynchronized is false
+3. Manual test: Select non-synchronized JamTrack → see loading progress → controls appear when synchronized
+</verification>
+
+<success_criteria>
+- handleJamTrackSelect calls loadJamTrack when syncResult.isSynchronized is false
+- Non-synchronized JamTracks trigger the download flow automatically
+- User sees loading/progress indicators while JamTrack is being processed
+- Build passes with no errors
+- UAT gap "User sees loading/progress indicators while JamTrack is being processed" is closed
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/26-jamtrack-polish/26-04-SUMMARY.md`
+</output>

.planning/phases/26-jamtrack-polish/26-UAT.md

@@ -1,9 +1,9 @@
 ---
-status: complete
+status: diagnosed
 phase: 26-jamtrack-polish
-source: [26-01-SUMMARY.md, 26-02-SUMMARY.md]
+source: [26-01-SUMMARY.md, 26-02-SUMMARY.md, 26-03-SUMMARY.md]
 started: 2026-02-25T13:50:00Z
-updated: 2026-02-25T14:00:00Z
+updated: 2026-02-25T18:05:00Z
 ---
 
 ## Current Test
@@ -21,10 +21,10 @@ notes: User manually adjusted dimensions to look good
 expected: In the JamTrack player, click the "create custom mix" link. A new browser tab should open with the JamTrack editor at /jamtracks/{id}.
 result: pass
 
-### 3. Controls deferred until track ready
+### 3. Controls and stems deferred until track ready (re-test after fix)
-expected: Select a JamTrack that needs downloading. You should see loading/download progress first, and the playback controls (play/stop/seek) should only appear AFTER the track is synchronized.
+expected: Select a JamTrack that needs downloading. You should see loading/download progress first. The playback controls (play/stop/seek) should only appear AFTER the track is synchronized. Stems should only appear in the session screen AFTER the track is synchronized.
 result: issue
-reported: "Not only I see the playback controls before the JamTrack been processed in the server, but I also see the tracks (stems) of that JamTrack been shown in the Session Screen. This is wrong."
+reported: "Now when I opened a JamTrack, I see the JamTrack player only with close button. Can not see any status or progress indicators of what's happening there."
 severity: major
 
 ### 4. No console warnings on close
@@ -41,12 +41,18 @@ skipped: 0
 
 ## Gaps
 
-- truth: "Controls and stems should only appear after JamTrack is synchronized"
+- truth: "User sees loading/progress indicators while JamTrack is being processed"
   status: failed
-  reason: "User reported: Not only I see the playback controls before the JamTrack been processed in the server, but I also see the tracks (stems) of that JamTrack been shown in the Session Screen. This is wrong."
+  reason: "User reported: Now when I opened a JamTrack, I see the JamTrack player only with close button. Can not see any status or progress indicators of what's happening there."
   severity: major
   test: 3
-  root_cause: ""
+  root_cause: "Plan 26-03 fix was too aggressive - checkJamTrackSync needs to trigger loading state, but downloadState may be staying in 'idle' instead of transitioning to a loading state that shows progress UI"
-  artifacts: []
+  artifacts:
-  missing: []
+    - path: "jam-ui/src/components/client/JKSessionScreen.js"
+      issue: "handleJamTrackSelect calls checkJamTrackSync but if track is not synchronized, no loading UI is triggered"
+    - path: "jam-ui/src/components/client/JKSessionJamTrackPlayer.js"
+      issue: "Download progress UI (lines 598-715) only shows for specific states - may not be showing for the state after checkJamTrackSync"
+  missing:
+    - "If checkJamTrackSync returns not synchronized, trigger loadJamTrack to start the download/packaging flow"
+    - "Ensure download state transitions to a state that shows progress UI (checking/packaging/downloading)"
   debug_session: ""