---
phase: 03-backing-track-finalization
type: execute
---

<objective>
Complete volume and loop controls implementation and resolve UAT-003 (seek while paused limitation) from Phase 2.

Purpose: Finalize all playback controls with proper jamClient integration and resolve or document the seek-while-paused limitation discovered during Phase 2 UAT testing.

Output: Fully functional volume and loop controls with correct jamClient methods, and UAT-003 either fixed with working seek-while-paused or documented as known jamClient limitation.
</objective>

<execution_context>
@./.claude/get-shit-done/workflows/execute-phase.md
@./.claude/get-shit-done/templates/summary.md
@./.claude/get-shit-done/references/checkpoints.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-backing-track-playback-monitoring/01-01-SUMMARY.md
@.planning/phases/02-backing-track-seek-controls/02-01-SUMMARY.md
@.planning/phases/02-backing-track-seek-controls/02-01-ISSUES.md
@jam-ui/src/components/client/JKSessionBackingTrackPlayer.js

**Key patterns from Phase 2:**
- jamClient methods return Promises - always use async/await
- jamClient returns string values - always parseInt() before math operations
- Never store jamClient in Redux state - pass as prop
- End-of-track requires SessionStopPlay() reset before new playback

**Deferred issue from Phase 2:**
- UAT-003: Seek while paused doesn't register with jamClient
- Severity: Minor (seek during playback works perfectly)
- Need to investigate and either fix or document as limitation

**Current implementation gaps:**
- Volume handler has conditional fallbacks (SetBackingTrackVolume vs SetMixerVolume) - lines 182-187
- Loop handler conditionally checks SessionSetBackingTrackLoop existence - lines 200-202
- Both need research to find correct jamClient methods
</context>

<tasks>

<task type="auto">
  <name>Task 1: Research and finalize volume/loop controls</name>
  <files>jam-ui/src/components/client/JKSessionBackingTrackPlayer.js</files>
  <action>Research correct jamClient methods for volume and loop controls by:

1. Check jamClient available methods (grep jamClient codebase or console.log jamClient keys)
2. Look at legacy web implementation in web/app/assets/javascripts/ for backing track volume/loop patterns
3. Test which methods actually work with backing tracks

For volume (lines 172-191):
- Current code has conditional fallbacks to SetBackingTrackVolume or SetMixerVolume
- Determine the correct method and remove fallback logic
- Ensure 0-100 slider value converts to correct range for jamClient
- Add proper error handling with specific error messages

For loop (lines 193-206):
- Current code conditionally checks SessionSetBackingTrackLoop existence
- Verify this is the correct method or find alternative
- Remove conditional existence check if method is confirmed
- Add proper error handling

Test both controls thoroughly:
- Volume: 0%, 50%, 100% - verify audio level changes
- Loop: Enable loop, play to end, verify restart
- Ensure no console errors from undefined methods</action>
  <verify>
- Volume slider changes audio level smoothly (0-100%)
- Loop checkbox enables/disables track looping
- No console errors about undefined methods
- No conditional fallback code remains (clean implementation)
  </verify>
  <done>Volume and loop controls use correct jamClient methods without fallbacks, properly tested and working</done>
</task>

<task type="auto">
  <name>Task 2: Investigate UAT-003 seek while paused limitation</name>
  <files>jam-ui/src/components/client/JKSessionBackingTrackPlayer.js</files>
  <action>Investigate UAT-003 from Phase 2 (seek while paused doesn't take effect):

**Background from Phase 2 UAT:**
- When paused at position A, dragging slider to position B updates UI but seek doesn't register
- On resume, plays from position A (not B), then on next play starts from B
- Appears jamClient.SessionTrackSeekMs() doesn't register when track is paused

**Investigation approaches to try:**

1. **Force position sync after seek:**
   - After SessionTrackSeekMs(), call SessionCurrrentPlayPosMs() and verify position changed
   - If position didn't change, try calling SessionStopPlay() then SessionTrackSeekMs()

2. **State machine approach:**
   - When paused, store seeked position in React state
   - On resume (handlePlay), seek to stored position before calling SessionStartPlay()
   - Clear stored position once applied

3. **Check jamClient state:**
   - Log jamClient.isSessionTrackPlaying() during seek while paused
   - Check if jamClient has "seek to position on next play" method

4. **Test SessionTrackSeekMs parameters:**
   - Verify we're passing correct position format (integer milliseconds)
   - Try seeking while playing, verify it works, compare with paused behavior

Add detailed logging with [BTP-UAT003] prefix to track what's happening:
- Log before/after seek position
- Log jamClient state (playing/paused)
- Log SessionTrackSeekMs() call and return value

Document findings in code comments for next task.</action>
  <verify>
- Add diagnostic logging for seek-while-paused behavior
- Test multiple approaches to make seek work while paused
- Document which approaches work/don't work in code comments
  </verify>
  <done>UAT-003 thoroughly investigated with multiple approaches tested and results documented in code</done>
</task>

<task type="checkpoint:decision" gate="blocking">
  <decision>How to handle UAT-003 (seek while paused limitation)</decision>
  <context>After investigation in Task 2, we need to decide how to proceed with UAT-003 based on findings.

**Background:** Phase 2 UAT discovered that seeking while paused doesn't take effect until next play cycle. Seeking during playback works perfectly. This is minor severity since most users seek while playing.

**Investigation completed in Task 2** should reveal whether:
- Fix is possible (workaround found that makes seek-while-paused work)
- Fix is not possible (jamClient limitation, no workaround)
</context>
  <options>
    <option id="fix">
      <name>Implement fix from Task 2 investigation</name>
      <pros>Best UX - seek works in all scenarios, consistency, user expectations met</pros>
      <cons>May require workaround code, potential edge cases to handle, more testing needed</cons>
    </option>
    <option id="document">
      <name>Document as known limitation</name>
      <pros>Clean code without workarounds, matches jamClient behavior, fast to complete</pros>
      <cons>Slightly degraded UX for seek-while-paused use case, users must adapt workflow</cons>
    </option>
  </options>
  <resume-signal>Based on Task 2 investigation results, select: "fix" or "document"</resume-signal>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] Volume control works smoothly (0-100%)
- [ ] Loop control enables/disables looping correctly
- [ ] No conditional fallback code in volume/loop handlers
- [ ] UAT-003 investigation completed with findings documented
- [ ] Decision made on UAT-003 resolution approach
- [ ] If "fix" selected: Fix implemented and tested
- [ ] If "document" selected: Limitation documented in code/ISSUES.md
- [ ] No console errors from volume/loop/seek operations
</verification>

<success_criteria>

- Volume and loop controls use correct jamClient methods
- All conditional fallbacks removed (clean implementation)
- UAT-003 thoroughly investigated with approaches tested
- UAT-003 either fixed with working implementation or documented as limitation
- All changes committed with descriptive messages
- Ready for Plan 03-02 (error handling)
</success_criteria>

<output>
After completion, create `.planning/phases/03-backing-track-finalization/03-01-SUMMARY.md`:

# Phase 3 Plan 1: Controls Completion & UAT-003 Resolution Summary

**Finalized volume/loop controls and resolved UAT-003 seek-while-paused limitation**

## Accomplishments

- Researched and implemented correct jamClient methods for volume/loop
- Removed conditional fallback code from handlers
- Investigated UAT-003 with multiple approaches
- [Either: Implemented fix for seek-while-paused | Or: Documented as jamClient limitation]

## Files Created/Modified

- `jam-ui/src/components/client/JKSessionBackingTrackPlayer.js` - Volume/loop finalization, UAT-003 resolution

## Decisions Made

- Volume control: [Which method used and why]
- Loop control: [Which method used and why]
- UAT-003 resolution: [Fix or document decision and rationale]

## Issues Encountered

[Any issues during investigation/implementation, or "None"]

## Next Phase Readiness

Ready for Plan 03-02 (Error Handling & Resilience). All controls finalized, UAT-003 resolved.
</output>
