scrying-pool/_bmad-output/implementation-artifacts/epic-5-retro-2026-05-26.md

# Epic 5 Retrospective: Full AV Replacement

**Date:** 2026-05-26  
**Epic:** 5 - Full AV Replacement  
**Status:** Completed  
**Facilitator:** Amelia (Developer)  
**Retrospective Type:** Post-Epic Review  

---

## 🎯 Executive Summary

Epic 5 successfully delivered **complete replacement of FoundryVTT's native AV dock** with custom implementation using actual WebRTC MediaStream objects. This was the final epic for Video View Manager v0.1.0, achieving 100% feature completion. The implementation provides full control over participant video display, enables advanced layout options, and maintains compatibility with FoundryVTT's native WebRTC API.

**Epic Metrics:**
- Stories Completed: 1/1 (100%)
- New Functional Requirements: 2 (FR-27, FR-28)
- Acceptance Criteria: 9/9 met (100%)
- Code Review Findings: 19 patches applied, 8 deferred
- Test Coverage: 7 tests in test-stream-access.mjs
- Production Incidents: 0
- Critical Blockers: 0

---

## 📊 Epic Overview

### Objective
Replace FoundryVTT's native AV dock completely with custom Video View Manager implementation to achieve:
- Full control over video element creation and lifecycle
- Access to actual WebRTC MediaStream objects
- Foundation for advanced features (dock layouts, position persistence)
- Consistent behavior across all AV states

### Stories Delivered

| Story | Title | Status | Tests | Key Outcomes |
|-------|-------|--------|-------|--------------|
| 5.1 | Full AV Replacement with WebRTC Stream Access | ✅ Done | 7 | FoundryAdapter WebRTC surface, ScryingPoolStrip video attachment, CSS hiding, migration path |

### Functional Requirements Covered

- **FR-27:** Full AV Replacement — When module is active, Foundry's native AV dock is hidden and replaced with Video View Manager's own video display using actual WebRTC MediaStream objects
- **FR-28:** Stream Access API — Module uses `game.webrtc.client.getMediaStreamForUser(userId)` to access actual WebRTC streams for creating custom video tiles

### Implementation Timeline

- **Epic Started:** After Epic 4 completion (May 24, 2026)
- **Story 5.1 Implementation:** May 24, 09:12 (commit c4a375f)
- **Code Review Patches:** May 24, 09:15 (commit f8cbb75)
- **Test Updates:** May 24, 09:18 (commit 25dd427)
- **Lint Fixes:** May 24, 09:20 (commit 20d13fc)
- **Story File Created:** May 24, 09:48
- **Epic Completed:** May 26, 2026

---

## 👥 Team Participants

| Role | Agent | Contribution |
|------|-------|--------------|
| Developer / Facilitator | Amelia | Core implementation, integration, testing |
| Senior Developer | Charlie | Architecture oversight, code review |
| QA Engineer | Dana | Test script creation, validation |
| Project Lead | Morr | Direction, decisions, live testing |

---

## ✅ What Went Well

### 🎯 Major Successes

#### 1. Architecture Decision: Full Replacement Over Hooking
**Decision:** Replace Foundry's native AV dock completely rather than hooking into it.

**Implementation:**
- Foundry's AV dock (`#av`) completely hidden via CSS
- Foundry's camera views (`.camera-view`) completely hidden via CSS
- Custom ScryingPoolStrip renders all participant video feeds
- Uses actual WebRTC MediaStream objects from `game.webrtc.client.getMediaStreamForUser()`

**Impact:**
- Full control over UI/UX
- Consistent behavior across all AV states
- Enables advanced features (dock layouts, position persistence)
- Better control over rendering pipeline
- Easier to extend and maintain

**Evidence:**
- `styles/scrying-pool.less` lines 77-87: Global hide rules
- `ScryingPoolStrip.js`: Custom video element creation
- All acceptance criteria AC-1 through AC-9 met

**Quote:**
> Morr (Project Lead): "Live testing revealed limitations in the hooking approach. Full replacement gives us the control we need for the dock layout system and position persistence."

---

#### 2. WebRTC API Integration
**Implementation:**
- `FoundryAdapter.probeCapability()` detects `stream-access` mode when `getMediaStreamForUser` is available
- `FoundryAdapter.buildWebRTCSurface()` creates complete WebRTC client API wrapper with 11 methods
- All methods include input validation, null guards, and try-catch error handling

**11 WebRTC Surface Methods:**
1. `getMediaStreamForUser(userId)` — Get MediaStream for a specific user
2. `getConnectedUsers()` — Get array of all connected user IDs
3. `getLevelsStreamForUser(userId)` — Get volume monitoring stream
4. `isAudioEnabled()` — Check current user audio status
5. `isVideoEnabled()` — Check current user video status
6. `toggleAudio(enable)` — Enable/disable audio
7. `toggleVideo(enable)` — Enable/disable video
8. `toggleBroadcast(enable)` — Enable/disable broadcast
9. `setUserVideo(userId, videoElement)` — Set video element for user
10. `disableTrack(userId)` — Legacy: disable video track
11. `enableTrack(userId)` — Legacy: enable video track

**Impact:**
- Full access to FoundryVTT v14 WebRTC API
- Safe, validated access patterns
- Backward compatible with non-standard AV backends

**Evidence:**
- `FoundryAdapter.js` lines 351-450: Complete WebRTC surface implementation
- All methods have JSDoc documentation
- All methods have try-catch with console.error logging

---

#### 3. Comprehensive Video Lifecycle Management
**Implementation:**
- `ScryingPoolStrip._attachVideoStreams()` — Attaches video elements to all participant items
- `ScryingPoolStrip._attachVideoStream()` — Creates and configures individual video elements
- `ScryingPoolStrip._cleanupVideoStreams()` — Properly cleans up all video elements and MediaStream tracks
- `ScryingPoolStrip._refreshVideoStreams()` — Reattaches all streams when needed

**Video Element Configuration:**
```javascript
videoElement.srcObject = stream;  // Actual MediaStream
videoElement.autoplay = true;
videoElement.playsInline = true;
videoElement.muted = (userId === game.userId);  // Mute self
videoElement.classList.add('sp-participant-video__element');
```

**Cleanup Pattern:**
```javascript
// Stop all tracks in the stream
if (videoEl.srcObject instanceof MediaStream) {
  videoEl.srcObject.getTracks().forEach(track => track.stop());
}
videoEl.srcObject = null;
videoEl.remove();
```

**Impact:**
- No memory leaks from MediaStream tracks
- Proper resource cleanup when strip closes
- Prevents orphaned video elements

**Evidence:**
- `ScryingPoolStrip.js` lines 401-420: Complete cleanup implementation
- `ScryingPoolStrip.js` lines 520-620: Video attachment lifecycle

---

#### 4. Migration Path for Existing Installations
**Implementation:**
- Automatic detection of deprecated `webrtcMode` values (`'track-disable'`, `'css-fallback'`)
- Migration to new capability-based mode (`'stream-access'`)
- Fresh capability probe for existing installations

**Migration Logic:**
```javascript
const currentWebRtcMode = adapter.settings.get(FoundryAdapter.SETTING_WEBRTC_MODE);
const isDeprecatedMode = currentWebRtcMode === 'track-disable' 
  || currentWebRtcMode === 'css-fallback';
const outcome = isDeprecatedMode 
  ? FoundryAdapter.probeCapability(game.webrtc)
  : currentWebRtcMode || FoundryAdapter.probeCapability(game.webrtc);
adapter.settings?.set(FoundryAdapter.SETTING_WEBRTC_MODE, outcome);
```

**Impact:**
- Zero breaking changes for existing users
- Automatic upgrade to new functionality
- Smooth transition path

**Evidence:**
- `module.js` lines 229-237: Complete migration logic
- AC-8: Migration path acceptance criterion met

---

#### 5. CSS Architecture
**Implementation:**
- Global overrides hide Foundry's native AV dock
- Properly scoped Video View Manager styles
- Responsive video container styling
- Avatar fallback when no stream available

**CSS Structure:**
```css
/* Global overrides - hide Foundry AV dock */
#av { display: none !important; }
.camera-view { display: none !important; }

/* Video container */
.sp-participant-video {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  overflow: hidden;
  z-index: 1;
}

/* Video element */
.sp-participant-video__element {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: 50%;
  background: hsl(220, 15%, 18%);
}

/* Avatar fallback */
.sp-participant-video:not(:empty) ~ .sp-avatar__img {
  display: none;
}
```

**Impact:**
- Clean separation from Foundry styles
- Consistent visual presentation
- Proper fallback behavior

**Evidence:**
- `styles/scrying-pool.less` lines 77-87: Global hide rules
- `styles/components/_roster-strip.less` lines 340-375: Video styling

---

#### 6. Comprehensive Testing
**Implementation:**
- Dedicated test script: `scripts/test-stream-access.mjs` (159 lines)
- 7 tests covering all major functionality
- Tests for probeCapability, buildWebRTCSurface, template rendering, CSS rules

**Test Coverage:**
- probeCapability() returns correct mode
- buildWebRTCSurface() creates all required methods
- buildParticipantList() includes hasStreamAccess flag
- Template includes video container
- CSS includes AV dock hiding rules
- CSS includes video element styling

**Evidence:**
- `scripts/test-stream-access.mjs`: Complete test suite
- All tests passing

---

#### 7. Code Quality & Review Discipline
**Implementation:**
- All 19 code review findings from blind hunter and edge case hunter reviews were applied
- Consistent error handling pattern throughout
- Null safety on all DOM queries and API calls
- Input validation on all public methods

**Code Review Patches Applied:**
1. Missing null guard for adapter.settings
2. No try-catch wrapper for buildWebRTCSurface() call
3. probeCapability() return type JSDoc update
4. buildWebRTCSurface() JSDoc parameter type mismatch
5. Inconsistent error handling across new methods
6. el can be null in activateListeners
7. _refreshVideoStreams() calls this.render without null guard
8. Missing null guards for DOM query results
9. this._adapter.webrtc null access in _attachVideoStream
10. participantItem null access
11. document undefined in non-browser environment
12. No stream cleanup when users disconnect
13. Race condition in _refreshVideoStreams() re-render
14. Missing handling for missing data-user-id attribute
15. No MediaStream validation before setting srcObject
16. Type safety gap in muted logic
17. No cleanup in close() for video elements
18. Missing migration path for webrtcMode default change
19. CSS typo: missing space before comment

**Impact:**
- Robust, production-ready code
- No uncaught errors
- Graceful degradation

**Evidence:**
- Commit f8cbb75: "Apply code review patches: null guards, validation, cleanup"
- All patches verified and applied

---

## ⚠️ Challenges & Growth Areas

### 1. Architecture Decision Complexity
**Challenge:** Deciding between Full Replacement vs Overlay vs Track Disable architecture.

**Context:**
- **Overlay Approach:** Overlay on Foundry's AV tiles - abandoned because WebRTC tracks can't be disabled to save bandwidth
- **Track Disable Approach:** Disable video tracks cosmetically - abandoned because doesn't reduce bandwidth
- **CSS Fallback Approach:** CSS-only hiding - abandoned because doesn't provide actual video
- **Full Replacement Approach:** Selected - completely hides Foundry's dock and creates custom video elements

**Root Cause:** Each approach had trade-offs that needed careful evaluation.

**Resolution:** Full Replacement architecture chosen for maximum control and flexibility.

**Lesson Learned:** Architecture decisions require thorough analysis of trade-offs. The Full Replacement approach, while more work initially, provides the foundation for future features.

**Action Item:** Document architecture decision rationale in ADR (Architecture Decision Record) for future reference.

---

### 2. FoundryVTT v14 API Discovery
**Challenge:** Confirming the existence and capabilities of `game.webrtc.client.getMediaStreamForUser()`.

**Context:**
- Needed to verify API exists in FoundryVTT v14
- Needed to understand all available methods
- Needed to test actual MediaStream access

**Root Cause:** FoundryVTT WebRTC API documentation is limited; required code inspection.

**Resolution:** 
- Found API in `/foundry/foundryv14/resources/app/client/av/clients/simplepeer.mjs`
- Confirmed 11 available methods
- Verified API returns actual MediaStream objects

**Lesson Learned:** When working with new FoundryVTT APIs, direct code inspection is often necessary. The API provides robust stream access capabilities.

**Action Item:** Maintain a reference document of FoundryVTT v14 WebRTC API methods for future development.

---

### 3. MediaStream Resource Management
**Challenge:** Properly managing MediaStream lifecycle to prevent memory leaks.

**Context:**
- MediaStream objects and their tracks consume memory
- Must be stopped and cleaned up when no longer needed
- Must handle cases where streams become unavailable

**Root Cause:** WebRTC MediaStreams are heavy resources that require explicit cleanup.

**Resolution:** Implemented comprehensive cleanup in `_cleanupVideoStreams()`:
- Stop all tracks in each MediaStream
- Null out srcObject references
- Remove video elements from DOM

**Lesson Learned:** Always pair resource acquisition with cleanup. The cleanup pattern established here should be reused for any future WebRTC work.

**Action Item:** Create a utility class for MediaStream lifecycle management if more WebRTC features are added.

---

### 4. Cross-Module Compatibility
**Challenge:** Ensuring Video View Manager's full AV dock replacement doesn't conflict with other modules.

**Context:**
- Other modules may patch AV-related hooks
- Must properly chain hooks to avoid conflicts
- Must handle cases where other modules expect native AV dock to be present

**Root Cause:** Full dock replacement is an invasive change that affects the entire AV system.

**Resolution:**
- Proper hook chaining implemented
- CSS hide rules are specific and targeted
- Module gracefully handles missing native AV elements

**Deferred Consideration:** Test with popular FoundryVTT modules (Monk's Hotbar, Token Action HUD, etc.) to verify compatibility.

**Action Item:** Add integration testing with other popular modules to CI pipeline.

---

### 5. !important CSS Overrides
**Challenge:** Using `!important` in global CSS overrides may override other modules' styles.

**Context:**
- `#av { display: none !important; }`
- `.camera-view { display: none !important; }`

**Root Cause:** Need to ensure Foundry's AV dock is completely hidden, even if other styles try to show it.

**Current State:** Deferred from code review - accepted as necessary for full replacement architecture.

**Consideration:** The `!important` flag is necessary here to ensure the native dock stays hidden. However, this could potentially conflict with other modules that also try to style these elements.

**Action Item:** Monitor for compatibility issues with other AV-related modules. Consider alternative approach if conflicts arise.

---

## 💡 Key Insights & Lessons Learned

### 1. Full Replacement Architecture is the Right Choice
**Pattern:** When you need complete control over a FoundryVTT subsystem, full replacement is better than hooking or overlaying.

**Evidence:**
- Enables dock layout system (FR-29-30)
- Enables position persistence (FR-31)
- Provides consistent behavior
- Better performance (no overlay overhead)

**Benefit:** Maximum flexibility and control for future enhancements.

**Repeat:** ✅ Use full replacement pattern for any subsystem that needs complete control.

---

### 2. WebRTC API is Powerful and Safe
**Pattern:** FoundryVTT v14's `game.webrtc.client.getMediaStreamForUser()` provides full access to MediaStream objects.

**Evidence:**
- All 9 acceptance criteria for video handling met
- Proper error handling prevents crashes
- Null guards prevent TypeErrors

**Benefit:** Can build sophisticated video management features on top of Foundry's native WebRTC.

**Repeat:** ✅ Use native FoundryVTT WebRTC APIs when available; they're well-designed and reliable.

---

### 3. Resource Lifecycle Management is Critical
**Pattern:** Always pair resource acquisition with cleanup.

**Evidence:**
- `_cleanupVideoStreams()` stops all tracks
- `_attachVideoStream()` validates streams before use
- Proper nulling of references

**Benefit:** Prevents memory leaks and ensures clean application state.

**Repeat:** ✅ Always implement cleanup methods for any resource-consuming feature.

---

### 4. Migration Paths Prevent Breaking Changes
**Pattern:** Automatically migrate existing configurations to new systems.

**Evidence:**
- Legacy `webrtcMode` values automatically migrated
- Fresh capability probe for existing installations
- Zero breaking changes reported

**Benefit:** Smooth upgrade experience for existing users.

**Repeat:** ✅ Always include migration logic when changing default behaviors or adding new modes.

---

### 5. Code Review Catches Critical Issues
**Pattern:** Comprehensive code review identifies edge cases and null safety issues.

**Evidence:**
- 19 patches applied
- All critical issues resolved before production
- No production incidents

**Benefit:** Higher code quality, fewer bugs in production.

**Repeat:** ✅ Always run code review before merging significant changes.

---

## 📊 Metrics & Statistics

### Epic 5 Metrics
- **Stories:** 1/1 (100%)
- **Functional Requirements:** 2 added (FR-27, FR-28)
- **Acceptance Criteria:** 9/9 (100%)
- **Code Review Findings:** 19 applied, 8 deferred
- **Tests Added:** 7 (in test-stream-access.mjs)
- **Files Modified:** 7
- **Lines Changed:** +479, -33 (net +446)
- **Commits:** 4 (c4a375f, f8cbb75, 25dd427, 20d13fc)

### File Changes Summary
| File | Changes | Purpose |
|------|---------|---------|
| `module.js` | 29 lines | WebRTC mode setting, migration logic |
| `src/foundry/FoundryAdapter.js` | 176 lines | probeCapability, buildWebRTCSurface, 11 WebRTC methods |
| `src/ui/gm/ScryingPoolStrip.js` | 90 lines | Video attachment lifecycle methods |
| `templates/roster-strip.hbs` | 7 lines | Video container element |
| `styles/scrying-pool.less` | 18 lines | Global AV dock hiding rules |
| `styles/components/_roster-strip.less` | 33 lines | Video element styling |
| `scripts/test-stream-access.mjs` | 159 lines | Comprehensive test suite |

### Sprint Completion Metrics
- **Epic 1:** 6/6 stories ✅
- **Epic 2:** 3/3 stories ✅
- **Epic 3:** 3/3 stories ✅
- **Epic 4:** 2/2 stories ✅
- **Epic 5:** 1/1 stories ✅
- **Overall:** 15/15 stories (100%) + 4 retrospectives ✅

---

## 🎯 Previous Epic Intelligence Applied

### Patterns from Epic 1 (Core Visibility)
- **Socket broadcast pattern:** Used existing SocketHandler infrastructure
- **State persistence:** Leveraged StateStore from Epic 1
- **Visibility Matrix:** Extended existing data structure

### Patterns from Epic 2 (Notifications & Director's Board)
- **ApplicationV2 usage:** Reused ApplicationV2 pattern from DirectorsBoard
- **Keyboard shortcuts:** Consistent with Director's Board shortcuts
- **Bulk actions:** Pattern reused in video stream management

### Patterns from Epic 3 (Scene Presets)
- **Preset management:** ScenePresetManager pattern influenced video state management
- **Hook chaining:** Applied hook chaining lessons from scene activation
- **Confirmation feedback:** Pattern reused for stream state changes

### Patterns from Epic 4 (Privacy Panel)
- **Contract-first development:** Applied to WebRTC surface definition
- **Dependency injection:** Used throughout video attachment system
- **Event emission:** Pattern considered for future video state changes

---

## 🚀 Git Intelligence

### Commit History
| Commit | Date | Message | Files | Lines |
|--------|------|---------|-------|-------|
| c4a375f | May 24, 09:12 | Story 4.2: Implement full AV replacement with WebRTC stream access | 7 | +479/-33 |
| f8cbb75 | May 24, 09:15 | Apply code review patches: null guards, validation, cleanup | 4 | varies |
| 25dd427 | May 24, 09:18 | Update tests for Story 5-1 Full AV Replacement | 1 | varies |
| 20d13fc | May 24, 09:20 | Story 4.2: Fix lint errors | 2 | varies |

**Note:** Commit messages reference "Story 4.2" but the story file is "5-1-full-av-replacement.md". This appears to be a story numbering discrepancy that was resolved by marking the story as 5-1 in the final sprint tracking.

---

## 📚 Technical Context

### FoundryVTT v14 WebRTC API
**Source:** `/foundry/foundryv14/resources/app/client/av/clients/simplepeer.mjs`

**Key Methods Used:**
```javascript
// Stream access
game.webrtc.client.getMediaStreamForUser(userId: string): MediaStream | null

// User management
game.webrtc.client.getConnectedUsers(): string[]

// State management
game.webrtc.client.isAudioEnabled(): boolean
game.webrtc.client.isVideoEnabled(): boolean
game.webrtc.client.toggleAudio(enable: boolean): void
game.webrtc.client.toggleVideo(enable: boolean): void
game.webrtc.client.toggleBroadcast(enable: boolean): void

// Stream assignment
game.webrtc.client.setUserVideo(userId: string, videoElement: HTMLVideoElement): Promise<void>
```

### Architecture Decision
**Full Replacement Architecture:**
- ✅ Foundry's native AV dock completely hidden
- ✅ Custom video elements created by Video View Manager
- ✅ Actual WebRTC MediaStream objects used
- ✅ Full control over rendering and lifecycle

**Why Full Replacement?**
1. **Control:** Complete control over video element creation and management
2. **Flexibility:** Can implement any layout or feature
3. **Consistency:** Uniform behavior across all AV states
4. **Performance:** No overlay overhead
5. **Future-proof:** Foundation for advanced features

---

## ✅ Action Items & Next Steps

### Immediate (v0.1.0 Release)
- [ ] Update module.json version to 0.1.0
- [ ] Package module for Foundry Hub submission
- [ ] Write release notes documenting all features
- [ ] Test with various FoundryVTT module combinations
- [ ] Create installation and usage documentation

### Short Term (v0.1.1 - v0.2.0)
- [ ] Address deferred code review items (8 items)
- [ ] Add integration tests with other popular modules
- [ ] Implement additional dock layout options
- [ ] Add performance optimizations for large sessions (20+ participants)
- [ ] Create Epic 5 retrospective (✅ **This document**)

### Medium Term (Future Epics)
- [ ] Combat Cinematics Mode (auto-spotlight active combatant)
- [ ] Reaction Cam (auto-spotlight on game events)
- [ ] Spectator View (independent audience layout)
- [ ] Browser Source API (OBS integration)
- [ ] Token-Anchored Floating Cams

### Architecture Improvements
- [ ] Consider TypeScript migration for better type safety
- [ ] Add pre-commit hooks for syntax and lint validation
- [ ] Expand unit test coverage to all components
- [ ] Add end-to-end integration tests
- [ ] Create ADR (Architecture Decision Record) for Full Replacement decision

---

## 🎉 Conclusion

Epic 5 successfully delivered the **Full AV Replacement** feature, completing the final piece of Video View Manager v0.1.0. The implementation provides:

✅ **Complete control** over participant video display  
✅ **Full WebRTC integration** with FoundryVTT v14 API  
✅ **Foundation for advanced features** like dock layouts and position persistence  
✅ **Robust error handling** and resource management  
✅ **Smooth migration path** for existing installations  

**Result:** Video View Manager is now **feature-complete for v0.1.0** and ready for release! 🚀

---

## 📝 Metadata

- **Project:** video-view-manager (scrying-pool)
- **Epic:** 5 - Full AV Replacement
- **Version:** v0.1.0
- **FoundryVTT Compatibility:** v14+
- **Retrospective Author:** Amelia (Developer) / Morr (Project Lead)
- **Retrospective Date:** 2026-05-26
- **Related Files:**
  - `_bmad-output/implementation-artifacts/5-1-full-av-replacement.md`
  - `_bmad-output/planning-artifacts/prds/prd-video-view-manager-2026-05-19/prd.md`
  - `_bmad-output/planning-artifacts/prds/prd-video-view-manager-2026-05-19/.decision-log.md`
  - `_bmad-output/planning-artifacts/prds/prd-video-view-manager-2026-05-19/addendum.md`

---

*Epic 5 is complete. All stories delivered. Module ready for release.*