CLose story 1.2
This commit is contained in:
+113
@@ -0,0 +1,113 @@
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
### 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-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-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.
|
||||
|
||||
| OQ | Phase Blocker? | Status |
|
||||
|---|---|---|
|
||||
| OQ-1: WebRTC track disable API access | Yes | Open — to be checked against v14 API during development; CSS fallback is safe default |
|
||||
| OQ-2: socketlib vs native socket API | Yes | **RESOLVED** — native FoundryVTT socket API |
|
||||
| OQ-3: GM own-feed hidden behavior | No | **RESOLVED** — GM always sees all activated feeds; own self-view is a configurable option |
|
||||
| OQ-4: Non-native AV backend support | No | **RESOLVED** — native WebRTC only for v1.0; others deferred to Later roadmap |
|
||||
| OQ-5: Scene hook timing | No | Deferred — 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 |
|
||||
|
||||
### 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.
|
||||
|
||||
### D-16 — PRD finalized
|
||||
**Date:** 2026-05-19
|
||||
**Decision:** PRD marked `status: final`. All decisions captured, all reconciliation gaps resolved, all [ASSUMPTION] tags indexed, polish complete.
|
||||
**Status:** Closed.
|
||||
@@ -0,0 +1,543 @@
|
||||
---
|
||||
title: "Video View Manager — FoundryVTT Webcam Visibility Control Module"
|
||||
status: final
|
||||
created: 2026-05-19
|
||||
updated: 2026-05-19
|
||||
---
|
||||
|
||||
# PRD: Video View Manager
|
||||
|
||||
## 0. Document Purpose
|
||||
|
||||
This PRD is the authoritative specification for **Video View Manager**, a FoundryVTT v14 module. It is written for the module author (Morr) and future contributors, and it is the source of record for scope decisions during development.
|
||||
|
||||
This document uses Glossary terms from §3 throughout §4+ and keeps functional requirements globally numbered FR-1 through FR-26 for stable reference. Inline `[ASSUMPTION]` tags in §4 mark unconfirmed inferences and are indexed in §9. The primary upstream input is `_bmad-output/brainstorming/brainstorming-session-2026-05-19-221747.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Vision
|
||||
|
||||
Video View Manager gives the GM granular, real-time control over webcam visibility in FoundryVTT v14. Its core value is simple: **the GM can hide or reveal any Participant's camera in one click, and every Viewer updates immediately.** Existing FoundryVTT AV controls do not provide this.
|
||||
|
||||
From that core, the module extends into session cinematography. Scene Presets let the GM configure camera states during prep and apply them on scene transitions. The Director's Board gives the GM bulk visibility control for larger groups. Contextual Notifications explain camera-state changes so feeds never disappear silently.
|
||||
|
||||
The module follows the **Progressive Enhancement Architecture**. Level 1 adds a right-click action to existing AV Tiles. Level 2 adds the Director's Board. Level 3 adds Scene Presets and automation. Participants stay informed, automation that changes an individual's on-screen presence requires explicit opt-in, and the GM always has an immediate override.
|
||||
|
||||
---
|
||||
|
||||
## 2. Target Users
|
||||
|
||||
### 2.1 Primary Personas
|
||||
|
||||
**Marcus — The Veteran GM**
|
||||
Marcus runs a biweekly campaign with 6 players on FoundryVTT. He preps meticulously and wants zero friction during play. He wants camera automation he can configure once, not an interface he must reopen mid-session. Every automation needs an obvious one-click override. He will use Scene Presets and the Director's Board extensively.
|
||||
|
||||
**Sofia — The Privacy-Conscious Player**
|
||||
Sofia joins two games a week. She has a home office setup and is comfortable on camera, but she does not want her face spotlighted unexpectedly during a dramatic moment she did not choose. She needs to know what state her feed is in at all times, and she expects a way to opt out of any effect that touches her camera automatically.
|
||||
|
||||
**Jake — The Actual-Play Streamer**
|
||||
Jake runs a public streamed game. He needs complete independence between what his players see and what his stream audience sees. Keyboard shortcuts are essential during live broadcast. He sees the Browser Source API and Spectator View (Later roadmap) as the features that turn this module into a production stack.
|
||||
|
||||
**Alex — The New Player**
|
||||
Alex has just joined their first online TTRPG. They are comfortable with Zoom but have never used FoundryVTT. They need the interface to use plain language ("Show" / "Hide") rather than technical vocabulary, toast notifications that explain what is happening, and a Portrait Fallback if their camera fails.
|
||||
|
||||
### 2.2 Jobs to Be Done
|
||||
|
||||
**Functional**
|
||||
- Hide a distracting Participant's video feed without removing them from the session
|
||||
- Spotlight one Participant for a dramatic reveal or emotional scene climax
|
||||
- Apply a Scene Preset when transitioning between scenes without manual intervention
|
||||
- Know at a glance which of 6+ Participants are hidden, visible, or offline
|
||||
|
||||
**Social / Emotional**
|
||||
- Feel in control of the table atmosphere as a GM — the visual equivalent of adjusting the lights
|
||||
- Trust that no Participant is hidden without knowing it (Participant transparency)
|
||||
- Participate fully in the session even when camera equipment fails (Portrait Fallback, Reaction Clip System)
|
||||
|
||||
### 2.3 Non-Users (v1.0)
|
||||
|
||||
- Solo FoundryVTT users with no AV participants
|
||||
- Groups using FoundryVTT v13 or earlier
|
||||
- Streamers requiring independent audience layouts (served in the later roadmap — §10)
|
||||
|
||||
### 2.4 Key User Journeys
|
||||
|
||||
**UJ-1. Marcus transitions into a boss fight and spotlights the villain's lair.**
|
||||
- **Persona + context:** Marcus, mid-session, activating a Scene named "Throne Room" where he wants only two Participants visible.
|
||||
- **Entry state:** A Scene Preset is configured at prep time; the Director's Board is closed.
|
||||
- **Path:** (1) Marcus activates the "Throne Room" scene. (2) The module auto-applies the saved preset — two Participants are visible and four are hidden. (3) A toast appears for all Participants: "Scene changed: camera layout updated." (4) Marcus glances at the AV Tile strip — hidden tiles show a grey overlay with a lock icon.
|
||||
- **Climax:** The table's visual focus narrows to the two Participants in the scene without Marcus touching a control.
|
||||
- **Resolution:** Marcus keeps narrating; he can override the preset with one right-click if needed.
|
||||
- **Edge case:** If a Participant whose feed should be visible is offline, the hidden overlay still appears and the preset is marked partially applied.
|
||||
|
||||
**UJ-2. Sofia opts out of HP-Reactive Cam Styling before the session.**
|
||||
- **Persona + context:** Sofia, before the session starts, opening her FoundryVTT user settings.
|
||||
- **Entry state:** Authenticated as a Participant; the Player Privacy Panel is available in module settings; HP-Reactive Cam Styling is currently ON from an earlier opt-in.
|
||||
- **Path:** (1) Sofia opens the Player Privacy Panel. (2) She sees HP-Reactive Cam Styling: ON. (3) She toggles it OFF. (4) The setting saves instantly; no page reload is required.
|
||||
- **Climax:** Sofia knows her camera will not change appearance based on her HP.
|
||||
- **Resolution:** Her opt-out flag persists for future sessions in this world until she changes it.
|
||||
|
||||
**UJ-3. Jake opens the Director's Board at session start to configure the layout.**
|
||||
- **Persona + context:** Jake, 5 minutes before going live, with 5 Participants connected.
|
||||
- **Entry state:** Authenticated as GM; the Director's Board has not been opened this session.
|
||||
- **Path:** (1) Jake presses the keyboard shortcut (⌘/Ctrl+Shift+V). (2) The Director's Board opens as a floating window. (3) Jake sees all 5 Participants in a seating-chart layout with their current states. (4) He sets Participant 4 to "Hidden" (late joiner, not on yet). (5) He uses Spotlight on his own card to confirm his feed remains visible.
|
||||
- **Climax:** Jake's table is visually configured for broadcast before he goes live.
|
||||
- **Resolution:** The Director's Board stays open in a corner, and Jake uses it as a live monitor during the session.
|
||||
|
||||
**UJ-4. Alex sees a toast notification when their feed is hidden.**
|
||||
- **Persona + context:** Alex, playing for the first time; Marcus has just hidden Alex's camera to manage a technical glitch.
|
||||
- **Entry state:** Alex's AV Tile is live; Marcus triggers hide from the context menu.
|
||||
- **Path:** (1) Alex's tile changes to Portrait Fallback mode with a grey overlay. (2) Alex receives a toast: "GM has hidden your camera. Your portrait is shown to other Participants." (3) Alex sees a small "Camera hidden" badge on their own tile.
|
||||
- **Climax:** Alex understands exactly what happened and why — no confusion or anxiety.
|
||||
- **Resolution:** Alex can keep playing; their audio is unaffected.
|
||||
|
||||
---
|
||||
|
||||
## 3. Glossary
|
||||
|
||||
- **AV Tile** — The FoundryVTT UI element that renders a Participant's audio/video feed. The primary surface for right-click interactions in Level 1 of the Progressive Enhancement Architecture.
|
||||
- **Browser Source API** — A Later-roadmap streaming interface that exposes camera-layout outputs for external broadcast tooling such as OBS.
|
||||
- **Combat Cinematics Mode** — An automation mode that manages the Visibility Matrix during active FoundryVTT combat, spotlighting the active combatant's feed. Part of the Later roadmap.
|
||||
- **Director's Board** — The floating window for bulk Visibility Matrix management. Primary UI surface for Level 2/3 interactions. Synonyms are not permitted — this is not "the settings panel" or "the popout."
|
||||
- **Director's Board Stage Lighting States** — A Later-roadmap preset vocabulary tier for cinematic bulk actions such as Wash, Focus, and Blackout.
|
||||
- **Dual Layout System** — A Later-roadmap architecture that separates the Participant-facing layout from the Spectator View.
|
||||
- **GM** — Game Master. The FoundryVTT user with the `GAMEMASTER` role. Has exclusive authority over the Visibility Matrix unless Player Permissions are extended (future roadmap).
|
||||
- **HP-Reactive Cam Styling** — An opt-in automation effect that changes the presentation of a Participant's feed based on HP-related game events. Part of the Later roadmap.
|
||||
- **NPC Presence Tiles** — A Later-roadmap feature that displays static image tiles for NPC voice actors or other non-camera presences.
|
||||
- **Participant** — Any connected FoundryVTT user with an AV presence (camera, microphone, or both), including the GM.
|
||||
- **Participant State** — One of eight enumerated states describing a Participant's AV presence: `active`, `hidden`, `self-muted`, `offline`, `cam-lost`, `reconnecting`, `never-connected`, `ghost`. Defined in §4.1.
|
||||
- **Player Privacy Panel** — The per-user settings interface for opting in or out of cinematic automation effects. Scoped to the current user; accessible from module settings.
|
||||
- **Portrait Fallback** — A static image (user avatar or actor portrait) displayed in place of a live camera feed when a Participant has no camera, or when their feed is `cam-lost`.
|
||||
- **Progressive Enhancement Architecture** — The three-level UI model: Level 1 (right-click on existing AV Tiles — zero new UI), Level 2 (Director's Board), Level 3 (Scene Presets + full automation). Each level is independently useful.
|
||||
- **Pull Visibility Model** — A Later-roadmap visibility model in which feeds remain hidden until a Viewer explicitly requests them.
|
||||
- **Reaction Cam** — An opt-in feature that automatically spotlights a Participant's feed during key game moments (for example, taking damage in combat). Part of the Later roadmap.
|
||||
- **Reaction Clip System** — A Later-roadmap fallback that shows a short video snippet when a Participant has no live camera feed.
|
||||
- **Scene Preset** — A saved snapshot of the Visibility Matrix, optionally linked to a FoundryVTT Scene for automatic application on scene activation.
|
||||
- **Spectator View** — A read-only camera layout independent from the Participant layout, intended for streaming audiences. Part of the Later roadmap.
|
||||
- **The Living Table** — A Later-roadmap concept that exposes the full seating-chart UI for `Map<participantId, Map<viewerId, VisibilityState>>` relationships.
|
||||
- **Token-Anchored Floating Cams** — A Later-roadmap feature that links camera surfaces to canvas tokens.
|
||||
- **Visibility Matrix** — The authoritative data structure representing all camera visibility relationships: `Map<participantId, Map<viewerId, VisibilityState>>`. Stored in world-level settings and broadcast to all clients on change.
|
||||
- **Zero-UI Full Automation Mode** — A Later-roadmap mode that minimizes manual camera control after initial configuration.
|
||||
- **Visibility State** — The visibility setting for one Participant's camera as seen by one Viewer. Distinct from Participant State: a feed can be `active` but have a `hidden` Visibility State for specific viewers.
|
||||
- **Viewer** — A Participant who is receiving (watching) another Participant's camera feed.
|
||||
|
||||
---
|
||||
|
||||
## 4. Features
|
||||
|
||||
### 4.1 Core Visibility Toggle
|
||||
|
||||
**Description:** The North Star feature. The GM right-clicks any AV Tile to toggle that Participant's visibility for all Viewers. The change broadcasts to all connected clients, persists across reconnections, and updates the AV Tile with a clear indicator explaining *why* the feed is in its current state. All eight Participant States render without layout disruption. Realizes UJ-1, UJ-4.
|
||||
|
||||
This feature implements **Level 1** of the Progressive Enhancement Architecture. It adds no new UI beyond a context-menu action on existing AV Tiles.
|
||||
|
||||
**Participant States (FR-5):**
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| `active` | Camera on; feed visible to permitted Viewers |
|
||||
| `hidden` | Camera on; GM has set Visibility State to hidden |
|
||||
| `self-muted` | Participant voluntarily turned off their own camera |
|
||||
| `offline` | Participant's connection dropped entirely |
|
||||
| `cam-lost` | Participant connected but camera device failed |
|
||||
| `reconnecting` | Transitional; feed is expected to return |
|
||||
| `never-connected` | Participant joined with no camera device |
|
||||
| `ghost` | GM observing silently (no AV presence broadcast) |
|
||||
|
||||
**Functional Requirements:**
|
||||
|
||||
#### FR-1: GM toggles Participant visibility via right-click
|
||||
The GM can hide or show any Participant's camera feed by right-clicking their AV Tile and selecting "Hide Camera" / "Show Camera." Realizes UJ-1, UJ-4.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Selecting "Hide Camera" sets the target Participant's Visibility State to `hidden` for all Viewers.
|
||||
- Selecting "Show Camera" sets the target Participant's Visibility State to `active` for all Viewers.
|
||||
- The AV Tile indicator updates on all connected clients within 500 ms.
|
||||
- The context-menu entry appears on all AV Tiles when the user is logged in as GM.
|
||||
|
||||
**Out of Scope:** Asymmetric visibility (hiding from specific Viewers only) — deferred to Later roadmap.
|
||||
|
||||
#### FR-2: Visibility state broadcast via socket
|
||||
All Visibility Matrix changes are broadcast to all connected clients in real time.
|
||||
|
||||
**Consequences (testable):**
|
||||
- A client that joins mid-session receives the current Visibility Matrix on connection.
|
||||
- State-change latency from GM action to all-client update stays at or below 500 ms on a local network.
|
||||
- The module uses the native FoundryVTT socket API through a registered module event (for example, `module.video-view-manager.visibilityUpdate`).
|
||||
|
||||
#### FR-3: Visibility state persistence
|
||||
Visibility Matrix state persists in world-level settings across page refreshes and session breaks.
|
||||
|
||||
**Consequences (testable):**
|
||||
- A Participant who disconnects and reconnects returns to the previously set Visibility State.
|
||||
- The saved state survives a full FoundryVTT server restart.
|
||||
- A new Participant defaults to `active` on first connection to the world [ASSUMPTION].
|
||||
|
||||
#### FR-4: AV Tile visual indicator for Participant State
|
||||
Each AV Tile displays a state indicator that distinguishes all relevant Participant States by using plain language and an icon. Realizes UJ-4.
|
||||
|
||||
**Consequences (testable):**
|
||||
- `hidden` state renders a grey overlay, a lock icon, and the tooltip "Camera hidden by GM."
|
||||
- `self-muted` state renders a camera-off icon distinct from the lock icon.
|
||||
- `offline` state renders a disconnection icon and the tooltip "Participant offline."
|
||||
- `cam-lost` state renders a camera-error icon and the tooltip "Camera unavailable."
|
||||
- `reconnecting` state renders a spinner icon.
|
||||
- All icons come from the FoundryVTT icon library; the module adds no external dependency.
|
||||
|
||||
#### FR-5: Eight Participant States rendered without layout disruption
|
||||
All Participant States produce appropriate visual feedback and do not cause AV Tile reflow or layout shift for other Participants.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Hiding or revealing a Participant's feed does not change the position of other AV Tiles.
|
||||
- Mid-combat state transitions (`active` → `offline` → `reconnecting`) do not shift the combat tracker or map canvas layout.
|
||||
- A Participant in `ghost` state has no AV Tile rendered for other Participants.
|
||||
|
||||
#### FR-6: GM sees all activated Participant feeds; GM self-view is configurable
|
||||
The GM always sees all activated Participant feeds regardless of Visibility State. The GM's own feed in their own view can be toggled in a module setting.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Hidden tiles in the GM's view render at reduced opacity with a lock icon overlay.
|
||||
- The GM hears audio from all Participants regardless of Visibility State.
|
||||
- The module setting "Show my own feed to myself" (default: ON) controls whether the GM's own AV Tile appears in the GM's interface.
|
||||
- Other Participants do not render hidden feeds.
|
||||
|
||||
#### FR-7: WebRTC track disabling with CSS fallback
|
||||
Real WebRTC track disabling is the preferred implementation when the FoundryVTT v14 API allows programmatic track access. CSS/DOM cosmetic hiding is the fallback.
|
||||
|
||||
**Consequences (testable):**
|
||||
- When WebRTC track disabling is active, a hidden feed does not consume inbound video bandwidth on the receiving client.
|
||||
- A world setting reports which mode is active: WebRTC track disabling or CSS fallback.
|
||||
- [ASSUMPTION: FoundryVTT v14's `game.webrtc` exposes RTCPeerConnection access sufficient for track disabling; see OQ-1.]
|
||||
|
||||
**Out of Scope:** Audio track manipulation — this module manages video visibility only. Audio muting remains native FoundryVTT functionality.
|
||||
|
||||
#### FR-8: Portrait Fallback for no-camera Participants
|
||||
When a Participant has no camera device (`never-connected`) or enters `cam-lost` state, their AV Tile displays a Portrait Fallback image.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The default Portrait Fallback uses the FoundryVTT user avatar and falls back to a system placeholder if no avatar is set.
|
||||
- Participants can set a custom Portrait Fallback through the Player Privacy Panel (FR-26).
|
||||
- Portrait Fallback renders at the same dimensions as a live camera-feed tile.
|
||||
|
||||
**Feature-specific NFRs:**
|
||||
- Visibility Matrix updates must not block the FoundryVTT rendering loop; state changes apply asynchronously.
|
||||
- The module must not interfere with FoundryVTT's native AV mute/unmute controls.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Director's Board
|
||||
|
||||
**Description:** The Director's Board is a floating window for bulk Visibility Matrix management in sessions with 4+ Participants. It is **Level 2** of the Progressive Enhancement Architecture. The seating-chart layout matches how TTRPG groups visualize the table. Realizes UJ-3.
|
||||
|
||||
**Functional Requirements:**
|
||||
|
||||
#### FR-9: GM opens Director's Board via sidebar button and keyboard shortcut
|
||||
A dedicated button in the FoundryVTT controls sidebar opens the Director's Board. A keyboard shortcut (default: `Ctrl+Shift+V`) also opens it. Realizes UJ-3.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The Director's Board opens as a resizable, draggable `ApplicationV2` window [ASSUMPTION].
|
||||
- Opening the Director's Board does not change the existing AV Tile strip.
|
||||
- The keyboard shortcut is configurable in module settings.
|
||||
- The window closes and reopens instantly, supporting both a pre-session setup workflow and a live-monitor workflow.
|
||||
|
||||
#### FR-10: Director's Board displays full Visibility Matrix in seating-chart layout
|
||||
All connected Participants are shown with their current Visibility State, name, and portrait.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Every Participant card displays the name, portrait, current Participant State, and current Visibility State.
|
||||
- The layout reads as a seating chart, not a list.
|
||||
- Updates to Visibility State appear in the Director's Board within 500 ms, matching FR-2.
|
||||
|
||||
#### FR-11: Per-Participant visibility toggle from Director's Board
|
||||
The GM can toggle any single Participant's Visibility State from that Participant's card in the Director's Board.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The action matches FR-1 for behavior and persistence.
|
||||
- The GM toggles a Participant with a single click on that Participant card.
|
||||
|
||||
#### FR-12: Bulk actions — Show All and Hide All
|
||||
Two bulk-action buttons apply Show or Hide to all Participants simultaneously.
|
||||
|
||||
**Consequences (testable):**
|
||||
- "Show All" sets every eligible Participant Visibility State to `active`.
|
||||
- "Hide All" sets every eligible Participant Visibility State to `hidden`.
|
||||
- A one-step "Undo" action restores the Visibility Matrix state that existed immediately before the bulk action.
|
||||
- Participants in `ghost` state are excluded from bulk actions.
|
||||
|
||||
#### FR-13: Spotlight action on a single Participant
|
||||
"Spotlight" shows exactly one Participant's feed and hides all others in a single action.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Spotlight stores the current Visibility Matrix as a pre-spotlight snapshot.
|
||||
- A "Restore" action reverts to that pre-spotlight snapshot.
|
||||
- Spotlight remains distinct from a manual Hide All plus Show One sequence: one dedicated action and one undo step.
|
||||
|
||||
#### FR-14: Keyboard shortcuts for Director's Board actions
|
||||
All primary Director's Board actions are accessible without a mouse. Realizes UJ-3.
|
||||
|
||||
**Consequences (testable):**
|
||||
- `Space` or `Enter` toggles the focused Participant.
|
||||
- Arrow keys move focus between Participant cards.
|
||||
- `Ctrl+Shift+S` runs Show All, `Ctrl+Shift+H` runs Hide All, and `Ctrl+Shift+P` spotlights the focused Participant.
|
||||
- The `?` key opens a shortcut reference panel within the Director's Board.
|
||||
- All shortcuts are configurable and documented in module settings.
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Scene-Aware Visibility Presets
|
||||
|
||||
**Description:** Scene Presets are saved Visibility Matrix configurations that can be applied manually or automatically when a FoundryVTT Scene activates. This is **Level 3** of the Progressive Enhancement Architecture: configure during prep, then use during play. Realizes UJ-1.
|
||||
|
||||
**Functional Requirements:**
|
||||
|
||||
#### FR-15: GM saves a named Scene Preset from the current Visibility Matrix
|
||||
Any current Visibility Matrix state can be saved as a named preset with a single action from the Director's Board or module settings.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The preset captures the full current Visibility Matrix at save time.
|
||||
- The preset name is editable, and names remain unique within a world.
|
||||
- Up to 50 presets can be stored in world settings [ASSUMPTION: adequate for any campaign].
|
||||
|
||||
#### FR-16: GM loads a Scene Preset at any time
|
||||
Applying a preset overrides the current Visibility Matrix.
|
||||
|
||||
**Consequences (testable):**
|
||||
- All clients receive the preset state within 500 ms through the same path as FR-2.
|
||||
- Loading a preset generates the Contextual Notification defined in FR-20: "GM applied preset: [Preset Name]."
|
||||
- The preset applies regardless of which Participants are online; offline Participants receive the stored state on reconnection under FR-3.
|
||||
|
||||
#### FR-17: Scene Preset auto-applies on FoundryVTT Scene activation
|
||||
A preset can be linked to a Scene; it applies automatically when that Scene is activated.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The Scene-to-Preset association is configured in Scene settings or module settings.
|
||||
- Auto-apply fires on the `updateScene` hook, and a configurable 0–5000 ms pre-delay supports dramatic transitions [ASSUMPTION: sufficient hook timing — to be verified during FR-17 development].
|
||||
- All clients receive the notification "Scene changed: camera layout updated." matching UJ-1.
|
||||
|
||||
#### FR-18: Scene Preset auto-apply can be disabled per scene or globally
|
||||
GMs retain full manual override.
|
||||
|
||||
**Consequences (testable):**
|
||||
- A per-scene toggle disables auto-apply for that Scene without removing the association.
|
||||
- A global "Disable All Auto-Apply" toggle in module settings overrides all per-Scene configurations.
|
||||
- The Director's Board always provides a manual override during play, regardless of automation state.
|
||||
|
||||
#### FR-19: Preset import/export as JSON
|
||||
Presets can be exported to and imported from a JSON file.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Export writes all presets to one human-readable JSON file that the browser downloads.
|
||||
- Import reads a JSON file and merges or replaces existing presets, based on user choice; invalid JSON shows an error.
|
||||
- The module README documents the exported JSON format for community sharing.
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Contextual Notifications
|
||||
|
||||
**Description:** Contextual Notifications use plain-language toasts to inform Participants when camera states change. They prevent silent surprises, and notification verbosity is configurable. Realizes UJ-4.
|
||||
|
||||
**Functional Requirements:**
|
||||
|
||||
#### FR-20: Toast notification on GM visibility change
|
||||
When the GM changes any Participant's Visibility State, all Participants receive a toast notification in plain language.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The message uses the Participant display name: "GM hid [Name]'s camera" or "GM showed [Name]'s camera."
|
||||
- The toast uses FoundryVTT's native notification UI.
|
||||
- The affected Participant receives a distinct personal notification: "GM has hidden your camera. Your portrait is shown to other Participants."
|
||||
|
||||
#### FR-21: Notification verbosity configuration
|
||||
Notification output is configurable per user.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Three modes are available: `All` (default), `GM Only`, and `Silent`.
|
||||
- The configuration is stored in user-level client settings, not world settings.
|
||||
- `Silent` mode still shows the personal notification to the affected Participant; the GM cannot suppress the FR-20 personal message.
|
||||
|
||||
#### FR-22: Persistent feed status indicator on own AV Tile
|
||||
Each Participant always sees the current state of their own feed through a persistent status badge on their own AV Tile.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The badge shows one of these states: "Live," "Hidden by GM," "Muted," or "No Camera."
|
||||
- The badge updates within 500 ms when the state changes.
|
||||
- Only the owning Participant sees the badge; other Participants do not see badges on other AV Tiles.
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Player Privacy Panel
|
||||
|
||||
**Description:** The Player Privacy Panel contains per-user settings for consenting to, or withdrawing consent from, cinematic automation effects that touch individual Participants. Design principle: **automation effects that touch a Participant's on-screen presence require explicit opt-in and remain off by default.** The GM retains unconditional hide/show authority under FR-1. Automation that auto-spotlights or visually modifies a Participant remains opt-in by user choice. Realizes UJ-2.
|
||||
|
||||
**Functional Requirements:**
|
||||
|
||||
#### FR-23: Player Privacy Panel accessible from module settings
|
||||
Each user can open their Player Privacy Panel from the module settings tab in FoundryVTT.
|
||||
|
||||
**Consequences (testable):**
|
||||
- The panel lists every automation effect that can touch the owning user, along with the current opt-in status.
|
||||
- The owning user can edit the panel; the GM can view but not edit another Participant's panel settings.
|
||||
- The settings persist in world-level user flags.
|
||||
|
||||
#### FR-24: Opt-in to Reaction Cam automation
|
||||
A Participant must explicitly opt in before Reaction Cam (Later roadmap) can auto-spotlight them. The default is **off**.
|
||||
|
||||
**Consequences (testable):**
|
||||
- Reaction Cam remains disabled for a Participant unless that Participant explicitly enables it in the Player Privacy Panel.
|
||||
- The Director's Board displays a "Reaction Cam: Enabled" badge on opted-in Participant cards; no badge means off.
|
||||
- The opt-in flag persists across sessions until the user changes it.
|
||||
- Combat Cinematics Mode and any other Reaction Cam trigger respect this flag; they skip opted-out Participants silently.
|
||||
|
||||
#### FR-25: Opt-in to HP-Reactive Cam Styling
|
||||
A Participant must explicitly opt in before HP-Reactive Cam Styling (Later roadmap) applies to their feed. The default is **off**.
|
||||
|
||||
**Consequences (testable):**
|
||||
- HP-Reactive Cam Styling remains disabled for a Participant unless that Participant explicitly enables it.
|
||||
- The GM is not notified of individual styling opt-in statuses; this preference remains private.
|
||||
|
||||
#### FR-26: Custom Portrait Fallback
|
||||
A Participant can set a custom image as their Portrait Fallback (used in FR-8 when the camera is unavailable).
|
||||
|
||||
**Consequences (testable):**
|
||||
- A file picker in the Player Privacy Panel sets the custom portrait.
|
||||
- Accepted formats are PNG, JPG, WEBP, and static GIF.
|
||||
- The image falls back to the FoundryVTT user avatar if no custom portrait is set, then to the system placeholder if no avatar exists.
|
||||
|
||||
---
|
||||
|
||||
## 5. Non-Goals (Explicit)
|
||||
|
||||
- **Not an AV transport layer.** This module does not host, relay, or record audio/video streams. FoundryVTT's native WebRTC / AV stack handles all transport.
|
||||
- **No audio control.** The module manages video visibility only. Muting audio remains native FoundryVTT functionality.
|
||||
- **No recording or archiving.** No session video capture or replay features in v1.0.
|
||||
- **FoundryVTT v13 and earlier are not supported.** v14 is the minimum compatibility floor; no backport is planned.
|
||||
- **No central preset registry.** Community preset sharing is a local JSON export/import workflow only. No cloud or server-side storage.
|
||||
- **No AI-driven visibility decisions.** All visibility changes are GM-initiated or rule-based (Scene Preset auto-apply). No ML or heuristic automation.
|
||||
- **No asymmetric per-Viewer visibility (v1.0).** The Visibility Matrix is GM-to-everyone in v1.0; the full `Map<participantId, Map<viewerId, VisibilityState>>` model is architecturally supported but is not exposed in the UI until the Later roadmap.
|
||||
- **No third-party streaming platform integration.** No OBS, Twitch, or YouTube API in v1.0. Browser Source API is a Later roadmap item.
|
||||
- **Native WebRTC AV backend only (v1.0).** The module operates exclusively with FoundryVTT's built-in WebRTC stack. Jitsi Meeting Server and other third-party AV backends are not supported in v1.0; they are deferred to the Later roadmap.
|
||||
|
||||
---
|
||||
|
||||
## 6. MVP Scope
|
||||
|
||||
### 6.1 In Scope (v1.0)
|
||||
|
||||
- Core Visibility Toggle (FR-1 – FR-8): right-click toggle, broadcast, persistence, visual indicators, 8 Participant States, WebRTC track disabling with CSS fallback, Portrait Fallback
|
||||
- Director's Board (FR-9 – FR-14): seating-chart window, bulk actions, Spotlight, keyboard shortcuts
|
||||
- Scene-Aware Visibility Presets (FR-15 – FR-19): save, load, auto-apply, and JSON import/export
|
||||
- Contextual Notifications (FR-20 – FR-22): toast system, verbosity configuration, persistent self-status badge
|
||||
- Player Privacy Panel (FR-23 – FR-26): opt-in controls for future automation effects, custom portrait
|
||||
- FoundryVTT v14+ compatibility; `module.json` per v14 manifest schema
|
||||
- English UI strings; i18n-ready string keys for community translation
|
||||
|
||||
### 6.2 Out of Scope for MVP
|
||||
|
||||
- Combat Cinematics Mode (auto-spotlight active combatant) — deferred to Later; see §10. `[NOTE FOR PM: This is emotionally load-bearing for Marcus-persona GMs. Consider as v1.1 if Day 1 ship goes smoothly.]`
|
||||
- Reaction Cam (auto-spotlight on damage/dramatic event) — deferred to Later; see §10
|
||||
- Director's Board Stage Lighting States (Wash / Focus / Blackout presets) — deferred to Later
|
||||
- Token-Anchored Floating Cams — deferred to Later; requires deep canvas integration
|
||||
- HP-Reactive Cam Styling — deferred to Later
|
||||
- Spectator View / Dual Layout System — deferred to Later
|
||||
- Browser Source API (OBS-ready tile URLs) — deferred to Later
|
||||
- NPC Presence Tiles — deferred to Later
|
||||
- Zero-UI Full Automation Mode — deferred to Later
|
||||
- Pull Visibility Model (opt-in to see feeds) — deferred to Later
|
||||
- Reaction Clip System (video snippet fallback for no-camera Participants) — deferred to Later
|
||||
- Full asymmetric per-Viewer visibility in the Director's Board — deferred to Later
|
||||
- FoundryVTT v13 compatibility backport — will not build
|
||||
|
||||
---
|
||||
|
||||
## 7. Success Metrics
|
||||
|
||||
**Primary**
|
||||
- **SM-1: Installation count** — 500 installs within 90 days of Foundry Hub listing. Validates FR-1 through FR-8 (broad appeal of the core feature).
|
||||
- **SM-2: Weekly active worlds** — ≥30% of installing worlds use the module in at least one session per week after the first week. Validates overall module stickiness across all v1.0 features.
|
||||
|
||||
**Secondary**
|
||||
- **SM-3: Core toggle regression-free** — Zero bug reports for FR-1 through FR-4 (basic toggle + persistence) in the first 30 days. Validates Day 1 reliability.
|
||||
- **SM-4: Open P1 bug count** — No more than 3 open P1 bugs at any point in the first 90 days. Validates overall module quality.
|
||||
- **SM-5: State-persistence failures** — Zero user-reported Visibility State loss across reconnection (FR-3) after 30 days.
|
||||
|
||||
**Counter-metrics (do not optimize)**
|
||||
- **SM-C1: Feature depth penetration** — Do not optimize for users enabling every feature. The module is successful if most users remain at Level 1 (right-click only) and only power users reach Level 3 (Scene Presets + Director's Board). Depth adoption is a health signal, not the goal. Counterbalances SM-1 and SM-2.
|
||||
- **SM-C2: Notification frequency** — Do not make toast notifications more prominent, frequent, or verbose. FR-20 notifications exist to remove confusion, not to draw attention. Counterbalances SM-3.
|
||||
|
||||
---
|
||||
|
||||
## 8. Open Questions
|
||||
|
||||
1. **OQ-1:** Does FoundryVTT v14's `game.webrtc` / `AVMaster` API expose a programmatic method for disabling a specific peer's incoming video track (RTCPeerConnection track manipulation), or must the module hook at a lower level? To be resolved by inspecting the v14 AV API during development. FR-7 CSS fallback is the safe default until confirmed.
|
||||
2. ~~**OQ-2 (Phase blocker):** Is `socketlib` the recommended socket broadcast approach for v14, or does FoundryVTT v14 expose a sufficient native socket API?~~ **RESOLVED:** Native FoundryVTT socket API will be used. `socketlib` dependency will not be added.
|
||||
3. ~~**OQ-3:** What is the intended behavior when the GM's own feed is set to `hidden` — should the GM see their own feed in their view unchanged, or see the hidden state overlay like other GMs would?~~ **RESOLVED:** The GM always sees all activated Participant feeds. The GM's own feed visibility in their own view is a configurable option (show/hide self-view).
|
||||
4. ~~**OQ-4:** Should the module operate with Jitsi Meeting Server and other non-native AV backends (beyond native WebRTC), or is native WebRTC the only supported backend for v1.0?~~ **RESOLVED:** Native WebRTC only for v1.0. Non-native backends (Jitsi, etc.) are deferred to the Later roadmap.
|
||||
5. **OQ-5:** Do FoundryVTT v14 scene activation hooks fire early enough for Scene Preset auto-apply (FR-17) to avoid a visible flash of the wrong camera layout before the preset applies? Not a concern for the first implementation stage — defer to testing.
|
||||
6. **OQ-6:** Should Scene Presets support partial application — applying only to currently connected Participants and deferring state for offline ones — or should they always apply to all participant slots unconditionally? This cannot be decided yet and will be resolved during FR-15/FR-16 implementation.
|
||||
|
||||
---
|
||||
|
||||
## 9. Assumptions Index
|
||||
|
||||
- **§4.1 / FR-3:** New Participants default to `active` Visibility State on first connection to a world. This is the socially safe default.
|
||||
- **§4.1 / FR-7:** FoundryVTT v14's WebRTC implementation exposes RTCPeerConnection objects at a level accessible to a module, enabling programmatic track disabling without patching the core AV system.
|
||||
- **§4.2 / FR-9:** FoundryVTT v14's `ApplicationV2` API is the correct pattern for a resizable floating window with persistent state.
|
||||
- **§4.3 / FR-15:** 50 presets per world is an adequate upper bound for any campaign use case. If communities surface larger preset libraries, this can increase.
|
||||
- **§4.3 / FR-17:** The `updateScene` hook (or its v14 equivalent) fires early enough in the scene-transition lifecycle to apply the preset before the AV Tile strip re-renders.
|
||||
|
||||
---
|
||||
|
||||
## 10. Product Roadmap (Later Features)
|
||||
|
||||
The following concepts from the brainstorming session are architecturally consistent with v1.0 but are deferred to keep the initial release focused. They are listed here to prevent scope creep in v1.0 tickets while preserving the broader product vision.
|
||||
|
||||
| Concept | Brainstorm ID | Theme | Notes |
|
||||
|---|---|---|---|
|
||||
| Combat Cinematics Mode | #4 | Automation | Auto-spotlight active combatant; requires Reaction Cam opt-in (FR-24) already in v1.0 |
|
||||
| Reaction Cam | #5, #17 | Cinematic | Opt-in per FR-24; triggers from game events |
|
||||
| Director's Board Stage Lighting States | #7 | Cinematic | Wash / Focus / Blackout vocabulary tier |
|
||||
| Token-Anchored Floating Cams | #8 | Cinematic | Deep canvas integration; high complexity |
|
||||
| HP-Reactive Cam Styling | #9 | Cinematic | Opt-in per FR-25 already scaffolded in v1.0 |
|
||||
| NPC Presence Tiles | #10 | Extended Presence | Static image tiles for NPC voice actors |
|
||||
| Spectator View | #11 | Streaming | Independent audience layout |
|
||||
| Zero-UI Full Automation Mode | #12 | Automation | Full configure-once, no-touch operation |
|
||||
| The Living Table (full seating chart) | #1 | Core Architecture | Full `Map<p, Map<v, State>>` UI exposure |
|
||||
| Pull Visibility Model | #14 | Core Architecture | Nothing is visible until actively requested |
|
||||
| Reaction Clip System | #15 | Privacy + Presence | Video snippet fallback for no-camera Participants |
|
||||
| Dual Layout System + Browser Source API | #18, #19 | Streaming | OBS-ready tile URLs; production stack |
|
||||
|
||||
---
|
||||
|
||||
## Cross-Cutting NFRs
|
||||
|
||||
**Compatibility**
|
||||
- The module must not conflict with other popular FoundryVTT modules (Monk's Hotbar, Token Action HUD, etc.) by patching shared DOM selectors or overriding core FoundryVTT hooks without proper chaining.
|
||||
- All hooks must use FoundryVTT's `Hooks.on()` registration pattern, never `Hooks.once()` for persistent behavior.
|
||||
|
||||
**Performance**
|
||||
- No Visibility Matrix operation should block the FoundryVTT main render loop.
|
||||
- The Director's Board must render and become interactive within 1 second even with 12 Participants.
|
||||
- Socket message payload for a Visibility Matrix update must be ≤ 4 KB.
|
||||
|
||||
**Reliability**
|
||||
- If the socket broadcast fails because of a network interruption, the GM client retries up to 3 times before surfacing an error notification.
|
||||
- The module must fail gracefully if `game.webrtc` is unavailable (for example, when AV is disabled); all UI elements are hidden or disabled rather than erroring.
|
||||
|
||||
**Privacy**
|
||||
- The module does not transmit any data outside the FoundryVTT world. No analytics, telemetry, or third-party calls.
|
||||
- Participant names and portraits are used only within the FoundryVTT session; no external storage is allowed.
|
||||
|
||||
**Accessibility**
|
||||
- All interactive elements in the Director's Board have ARIA labels and are keyboard navigable (FR-14).
|
||||
- State-indicator icons (FR-4) include tooltip text for screen-reader compatibility.
|
||||
|
||||
**Language and Voice**
|
||||
- Default UI labels use plain language: "Show," "Hide," "Spotlight," "Hidden by GM," "No Camera." Technical or cinematic vocabulary (for example, "Visibility Matrix" or "Wash / Focus / Blackout") is reserved for documentation, tooltips in advanced mode, and developer-facing strings — never as primary interface labels.
|
||||
- This two-tier vocabulary principle applies to all present and future features. Downstream contributors must follow the plain-language default; advanced or cinematic terms may appear only in optional advanced mode.
|
||||
|
||||
**GM Override Guarantee**
|
||||
- Every automation feature — present (Scene Presets, FR-17/FR-18) and future (Combat Cinematics Mode, Reaction Cam, Zero-UI Full Automation Mode) — must expose an obvious one-click GM override that is accessible without opening configuration UI.
|
||||
- The Director's Board "Hide All" action (FR-12) serves as the module's emergency path: the GM can silence all cameras in one click at any time, regardless of active automation state.
|
||||
- This is a non-negotiable cross-cutting rule: no automation may be implemented if it cannot be interrupted or overridden immediately by the GM.
|
||||
|
||||
**Delivery Risk Note (v1.0 scope)**
|
||||
- v1.0 intentionally combines the Day 1 core toggle (FR-1–FR-8) with Week 1–2 enhancements (FR-9–FR-26) into a single release. The brainstorming established Day 1 as a shippable standalone product; if delivery constraints arise, the Level 1 core toggle (FR-1–FR-8) is the minimum shippable increment, and all higher-level features can shift to v1.1 without breaking the architecture.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
# Reconciliation: Brainstorming → PRD
|
||||
|
||||
## Gaps Found (5 total)
|
||||
### G-1: Reaction Cam consent model flipped from opt-in to opt-out
|
||||
**Source:** Brainstorming Phase 3 / Sofia persona + Key Tension Resolved (brainstorming-session-2026-05-19-221747.md:130-150)
|
||||
**Gap:** The brainstorming resolved the Marcus/Sofia tension with a consent-aware rule: Reaction Cam is **opt-in at setup**. The PRD partially preserves the privacy concern, but FR-24 defines Reaction Cam as an **opt-out** setting, which weakens the explicit consent model and contradicts the brainstorming resolution.
|
||||
**Severity:** Critical
|
||||
**Suggestion:** Update the PRD so Reaction Cam is consistently framed as opt-in everywhere (Vision, Privacy Panel, Roadmap, and any future automation language). If the product owner intentionally changed this, document the rationale explicitly as a scope decision rather than leaving it as a silent inversion.
|
||||
|
||||
### G-2: Vocabulary-tier UX and product voice are under-specified
|
||||
**Source:** Alex persona + Idea #21 / Week 1–2 priorities (brainstorming-session-2026-05-19-221747.md:142-146, 173-178, 225-230)
|
||||
**Gap:** The brainstorming made "plain language by default, power terms in advanced mode" a distinct product idea and onboarding strategy. The PRD keeps some plain-language copy examples, but it does not preserve the broader UX rule of **default-simple vocabulary with optional advanced/cinematic terminology**. Because the PRD is glossary-heavy, downstream implementation could drift toward expert-facing labels and lose the beginner-friendly voice that Alex validated.
|
||||
**Severity:** Moderate
|
||||
**Suggestion:** Add an explicit UX/content principle or requirement: default labels use plain language (Show/Hide/Spotlight), while cinematic or advanced terminology is optional in advanced mode/tooltips/documentation.
|
||||
|
||||
### G-3: Director's Board usage model drifted away from the brainstormed workflow
|
||||
**Source:** SCAMPER Combine decision + Marcus/Jake personas (brainstorming-session-2026-05-19-221747.md:101, 124-140)
|
||||
**Gap:** The brainstorming positioned the seating-chart popout as a **low-frequency setup/control tool**: open at session start, close during play, and reopen instantly via shortcut when needed. The PRD includes keyboard access, but UJ-3 reframes the Director's Board as something that stays open in a corner during the session. That changes the intended operating model and may push the implementation toward a noisier, always-on control-room UI instead of a lightweight prep-time tool.
|
||||
**Severity:** Moderate
|
||||
**Suggestion:** Revise the PRD to clarify the intended workflow: the Director's Board is primarily a pre-session / between-scenes tool with instant shortcut recall, not something assumed to remain open throughout play. If both modes are desirable, state that explicitly.
|
||||
|
||||
### G-4: "Every automation needs a one-click GM override" is not elevated as a cross-cutting rule
|
||||
**Source:** Marcus persona + Question Storming "panic button" (brainstorming-session-2026-05-19-221747.md:54, 124-128)
|
||||
**Gap:** The brainstorming established a strong control principle: automation is welcome only if the GM can immediately override it, including an instant hide-all/panic path. The PRD implements some related mechanics (Hide All, manual overrides for Scene Presets), but it does not carry forward the broader **product rule** that every present and future automation surface must expose an immediate GM override. That omission matters because downstream work on Scene Presets, Combat Cinematics, and Reaction Cam could become harder to interrupt safely.
|
||||
**Severity:** Moderate
|
||||
**Suggestion:** Add a cross-cutting requirement or design principle: every automation-capable feature must provide an obvious one-click GM override, and the module must expose an emergency hide-all action reachable without opening deep configuration UI.
|
||||
|
||||
### G-5: The brainstorm's phased-delivery discipline is blurred in the PRD
|
||||
**Source:** North Star + Priority Stack + Session Summary (brainstorming-session-2026-05-19-221747.md:208-238, 277-293)
|
||||
**Gap:** The brainstorming repeatedly anchored the product around a tightly scoped Day 1 ship: right-click toggle first, then practical Week 1–2 enhancements, then cinematic/streaming power features later. The PRD preserves the concepts but largely collapses Day 1 and Week 1–2 work into one v1.0 scope. That weakens the brainstorming's explicit risk-control signal: keep the first release rooted in the shippable core toggle.
|
||||
**Severity:** Moderate
|
||||
**Suggestion:** Add a release-phasing addendum or split scope more clearly into MVP / post-MVP milestones (for example: Level 1 ship first, then Director's Board + Presets, then privacy/automation scaffolding). If the all-in v1.0 scope is intentional, note the increased delivery risk explicitly.
|
||||
|
||||
## Intentional Drops (confirmed out of scope)
|
||||
- Full asymmetric per-viewer visibility control / who-sees-who UI exposure — correctly deferred to Later roadmap / v1.0 non-goal.
|
||||
- Pull Visibility Model — correctly deferred to Later roadmap.
|
||||
- Combat Cinematics Mode — correctly deferred to Later roadmap.
|
||||
- Reaction Cam feature execution — correctly deferred to Later roadmap (while privacy prerequisites remain relevant now).
|
||||
- Stage Lighting States / theatrical vocabulary mode — correctly deferred to Later roadmap.
|
||||
- Token-Anchored Floating Cams — correctly deferred to Later roadmap.
|
||||
- HP-Reactive Camera Styling runtime behavior — correctly deferred to Later roadmap.
|
||||
- NPC Presence Tiles — correctly deferred to Later roadmap.
|
||||
- Spectator Curtain / Dual Layout System — correctly deferred to Later roadmap.
|
||||
- Browser Source API / OBS-ready tile URLs — correctly deferred to Later roadmap.
|
||||
- Zero-UI Full Automation Mode — correctly deferred to Later roadmap.
|
||||
- Reaction Clip System — correctly deferred to Later roadmap.
|
||||
- Non-native AV backends (e.g. Jitsi) — correctly excluded for v1.0 by explicit non-goal/open-question resolution.
|
||||
Reference in New Issue
Block a user