scrying-pool/_bmad-output/planning-artifacts/prds/prd-video-view-manager-2026-05-19/.decision-log.md

# Decision Log — Video View Manager PRD

**Workspace:** `_bmad-output/planning-artifacts/prds/prd-video-view-manager-2026-05-19/`
**Created:** 2026-05-19
**Author:** Morr
**Last Updated:** 2026-05-26

---

## Decisions

### D-1 — PRD scope: full vision with roadmap
**Date:** 2026-05-19
**Decision:** PRD covers full product vision across all 3 priority tiers. v1.0 = Day 1 + Week 1–2 features (FR-1 through FR-26). Later-tier features are documented in §10 as a roadmap, not as FRs.
**Rationale:** User selected "Full vision PRD" during working mode selection.
**Status:** Captured in §10 Product Roadmap. **UPDATED:** Expanded to include FR-27 through FR-32 from live testing.

### D-2 — WebRTC track disabling preferred
**Date:** 2026-05-19
**Decision:** Real WebRTC track disabling is the preferred visibility implementation. CSS/DOM cosmetic hiding is the fallback. The choice is surfaced at runtime via a module config flag.
**Rationale:** User selected "Real WebRTC track disabling preferred" during working mode selection.
**Status:** Captured in FR-7. OQ-1 is the open research question to confirm feasibility.

### D-3 — FoundryVTT v14 minimum; no v13 backport
**Date:** 2026-05-19
**Decision:** Module targets FoundryVTT v14+ exclusively. No v13 compatibility.
**Rationale:** User selected "v14 only" during working mode selection.
**Status:** Captured in §5 Non-Goals and §6 MVP Scope.

### D-4 — Public community release (Foundry Hub)
**Date:** 2026-05-19
**Decision:** Module is intended for public listing on Foundry Hub / FoundryVTT package repository. PRD rigor calibrated to medium stakes (public community release).
**Rationale:** User selected "Public FoundryVTT module release" during stakes calibration.
**Status:** Informs Success Metrics (SM-1, SM-2) and Cross-Cutting NFRs (compatibility, privacy).

### D-5 — Progressive Enhancement Architecture as structural principle
**Date:** 2026-05-19
**Decision:** The module's UI and feature set is organized around 3 levels: Level 1 (right-click, zero new UI), Level 2 (Director's Board popout), Level 3 (Scene Presets + automation). Features are additive; Level 1 alone is a shippable product.
**Rationale:** From brainstorming SCAMPER-E result (#13). Confirmed as the structural model for §4 Features.
**Status:** Captured in feature descriptions for §4.1, §4.2, §4.3.

### D-6 — Seating chart metaphor for Director's Board
**Date:** 2026-05-19
**Decision:** The Director's Board uses a spatial seating chart layout, not a list or grid of raw settings.
**Rationale:** From brainstorming SCAMPER-S insight. Reinforced by Role Playing Persona 4 (Alex).
**Status:** Captured in FR-10.

### D-7 — Reaction Cam is opt-in at the player level
**Date:** 2026-05-19
**Decision:** Any automation that auto-spotlights a player's face (Reaction Cam, Combat Cinematics Mode) requires explicit player opt-in (or alternatively opt-out via Privacy Panel). The opt-out flag (FR-24) is included in v1.0 even though the Reaction Cam itself is a Later feature.
**Rationale:** Privacy tension between Marcus (GM) and Sofia (player) resolved in Role Playing phase: "Reaction cam opt-in resolved the Marcus/Sofia privacy tension elegantly."
**Status:** Captured in FR-24. Opt-out scaffolding ships in v1.0 to avoid a breaking change when Reaction Cam is released.

### D-8 — i18n string keys in v1.0; English strings only at ship
**Date:** 2026-05-19
**Decision:** All UI strings are externalized to i18n key files in v1.0 (enabling community translation contributions), but only English strings ship at the initial release.
**Rationale:** Standard FoundryVTT module convention. Community translation is a common contribution pattern in the ecosystem.
**Status:** Captured in §6.1 MVP Scope.

### D-9 — Native FoundryVTT socket API for state broadcast
**Date:** 2026-05-19
**Decision:** Visibility Matrix changes are broadcast via the native FoundryVTT socket API using a registered module event name. `socketlib` will not be added as a dependency.
**Rationale:** User confirmed: "Native Foundry socket API."
**Status:** Captured in FR-2 and §9 Assumptions Index. OQ-2 closed.

### D-10 — WebRTC track disable feasibility deferred to API inspection
**Date:** 2026-05-19
**Decision:** Whether real WebRTC track disabling is feasible will be determined by inspecting the FoundryVTT v14 AV API during development. CSS/DOM cosmetic hiding remains the safe default until confirmed.
**Rationale:** User confirmed: "Not sure, to be checked with the API itself." OQ-1 remains open but is unblocking — CSS fallback ships regardless.
**Status:** OQ-1 downgraded from hard phase blocker to development-time research item. FR-7 unchanged.

### D-11 — GM sees all activated feeds; own self-view is configurable
**Date:** 2026-05-19
**Decision:** The GM always sees all activated player webcams. The GM's own feed visibility in their own view is a configurable module setting ("Show my own feed to myself", default ON).
**Rationale:** User answer to OQ-3: "All activated webcam of players + himself as an option."
**Status:** Captured in FR-6. OQ-3 closed.

### D-12 — Native WebRTC only for v1.0; non-native AV backends deferred
**Date:** 2026-05-19
**Decision:** Only FoundryVTT's native WebRTC AV backend is supported in v1.0. Jitsi Meeting Server and other backends are not in scope.
**Rationale:** User answer to OQ-4: "Not planned in first steps, maybe later."
**Status:** Captured in §5 Non-Goals. OQ-4 closed; deferred to Later roadmap.

### D-13 — Reaction Cam / automation effects are opt-in (not opt-out)
**Date:** 2026-05-19
**Decision:** Any automation feature that auto-spotlights or visually modifies a player's feed requires explicit player opt-in. Default state is OFF.
**Rationale:** Reconciliation found the PRD had silently inverted the brainstorming's model. User confirmed opt-in is correct.
**Status:** FR-24, FR-25, and §4.5 description updated.

### D-14 — Director's Board supports both setup and live-monitor modes
**Date:** 2026-05-19
**Decision:** The Director's Board is valid as a pre-session setup tool and as a live monitor kept open during play. Both modes are explicitly supported.
**Rationale:** User confirmed both modes valid.
**Status:** FR-9 updated.

### D-15 — GM override guarantee as cross-cutting rule
**Date:** 2026-05-19
**Decision:** Every automation feature must expose a one-click GM override. Director's Board "Hide All" is the universal panic path.
**Rationale:** From brainstorming "panic button" + Marcus persona. Elevated to cross-cutting design rule.
**Status:** Added to Cross-Cutting NFRs.

---

## Live Testing Decisions (May 20-25, 2026)

### D-16 — Full AV Dock Replacement
**Date:** 2026-05-20
**Decision:** Replace FoundryVTT's native AV dock completely with custom ScryingPoolStrip and RoleRenderer components rather than hooking into the native dock.
**Rationale:** Live testing revealed limitations in hooking approach; full replacement provides better control over rendering, layout, and participant management. Enables consistent behavior across all AV states.
**Status:** Implemented in FR-27, FR-28. Captured in §4.6 Full AV Dock Replacement.
**Trade-offs:** 
- PRO: Full control over UI/UX, consistent behavior, easier to extend
- PRO: Enables dock layout system and position persistence
- CON: Must handle all edge cases that native dock handles
- CON: Potential compatibility issues with other AV-related modules

### D-17 — Dock Layout System
**Date:** 2026-05-22
**Decision:** Implement configurable dock layouts with 6 options: vertical-sm, vertical-md, horizontal-sm, horizontal-md, mosaic-sm, mosaic-md.
**Rationale:** User feedback from live testing requested flexibility in how participant tiles are arranged to match different table setups and screen configurations. GM controls direction/size at world level; individual users can override size preference.
**Status:** Implemented in FR-29, FR-30. Captured in §4.7 Dock Layout System.
**Implementation Notes:**
- World-scoped `dockLayout` setting controls direction and canonical size
- Client-scoped `dockLayoutExpanded` setting allows per-user override ('' = inherit, 'sm' = small, 'md' = large)
- Director's Board includes visual selector for layout configuration
- Legacy boolean values automatically migrated to string format

### D-18 — Position Persistence
**Date:** 2026-05-24
**Decision:** ScryingPoolStrip window position persists across sessions using GM user flags.
**Rationale:** User feedback indicated frustration with repositioning the dock every session. Position persistence improves UX consistency.
**Status:** Implemented in FR-31. Captured in §4.8 Position Persistence.
**Implementation Notes:**
- Position (left, top) saved to GM user flags on move
- Loaded on module initialization via `_loadPosition()` method
- First-time users get default position

### D-19 — ApplicationV2 API Migration
**Date:** 2026-05-20
**Decision:** Migrate all UI components to use FoundryVTT v14 ApplicationV2 API with HandlebarsApplicationMixin.
**Rationale:** FoundryVTT v14 requires ApplicationV2 for proper window management, resizing, and lifecycle. Previous implementation had compatibility issues.
**Status:** Implemented in FR-32. Captured in §4.9 Implementation Quality.
**Implementation Notes:**
- ScryingPoolStrip extends HandlebarsApplicationMixin(ApplicationV2)
- DirectorsBoard extends HandlebarsApplicationMixin(ApplicationV2)
- Fixed jQuery parameter handling in _onRender methods
- Added proper PARTS and DEFAULT_OPTIONS static properties

### D-20 — PortraitFallbackHandler Integration
**Date:** 2026-05-23
**Decision:** Enhance portrait fallback system with dedicated PortraitFallbackHandler component for consistent image resolution.
**Rationale:** Live testing revealed inconsistent fallback behavior. Dedicated handler provides clear priority chain and better integration with custom portraits.
**Status:** Implemented in FR-8 enhancement, FR-26. Captured in Glossary and §4.1.
**Implementation Notes:**
- Priority chain: custom fallback portrait -> user.avatar -> user.character?.img -> mystery-man
- Integrated with RoleRenderer for participant list building
- Handled in buildParticipantList function

### D-21 — CSS Build Pipeline
**Date:** 2026-05-24
**Decision:** Add postinstall script to automatically build CSS from LESS source files.
**Rationale:** Streamlines development and distribution; ensures styles are always up-to-date.
**Status:** Implementation note in §6.1 MVP Scope.
**Implementation Notes:**
- Added postinstall script to package.json
- Moved styles to root styles/ folder for FoundryVTT compatibility
- Updated .gitignore to allow dist/styles/ for CSS distribution

### D-22 — Video Widget Width Customization (v0.1.1)
**Date:** 2026-05-26
**Decision:** Add configurable width options for small and large video tiles via dropdown selection in Director's Board.
**Rationale:** User feedback requested ability to customize video widget size to match screen space and table preferences. Extends the existing Dock Layout System (D-17) by adding granular control over tile dimensions.
**Status:** Planned for v0.1.1. Captured in FR-33, FR-34.
**Implementation Notes:**
- Two world-scoped settings: `widgetWidthSm` (default: 80px) and `widgetWidthMd` (default: 120px)
- Dropdown options: 60px, 80px, 100px, 120px, 150px, 200px
- Dropdown UI in Director's Board settings panel
- Applies to all dock layout variants (vertical, horizontal, mosaic)
- Independent of layout direction
- OnChange callback triggers strip re-render for all users

---

## Decision Summary Table

| Decision | Date | Status | Related FRs | Section |
|----------|------|--------|-------------|---------|
| D-1 | 2026-05-19 | Active | FR-1-34 | §1, §6, §10 |
| D-2 | 2026-05-19 | Active | FR-7 | §4.1, §9 |
| D-3 | 2026-05-19 | Active | All | §5, §6 |
| D-4 | 2026-05-19 | Active | All | §7, Cross-cutting |
| D-5 | 2026-05-19 | Active | FR-1-26 | §4 |
| D-6 | 2026-05-19 | Active | FR-10 | §4.2 |
| D-7 | 2026-05-19 | Active | FR-24 | §4.5 |
| D-8 | 2026-05-19 | Active | All | §6.1 |
| D-9 | 2026-05-19 | Active | FR-2 | §4.1, §9 |
| D-10 | 2026-05-19 | Active | FR-7 | §4.1, §8 |
| D-11 | 2026-05-19 | Active | FR-6 | §4.1, §9 |
| D-12 | 2026-05-19 | Active | All | §5 |
| D-13 | 2026-05-19 | Active | FR-24, FR-25 | §4.5 |
| D-14 | 2026-05-19 | Active | FR-9 | §4.2 |
| D-15 | 2026-05-19 | Active | All automation | Cross-cutting |
| **D-16** | **2026-05-20** | **Active** | **FR-27, FR-28** | **§4.6** |
| **D-17** | **2026-05-22** | **Active** | **FR-29, FR-30** | **§4.7** |
| **D-18** | **2026-05-24** | **Active** | **FR-31** | **§4.8** |
| **D-19** | **2026-05-20** | **Active** | **FR-32** | **§4.9** |
| **D-20** | **2026-05-23** | **Active** | **FR-8, FR-26** | **§4.1, §4.5** |
| **D-21** | **2026-05-24** | **Active** | **N/A** | **§6.1** |
| **D-22** | **2026-05-26** | **Planned** | **FR-33, FR-34** | **§4.7.5** |

---

## Open Questions Status

| OQ | Phase Blocker? | Status | Related Decisions |
|---|---|---|---|
| OQ-1: WebRTC track disable API access | No | Open — to be checked against v14 API during development; CSS fallback is safe default | D-2, D-10 |
| OQ-2: socketlib vs native socket API | No | **RESOLVED** — native FoundryVTT socket API | D-9 |
| OQ-3: GM own-feed hidden behavior | No | **RESOLVED** — GM always sees all activated feeds; own self-view is configurable | D-11 |
| OQ-4: Non-native AV backend support | No | **RESOLVED** — native WebRTC only for v1.0 | D-12 |
| OQ-5: Scene hook timing | No | Open — not a concern for first implementation stage | |
| OQ-6: Partial vs full preset application | No | Open — to be resolved during FR-15/FR-16 implementation | |
| **OQ-7: Full AV replacement edge cases** | **No** | **Open** — Does full AV dock replacement handle all edge cases? | **D-16** |
| **OQ-8: Widget width defaults** | **No** | **Open** — Optimal default width values for small (80px) and large (120px)? | **D-22** |

---

## PRD Version History

| Version | Date | Status | Author | Changes |
|---------|------|--------|--------|---------|
| 1.0 | 2026-05-19 | final | Morr | Initial PRD with FR-1 through FR-26 |
| **1.1** | **2026-05-25** | **draft** | **Morr** | **Added FR-27 through FR-32 from live testing; updated D-1, added D-16 through D-21** |
| **1.2** | **2026-05-26** | **draft** | **Morr** | **Added FR-33 through FR-34 for v0.1.1 (Video Widget Width Customization); added D-22, OQ-8** |