# v1.6 Media Features Polish - Research Summary

**Synthesized:** 2026-02-25
**Research Files:** METRONOME-UI.md, JAMTRACK-LOADING.md, BACKINGTRACK-SYNC.md, PERFORMANCE-AUDIT.md

## Executive Summary

Research across four domains reveals that v1.6 issues fall into three categories: **integration gaps** (missing track sync), **sequence bugs** (premature UI rendering), and **performance issues** (blocking callbacks, missing cleanup). Most fixes follow patterns established in v1.4/v1.5.

| Category | Issue | Root Cause | Fix Complexity |
|----------|-------|------------|----------------|
| JamTrack | Freeze on play | Premature UI rendering | MEDIUM |
| JamTrack | Doesn't fit WindowPortal | Hardcoded size mismatch | LOW |
| JamTrack | Create custom mix | Missing navigation | LOW |
| Backing Track | Doesn't sync to session | Missing track sync call | LOW |
| Metronome | Sluggish controls | Blocking await in onChange | MEDIUM |
| Metronome | "about:blank" URL | Browser security (UNFIXABLE) | N/A |
| Performance | JamTrack callback leak | No cleanup for window.* callbacks | MEDIUM |
| Performance | Backing Track async | Missing ignore flag | LOW |

## Key Findings by Feature

### 1. JamTrack Loading Sequence

**Problem:** User selects JamTrack → Stems appear immediately → User clicks play → "Checking sync status..." → Freeze

**Root Cause:** `handleJamTrackSelect()` in JKSessionScreen.js dispatches UI state (`setSelectedJamTrack`, `setJamTrackStems`) BEFORE backend processing (packaging 5-30s → downloading 10-60s → keying 1-5s).

**Fix:** Defer UI rendering until `loadJamTrack()` thunk completes:
1. Show loading indicator during backend processing
2. Only dispatch UI state after track is synchronized
3. Change conditional rendering to require `state === 'synchronized'` (not `idle`)

**WindowPortal sizing:** Window is 600x500 but player content is 420px wide. Fix: reduce to 460x350.

**Create custom mix:** Currently `console.log('TODO')`. Fix: `window.open('/jamtracks/{id}', '_blank')`.

### 2. Backing Track Sync

**Problem:** Backing Track opens in popup but doesn't appear in session screen.

**Root Cause:** `handleBackingTrackSelected()` calls `jamClient.SessionOpenBackingTrackFile()` directly instead of `openBackingTrack()` action from useMediaActions.js.

**Why it matters:** `openBackingTrack()` includes track sync:
```javascript
// useMediaActions.js line 41-60
const openBackingTrack = async (filePath) => {
  await jamClient.SessionOpenBackingTrackFile(filePath, false);
  updateMediaSummary({ backingTrackOpen: true });
  dispatch(syncTracksToServer(sessionId, jamClient));  // ← This is missing!
};
```

**Fix:** Use existing `openBackingTrack()` action instead of direct jamClient call. Pattern matches working Metronome flow.

### 3. Metronome Controls

**Problem:** Controls feel sluggish when adjusting BPM/sound/meter.

**Root Cause:** `handleBpmChange` (and similar handlers) use `await jamClient.SessionSetMetronome()` directly in onChange handler. When user drags slider, every pixel change triggers a blocking native client call (50-200ms each).

**Fix:** Debounce native client calls with 300ms timeout:
```javascript
// Update local state immediately, debounce jamClient call
setBpm(numValue);
clearTimeout(pendingRef.current);
pendingRef.current = setTimeout(() => {
  jamClient.SessionSetMetronome(...);
}, 300);
```

**"about:blank" URL bar:** CANNOT be fixed. Browser security prevents hiding URL bar in popup windows. WindowPortal uses `window.open('', '_blank', ...)` which creates about:blank document. Flags like `location=no` are deprecated/ignored in modern browsers.

**Options:**
- Keep WindowPortal (consistent with JamTrack, BackingTrack, Chat)
- Switch to Modal (removes URL bar but blocks main window, can't reposition)
- Recommend: Document limitation, keep WindowPortal for consistency

### 4. Performance Audit

**Critical Issues:**

1. **JamTrack callback leak** (mediaSlice.js):
   - `window.jamTrackDownloadProgress`, `window.jamTrackDownloadSuccess`, `window.jamTrackDownloadFail` are set but never cleaned up
   - Multiple JamTracks or navigation during download leaks callbacks
   - Fix: Use `callbacksRef` pattern from useRecordingHelpers

2. **Metronome sluggishness** (addressed in section 3 above)

3. **Backing Track missing ignore flag** (JKSessionBackingTrackPlayer.js):
   - Duration fetch useEffect lacks ignore flag
   - May set state after unmount if fetch is slow
   - Fix: Add `let ignore = false; return () => { ignore = true; };`

**Non-Issues (already clean):**
- Timer/interval cleanup: Backing Track and JamTrack both clean up properly
- Unbounded arrays: None found, Redux state properly bounded
- Visibility tracking: All three components have it

## Scoping Recommendations

### Must Fix (User-reported issues)

| ID | Issue | Effort |
|----|-------|--------|
| JT-01 | JamTrack freeze on play (defer UI rendering) | 2-3 hours |
| JT-02 | JamTrack WindowPortal size | 5 minutes |
| JT-03 | Create custom mix navigation | 5 minutes |
| BT-01 | Backing Track sync to session | 1-2 hours |
| MET-01 | Metronome sluggish controls (debounce) | 1 hour |

### Should Fix (Performance/stability)

| ID | Issue | Effort |
|----|-------|--------|
| PERF-01 | JamTrack callback cleanup | 1-2 hours |
| PERF-02 | Backing Track ignore flag | 30 minutes |

### Won't Fix (Browser limitations)

| ID | Issue | Reason |
|----|-------|--------|
| MET-URL | "about:blank" URL bar | Browser security constraint, cannot be changed |

## Recommended Phases

**Phase 26: Fix JamTrack Loading**
- JT-01: Defer UI rendering
- JT-02: WindowPortal sizing
- JT-03: Create custom mix link
- PERF-01: Callback cleanup

**Phase 27: Fix Backing Track Sync**
- BT-01: Use openBackingTrack() action
- PERF-02: Ignore flag for async

**Phase 28: Fix Metronome Controls**
- MET-01: Debounce native client calls
- Document WindowPortal URL limitation

## Technical Decisions to Confirm

1. **Metronome WindowPortal vs Modal**: Keep WindowPortal for consistency? (Recommended: Yes)
2. **JamTrack loading indicator location**: Modal or toast? (Research suggests toast)
3. **Debounce timing**: 300ms for all controls? (Standard for responsive UI)

## Sources

- METRONOME-UI.md: WindowPortal analysis, existing styling audit
- JAMTRACK-LOADING.md: Loading sequence breakdown, root cause identification
- BACKINGTRACK-SYNC.md: Track sync flow comparison with Metronome
- PERFORMANCE-AUDIT.md: Cleanup pattern compliance, sluggishness analysis

---
*Research synthesis complete. Ready for requirements definition.*
