CLose story 1.2
This commit is contained in:
@@ -0,0 +1,300 @@
|
||||
---
|
||||
stepsCompleted: [1, 2, 3, 4]
|
||||
session_active: false
|
||||
workflow_completed: true
|
||||
ideas_generated: [21]
|
||||
inputDocuments: []
|
||||
session_topic: 'FoundryVTT v14 webcam view manager module'
|
||||
session_goals: 'Granular webcam visibility control per player, individual enable/disable, efficient and practical UI, who-sees-who selection between connected players'
|
||||
selected_approach: 'ai-recommended'
|
||||
techniques_used: ['Question Storming', 'SCAMPER Method', 'Role Playing']
|
||||
ideas_generated: []
|
||||
context_file: ''
|
||||
---
|
||||
|
||||
# Brainstorming Session Results
|
||||
|
||||
**Facilitator:** Morr
|
||||
**Date:** 2026-05-19
|
||||
|
||||
## Session Overview
|
||||
|
||||
**Topic:** FoundryVTT v14 webcam view manager module
|
||||
**Goals:** Granular webcam visibility control per player, individual enable/disable, efficient and practical UI, who-sees-who selection between connected players
|
||||
|
||||
### Session Setup
|
||||
|
||||
_Fresh session initialized. No context file provided._
|
||||
|
||||
## Technique Selection
|
||||
|
||||
**Approach:** AI-Recommended Techniques
|
||||
**Analysis Context:** FoundryVTT v14 webcam view manager module with focus on granular player-to-player visibility control and practical UI design
|
||||
|
||||
**Recommended Techniques:**
|
||||
|
||||
- **Question Storming:** Surface hidden requirements, edge cases, and unknowns before generating solutions — defines the correct problem space
|
||||
- **SCAMPER Method:** Systematic 7-lens feature/UI idea generation (Substitute, Combine, Adapt, Modify, Put to other use, Eliminate, Reverse)
|
||||
- **Role Playing:** Embody GM, players, streamers, mobile users to ground ideas in real human perspective
|
||||
|
||||
**AI Rationale:** This sequence moves from problem definition → systematic generation → human validation. Ideal for a technical product with multiple user roles and complex interaction states.
|
||||
|
||||
---
|
||||
|
||||
## Technique Execution Results
|
||||
|
||||
### Phase 1: Question Storming
|
||||
|
||||
**Interactive Focus:** Surfacing hidden requirements, edge cases, and architectural constraints before generating solutions.
|
||||
|
||||
**Key Questions Generated:**
|
||||
- Who has permission to change visibility? Only GM, or can players hide themselves?
|
||||
- What happens when a player joins mid-session — visible by default or hidden?
|
||||
- Should visibility be symmetric or asymmetric (GM sees all, players see what's allowed)?
|
||||
- What's the "panic button" — how does GM instantly hide all cams?
|
||||
- How does this interact with FoundryVTT's existing AV system (`game.webrtc`)?
|
||||
- If a webcam disconnects, does its slot disappear or leave a placeholder?
|
||||
- What if it disconnects mid-combat — does the layout reflow and disrupt players?
|
||||
- Is a disconnected cam different from a hidden cam?
|
||||
- What about reconnection — does it snap back to previous state or reset?
|
||||
- What if the GM's own webcam disconnects?
|
||||
- Should the UI communicate WHY a feed is absent? (Camera off vs Player disconnected vs GM hid this feed)
|
||||
- Where does this UI live? Sidebar? Floating overlay? Popout?
|
||||
- On a screen with 8 players, how do you display a visibility matrix without a spreadsheet nightmare?
|
||||
- Should there be presets? ("Cinematic mode", "Social mode")
|
||||
- What visual feedback tells a player their own feed is hidden from someone?
|
||||
- Should players know they're being hidden, or is it silent?
|
||||
- Does FoundryVTT's WebRTC even support per-viewer stream filtering, or must visibility be faked client-side?
|
||||
- How do settings persist across sessions?
|
||||
- What happens in combat vs exploration — should the module have scene-aware presets?
|
||||
|
||||
**Breakthrough Insight — The Visibility Matrix:**
|
||||
The module's data model isn't `Map<playerId, boolean>` — it's `Map<playerId, Map<viewerId, VisibilityState>>`. Every player has a visibility setting *per observer*. This is the architectural heart of "who sees what."
|
||||
|
||||
**Participant State Machine (8 states identified):**
|
||||
- `active` — Camera on, feed visible to permitted viewers
|
||||
- `hidden` — Camera on, but GM/module has hidden it
|
||||
- `self-muted` — Player turned off their own cam voluntarily
|
||||
- `offline` — Player's connection dropped entirely
|
||||
- `cam-lost` — Player connected but camera device failed
|
||||
- `reconnecting` — Transitional, feed expected to return
|
||||
- `never-connected` — Player joined with no camera
|
||||
- `ghost` — Secretly observing (GM special state)
|
||||
|
||||
**3 Core Tensions Identified:**
|
||||
1. Asymmetric visibility — the matrix is powerful but complex to display
|
||||
2. Silent vs announced changes — trust and social design
|
||||
3. Technical layer — is filtering real (WebRTC) or cosmetic (CSS hide)?
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: SCAMPER Method
|
||||
|
||||
**Interactive Focus:** Systematic 7-lens feature and UI idea generation.
|
||||
|
||||
#### S — Substitute
|
||||
Explored substituting the toggle metaphor with spatial/contextual alternatives. Key insight: the **seating chart metaphor** maps naturally to how TTRPG players think about the table.
|
||||
|
||||
#### C — Combine
|
||||
Explored combining with combat tracker, scene transitions, character status. Key insight: **Combat Cinematics Mode** — the module acts as a live director during combat, auto-spotlighting the active combatant.
|
||||
|
||||
**Decision captured:** Dedicated popout window for the seating chart UI — low-frequency tool, opened at session start, closed during play.
|
||||
|
||||
#### A — Adapt
|
||||
Adapted patterns from video conferencing (spotlight/pin), broadcast control rooms (switcher), and theater (lighting states). Key insight: **Stage Lighting States** — "Wash/Focus/Blackout" maps perfectly to TTRPG dramatic vocabulary.
|
||||
|
||||
#### M — Modify
|
||||
Scaled up (token-anchored floating cams) and distorted (HP-reactive cam styling). Key insight: **Token-Anchored Floating Cams** — player faces float above tokens on the canvas.
|
||||
|
||||
#### P — Put to Other Uses
|
||||
Discovered unexpected applications: NPC presence tiles, spectator curtain for streamers, murder mystery reveals. Key insight: **Spectator Curtain** opens the module to the actual-play streaming market.
|
||||
|
||||
#### E — Eliminate
|
||||
Stripped features to find the irreducible core. Key insight: **Progressive Enhancement Architecture** — Level 1 (right-click) → Level 2 (Director's Board) → Level 3 (popout). MVP might be just Level 1.
|
||||
|
||||
#### R — Reverse
|
||||
Flipped the control model. Key insight: **Pull Visibility Model** — nothing visible until someone actively requests to see it. Also: **Reaction Clip System** for players without webcams.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Role Playing
|
||||
|
||||
**Interactive Focus:** Embodying 4 stakeholder personas to stress-test all concepts.
|
||||
|
||||
**Persona 1 — Marcus (Veteran GM):**
|
||||
- Wants zero-clicks during play — automation is king
|
||||
- Scene-aware presets match his prep workflow perfectly
|
||||
- Every automation needs a one-click GM override
|
||||
- Reaction cam needs per-scene disable option
|
||||
|
||||
**Persona 2 — Sofia (Privacy-Conscious Player):**
|
||||
- Pull visibility model respects player agency
|
||||
- Reaction clip system includes her when bandwidth is poor
|
||||
- HP-reactive cam sizing must be opt-in per player
|
||||
- Reaction cam auto-popup is a privacy risk without opt-out
|
||||
|
||||
**Persona 3 — Jake (Actual-Play Streamer):**
|
||||
- Spectator curtain is critical — audience vs player views must be independent
|
||||
- Keyboard shortcuts essential during live broadcast
|
||||
- Browser Source API (OBS-ready tile URLs) transforms the module into a production stack
|
||||
- Seating chart popout needs instant keyboard shortcut access
|
||||
|
||||
**Persona 4 — Alex (New Player):**
|
||||
- Seating chart metaphor instantly understood; visibility matrix jargon was not
|
||||
- Plain language everywhere — "Show/Hide/Spotlight" not "Wash/Focus/Blackout"
|
||||
- Automation without feedback is terrifying — needs toast notifications
|
||||
- Portrait fallback for bad/missing cameras reduces anxiety
|
||||
|
||||
**Key Tension Resolved:**
|
||||
Marcus wants drama (reaction cam), Sofia wants privacy (no surprise reveals).
|
||||
→ **Resolution:** Reaction cam is opt-in at character/player setup. Consent-aware design.
|
||||
|
||||
---
|
||||
|
||||
## Complete Idea Inventory (21 Concepts)
|
||||
|
||||
| # | Concept | Source | Theme |
|
||||
|---|---|---|---|
|
||||
| 1 | The Living Table | SCAMPER-S | Core Architecture |
|
||||
| 2 | Table Manager Popout | SCAMPER-S | Core Architecture |
|
||||
| 3 | Scene-Aware Visibility Presets | SCAMPER-C | Automation |
|
||||
| 4 | Combat Cinematics Mode | SCAMPER-C | Automation + Cinematic |
|
||||
| 5 | The Reaction Cam | SCAMPER-C | Cinematic |
|
||||
| 6 | The Director's Board | SCAMPER-A | Cinematic |
|
||||
| 7 | Stage Lighting States | SCAMPER-A | Cinematic |
|
||||
| 8 | Token-Anchored Floating Cams | SCAMPER-M | Cinematic |
|
||||
| 9 | HP-Reactive Cam Styling | SCAMPER-M | Cinematic |
|
||||
| 10 | NPC Presence Tiles | SCAMPER-P | Extended Presence |
|
||||
| 11 | Spectator Curtain | SCAMPER-P | Streaming |
|
||||
| 12 | Zero-UI Automation Mode | SCAMPER-E | Automation |
|
||||
| 13 | Progressive Enhancement Architecture | SCAMPER-E | Core Architecture |
|
||||
| 14 | Pull Visibility Model | SCAMPER-R | Core Architecture |
|
||||
| 15 | Reaction Clip System | SCAMPER-R | Privacy + Extended Presence |
|
||||
| 16 | Player Privacy Preferences Panel | Role Playing | Privacy |
|
||||
| 17 | Opt-In Reaction Cam | Role Playing | Privacy + Cinematic |
|
||||
| 18 | Dual Layout System | Role Playing | Streaming |
|
||||
| 19 | Browser Source API | Role Playing | Streaming |
|
||||
| 20 | Contextual Action Notifications | Role Playing | Automation |
|
||||
| 21 | Vocabulary Tiers | Role Playing | UX / Onboarding |
|
||||
|
||||
---
|
||||
|
||||
## Idea Organization and Prioritization
|
||||
|
||||
### Thematic Clusters
|
||||
|
||||
**🏗️ Theme 1: Core Architecture**
|
||||
*What the module IS — foundational data model and UI structure*
|
||||
- #1 The Living Table, #2 Table Manager Popout, #13 Progressive Enhancement, #14 Pull Visibility Model
|
||||
|
||||
**🤖 Theme 2: Automation & Intelligence**
|
||||
*The module as silent director — configure once, run forever*
|
||||
- #3 Scene-Aware Presets, #4 Combat Cinematics Mode, #12 Zero-UI Automation Mode, #20 Contextual Notifications
|
||||
|
||||
**🎬 Theme 3: Cinematic & Dramatic Effects**
|
||||
*Transforms sessions into cinematic experiences*
|
||||
- #5 Reaction Cam, #6 Director's Board, #7 Stage Lighting States, #8 Token-Anchored Cams, #9 HP-Reactive Styling, #17 Opt-In Reaction Cam
|
||||
|
||||
**🔒 Theme 4: Privacy & Player Agency**
|
||||
*No surprises — players always in control*
|
||||
- #15 Reaction Clip System, #16 Player Privacy Panel, #17 Opt-In Reaction Cam, #21 Vocabulary Tiers
|
||||
|
||||
**📺 Theme 5: Streaming & Extended Presence**
|
||||
*Actual-play production without a technical director*
|
||||
- #10 NPC Presence Tiles, #11 Spectator Curtain, #18 Dual Layout System, #19 Browser Source API
|
||||
|
||||
---
|
||||
|
||||
### ⭐ North Star Feature (Confirmed by User)
|
||||
|
||||
> **As a GM, I can click a player's webcam tile and toggle it visible/hidden for all players — instantly, reliably, one click.**
|
||||
|
||||
Everything else is either a smarter trigger for this toggle, a richer display of its state, an extension of who controls it, or an extra surface for its result.
|
||||
|
||||
---
|
||||
|
||||
### Priority Stack
|
||||
|
||||
**🥇 Day 1 — The Core Toggle**
|
||||
- GM clicks a player's cam tile → cam hidden/shown for all players
|
||||
- State persists through player reconnection
|
||||
- Plain visual indicator: "this cam is hidden by GM"
|
||||
- Right-click context menu on existing AV tiles (Level 1 — zero new UI)
|
||||
- FoundryVTT v14 API scope: hook into `game.webrtc` / existing AV tiles, store state in `game.settings` or socket broadcast
|
||||
|
||||
**🥈 Week 1–2 — Make it practical**
|
||||
- #2 Table Manager Popout (bulk management for 6+ players)
|
||||
- #3 Scene-Aware Presets (configure at prep, not during play)
|
||||
- #20 Contextual Notifications ("GM hid Sofia's cam")
|
||||
- #16 Player Privacy Panel (opt-out of effects)
|
||||
- #21 Vocabulary Tiers (plain language default, power terms in advanced mode)
|
||||
|
||||
**🥉 Later — Make it powerful**
|
||||
- #4 Combat Cinematics Mode + #17 Opt-In Reaction Cam
|
||||
- #6 Director's Board + #7 Stage Lighting States
|
||||
- #12 Zero-UI Automation Mode
|
||||
- #1 Living Table / full seating chart UI
|
||||
- #11 Spectator Curtain + #18 Dual Layout + #19 Browser Source API
|
||||
- #8 Token-Anchored Cams, #9 HP-Reactive Styling, #10 NPC Presence Tiles, #15 Reaction Clip System
|
||||
|
||||
---
|
||||
|
||||
## Action Planning
|
||||
|
||||
### Day 1 Implementation Roadmap
|
||||
|
||||
**1. Research — FoundryVTT v14 AV API**
|
||||
- Read `game.webrtc` API and AVMaster hooks
|
||||
- Identify how existing cam tiles are rendered in the DOM
|
||||
- Determine if visibility is real (WebRTC track disable) or cosmetic (CSS)
|
||||
- Check `game.settings` for persistent storage approach
|
||||
- Review `socketlib` or native socket options for broadcasting state to all clients
|
||||
|
||||
**2. Build — Core Toggle (MVP)**
|
||||
- Register module in `module.json` for FoundryVTT v14
|
||||
- Hook into AV cam tile render to inject right-click context menu
|
||||
- Implement `setPlayerCamVisible(playerId, visible)` function
|
||||
- Broadcast state change via socket to all connected clients
|
||||
- Each client applies visibility to their local cam tile render
|
||||
- Persist state in `game.settings` (world-level)
|
||||
- Add visual indicator on hidden tiles (icon overlay or opacity change)
|
||||
|
||||
**3. Test — Edge Cases from Question Storming**
|
||||
- Player disconnects while hidden → reconnects → state restored correctly
|
||||
- GM cam hidden → what happens to GM's own view?
|
||||
- Player with no camera → graceful fallback (portrait shown)
|
||||
- Mid-combat hide → layout stable, no reflow disruption
|
||||
|
||||
**4. Ship — Level 1**
|
||||
- Zero new UI surface — pure right-click enhancement
|
||||
- Works on all existing FoundryVTT AV layouts
|
||||
- Document the 8-state participant model for future development
|
||||
|
||||
---
|
||||
|
||||
## Session Summary and Insights
|
||||
|
||||
**Key Achievements:**
|
||||
- 21 breakthrough concepts generated across 3 creative techniques
|
||||
- 5 thematic clusters identified covering the full product surface
|
||||
- North star feature confirmed and scoped for Day 1 implementation
|
||||
- 4 user personas stress-tested all concepts — critical tensions resolved
|
||||
- Clear 3-tier priority stack established (Day 1 → Week 1-2 → Later)
|
||||
- FoundryVTT v14 technical scope defined for MVP
|
||||
|
||||
**Breakthrough Moments:**
|
||||
- The seating chart metaphor reframed the UI from "settings panel" to "spatial social experience"
|
||||
- The visibility matrix (`Map<playerId, Map<viewerId, State>>`) clarified the true data model complexity
|
||||
- The 4-persona analysis revealed 3 distinct user tiers (GM power, player privacy, streamer production)
|
||||
- Progressive Enhancement Architecture ensures the module is useful at every complexity level
|
||||
- Reaction cam opt-in resolved the Marcus/Sofia privacy tension elegantly
|
||||
|
||||
**Creative Facilitation Narrative:**
|
||||
The session began with a simple goal — webcam visibility control — and evolved into a session cinematography platform. Question Storming surfaced the architectural complexity (8 participant states, visibility matrix). SCAMPER transformed the concept from utility to product, discovering the seating chart metaphor, combat cinematics, and streaming tools. Role Playing grounded the ideas in human reality, revealing the privacy-first design principle and the 4-level user tier model. The final anchor back to "GM toggle = Day 1" ensures the ambitious vision stays rooted in a shippable, focused MVP.
|
||||
|
||||
**Your Next Steps:**
|
||||
1. Read FoundryVTT v14 AV API documentation (`game.webrtc`, `AVMaster`, cam tile hooks)
|
||||
2. Build the right-click toggle on existing cam tiles (Day 1 MVP)
|
||||
3. Test the 8 participant state transitions
|
||||
4. Plan the Table Manager Popout and Scene Presets for Week 1–2
|
||||
5. Keep the 21-concept inventory as the product backlog for future sprints
|
||||
+581
@@ -0,0 +1,581 @@
|
||||
# Story 1.1: Module Scaffold, CI/CD Pipeline & Design Token System
|
||||
|
||||
Status: done
|
||||
|
||||
## Story
|
||||
|
||||
As a **developer**,
|
||||
I want a fully configured module scaffold with the complete `--sp-*` design token system, contract files, tooling, and CI,
|
||||
so that every subsequent story builds on enforced boundaries, verified tooling, and a stable design language.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Given** the repository is checked out fresh **When** `npm install && npm run lint && npm run typecheck && npm run test` are executed **Then** all commands exit 0 **And** `npm run build` produces `module.zip` containing `module.json`, `scripts/`, `styles/`, `templates/`, `lang/`
|
||||
|
||||
2. **Given** the module is installed in FoundryVTT v14 **When** FoundryVTT loads **Then** the module activates with no console errors and `game.modules.get('video-view-manager').active === true`
|
||||
|
||||
3. **Given** a developer writes an exported function without a JSDoc comment **When** `npm run lint` runs **Then** `eslint` reports a `jsdoc/require-jsdoc` violation
|
||||
|
||||
4. **Given** a source file imports from a restricted layer **When** `npm run lint` runs **Then** `import/no-restricted-paths` reports a boundary violation
|
||||
|
||||
5. **Given** a Gitea push is made **When** the CI workflow runs **Then** lint, typecheck, and test all run; a failing test fails the workflow
|
||||
|
||||
6. **Given** a developer writes module CSS using a Foundry `--color-*`/`--font-*`/`--border-*` token directly inside `.scrying-pool` CSS **When** the linting convention is enforced **Then** a violation is reported — all Foundry tokens must be aliased through `--sp-*`
|
||||
|
||||
7. **Given** a developer renders any participant state **When** they look up the token system in `styles/scrying-pool.less` **Then** all token layers are defined:
|
||||
- Layer 1: SP semantic aliases (`--sp-surface`, `--sp-border`, `--sp-text-primary`, `--sp-text-secondary`, `--sp-accent`, `--sp-focus`) mapping to Foundry tokens with hardcoded fallbacks
|
||||
- Layer 2: SP Participant State tokens for all 8 states (`active`, `hidden`, `self-muted`, `offline`, `cam-lost`, `reconnecting`, `never-connected`, `ghost`)
|
||||
- Layer 3: SP Urgency + Motion tokens (`--sp-urgency-director`, `--sp-urgency-awareness`, `--sp-fade-hide`, `--sp-pulse-reconnecting`, `--sp-shimmer-degraded`, `--sp-toast-delay`)
|
||||
- **And** the `VisibilityBadge` `:root` exception is documented: badge tokens declared on `:root` because badge mounts outside `.scrying-pool` root
|
||||
- **And** all animated token usages gated under `@media (prefers-reduced-motion: no-preference)`
|
||||
|
||||
8. **Given** the 4 contract files exist **When** a story imports `src/contracts/visibility-matrix.js` **Then** it exports a canonical shape constant, a factory function (`createVisibilityMatrix()`), and a guard/validator function (`isValidVisibilityMatrix(data)`) **And** the same factory + validator pattern applies to `socket-message.js`, `pending-op.js`, `scene-preset.js`
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [x] Task 1: Initialize npm project and install devDependencies (AC: #1)
|
||||
- [x] 1.1 Run `npm init -y` and configure `package.json` with exact scripts block (see Dev Notes)
|
||||
- [x] 1.2 Install all devDependencies with pinned versions (see Dev Notes)
|
||||
- [x] 1.3 Verify `npm install` exits 0 with lock file generated
|
||||
|
||||
- [x] Task 2: Create root config files (AC: #1, #3, #4)
|
||||
- [x] 2.1 Create `tsconfig.json` with `checkJs`, `strict`, `noEmit`, `ESNext` target, `module: ESNext`, `moduleResolution: node16`, `allowJs: true`
|
||||
- [x] 2.2 Create `.eslintrc.js` with `jsdoc/require-jsdoc` on all exported symbols and `import/no-restricted-paths` zones for all 6 boundary rules (see Dev Notes)
|
||||
- [x] 2.3 Create `vitest.config.js` with happy-dom environment, path aliases, coverage config
|
||||
- [x] 2.4 Create `.gitignore` excluding `dist/`, `node_modules/`, `*.zip`
|
||||
|
||||
- [x] Task 3: Create `module.json` v14 manifest (AC: #2)
|
||||
- [x] 3.1 Set `id: "video-view-manager"`, title, version from `package.json`, v14 compatibility block
|
||||
- [x] 3.2 Register `esmodules: ["module.js"]`, `styles: ["dist/styles/scrying-pool.css"]`, `languages: [{ lang: "en", name: "English", path: "lang/en.json" }]`
|
||||
|
||||
- [x] Task 4: Create `scripts/package.mjs` release script (AC: #1)
|
||||
- [x] 4.1 Read version from `package.json`; write into `module.json` at release time
|
||||
- [x] 4.2 Produce `module.zip` containing: `module.json`, `module.js`, `dist/`, `lang/`, `templates/`, `src/`
|
||||
- [x] 4.3 Single version source of truth — `package.json` only; never manually edit `module.json` version field
|
||||
|
||||
- [x] Task 5: Create `module.js` entry point stub (AC: #2)
|
||||
- [x] 5.1 Empty orchestrator that registers `Hooks.once('init', () => {})` and `Hooks.once('ready', () => {})`
|
||||
- [x] 5.2 No business logic — wiring only; add `[ScryingPool]` console log to confirm load
|
||||
- [x] 5.3 Export nothing (module entry point, not a library)
|
||||
|
||||
- [x] Task 6: Create the 4 contract files in `src/contracts/` (AC: #8)
|
||||
- [x] 6.1 `src/contracts/visibility-matrix.js` — typedef + `createVisibilityMatrix()` + `isValidVisibilityMatrix()`
|
||||
- [x] 6.2 `src/contracts/socket-message.js` — typedef + `createSocketMessage()` + `isValidSocketMessage()`
|
||||
- [x] 6.3 `src/contracts/pending-op.js` — typedef + `createPendingOp()` + `isValidPendingOp()`
|
||||
- [x] 6.4 `src/contracts/scene-preset.js` — typedef + `createScenePreset()` + `isValidScenePreset()`
|
||||
- [x] 6.5 All validators: reject unknown keys, throw `TypeError` with field name on violation; timestamps as finite non-negative integers; id fields non-empty strings; nullable fields explicit `null`
|
||||
|
||||
- [x] Task 7: Create design token LESS system (AC: #6, #7)
|
||||
- [x] 7.1 Create `styles/scrying-pool.less` entry point with `@import` references only
|
||||
- [x] 7.2 Create `styles/tokens/_base.less` — Layer 1 SP semantic aliases (6 tokens + hardcoded fallbacks)
|
||||
- [x] 7.3 Create `styles/tokens/_states.less` — Layer 2 all 8 participant states + `pending` (9 total); color + icon + shape per state; LESS map `@sp-states` (see Dev Notes for exact map)
|
||||
- [x] 7.4 Create `styles/tokens/_motion.less` — Layer 3/4 urgency + motion tokens; `--sp-fade-hide`, `--sp-pulse-reconnecting`, `--sp-shimmer-degraded`, `--sp-toast-delay`; all animated tokens under `@media (prefers-reduced-motion: no-preference)`
|
||||
- [x] 7.5 Create `styles/tokens/_focus.less` — module-wide focus ring; high-contrast outer ring + inner offset
|
||||
- [x] 7.6 Add `:root` block for `VisibilityBadge` exception with documenting comment
|
||||
- [x] 7.7 Create `styles/components/` stubs (empty files with scope comment): `_participant-card.less`, `_roster-strip.less`, `_directors-board.less`, `_scene-preset-panel.less`, `_notification.less`, `_player-badge.less`, `_player-panel.less`
|
||||
- [x] 7.8 Verify `npm run build` produces `dist/styles/scrying-pool.css`
|
||||
|
||||
- [x] Task 8: Create test infrastructure (AC: #1)
|
||||
- [x] 8.1 Create `tests/helpers/foundryAdapterMock.js` — `createFoundryAdapterMock(overrides={})` canonical mock; covers `settings`, `socket`, `users`, `scenes`, `notifications`, `webrtc: null`, `hooks`
|
||||
- [x] 8.2 Create `tests/fixtures/socket-payloads.js` — `Object.freeze`'d stub with valid + malformed shapes (missing `opId`, wrong enum, extra keys)
|
||||
- [x] 8.3 Create `tests/fixtures/visibility-states.js`, `state-store-snapshots.js`, `scene-preset.js`, `pending-op.js`, `foundry-adapter.js` — all `Object.freeze`'d
|
||||
- [x] 8.4 Create contract test files in `tests/unit/contracts/` for all 4 contracts — test factory happy path, validator rejections
|
||||
|
||||
- [x] Task 9: Create Gitea CI workflow (AC: #5)
|
||||
- [x] 9.1 Create `.gitea/workflows/ci.yml` — runs on every push; steps: `npm ci`, `npm run lint`, `npm run typecheck`, `npm run test`
|
||||
- [x] 9.2 Failing test must fail the workflow (non-zero exit propagates)
|
||||
|
||||
- [x] Task 10: Create `lang/en.json` i18n skeleton (AC: #1)
|
||||
- [x] 10.1 Create with empty-but-valid JSON `{}` — or a top-level `"video-view-manager"` namespace stub
|
||||
- [x] 10.2 Register in `module.json` as `languages` array entry
|
||||
|
||||
- [x] Task 11: Create `templates/` stubs (AC: #1)
|
||||
- [x] 11.1 Create minimal stub `.hbs` files: `directors-board.hbs`, `participant-card.hbs`, `roster-strip.hbs`, `scene-preset-panel.hbs`, `player-panel.hbs`
|
||||
|
||||
- [x] Task 12: Verify full pipeline (AC: #1, #3, #4)
|
||||
- [x] 12.1 `npm run lint` exits 0 on clean code; reports violation on missing JSDoc export
|
||||
- [x] 12.2 `npm run typecheck` exits 0
|
||||
- [x] 12.3 `npm run test` exits 0 (contract tests pass)
|
||||
- [x] 12.4 `npm run build` produces `dist/styles/scrying-pool.css`
|
||||
- [x] 12.5 `npm run release` produces `module.zip`
|
||||
|
||||
### Review Findings
|
||||
|
||||
- [x] [Review][Decision] Empty module entry point — Hooks registered with empty implementations, no actual operations (RESOLVED: Keep as stub for story 1.1)
|
||||
- [x] [Review][Decision] Production zip includes source — `src/` included in INCLUDE list for production module.zip (RESOLVED: Keep as-is, standard for Foundry modules)
|
||||
- [x] [Review][Decision] Hardcoded module.json version — Violates single source of truth (managed by package.json) (RESOLVED: Keep hardcoded, synced at release time)
|
||||
- [x] [Review][Patch] Missing zip dependency [scripts/package.mjs:47]
|
||||
- [x] [Review][Patch] Build dependency not declared [package.json:14] (less is already installed, lessc available)
|
||||
- [x] [Review][Patch] Incomplete .gitignore [.gitignore:1-4]
|
||||
- [x] [Review][Patch] No error handling for file reads [scripts/package.mjs:22,24]
|
||||
- [x] [Review][Patch] Zip command injection risk [scripts/package.mjs:43-44]
|
||||
- [x] [Review][Patch] Incomplete lint scope [package.json:10]
|
||||
- [x] [Review][Patch] Missing ts-nocheck on module.js [module.js:1]
|
||||
- [x] [Review][Patch] Overly restrictive import zones [eslint.config.js:42-91] (Added import/resolver settings)
|
||||
|
||||
---
|
||||
|
||||
**Group 2a Findings (package-lock.json):**
|
||||
- [x] [Review][Patch] Missing foundry-vtt-types dependency — Added to package.json and package-lock.json per AC#1
|
||||
- [x] [Review][Patch] Lock file out of sync — Added zip dependency to package-lock.json root devDependencies
|
||||
|
||||
---
|
||||
|
||||
**Group 2b Findings (package-lock.json lines 2401-4967):**
|
||||
- [x] [Review][Patch] Invalid placeholder hash for zip — Replaced with real SHA-512 hash from npm registry
|
||||
- [x] [Review][Patch] Missing integrity hash for foundry-vtt-types — Added integrity field using npm registry version
|
||||
- [x] [Review][Patch] foundry-vtt-types not SHA-pinned — Changed to npm registry version 13.346.0-beta.20250812191140
|
||||
- [x] [Review][Patch] Missing integrity hashes — All entries now have integrity fields
|
||||
- [x] [Review][Patch] Root package missing license field — Added MIT license to root entry
|
||||
- [x] [Review][Patch] No root package engine specification — Added Node.js >=18.0.0 engines field
|
||||
- [x] [Review][Decision] Non-pinned devDependencies — Use caret ranges vs exact pinned versions per spec (DEFERRED: Address when version pinning strategy finalized)
|
||||
- [x] [Review][Defer] Vulnerable dependency CVE-2023-43645 — flat-cache-4.0.1 (verify vulnerability)
|
||||
|
||||
---
|
||||
|
||||
**Group 2b Re-review Findings:**
|
||||
- [x] [Review][Patch] Beta dependency risk — Changed foundry-vtt-types from 13.346.0-beta to stable 9.280.1
|
||||
- [x] [Review][Patch] Version range too permissive — Changed @types/node from ^22.0.0 to 22.x per spec
|
||||
- [x] [Review][Decision] Non-pinned devDependencies — Caret ranges violate exact version requirement per Task 1.2 (RESOLVED: Keep caret ranges, lock file provides exact resolved versions)
|
||||
- [ ] [Review][Defer] Version conflicts — Multiple versions: make-dir (5.7.2, 6.3.1, 7.8.0), debug (4.4.3, 3.2.7)
|
||||
- [x] [Review][Dismiss] Platform-specific optionals — 83+ optional packages (expected npm behavior)
|
||||
- [x] [Review][Dismiss] Postinstall script risk — esbuild/fsevents (expected npm behavior)
|
||||
- [x] [Review][Dismiss] Nested node_modules — 9 nested paths (expected npm behavior)
|
||||
- [x] [Review][Dismiss] Engine requirement mismatch — Root >=18.0.0 vs dep ranges (expected npm behavior)
|
||||
- [x] [Review][Dismiss] Peer dependency breadth — eslint-plugin-import range (expected npm behavior)
|
||||
- [x] [Review][Dismiss] Optional peer without fallback — happy-dom requires @types/node (expected npm behavior)
|
||||
- [x] [Review][Dismiss] Packages with install scripts — esbuild/fsevents expected behavior
|
||||
|
||||
---
|
||||
|
||||
**Group 3 Findings (Source Contracts):**
|
||||
- [x] [Review][Patch] Whitespace strings pass validation — Added .trim() to string checks [src/contracts/pending-op.js]
|
||||
- [x] [Review][Patch] Non-finite timeoutId passes — Added Number.isFinite() check [src/contracts/pending-op.js]
|
||||
- [x] [Review][Patch] Missing canonical shape constant — Added PENDING_OP_VERSION [src/contracts/pending-op.js]
|
||||
- [x] [Review][Patch] Incomplete validator — Added finite non-negative check for timeoutId [src/contracts/pending-op.js]
|
||||
- [x] [Review][Decision] Factory signature deviation — Positional params vs Partial<PendingOp> input (RESOLVED: Keep positional params for ergonomics, matches other contracts)
|
||||
- [x] [Review][Dismiss] No max string length validation — Expected behavior [src/contracts/pending-op.js:54-64]
|
||||
- [x] [Review][Dismiss] Future issuedAt allowed — Expected behavior [src/contracts/pending-op.js:66]
|
||||
- [x] [Review][Dismiss] Unvalidated createPendingOp — Expected behavior [src/contracts/pending-op.js:35]
|
||||
|
||||
---
|
||||
|
||||
**Group 4 Findings (Styles & Tokens):**
|
||||
- [x] [Review][Patch] Focus indicator removal — Added visible fallback comment [styles/tokens/_focus.less:15]
|
||||
- [x] [Review][Patch] Reduced motion kills animations — Replaced universal selector, removed !important [styles/tokens/_motion.less]
|
||||
- [x] [Review][Patch] Universal selector performance — Replaced with specific selectors [styles/tokens/_motion.less]
|
||||
- [x] [Review][Patch] Overuse of !important — Removed from reduced motion rules [styles/tokens/_motion.less]
|
||||
- [x] [Review][Patch] Focus ring clipped by overflow — Added overflow warning comment [styles/tokens/_focus.less:17]
|
||||
- [x] [Review][Patch] Missing --sp-urgency-awareness token — Added to Layer 3 [styles/tokens/_motion.less]
|
||||
- [x] [Review][Patch] urgency-director in wrong layer — Moved from Layer 1 to Layer 3 [styles/tokens/_motion.less]
|
||||
- [x] [Review][Decision] Empty component files — 7 files with only comments (story 1.5+ stubs) (RESOLVED: Keep as-is)
|
||||
- [x] [Review][Decision] No light theme support — Only dark theme colors defined (RESOLVED: Keep dark-only)
|
||||
- [x] [Review][Decision] Shadow DOM scope issue — :root badge tokens inaccessible (RESOLVED: Keep as-is, mounts to Foundry AV tile)
|
||||
- [x] [Review][Dismiss] WCAG contrast warnings — Documented in spec as intentional (icon/shape only)
|
||||
- [x] [Review][Dismiss] Nested var() compatibility — Acceptable browser support
|
||||
|
||||
---
|
||||
|
||||
**Group 5 Findings (Templates):**
|
||||
- [x] [Review][Patch] Missing accessibility — Added role="region" and aria-label to all template divs [templates/*.hbs]
|
||||
- [x] [Review][Patch] Non-ASCII character — Replaced em-dash `—` with ASCII hyphen `-` in comments [templates/*.hbs]
|
||||
- [x] [Review][Patch] Missing data attributes — Added data-component for JS targeting [templates/*.hbs]
|
||||
- [x] [Review][Dismiss] Non-semantic class name — "scrying-pool" is module root (intentional per spec)
|
||||
- [x] [Review][Dismiss] Generic class name — BEM-like component names inside .scrying-pool (intentional per architecture)
|
||||
- [x] [Review][Dismiss] Empty template structure — Intentional stubs for story 1.5+ (Task 11.1)
|
||||
- [x] [Review][Dismiss] Incomplete delivery — False positive (all 5 templates present)
|
||||
|
||||
---
|
||||
|
||||
**Group 6 Findings (Tests):**
|
||||
- [x] [Review][Patch] Story 1.2 test file pollutes scope — Removed tests/unit/foundry/FoundryAdapter.test.js
|
||||
- [x] [Review][Patch] Story 1.2 fixture pollutes scope — Removed tests/fixtures/foundry-adapter.js
|
||||
- [x] [Review][Patch] Redundant fixture duplicates mock — Removed tests/fixtures/foundry-adapter.js (with AA-02)
|
||||
- [x] [Review][Patch] Unfrozen mutable array — Fixed contents: [] → Object.freeze([]) in foundry-adapter.js stub (merged with AA-02 removal)
|
||||
- [x] [Review][Patch] Non-string state values not tested — Added Symbol and object tests to visibility-matrix.test.js
|
||||
- [x] [Review][Patch] Non-finite updatedAt not tested — Added NaN and Infinity tests to scene-preset.test.js
|
||||
- [x] [Review][Patch] Missing revision fixture — Added missingRevision to socket-payloads.js
|
||||
- [x] [Review][Patch] Empty event string not tested — Added test in socket-message.test.js
|
||||
- [x] [Review][Patch] String timeoutId not tested — Added test in pending-op.test.js
|
||||
- [x] [Review][Patch] Mock inconsistency — Aligned users.current() with users.get() in foundryAdapterMock.js
|
||||
- [x] [Review][Defer] MAX_PAYLOAD_BYTES size boundary — Story 1.2+ SocketHandler responsibility
|
||||
- [x] [Review][Defer] Prototype pollution in matrix — Covered by unknown key rejection
|
||||
- [x] [Review][Defer] Multi-track stream test — Story 1.2+ WebRTC surface
|
||||
- [x] [Review][Defer] Invalid snapshot fixtures — Story 1.3+ StateStore
|
||||
- [x] [Review][Dismiss] Numeric/special char matrix keys — userId always string per contract
|
||||
- [x] [Review][Dismiss] Empty userId in matrix — Already tested in visibility-matrix.test.js
|
||||
- [x] [Review][Dismiss] Long preset name fixture — Edge case, not critical
|
||||
- [x] [Review][Dismiss] Negative issuedAt test — Existing test covers
|
||||
- [x] [Review][Dismiss] Populated game state fixture — Tests can customize mock
|
||||
- [x] [Review][Dismiss] Large matrix stress test — Performance concern, not correctness
|
||||
- [x] [Review][Dismiss] Circular reference in gameWebrtc — Story 1.2+ WebRTC
|
||||
- [x] [Review][Dismiss] Boolean/number payload values — Type validation handles
|
||||
- [x] [Review][Dismiss] Undefined parameters in createScenePreset — Factory handles defaults
|
||||
- [x] [Review][Dismiss] Mock methods not vi.fn by default — Test utility concern, not bug
|
||||
|
||||
---
|
||||
|
||||
**Group 7 Findings (CI/CD & i18n):**
|
||||
- [x] [Review][Decision] pull_request trigger scope — Kept as enhancement beyond Task 9 spec (AC5 still met) [.gitea/workflows/ci.yml]
|
||||
- [x] [Review][Decision] Build step scope — Kept as enhancement beyond Task 9 spec [.gitea/workflows/ci.yml]
|
||||
- [x] [Review][Patch] Unpinned action versions — Pinned to commit SHAs [.gitea/workflows/ci.yml:9,13]
|
||||
- [x] [Review][Patch] Overly permissive branch triggers — Restricted from ["**"] to ["main"] [.gitea/workflows/ci.yml:3-7]
|
||||
- [x] [Review][Patch] Missing npm audit — Added security audit step [.gitea/workflows/ci.yml:24-25]
|
||||
- [x] [Review][Patch] Empty i18n breaks Foundry — Added namespace stub {"video-view-manager": {}} [lang/en.json]
|
||||
- [x] [Review][Defer] Missing failure notifications — Story 1.2+ (EC-002)
|
||||
- [x] [Review][Defer] Missing build artifact upload — Story 1.2+ (EC-006)
|
||||
- [x] [Review][Defer] No Node.js matrix testing — Story 1.2+ (EC-004)
|
||||
- [x] [Review][Defer] Missing concurrency control — Story 1.2+ (EC-008)
|
||||
- [x] [Review][Defer] Missing i18n schema validation — Story 1.2+ (EC-I18N-003)
|
||||
- [x] [Review][Dismiss] ubuntu-latest not pinned — Story 1.2+ (EC-003)
|
||||
- [x] [Review][Dismiss] Missing coverage upload — Story 1.2+ (EC-005)
|
||||
- [x] [Review][Dismiss] Translation fallback — Handled by Foundry i18n system (EC-I18N-002)
|
||||
- [x] [Review][Dismiss] Missing encoding spec — UTF-8 default in Node.js (EC-I18N-005)
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### npm scripts — exact definitions
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"build": "lessc styles/scrying-pool.less dist/styles/scrying-pool.css",
|
||||
"watch": "chokidar 'styles/**/*.less' -c 'lessc styles/scrying-pool.less dist/styles/scrying-pool.css'",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"lint": "eslint src/ module.js",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"release": "node scripts/package.mjs"
|
||||
}
|
||||
```
|
||||
|
||||
### devDependencies — exact pinned versions
|
||||
|
||||
```bash
|
||||
npm install --save-dev \
|
||||
less@4.6.4 \
|
||||
chokidar@5.0.0 \
|
||||
vitest@2.1.8 \
|
||||
happy-dom@20.x \
|
||||
typescript@5.9.3 \
|
||||
@league-of-foundry-developers/foundry-vtt-types@{pin to a specific commit SHA for v14} \
|
||||
@types/node@22.x \
|
||||
eslint \
|
||||
eslint-plugin-jsdoc \
|
||||
eslint-plugin-import
|
||||
```
|
||||
|
||||
> ⚠️ `foundry-vtt-types` MUST be pinned to a specific commit SHA, not `#main`. Document the SHA and the Foundry v14 version it targets in a comment in `tsconfig.json` or `package.json`.
|
||||
> `chokidar` is for LESS watch only — `less --watch` does NOT detect changes in `@import`-ed partials.
|
||||
|
||||
### Import boundary rules (hard — must be wired into `.eslintrc.js`)
|
||||
|
||||
```
|
||||
src/core/ → may import: src/contracts/, src/utils/ ONLY
|
||||
src/foundry/ → may import: src/contracts/, src/utils/
|
||||
src/notifications/ → may import: src/core/, src/contracts/, src/utils/
|
||||
src/presets/ → may import: src/core/, src/contracts/, src/utils/
|
||||
src/ui/ → may import: src/core/, src/contracts/, src/utils/
|
||||
src/contracts/ → no internal imports
|
||||
src/utils/ → no internal imports
|
||||
module.js → may import: all of src/
|
||||
```
|
||||
|
||||
❌ `src/core/` importing `src/foundry/`, `src/ui/`, `src/notifications/`, or `src/presets/` is a hard violation.
|
||||
❌ `src/foundry/` importing `src/core/` or `src/ui/` is a hard violation.
|
||||
|
||||
These must be configured as `import/no-restricted-paths` zones — not aspirational documentation.
|
||||
|
||||
### Contract file pattern (apply to all 4)
|
||||
|
||||
```js
|
||||
/** @typedef {{ opId: string, userId: string, targetState: string,
|
||||
* previousState: string, issuedAt: number, timeoutId: number|null }} PendingOp */
|
||||
|
||||
/**
|
||||
* @param {Partial<PendingOp>} input
|
||||
* @returns {PendingOp}
|
||||
*/
|
||||
export function createPendingOp(input) { ... }
|
||||
|
||||
/**
|
||||
* @param {unknown} dto
|
||||
* @returns {PendingOp}
|
||||
* @throws {TypeError} with field name on violation
|
||||
*/
|
||||
export function isValidPendingOp(dto) { ... }
|
||||
```
|
||||
|
||||
Validator rules:
|
||||
- Reject unknown keys
|
||||
- Timestamps: finite, non-negative integer
|
||||
- Id fields: non-empty string
|
||||
- Arrays default `[]`
|
||||
- Nullable fields explicit `null` (never `undefined`)
|
||||
|
||||
### LESS state map — exact shape for `styles/tokens/_states.less`
|
||||
|
||||
```less
|
||||
@sp-states: {
|
||||
active: { color: @sp-color-active, icon: '\f06e'; shape: solid; };
|
||||
hidden: { color: @sp-color-hidden, icon: '\f070'; shape: dashed; };
|
||||
self-muted: { color: @sp-color-muted, icon: '\f131'; shape: solid; };
|
||||
offline: { color: @sp-color-offline, icon: '\f00d'; shape: none; };
|
||||
cam-lost: { color: @sp-color-warning, icon: '\f03d'; shape: dashed; };
|
||||
reconnecting: { color: @sp-color-info, icon: '\f021'; shape: pulse; };
|
||||
never-connected: { color: @sp-color-neutral, icon: '\f068'; shape: none; };
|
||||
ghost: { color: @sp-color-ghost, icon: '\f2be'; shape: dotted; };
|
||||
pending: { color: @sp-color-neutral, icon: '\f110'; shape: pulse; };
|
||||
};
|
||||
```
|
||||
|
||||
State colour values (from UX spec):
|
||||
|
||||
| State | Hex | WCAG AA |
|
||||
|---|---|---|
|
||||
| `active` | `#4a9e6b` | ✅ |
|
||||
| `hidden` | `#6b7280` | ⚠️ Icon/shape only |
|
||||
| `self-muted` | `#8b92a5` | ✅ |
|
||||
| `offline` | `#4b5563` | ⚠️ Icon/shape only |
|
||||
| `cam-lost` | `#9ca3af` | ✅ |
|
||||
| `reconnecting` | `#c8982a` | ✅ |
|
||||
| `never-connected` | `#374151` | ⚠️ Icon/shape only |
|
||||
| `ghost` | `#1f2937` | ⚠️ Icon/shape only |
|
||||
|
||||
> ⚠️ States marked "Icon/shape only" MUST NOT appear as text or small-pill foreground — colour is supplementary; icon + shape carry the primary signal (WCAG requirement).
|
||||
|
||||
### Layer 1 SP semantic alias tokens (exact values from UX spec)
|
||||
|
||||
```css
|
||||
:root {
|
||||
--sp-surface: var(--sp-theme-surface, var(--color-bg-option, #141618));
|
||||
--sp-text-primary: var(--sp-theme-text-primary, var(--color-text-primary, #dde2e8));
|
||||
--sp-text-secondary: var(--sp-theme-text-muted, var(--color-text-secondary, #7a8390));
|
||||
--sp-accent: var(--sp-theme-accent, var(--color-warm-2, #4a9e6b));
|
||||
--sp-focus: var(--sp-theme-focus, var(--color-focus-outline, #63c287));
|
||||
--sp-urgency-director: var(--sp-theme-urgency, #c8982a); /* NO Foundry error/warn token */
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ `--sp-urgency-director` MUST NOT inherit Foundry's error/warn colours. A director cue is a deliberate stage direction, not a failure.
|
||||
|
||||
### State token naming — three sub-tokens per state
|
||||
|
||||
Each state provides three CSS custom properties:
|
||||
```
|
||||
--sp-state-{name}-text
|
||||
--sp-state-{name}-border
|
||||
--sp-state-{name}-bg
|
||||
```
|
||||
|
||||
### VisibilityBadge `:root` exception
|
||||
|
||||
Badge (`PlayerStatusBadge`) is mounted outside the `.scrying-pool` root DOM node, directly onto Foundry's AV tile DOM. Badge state tokens MUST be declared on `:root` so they are available outside the module's root. Add a prominent comment explaining this architectural exception.
|
||||
|
||||
### Naming conventions (enforce across all files)
|
||||
|
||||
- JS files (classes/modules): PascalCase — `StateStore.js`, `FoundryAdapter.js`
|
||||
- Utility/helper files: camelCase — `uuid.js`
|
||||
- Contract files: kebab-case — `socket-message.js`, `pending-op.js`
|
||||
- Test files: `{SourceFile}.test.js` — `StateStore.test.js`
|
||||
- Named exports only — `export class StateStore {}`, never `export default`
|
||||
- World settings prefix: `scrying-pool.` — never `video-view-manager.X`, `sp.X`, `vvm.X`
|
||||
- Socket events prefix: `scrying-pool.`
|
||||
- CSS prefix: `.sp-` or scoped under `.scrying-pool`
|
||||
- Console prefix: `[ScryingPool]` on ALL console calls
|
||||
- Public API returns `null` not `undefined` for "not found"
|
||||
|
||||
### Constructor rule
|
||||
|
||||
```js
|
||||
// ✅ constructor(adapter) { this._adapter = adapter; }
|
||||
// init() { this._adapter.hooks.once('ready', () => this._onReady()); }
|
||||
// ❌ constructor(adapter) { adapter.hooks.once('ready', ...); }
|
||||
```
|
||||
Lifecycle registration belongs in `module.js` (owns `Hooks.once('init')` and `Hooks.once('ready')`). Individual module constructors must be side-effect free.
|
||||
|
||||
### Test pattern — canonical mock
|
||||
|
||||
```js
|
||||
import { createFoundryAdapterMock } from '../helpers/foundryAdapterMock.js'
|
||||
const adapter = createFoundryAdapterMock({ settings: { get: () => 'custom' } })
|
||||
```
|
||||
**No ad-hoc stubs.** All tests use `createFoundryAdapterMock` — the canonical mock factory is established in this story and reused by all subsequent tests.
|
||||
|
||||
### Fixture pattern
|
||||
|
||||
```js
|
||||
// All fixtures are Object.freeze'd
|
||||
export const SOCKET_PAYLOADS = Object.freeze({ ... })
|
||||
// Include negative/invalid fixtures for every validateX() rejection branch
|
||||
```
|
||||
|
||||
### socket-payloads.js fixture shape (stub at this stage)
|
||||
|
||||
Must include at minimum:
|
||||
- Valid intent payload (`scrying-pool.visibility.set`)
|
||||
- Valid echo payload (`scrying-pool.visibility.updated`)
|
||||
- Malformed: missing `opId`
|
||||
- Malformed: wrong enum value for state
|
||||
- Malformed: extra unknown keys
|
||||
|
||||
### State precedence (for VisibilityManager stories — document here for context)
|
||||
|
||||
```
|
||||
pending > cam-lost > reconnecting > offline > never-connected > self-muted > hidden > ghost > active
|
||||
```
|
||||
|
||||
CSS never handles multi-state conflicts — VisibilityManager/RoleRenderer resolve before rendering.
|
||||
|
||||
### module.json v14 manifest required fields
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "video-view-manager",
|
||||
"title": "Video View Manager (Scrying Pool)",
|
||||
"version": "0.1.0",
|
||||
"compatibility": { "minimum": "14", "verified": "14" },
|
||||
"esmodules": ["module.js"],
|
||||
"styles": ["dist/styles/scrying-pool.css"],
|
||||
"languages": [{ "lang": "en", "name": "English", "path": "lang/en.json" }]
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ `version` field in `module.json` is managed by `scripts/package.mjs` at release time. Do NOT edit it manually during development.
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
This is story 1.1 — the project root is currently empty. Create the full directory structure from scratch:
|
||||
|
||||
```
|
||||
video-view-manager/
|
||||
├── module.json
|
||||
├── module.js ← stub (Hooks.once init/ready only)
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── vitest.config.js
|
||||
├── .eslintrc.js
|
||||
├── .gitignore
|
||||
├── .gitea/workflows/ci.yml
|
||||
├── scripts/package.mjs
|
||||
├── src/
|
||||
│ ├── contracts/ ← 4 contract files (full implementation)
|
||||
│ └── utils/uuid.js ← stub (opId generation for PendingOp, later stories)
|
||||
├── styles/
|
||||
│ ├── scrying-pool.less ← @import entry point only
|
||||
│ ├── tokens/
|
||||
│ │ ├── _base.less
|
||||
│ │ ├── _states.less
|
||||
│ │ ├── _motion.less
|
||||
│ │ └── _focus.less
|
||||
│ └── components/ ← 7 stub LESS files
|
||||
├── templates/ ← 5 stub .hbs files
|
||||
├── lang/en.json
|
||||
└── tests/
|
||||
├── helpers/foundryAdapterMock.js
|
||||
├── fixtures/ ← 6 fixture files (all Object.freeze'd)
|
||||
└── unit/contracts/ ← 4 contract test files
|
||||
```
|
||||
|
||||
**No `src/core/`, `src/foundry/`, `src/ui/` files yet** — those are Story 1.2+. Import boundary ESLint rules must still be configured now so they catch violations as soon as those files are created.
|
||||
|
||||
### References
|
||||
|
||||
- Architecture — scaffold decisions: [Source: _bmad-output/planning-artifacts/architecture.md#Starter Template Evaluation]
|
||||
- Architecture — project structure: [Source: _bmad-output/planning-artifacts/architecture.md#Complete Project Directory Structure]
|
||||
- Architecture — naming + enforcement: [Source: _bmad-output/planning-artifacts/architecture.md#Naming Patterns]
|
||||
- Architecture — import boundaries: [Source: _bmad-output/planning-artifacts/architecture.md#Import Boundary Rule]
|
||||
- Architecture — contract format: [Source: _bmad-output/planning-artifacts/architecture.md#Contracts]
|
||||
- Architecture — test patterns: [Source: _bmad-output/planning-artifacts/architecture.md#Test Patterns]
|
||||
- Architecture — LESS/CSS patterns: [Source: _bmad-output/planning-artifacts/architecture.md#LESS / CSS Patterns]
|
||||
- UX spec — design token layers: [Source: _bmad-output/planning-artifacts/ux-design-specification.md#Layer 1–4]
|
||||
- UX spec — state colour values: [Source: _bmad-output/planning-artifacts/ux-design-specification.md#state colour table]
|
||||
- UX spec — CSS scoping discipline: [Source: _bmad-output/planning-artifacts/ux-design-specification.md#Linting convention]
|
||||
- Epics — Story 1.1 ACs + deliverables: [Source: _bmad-output/planning-artifacts/epics.md#Story 1.1]
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
Claude Sonnet 4.6 (claude-sonnet-4.6) via GitHub Copilot CLI
|
||||
|
||||
### Debug Log References
|
||||
|
||||
- ESLint 9.x uses flat config (`eslint.config.js`), not `.eslintrc.js` as story spec states. Used flat config with `@eslint/js`, browser globals, and FoundryVTT globals declared explicitly.
|
||||
- LESS `*/` in block comments causes ParseError — switched all LESS `/** */` comments to `//` line comments.
|
||||
- `tsconfig.json`: `moduleResolution: "node16"` requires `module: "Node16"` — changed to `moduleResolution: "bundler"` (TS 5+ only, compatible with ESNext module).
|
||||
- Contract validators: destructuring `unknown` requires intermediate `Record<string, unknown>` cast for TypeScript strict mode.
|
||||
- `scripts/package.mjs`: `catch(err)` needs `err instanceof Error ? err.message : String(err)` under strict TS.
|
||||
- Test fixture/helper files with untyped stub functions use `// @ts-nocheck` pragma — deliberate, test infrastructure only.
|
||||
- `globals` package available transitively via ESLint — used for `globals.browser` in flat config.
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
- ✅ Task 1: `package.json` initialized, `npm install` exits 0; Node 24.14.1 / npm 11.4.0
|
||||
- ✅ Task 2: `tsconfig.json` (moduleResolution: bundler), `eslint.config.js` (flat config), `vitest.config.js`, `.gitignore`
|
||||
- ✅ Task 3: `module.json` v14 manifest with all required fields
|
||||
- ✅ Task 4: `scripts/package.mjs` release script; produces `module.zip` (14 KB) at v0.1.0
|
||||
- ✅ Task 5: `module.js` entry stub with `Hooks.once('init')` and `Hooks.once('ready')`
|
||||
- ✅ Task 6: All 4 contract files fully implemented with factory + validator; all validators reject unknown keys, throw `TypeError` with field name
|
||||
- ✅ Task 7: Full LESS token system; `npm run build` → `dist/styles/scrying-pool.css` ✅; VisibilityBadge `:root` exception documented
|
||||
- ✅ Task 8: 49 unit tests across 4 contract test files; all pass; `tests/helpers/foundryAdapterMock.js` canonical mock established
|
||||
- ✅ Task 9: `.gitea/workflows/ci.yml` — lint + typecheck + test + build on every push
|
||||
- ✅ Task 10: `lang/en.json` — valid `{}` skeleton
|
||||
- ✅ Task 11: 5 Handlebars template stubs created
|
||||
- ✅ Task 12: Full pipeline — `lint` ✅ `typecheck` ✅ `test` ✅ `build` ✅ `release` ✅
|
||||
|
||||
**Deviations from story spec:**
|
||||
- `eslint.config.js` (flat config) used instead of `.eslintrc.js` (ESLint 9 dropped `.eslintrc.*` support)
|
||||
- `moduleResolution: "bundler"` instead of `"node16"` (node16 requires module: Node16)
|
||||
- `foundry-vtt-types` not installed — `Hooks` declared via minimal `src/types/foundry-globals.d.ts` instead
|
||||
|
||||
### File List
|
||||
|
||||
- `package.json`
|
||||
- `package-lock.json`
|
||||
- `tsconfig.json`
|
||||
- `eslint.config.js`
|
||||
- `vitest.config.js`
|
||||
- `.gitignore`
|
||||
- `module.json`
|
||||
- `module.js`
|
||||
- `scripts/package.mjs`
|
||||
- `src/types/foundry-globals.d.ts`
|
||||
- `src/utils/uuid.js`
|
||||
- `src/contracts/visibility-matrix.js`
|
||||
- `src/contracts/socket-message.js`
|
||||
- `src/contracts/pending-op.js`
|
||||
- `src/contracts/scene-preset.js`
|
||||
- `styles/scrying-pool.less`
|
||||
- `styles/tokens/_base.less`
|
||||
- `styles/tokens/_states.less`
|
||||
- `styles/tokens/_motion.less`
|
||||
- `styles/tokens/_focus.less`
|
||||
- `styles/components/_participant-card.less`
|
||||
- `styles/components/_roster-strip.less`
|
||||
- `styles/components/_directors-board.less`
|
||||
- `styles/components/_scene-preset-panel.less`
|
||||
- `styles/components/_notification.less`
|
||||
- `styles/components/_player-badge.less`
|
||||
- `styles/components/_player-panel.less`
|
||||
- `lang/en.json`
|
||||
- `templates/directors-board.hbs`
|
||||
- `templates/participant-card.hbs`
|
||||
- `templates/roster-strip.hbs`
|
||||
- `templates/scene-preset-panel.hbs`
|
||||
- `templates/player-panel.hbs`
|
||||
- `.gitea/workflows/ci.yml`
|
||||
- `tests/helpers/foundryAdapterMock.js`
|
||||
- `tests/fixtures/socket-payloads.js`
|
||||
- `tests/fixtures/visibility-states.js`
|
||||
- `tests/fixtures/state-store-snapshots.js`
|
||||
- `tests/fixtures/scene-preset.js`
|
||||
- `tests/fixtures/pending-op.js`
|
||||
- `tests/fixtures/foundry-adapter.js`
|
||||
- `tests/unit/contracts/visibility-matrix.test.js`
|
||||
- `tests/unit/contracts/socket-message.test.js`
|
||||
- `tests/unit/contracts/pending-op.test.js`
|
||||
- `tests/unit/contracts/scene-preset.test.js`
|
||||
|
||||
### Change Log
|
||||
|
||||
- 2025-05-21: Story 1.1 implementation complete — full scaffold, CI, LESS token system, contracts, test infrastructure (49 tests, all pass; full pipeline lint/typecheck/test/build/release exits 0)
|
||||
+289
@@ -0,0 +1,289 @@
|
||||
# Story 1.2: WebRTC Spike — Track Disabling API Validation
|
||||
|
||||
Status: done
|
||||
|
||||
## Story
|
||||
|
||||
As a **developer**,
|
||||
I want to determine the FoundryVTT v14 WebRTC API capability and freeze the `FoundryAdapter.webrtc` interface contract,
|
||||
so that Story 1.3 can implement against a stable interface without ambiguity.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Given** FoundryVTT v14 running with AV enabled **When** the spike probe code executes **Then** the result is exactly one of three documented outcomes: `"track-disable"` (track.enabled = false confirmed on a remote inbound stream), `"css-fallback"` (programmatic track access unavailable; CSS/DOM hiding sufficient), or `"unsupported"` (neither approach reliably available) **And** the outcome is recorded as a code comment in `src/foundry/FoundryAdapter.js` with the FoundryVTT version tested against.
|
||||
|
||||
2. **Given** the spike outcome is determined **When** `src/foundry/FoundryAdapter.js` is examined **Then** the `FoundryAdapter.webrtc` interface contract is frozen: either `{ disableTrack(userId): void, enableTrack(userId): void }` or `null` **And** the `probeCapability()` static method documents which `game.webrtc` properties were checked and their availability.
|
||||
|
||||
3. **Given** the spike file exists **When** `module.js` runs its `Hooks.once('init')` handler **Then** `scrying-pool.webrtcMode` world setting is registered with `choices: ["track-disable", "css-fallback", "unsupported"]` (no default — set by probe outcome at first load).
|
||||
|
||||
4. **Given** outcome is `"track-disable"` **When** a participant is hidden **Then** `FoundryAdapter.webrtc.disableTrack(userId)` disables the inbound track (`track.enabled = false`) and no inbound video bandwidth is consumed.
|
||||
|
||||
5. **Given** outcome is `"css-fallback"` or `"unsupported"` **When** a participant is hidden **Then** CSS/DOM hiding is applied (cosmetic only; bandwidth still consumed). This path is the safe fallback.
|
||||
|
||||
6. **Given** `game.webrtc` is `null` or absent **When** `FoundryAdapter.probeCapability()` runs **Then** it returns `"unsupported"`, sets `webrtc` to `null`, no errors are thrown, no code attempts any WebRTC access.
|
||||
|
||||
7. **Given** the probe outcome is `"track-disable"` **When** `tests/unit/foundry/FoundryAdapter.test.js` runs **Then** tests verify: (a) interface shape parity with the canonical mock, (b) `disableTrack` calls `track.enabled = false` on the retrieved connection, (c) error path returns `null` gracefully and logs `[ScryingPool]` warning, (d) `null` game.webrtc path returns `null` without errors.
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [x] Task 1: Create `src/foundry/FoundryAdapter.js` skeleton with probe (AC: #1, #2, #6)
|
||||
- [x] 1.1 Create `src/foundry/` directory
|
||||
- [x] 1.2 Implement `FoundryAdapter` class — constructor side-effect-free; `static probeCapability(gameWebrtc)` method that inspects `game.webrtc` and returns one of the three outcome strings
|
||||
- [x] 1.3 Implement `webrtc` property: if probe outcome is `"track-disable"`, return `{ disableTrack(userId), enableTrack(userId) }` object; otherwise return `null`
|
||||
- [x] 1.4 **Actually run the probe** in a live FoundryVTT v14 session (or investigate the API surface via documentation/source) and record the outcome as a code comment at the top of the class
|
||||
- [x] 1.5 Add outcome comment block: `// OQ-1 Spike Result: <outcome> — FoundryVTT v<version> — <date> — <brief explanation>`
|
||||
|
||||
- [x] Task 2: Register `scrying-pool.webrtcMode` world setting in `module.js` (AC: #3)
|
||||
- [x] 2.1 Update `module.js` `Hooks.once('init')` stub to call `game.settings.register('scrying-pool', 'webrtcMode', { ... })`
|
||||
- [x] 2.2 Setting config: `scope: 'world'`, `config: false` (internal, not shown in settings UI), `type: String`, `choices: { 'track-disable': ..., 'css-fallback': ..., 'unsupported': ... }`, `default: 'css-fallback'`
|
||||
- [x] 2.3 Add setting key constant to `src/foundry/FoundryAdapter.js`: `static SETTING_WEBRTC_MODE = 'webrtcMode'` (+ `static SETTINGS_NS = 'scrying-pool'`)
|
||||
|
||||
- [x] Task 3: Update `tests/helpers/foundryAdapterMock.js` for webrtc interface (AC: #7)
|
||||
- [x] 3.1 Add `webrtc: null` default path (already present — verify it remains the canonical default)
|
||||
- [x] 3.2 Document that overriding webrtc with `{ disableTrack: vi.fn(), enableTrack: vi.fn() }` simulates the `"track-disable"` outcome
|
||||
|
||||
- [x] Task 4: Write `tests/unit/foundry/FoundryAdapter.test.js` (AC: #7)
|
||||
- [x] 4.1 Create `tests/unit/foundry/` directory
|
||||
- [x] 4.2 Test: `probeCapability(null)` returns `"unsupported"` without errors
|
||||
- [x] 4.3 Test: `probeCapability` with a mock `game.webrtc` that has `client.getMediaStreamForUser` → returns `"css-fallback"` (OQ-1 spike result: track-disable not achievable)
|
||||
- [x] 4.4 Test: `probeCapability` with a mock `game.webrtc` that lacks `client.getMediaStreamForUser` → returns `"unsupported"`
|
||||
- [x] 4.5 Test: `disableTrack(userId)` calls `track.enabled = false` on the resolved track
|
||||
- [x] 4.6 Test: `disableTrack(userId)` when `getMediaStreamForUser()` returns `null` → logs `[ScryingPool] warn` and does not throw
|
||||
- [x] 4.7 Test: `enableTrack(userId)` restores `track.enabled = true`
|
||||
- [x] 4.8 Test: FoundryAdapter interface shape matches `createFoundryAdapterMock()` surface keys
|
||||
|
||||
- [x] Task 5: Verify pipeline (AC: all)
|
||||
- [x] 5.1 `npm run lint` exits 0 — `src/foundry/` imports only `src/contracts/` and `src/utils/`
|
||||
- [x] 5.2 `npm run typecheck` exits 0
|
||||
- [x] 5.3 `npm run test` exits 0 (all FoundryAdapter tests pass)
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### This Is a Spike — Deliverable Is a Decision + Skeleton, Not a Full Implementation
|
||||
|
||||
Story 1.2 is **a spike story**. The primary output is:
|
||||
1. A documented, **frozen** `FoundryAdapter.webrtc` interface decision (`track-disable` or `null`)
|
||||
2. The minimal `src/foundry/FoundryAdapter.js` skeleton with the probe code
|
||||
3. The `scrying-pool.webrtcMode` setting registration
|
||||
|
||||
**Story 1.3 builds the full FoundryAdapter** (settings, socket, users, scenes, notifications, hooks surfaces). Do NOT implement the full adapter here — only the webrtc probe portion.
|
||||
|
||||
### File Path: Use Architecture-Canonical Path
|
||||
|
||||
The epics file references `src/adapters/foundry-adapter.js` but the **architecture document is canonical** — use `src/foundry/FoundryAdapter.js`. PascalCase filename matches the class name and the naming convention established in Story 1.1.
|
||||
|
||||
### Import Boundary — HARD RULE
|
||||
|
||||
`src/foundry/` may only import:
|
||||
- `src/contracts/`
|
||||
- `src/utils/`
|
||||
|
||||
No imports from `src/core/`, `src/ui/`, `src/notifications/`, or `src/presets/`. ESLint will catch violations automatically (wired in Story 1.1).
|
||||
|
||||
### FoundryAdapter Class Pattern
|
||||
|
||||
```js
|
||||
// src/foundry/FoundryAdapter.js
|
||||
|
||||
// OQ-1 Spike Result: <outcome> — FoundryVTT v14.x — <date>
|
||||
// <brief explanation of what was found>
|
||||
|
||||
/**
|
||||
* Sole gateway to game.* APIs. Feature-detects WebRTC availability.
|
||||
* @module foundry/FoundryAdapter
|
||||
*/
|
||||
export class FoundryAdapter {
|
||||
// Constructor must be side-effect free (architecture rule)
|
||||
constructor() {
|
||||
this.webrtc = null; // Set after probeCapability() call
|
||||
}
|
||||
|
||||
/**
|
||||
* Probes game.webrtc for track-disabling capability.
|
||||
* @param {unknown} gameWebrtc - game.webrtc value (may be null/undefined)
|
||||
* @returns {'track-disable'|'css-fallback'|'unsupported'}
|
||||
*/
|
||||
static probeCapability(gameWebrtc) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### module.js Integration (Minimal for This Story)
|
||||
|
||||
The `module.js` `Hooks.once('init')` stub currently has no body. This story adds only the setting registration. The full wiring (construct FoundryAdapter, StateStore, SocketHandler) is Story 1.3.
|
||||
|
||||
```js
|
||||
// module.js — update Hooks.once('init') to:
|
||||
Hooks.once("init", () => {
|
||||
console.log("[ScryingPool] init — module loading");
|
||||
game.settings.register("video-view-manager", "webrtcMode", {
|
||||
scope: "world",
|
||||
config: false,
|
||||
type: String,
|
||||
default: "css-fallback",
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### WebRTC Probe Investigation Guide
|
||||
|
||||
If you cannot run a live FoundryVTT instance, investigate the API surface this way:
|
||||
|
||||
1. **Check FoundryVTT v14 source / GitHub** for `AVMaster`, `WebRTCInterface`, and `game.webrtc` type definitions
|
||||
2. **Check `@league-of-foundry-developers/foundry-vtt-types`** for v14 type stubs (not installed — see Story 1.1 deviation, use `src/types/foundry-globals.d.ts`)
|
||||
3. **Probe sequence to try in browser console when Foundry is running with AV:**
|
||||
```js
|
||||
// Step 1: Is game.webrtc available?
|
||||
console.log(game.webrtc);
|
||||
// Step 2: Can we get connections?
|
||||
console.log(typeof game.webrtc?.getConnection);
|
||||
// Step 3: Can we reach RTCPeerConnection?
|
||||
const conn = game.webrtc?.getConnection?.(game.users.players[0]?.id);
|
||||
console.log(conn instanceof RTCPeerConnection);
|
||||
// Step 4: Can we access receivers / tracks?
|
||||
const receivers = conn?.getReceivers?.();
|
||||
console.log(receivers, receivers?.[0]?.track);
|
||||
// Step 5: Can we disable a track?
|
||||
const track = receivers?.[0]?.track;
|
||||
if (track) { track.enabled = false; console.log('track-disable confirmed'); }
|
||||
```
|
||||
4. Document outcome as a comment at the top of `FoundryAdapter.js`
|
||||
|
||||
### probeCapability() Logic Pattern
|
||||
|
||||
```js
|
||||
static probeCapability(gameWebrtc) {
|
||||
if (!gameWebrtc) return "unsupported";
|
||||
if (typeof gameWebrtc.getConnection !== "function") return "css-fallback";
|
||||
// Try to detect track access without a real peer (may need to run with AV active)
|
||||
// If getConnection signature exists AND returns RTCPeerConnection-like → "track-disable"
|
||||
// Conservative default if structural probe is inconclusive → "css-fallback"
|
||||
return "css-fallback"; // UPDATE AFTER SPIKE
|
||||
}
|
||||
```
|
||||
|
||||
### disableTrack / enableTrack Pattern (if track-disable confirmed)
|
||||
|
||||
```js
|
||||
// webrtc surface (only if probeCapability returns "track-disable")
|
||||
this.webrtc = {
|
||||
/**
|
||||
* Disables the inbound video/audio track for a participant (no bandwidth consumed).
|
||||
* @param {string} userId
|
||||
*/
|
||||
disableTrack(userId) {
|
||||
try {
|
||||
const conn = game.webrtc.getConnection(userId);
|
||||
const track = conn?.getReceivers()?.[0]?.track;
|
||||
if (track) track.enabled = false;
|
||||
else console.warn("[ScryingPool] disableTrack: no track found for", userId);
|
||||
} catch (err) {
|
||||
console.error("[ScryingPool] disableTrack failed:", err);
|
||||
}
|
||||
},
|
||||
enableTrack(userId) {
|
||||
try {
|
||||
const conn = game.webrtc.getConnection(userId);
|
||||
const track = conn?.getReceivers()?.[0]?.track;
|
||||
if (track) track.enabled = true;
|
||||
else console.warn("[ScryingPool] enableTrack: no track found for", userId);
|
||||
} catch (err) {
|
||||
console.error("[ScryingPool] enableTrack failed:", err);
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Test File Pattern
|
||||
|
||||
Follow established test patterns from Story 1.1:
|
||||
|
||||
```js
|
||||
// tests/unit/foundry/FoundryAdapter.test.js
|
||||
// @ts-nocheck
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { FoundryAdapter } from "../../../src/foundry/FoundryAdapter.js";
|
||||
import { createFoundryAdapterMock } from "../../helpers/foundryAdapterMock.js";
|
||||
|
||||
describe("FoundryAdapter.probeCapability", () => {
|
||||
it("returns unsupported when gameWebrtc is null", () => {
|
||||
expect(FoundryAdapter.probeCapability(null)).toBe("unsupported");
|
||||
});
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
Use `vi.fn()` for all stubs. No ad-hoc stubs — extend `createFoundryAdapterMock` as needed.
|
||||
|
||||
### Toolchain Deviations from Story 1.1 (Carry Forward)
|
||||
|
||||
- **ESLint flat config:** `eslint.config.js` (NOT `.eslintrc.js` — ESLint 9 dropped legacy config)
|
||||
- **TypeScript:** `moduleResolution: "bundler"` (NOT `"node16"`)
|
||||
- **No foundry-vtt-types package** — FoundryVTT globals declared in `src/types/foundry-globals.d.ts`
|
||||
- **Node:** 24.14.1 / npm 11.4.0
|
||||
|
||||
### Hard Exit Rule
|
||||
|
||||
**Story 1.3 must not start until this story is merged and `FoundryAdapter.webrtc` interface is frozen.** The outcome comment in `src/foundry/FoundryAdapter.js` and the `scrying-pool.webrtcMode` setting are the gate.
|
||||
|
||||
### Review Findings from Story 1.1 (Context Only — Do Not Fix in This Story)
|
||||
|
||||
The following open review items from Story 1.1 are tracked but NOT in scope for Story 1.2 (they belong to the code review workflow):
|
||||
- `[Review][Patch]` items in `scripts/package.mjs`, `.gitignore`, `package.json` — out of scope
|
||||
- `[Review][Decision]` items about source inclusion in zip — out of scope
|
||||
- Fix them in the Story 1.1 code review pass, not here
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
**New files this story creates:**
|
||||
```
|
||||
src/foundry/FoundryAdapter.js ← NEW (spike skeleton + webrtc probe only)
|
||||
tests/unit/foundry/FoundryAdapter.test.js ← NEW
|
||||
```
|
||||
|
||||
**Files modified this story:**
|
||||
```
|
||||
module.js ← Add scrying-pool.webrtcMode setting registration
|
||||
```
|
||||
|
||||
No other files should be touched. `src/foundry/` directory must be created.
|
||||
|
||||
### References
|
||||
|
||||
- Epics — Story 1.2 ACs: [Source: _bmad-output/planning-artifacts/epics.md#Story 1.2]
|
||||
- Architecture — FoundryAdapter surface contract: [Source: _bmad-output/planning-artifacts/architecture.md#FoundryAdapter Surface Contract]
|
||||
- Architecture — OQ-1 open question: [Source: _bmad-output/planning-artifacts/architecture.md#Open Question OQ-1]
|
||||
- Architecture — import boundary rules: [Source: _bmad-output/planning-artifacts/architecture.md#Import Boundary Rule]
|
||||
- Architecture — error handling by layer: [Source: _bmad-output/planning-artifacts/architecture.md#Error Handling by Layer]
|
||||
- Architecture — test patterns: [Source: _bmad-output/planning-artifacts/architecture.md#Test Patterns]
|
||||
- Architecture — naming patterns: [Source: _bmad-output/planning-artifacts/architecture.md#Naming Patterns]
|
||||
- Architecture — constructor side-effect-free rule: [Source: _bmad-output/planning-artifacts/architecture.md#Constructor Rule]
|
||||
- Story 1.1 — toolchain deviations: [Source: _bmad-output/implementation-artifacts/1-1-module-scaffold-cicd-pipeline-and-design-token-system.md#Dev Agent Record]
|
||||
- Story 1.1 — canonical mock established: [Source: _bmad-output/implementation-artifacts/1-1-module-scaffold-cicd-pipeline-and-design-token-system.md#Dev Notes]
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
Claude Sonnet 4.6 (claude-sonnet-4.6) via GitHub Copilot CLI
|
||||
|
||||
### Debug Log References
|
||||
|
||||
- **Task 2.1/2.3 correction:** Story spec had `game.settings.register('video-view-manager', ...)` and `SETTING_WEBRTC_MODE = 'video-view-manager.webrtcMode'`. Architecture convention specifies `scrying-pool.{key}` namespace — corrected to `game.settings.register('scrying-pool', 'webrtcMode', ...)` and `SETTING_WEBRTC_MODE = 'webrtcMode'` + `SETTINGS_NS = 'scrying-pool'`.
|
||||
- **Task 4.3 correction:** Story spec test expected `probeCapability` to return `"track-disable"` when `getConnection()` was present. Spike research revealed `getConnection()` doesn't exist in FoundryVTT v14 AVMaster, and `track.enabled = false` doesn't stop bandwidth. Test updated to reflect spike outcome: `client.getMediaStreamForUser` present → `"css-fallback"`.
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
- **OQ-1 resolved: `css-fallback`** — FoundryVTT v14 AVMaster has no `getConnection(userId)` method. Remote stream access goes via `game.webrtc.client.getMediaStreamForUser(userId)` (public AVClient abstract API). `track.enabled = false` on remote inbound tracks does NOT stop WebRTC bandwidth (RTP packets keep arriving). CSS/DOM cosmetic hiding is the honest implementation path. `FoundryAdapter.webrtc = null` in production.
|
||||
- `src/foundry/FoundryAdapter.js` created: side-effect-free constructor, `static probeCapability(gameWebrtc)`, `static buildWebRTCSurface(gameWebrtc)` (forward-compatibility / tested documentation), `static SETTINGS_NS`, `static SETTING_WEBRTC_MODE`. Full OQ-1 spike comment block at file top.
|
||||
- `module.js` updated: `Hooks.once('init')` now registers `scrying-pool.webrtcMode` world setting (scope: world, config: false, default: css-fallback, choices documented).
|
||||
- `tests/helpers/foundryAdapterMock.js` updated: `webrtc` JSDoc comment now documents the OQ-1 outcome and track-disable override pattern.
|
||||
- `tests/unit/foundry/FoundryAdapter.test.js` created: 18 tests — 5 for `probeCapability`, 7 for `buildWebRTCSurface` (disableTrack/enableTrack), 3 for constructor, 3 for interface shape parity with canonical mock.
|
||||
- Pipeline: `npm run lint` ✅ (0 new errors), `npm run typecheck` ✅ (exits 0), `npm run test` ✅ (67/67 pass, no regressions).
|
||||
|
||||
### File List
|
||||
|
||||
- `src/foundry/FoundryAdapter.js` — CREATED
|
||||
- `tests/unit/foundry/FoundryAdapter.test.js` — CREATED
|
||||
- `module.js` — MODIFIED (added scrying-pool.webrtcMode setting registration)
|
||||
- `tests/helpers/foundryAdapterMock.js` — MODIFIED (updated webrtc JSDoc comment)
|
||||
- `_bmad-output/implementation-artifacts/sprint-status.yaml` — MODIFIED (status: in-progress → review)
|
||||
@@ -0,0 +1,829 @@
|
||||
# Acceptance Auditor Review Layer
|
||||
|
||||
## ROLE
|
||||
You are **Acceptance Auditor** — a compliance checker. You review code changes against the specification and acceptance criteria. You must verify that the implementation matches the spec intent.
|
||||
|
||||
## INPUTS
|
||||
1. **Diff** (below)
|
||||
2. **Spec file**: `_bmad-output/implementation-artifacts/1-1-module-scaffold-cicd-pipeline-and-design-token-system.md`
|
||||
3. **Context docs**: Any documents referenced in the spec's frontmatter `context` field (none in this case)
|
||||
|
||||
## MISSION
|
||||
Check for:
|
||||
- **Violations of acceptance criteria** (AC #1, #2, #3... from the spec)
|
||||
- **Deviations from spec intent** (implementation does something different than described)
|
||||
- **Missing implementation** (spec says X should exist/behave a certain way, but it's not in the diff)
|
||||
- **Contradictions** (code violates constraints stated in the spec)
|
||||
|
||||
For each finding, identify:
|
||||
- Which AC or spec section it violates
|
||||
- Exact evidence from the diff
|
||||
- The expected vs actual behavior
|
||||
|
||||
## OUTPUT FORMAT
|
||||
Output ONLY a Markdown list of findings. No preamble, no summary. Each finding:
|
||||
```markdown
|
||||
- **[AC#X / SPEC]** Short title — file:line — what violates which AC + evidence
|
||||
```
|
||||
|
||||
## SPEC CONTENT
|
||||
# Story 1.1: Module Scaffold, CI/CD Pipeline & Design Token System
|
||||
|
||||
Status: review
|
||||
|
||||
## Story
|
||||
|
||||
As a **developer**,
|
||||
I want a fully configured module scaffold with the complete `--sp-*` design token system, contract files, tooling, and CI,
|
||||
so that every subsequent story builds on enforced boundaries, verified tooling, and a stable design language.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Given** the repository is checked out fresh **When** `npm install && npm run lint && npm run typecheck && npm run test` are executed **Then** all commands exit 0 **And** `npm run build` produces `module.zip` containing `module.json`, `scripts/`, `styles/`, `templates/`, `lang/`
|
||||
|
||||
2. **Given** the module is installed in FoundryVTT v14 **When** FoundryVTT loads **Then** the module activates with no console errors and `game.modules.get('video-view-manager').active === true`
|
||||
|
||||
3. **Given** a developer writes an exported function without a JSDoc comment **When** `npm run lint` runs **Then** `eslint` reports a `jsdoc/require-jsdoc` violation
|
||||
|
||||
4. **Given** a source file imports from a restricted layer **When** `npm run lint` runs **Then** `import/no-restricted-paths` reports a boundary violation
|
||||
|
||||
5. **Given** a Gitea push is made **When** the CI workflow runs **Then** lint, typecheck, and test all run; a failing test fails the workflow
|
||||
|
||||
6. **Given** a developer writes module CSS using a Foundry `--color-*`/`--font-*`/`--border-*` token directly inside `.scrying-pool` CSS **When** the linting convention is enforced **Then** a violation is reported — all Foundry tokens must be aliased through `--sp-*`
|
||||
|
||||
7. **Given** a developer renders any participant state **When** they look up the token system in `styles/scrying-pool.less` **Then** all token layers are defined:
|
||||
- Layer 1: SP semantic aliases (`--sp-surface`, `--sp-border`, `--sp-text-primary`, `--sp-text-secondary`, `--sp-accent`, `--sp-focus`) mapping to Foundry tokens with hardcoded fallbacks
|
||||
- Layer 2: SP Participant State tokens for all 8 states (`active`, `hidden`, `self-muted`, `offline`, `cam-lost`, `reconnecting`, `never-connected`, `ghost`)
|
||||
- Layer 3: SP Urgency + Motion tokens (`--sp-urgency-director`, `--sp-urgency-awareness`, `--sp-fade-hide`, `--sp-pulse-reconnecting`, `--sp-shimmer-degraded`, `--sp-toast-delay`)
|
||||
- **And** the `VisibilityBadge` `:root` exception is documented: badge tokens declared on `:root` because badge mounts outside `.scrying-pool` root
|
||||
- **And** all animated token usages gated under `@media (prefers-reduced-motion: no-preference)`
|
||||
|
||||
8. **Given** the 4 contract files exist **When** a story imports `src/contracts/visibility-matrix.js` **Then** it exports a canonical shape constant, a factory function (`createVisibilityMatrix()`), and a guard/validator function (`isValidVisibilityMatrix(data)`) **And** the same factory + validator pattern applies to `socket-message.js`, `pending-op.js`, `scene-preset.js`
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [x] Task 1: Initialize npm project and install devDependencies (AC: #1)
|
||||
- [x] 1.1 Run `npm init -y` and configure `package.json` with exact scripts block (see Dev Notes)
|
||||
- [x] 1.2 Install all devDependencies with pinned versions (see Dev Notes)
|
||||
- [x] 1.3 Verify `npm install` exits 0 with lock file generated
|
||||
|
||||
- [x] Task 2: Create root config files (AC: #1, #3, #4)
|
||||
- [x] 2.1 Create `tsconfig.json` with `checkJs`, `strict`, `noEmit`, `ESNext` target, `module: ESNext`, `moduleResolution: node16`, `allowJs: true`
|
||||
- [x] 2.2 Create `.eslintrc.js` with `jsdoc/require-jsdoc` on all exported symbols and `import/no-restricted-paths` zones for all 6 boundary rules (see Dev Notes)
|
||||
- [x] 2.3 Create `vitest.config.js` with happy-dom environment, path aliases, coverage config
|
||||
- [x] 2.4 Create `.gitignore` excluding `dist/`, `node_modules/`, `*.zip`
|
||||
|
||||
- [x] Task 3: Create `module.json` v14 manifest (AC: #2)
|
||||
- [x] 3.1 Set `id: "video-view-manager"`, title, version from `package.json`, v14 compatibility block
|
||||
- [x] 3.2 Register `esmodules: ["module.js"]`, `styles: ["dist/styles/scrying-pool.css"]`, `languages: [{ lang: "en", name: "English", path: "lang/en.json" }]`
|
||||
|
||||
- [x] Task 4: Create `scripts/package.mjs` release script (AC: #1)
|
||||
- [x] 4.1 Read version from `package.json`; write into `module.json` at release time
|
||||
- [x] 4.2 Produce `module.zip` containing: `module.json`, `module.js`, `dist/`, `lang/`, `templates/`, `src/`
|
||||
- [x] 4.3 Single version source of truth — `package.json` only; never manually edit `module.json` version field
|
||||
|
||||
- [x] Task 5: Create `module.js` entry point stub (AC: #2)
|
||||
- [x] 5.1 Empty orchestrator that registers `Hooks.once('init', () => {})` and `Hooks.once('ready', () => {})`
|
||||
- [x] 5.2 No business logic — wiring only; add `[ScryingPool]` console log to confirm load
|
||||
- [x] 5.3 Export nothing (module entry point, not a library)
|
||||
|
||||
- [x] Task 6: Create the 4 contract files in `src/contracts/` (AC: #8)
|
||||
- [x] 6.1 `src/contracts/visibility-matrix.js` — typedef + `createVisibilityMatrix()` + `isValidVisibilityMatrix()`
|
||||
- [x] 6.2 `src/contracts/socket-message.js` — typedef + `createSocketMessage()` + `isValidSocketMessage()`
|
||||
- [x] 6.3 `src/contracts/pending-op.js` — typedef + `createPendingOp()` + `isValidPendingOp()`
|
||||
- [x] 6.4 `src/contracts/scene-preset.js` — typedef + `createScenePreset()` + `isValidScenePreset()`
|
||||
- [x] 6.5 All validators: reject unknown keys, throw `TypeError` with field name on violation; timestamps as finite non-negative integers; id fields non-empty strings; nullable fields explicit `null`
|
||||
|
||||
- [x] Task 7: Create design token LESS system (AC: #6, #7)
|
||||
- [x] 7.1 Create `styles/scrying-pool.less` entry point with `@import` references only
|
||||
- [x] 7.2 Create `styles/tokens/_base.less` — Layer 1 SP semantic aliases (6 tokens + hardcoded fallbacks)
|
||||
- [x] 7.3 Create `styles/tokens/_states.less` — Layer 2 all 8 participant states + `pending` (9 total); color + icon + shape per state; LESS map `@sp-states` (see Dev Notes for exact map)
|
||||
- [x] 7.4 Create `styles/tokens/_motion.less` — Layer 3/4 urgency + motion tokens; `--sp-fade-hide`, `--sp-pulse-reconnecting`, `--sp-shimmer-degraded`, `--sp-toast-delay`; all animated tokens under `@media (prefers-reduced-motion: no-preference)`
|
||||
- [x] 7.5 Create `styles/tokens/_focus.less` — module-wide focus ring; high-contrast outer ring + inner offset
|
||||
- [x] 7.6 Add `:root` block for `VisibilityBadge` exception with documenting comment
|
||||
- [x] 7.7 Create `styles/components/` stubs (empty files with scope comment): `_participant-card.less`, `_roster-strip.less`, `_directors-board.less`, `_scene-preset-panel.less`, `_notification.less`, `_player-badge.less`, `_player-panel.less`
|
||||
- [x] 7.8 Verify `npm run build` produces `dist/styles/scrying-pool.css`
|
||||
|
||||
- [x] Task 8: Create test infrastructure (AC: #1)
|
||||
- [x] 8.1 Create `tests/helpers/foundryAdapterMock.js` — `createFoundryAdapterMock(overrides={})` canonical mock; covers `settings`, `socket`, `users`, `scenes`, `notifications`, `webrtc: null`, `hooks`
|
||||
- [x] 8.2 Create `tests/fixtures/socket-payloads.js` — `Object.freeze`'d stub with valid + malformed shapes (missing `opId`, wrong enum, extra keys)
|
||||
- [x] 8.3 Create `tests/fixtures/visibility-states.js`, `state-store-snapshots.js`, `scene-preset.js`, `pending-op.js`, `foundry-adapter.js` — all `Object.freeze`'d
|
||||
- [x] 8.4 Create contract test files in `tests/unit/contracts/` for all 4 contracts — test factory happy path, validator rejections
|
||||
|
||||
- [x] Task 9: Create Gitea CI workflow (AC: #5)
|
||||
- [x] 9.1 Create `.gitea/workflows/ci.yml` — runs on every push; steps: `npm ci`, `npm run lint`, `npm run typecheck`, `npm run test`
|
||||
- [x] 9.2 Failing test must fail the workflow (non-zero exit propagates)
|
||||
|
||||
- [x] Task 10: Create `lang/en.json` i18n skeleton (AC: #1)
|
||||
- [x] 10.1 Create with empty-but-valid JSON `{}` — or a top-level `"video-view-manager"` namespace stub
|
||||
- [x] 10.2 Register in `module.json` as `languages` array entry
|
||||
|
||||
- [x] Task 11: Create `templates/` stubs (AC: #1)
|
||||
- [x] 11.1 Create minimal stub `.hbs` files: `directors-board.hbs`, `participant-card.hbs`, `roster-strip.hbs`, `scene-preset-panel.hbs`, `player-panel.hbs`
|
||||
|
||||
- [x] Task 12: Verify full pipeline (AC: #1, #3, #4)
|
||||
- [x] 12.1 `npm run lint` exits 0 on clean code; reports violation on missing JSDoc export
|
||||
- [x] 12.2 `npm run typecheck` exits 0
|
||||
- [x] 12.3 `npm run test` exits 0 (contract tests pass)
|
||||
- [x] 12.4 `npm run build` produces `dist/styles/scrying-pool.css`
|
||||
- [x] 12.5 `npm run release` produces `module.zip`
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### npm scripts — exact definitions
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"build": "lessc styles/scrying-pool.less dist/styles/scrying-pool.css",
|
||||
"watch": "chokidar 'styles/**/*.less' -c 'lessc styles/scrying-pool.less dist/styles/scrying-pool.css'",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"lint": "eslint src/ module.js",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"release": "node scripts/package.mjs"
|
||||
}
|
||||
```
|
||||
|
||||
### devDependencies — exact pinned versions
|
||||
|
||||
```bash
|
||||
npm install --save-dev \
|
||||
less@4.6.4 \
|
||||
chokidar@5.0.0 \
|
||||
vitest@2.1.8 \
|
||||
happy-dom@20.x \
|
||||
typescript@5.9.3 \
|
||||
@league-of-foundry-developers/foundry-vtt-types@{pin to a specific commit SHA for v14} \
|
||||
@types/node@22.x \
|
||||
eslint \
|
||||
eslint-plugin-jsdoc \
|
||||
eslint-plugin-import
|
||||
```
|
||||
|
||||
> ⚠️ `foundry-vtt-types` MUST be pinned to a specific commit SHA, not `#main`. Document the SHA and the Foundry v14 version it targets in a comment in `tsconfig.json` or `package.json`.
|
||||
> `chokidar` is for LESS watch only — `less --watch` does NOT detect changes in `@import`-ed partials.
|
||||
|
||||
### Import boundary rules (hard — must be wired into `.eslintrc.js`)
|
||||
|
||||
```
|
||||
src/core/ → may import: src/contracts/, src/utils/ ONLY
|
||||
src/foundry/ → may import: src/contracts/, src/utils/
|
||||
src/notifications/ → may import: src/core/, src/contracts/, src/utils/
|
||||
src/presets/ → may import: src/core/, src/contracts/, src/utils/
|
||||
src/ui/ → may import: src/core/, src/contracts/, src/utils/
|
||||
src/contracts/ → no internal imports
|
||||
src/utils/ → no internal imports
|
||||
module.js → may import: all of src/
|
||||
```
|
||||
|
||||
❌ `src/core/` importing `src/foundry/`, `src/ui/`, `src/notifications/`, or `src/presets/` is a hard violation.
|
||||
❌ `src/foundry/` importing `src/core/` or `src/ui/` is a hard violation.
|
||||
|
||||
These must be configured as `import/no-restricted-paths` zones — not aspirational documentation.
|
||||
|
||||
### Contract file pattern (apply to all 4)
|
||||
|
||||
```js
|
||||
/** @typedef {{ opId: string, userId: string, targetState: string,
|
||||
* previousState: string, issuedAt: number, timeoutId: number|null }} PendingOp */
|
||||
|
||||
/**
|
||||
* @param {Partial<PendingOp>} input
|
||||
* @returns {PendingOp}
|
||||
*/
|
||||
export function createPendingOp(input) { ... }
|
||||
|
||||
/**
|
||||
* @param {unknown} dto
|
||||
* @returns {PendingOp}
|
||||
* @throws {TypeError} with field name on violation
|
||||
*/
|
||||
export function isValidPendingOp(dto) { ... }
|
||||
```
|
||||
|
||||
Validator rules:
|
||||
- Reject unknown keys
|
||||
- Timestamps: finite, non-negative integer
|
||||
- Id fields: non-empty string
|
||||
- Arrays default `[]`
|
||||
- Nullable fields explicit `null` (never `undefined`)
|
||||
|
||||
### LESS state map — exact shape for `styles/tokens/_states.less`
|
||||
|
||||
```less
|
||||
@sp-states: {
|
||||
active: { color: @sp-color-active, icon: '\f06e'; shape: solid; };
|
||||
hidden: { color: @sp-color-hidden, icon: '\f070'; shape: dashed; };
|
||||
self-muted: { color: @sp-color-muted, icon: '\f131'; shape: solid; };
|
||||
offline: { color: @sp-color-offline, icon: '\f00d'; shape: none; };
|
||||
cam-lost: { color: @sp-color-warning, icon: '\f03d'; shape: dashed; };
|
||||
reconnecting: { color: @sp-color-info, icon: '\f021'; shape: pulse; };
|
||||
never-connected: { color: @sp-color-neutral, icon: '\f068'; shape: none; };
|
||||
ghost: { color: @sp-color-ghost, icon: '\f2be'; shape: dotted; };
|
||||
pending: { color: @sp-color-neutral, icon: '\f110'; shape: pulse; };
|
||||
};
|
||||
```
|
||||
|
||||
State colour values (from UX spec):
|
||||
|
||||
| State | Hex | WCAG AA |
|
||||
|---|---|---|
|
||||
| `active` | `#4a9e6b` | ✅ |
|
||||
| `hidden` | `#6b7280` | ⚠️ Icon/shape only |
|
||||
| `self-muted` | `#8b92a5` | ✅ |
|
||||
| `offline` | `#4b5563` | ⚠️ Icon/shape only |
|
||||
| `cam-lost` | `#9ca3af` | ✅ |
|
||||
| `reconnecting` | `#c8982a` | ✅ |
|
||||
| `never-connected` | `#374151` | ⚠️ Icon/shape only |
|
||||
| `ghost` | `#1f2937` | ⚠️ Icon/shape only |
|
||||
|
||||
> ⚠️ States marked "Icon/shape only" MUST NOT appear as text or small-pill foreground — colour is supplementary; icon + shape carry the primary signal (WCAG requirement).
|
||||
|
||||
### Layer 1 SP semantic alias tokens (exact values from UX spec)
|
||||
|
||||
```css
|
||||
:root {
|
||||
--sp-surface: var(--sp-theme-surface, var(--color-bg-option, #141618));
|
||||
--sp-text-primary: var(--sp-theme-text-primary, var(--color-text-primary, #dde2e8));
|
||||
--sp-text-secondary: var(--sp-theme-text-muted, var(--color-text-secondary, #7a8390));
|
||||
--sp-accent: var(--sp-theme-accent, var(--color-warm-2, #4a9e6b));
|
||||
--sp-focus: var(--sp-theme-focus, var(--color-focus-outline, #63c287));
|
||||
--sp-urgency-director: var(--sp-theme-urgency, #c8982a); /* NO Foundry error/warn token */
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ `--sp-urgency-director` MUST NOT inherit Foundry's error/warn colours. A director cue is a deliberate stage direction, not a failure.
|
||||
|
||||
### State token naming — three sub-tokens per state
|
||||
|
||||
Each state provides three CSS custom properties:
|
||||
```
|
||||
--sp-state-{name}-text
|
||||
--sp-state-{name}-border
|
||||
--sp-state-{name}-bg
|
||||
```
|
||||
|
||||
### VisibilityBadge `:root` exception
|
||||
|
||||
Badge (`PlayerStatusBadge`) is mounted outside the `.scrying-pool` root DOM node, directly onto Foundry's AV tile DOM. Badge state tokens MUST be declared on `:root` so they are available outside the module's root. Add a prominent comment explaining this architectural exception.
|
||||
|
||||
### Naming conventions (enforce across all files)
|
||||
|
||||
- JS files (classes/modules): PascalCase — `StateStore.js`, `FoundryAdapter.js`
|
||||
- Utility/helper files: camelCase — `uuid.js`
|
||||
- Contract files: kebab-case — `socket-message.js`, `pending-op.js`
|
||||
- Test files: `{SourceFile}.test.js` — `StateStore.test.js`
|
||||
- Named exports only — `export class StateStore {}`, never `export default`
|
||||
- World settings prefix: `scrying-pool.` — never `video-view-manager.X`, `sp.X`, `vvm.X`
|
||||
- Socket events prefix: `scrying-pool.`
|
||||
- CSS prefix: `.sp-` or scoped under `.scrying-pool`
|
||||
- Console prefix: `[ScryingPool]` on ALL console calls
|
||||
- Public API returns `null` not `undefined` for "not found"
|
||||
|
||||
### Constructor rule
|
||||
|
||||
```js
|
||||
// ✅ constructor(adapter) { this._adapter = adapter; }
|
||||
// init() { this._adapter.hooks.once('ready', () => this._onReady()); }
|
||||
// ❌ constructor(adapter) { adapter.hooks.once('ready', ...); }
|
||||
```
|
||||
Lifecycle registration belongs in `module.js` (owns `Hooks.once('init')` and `Hooks.once('ready')`). Individual module constructors must be side-effect free.
|
||||
|
||||
### Test pattern — canonical mock
|
||||
|
||||
```js
|
||||
import { createFoundryAdapterMock } from '../helpers/foundryAdapterMock.js'
|
||||
const adapter = createFoundryAdapterMock({ settings: { get: () => 'custom' } })
|
||||
```
|
||||
**No ad-hoc stubs.** All tests use `createFoundryAdapterMock` — the canonical mock factory is established in this story and reused by all subsequent tests.
|
||||
|
||||
### Fixture pattern
|
||||
|
||||
```js
|
||||
// All fixtures are Object.freeze'd
|
||||
export const SOCKET_PAYLOADS = Object.freeze({ ... })
|
||||
// Include negative/invalid fixtures for every validateX() rejection branch
|
||||
```
|
||||
|
||||
### socket-payloads.js fixture shape (stub at this stage)
|
||||
|
||||
Must include at minimum:
|
||||
- Valid intent payload (`scrying-pool.visibility.set`)
|
||||
- Valid echo payload (`scrying-pool.visibility.updated`)
|
||||
- Malformed: missing `opId`
|
||||
- Malformed: wrong enum value for state
|
||||
- Malformed: extra unknown keys
|
||||
|
||||
### State precedence (for VisibilityManager stories — document here for context)
|
||||
|
||||
```
|
||||
pending > cam-lost > reconnecting > offline > never-connected > self-muted > hidden > ghost > active
|
||||
```
|
||||
|
||||
CSS never handles multi-state conflicts — VisibilityManager/RoleRenderer resolve before rendering.
|
||||
|
||||
### module.json v14 manifest required fields
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "video-view-manager",
|
||||
"title": "Video View Manager (Scrying Pool)",
|
||||
"version": "0.1.0",
|
||||
"compatibility": { "minimum": "14", "verified": "14" },
|
||||
"esmodules": ["module.js"],
|
||||
"styles": ["dist/styles/scrying-pool.css"],
|
||||
"languages": [{ "lang": "en", "name": "English", "path": "lang/en.json" }]
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ `version` field in `module.json` is managed by `scripts/package.mjs` at release time. Do NOT edit it manually during development.
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
This is story 1.1 — the project root is currently empty. Create the full directory structure from scratch:
|
||||
|
||||
```
|
||||
video-view-manager/
|
||||
├── module.json
|
||||
├── module.js ← stub (Hooks.once init/ready only)
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── vitest.config.js
|
||||
├── .eslintrc.js
|
||||
├── .gitignore
|
||||
├── .gitea/workflows/ci.yml
|
||||
├── scripts/package.mjs
|
||||
├── src/
|
||||
│ ├── contracts/ ← 4 contract files (full implementation)
|
||||
│ └── utils/uuid.js ← stub (opId generation for PendingOp, later stories)
|
||||
├── styles/
|
||||
│ ├── scrying-pool.less ← @import entry point only
|
||||
│ ├── tokens/
|
||||
│ │ ├── _base.less
|
||||
│ │ ├── _states.less
|
||||
│ │ ├── _motion.less
|
||||
│ │ └── _focus.less
|
||||
│ └── components/ ← 7 stub LESS files
|
||||
├── templates/ ← 5 stub .hbs files
|
||||
├── lang/en.json
|
||||
└── tests/
|
||||
├── helpers/foundryAdapterMock.js
|
||||
├── fixtures/ ← 6 fixture files (all Object.freeze'd)
|
||||
└── unit/contracts/ ← 4 contract test files
|
||||
```
|
||||
|
||||
**No `src/core/`, `src/foundry/`, `src/ui/` files yet** — those are Story 1.2+. Import boundary ESLint rules must still be configured now so they catch violations as soon as those files are created.
|
||||
|
||||
### References
|
||||
|
||||
- Architecture — scaffold decisions: [Source: _bmad-output/planning-artifacts/architecture.md#Starter Template Evaluation]
|
||||
- Architecture — project structure: [Source: _bmad-output/planning-artifacts/architecture.md#Complete Project Directory Structure]
|
||||
- Architecture — naming + enforcement: [Source: _bmad-output/planning-artifacts/architecture.md#Naming Patterns]
|
||||
- Architecture — import boundaries: [Source: _bmad-output/planning-artifacts/architecture.md#Import Boundary Rule]
|
||||
- Architecture — contract format: [Source: _bmad-output/planning-artifacts/architecture.md#Contracts]
|
||||
- Architecture — test patterns: [Source: _bmad-output/planning-artifacts/architecture.md#Test Patterns]
|
||||
- Architecture — LESS/CSS patterns: [Source: _bmad-output/planning-artifacts/architecture.md#LESS / CSS Patterns]
|
||||
- UX spec — design token layers: [Source: _bmad-output/planning-artifacts/ux-design-specification.md#Layer 1–4]
|
||||
- UX spec — state colour values: [Source: _bmad-output/planning-artifacts/ux-design-specification.md#state colour table]
|
||||
- UX spec — CSS scoping discipline: [Source: _bmad-output/planning-artifacts/ux-design-specification.md#Linting convention]
|
||||
- Epics — Story 1.1 ACs + deliverables: [Source: _bmad-output/planning-artifacts/epics.md#Story 1.1]
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
Claude Sonnet 4.6 (claude-sonnet-4.6) via GitHub Copilot CLI
|
||||
|
||||
### Debug Log References
|
||||
|
||||
- ESLint 9.x uses flat config (`eslint.config.js`), not `.eslintrc.js` as story spec states. Used flat config with `@eslint/js`, browser globals, and FoundryVTT globals declared explicitly.
|
||||
- LESS `*/` in block comments causes ParseError — switched all LESS `/** */` comments to `//` line comments.
|
||||
- `tsconfig.json`: `moduleResolution: "node16"` requires `module: "Node16"` — changed to `moduleResolution: "bundler"` (TS 5+ only, compatible with ESNext module).
|
||||
- Contract validators: destructuring `unknown` requires intermediate `Record<string, unknown>` cast for TypeScript strict mode.
|
||||
- `scripts/package.mjs`: `catch(err)` needs `err instanceof Error ? err.message : String(err)` under strict TS.
|
||||
- Test fixture/helper files with untyped stub functions use `// @ts-nocheck` pragma — deliberate, test infrastructure only.
|
||||
- `globals` package available transitively via ESLint — used for `globals.browser` in flat config.
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
- ✅ Task 1: `package.json` initialized, `npm install` exits 0; Node 24.14.1 / npm 11.4.0
|
||||
- ✅ Task 2: `tsconfig.json` (moduleResolution: bundler), `eslint.config.js` (flat config), `vitest.config.js`, `.gitignore`
|
||||
- ✅ Task 3: `module.json` v14 manifest with all required fields
|
||||
- ✅ Task 4: `scripts/package.mjs` release script; produces `module.zip` (14 KB) at v0.1.0
|
||||
- ✅ Task 5: `module.js` entry stub with `Hooks.once('init')` and `Hooks.once('ready')`
|
||||
- ✅ Task 6: All 4 contract files fully implemented with factory + validator; all validators reject unknown keys, throw `TypeError` with field name
|
||||
- ✅ Task 7: Full LESS token system; `npm run build` → `dist/styles/scrying-pool.css` ✅; VisibilityBadge `:root` exception documented
|
||||
- ✅ Task 8: 49 unit tests across 4 contract test files; all pass; `tests/helpers/foundryAdapterMock.js` canonical mock established
|
||||
- ✅ Task 9: `.gitea/workflows/ci.yml` — lint + typecheck + test + build on every push
|
||||
- ✅ Task 10: `lang/en.json` — valid `{}` skeleton
|
||||
- ✅ Task 11: 5 Handlebars template stubs created
|
||||
- ✅ Task 12: Full pipeline — `lint` ✅ `typecheck` ✅ `test` ✅ `build` ✅ `release` ✅
|
||||
|
||||
**Deviations from story spec:**
|
||||
- `eslint.config.js` (flat config) used instead of `.eslintrc.js` (ESLint 9 dropped `.eslintrc.*` support)
|
||||
- `moduleResolution: "bundler"` instead of `"node16"` (node16 requires module: Node16)
|
||||
- `foundry-vtt-types` not installed — `Hooks` declared via minimal `src/types/foundry-globals.d.ts` instead
|
||||
|
||||
### File List
|
||||
|
||||
- `package.json`
|
||||
- `package-lock.json`
|
||||
- `tsconfig.json`
|
||||
- `eslint.config.js`
|
||||
- `vitest.config.js`
|
||||
- `.gitignore`
|
||||
- `module.json`
|
||||
- `module.js`
|
||||
- `scripts/package.mjs`
|
||||
- `src/types/foundry-globals.d.ts`
|
||||
- `src/utils/uuid.js`
|
||||
- `src/contracts/visibility-matrix.js`
|
||||
- `src/contracts/socket-message.js`
|
||||
- `src/contracts/pending-op.js`
|
||||
- `src/contracts/scene-preset.js`
|
||||
- `styles/scrying-pool.less`
|
||||
- `styles/tokens/_base.less`
|
||||
- `styles/tokens/_states.less`
|
||||
- `styles/tokens/_motion.less`
|
||||
- `styles/tokens/_focus.less`
|
||||
- `styles/components/_participant-card.less`
|
||||
- `styles/components/_roster-strip.less`
|
||||
- `styles/components/_directors-board.less`
|
||||
- `styles/components/_scene-preset-panel.less`
|
||||
- `styles/components/_notification.less`
|
||||
- `styles/components/_player-badge.less`
|
||||
- `styles/components/_player-panel.less`
|
||||
- `lang/en.json`
|
||||
- `templates/directors-board.hbs`
|
||||
- `templates/participant-card.hbs`
|
||||
- `templates/roster-strip.hbs`
|
||||
- `templates/scene-preset-panel.hbs`
|
||||
- `templates/player-panel.hbs`
|
||||
- `.gitea/workflows/ci.yml`
|
||||
- `tests/helpers/foundryAdapterMock.js`
|
||||
- `tests/fixtures/socket-payloads.js`
|
||||
- `tests/fixtures/visibility-states.js`
|
||||
- `tests/fixtures/state-store-snapshots.js`
|
||||
- `tests/fixtures/scene-preset.js`
|
||||
- `tests/fixtures/pending-op.js`
|
||||
- `tests/fixtures/foundry-adapter.js`
|
||||
- `tests/unit/contracts/visibility-matrix.test.js`
|
||||
- `tests/unit/contracts/socket-message.test.js`
|
||||
- `tests/unit/contracts/pending-op.test.js`
|
||||
- `tests/unit/contracts/scene-preset.test.js`
|
||||
|
||||
### Change Log
|
||||
|
||||
- 2025-05-21: Story 1.1 implementation complete — full scaffold, CI, LESS token system, contracts, test infrastructure (49 tests, all pass; full pipeline lint/typecheck/test/build/release exits 0)--- DIFF TO REVIEW ---
|
||||
diff --git a/.gitignore b/.gitignore
|
||||
new file mode 100644
|
||||
index 0000000..c2ccb26
|
||||
--- /dev/null
|
||||
+++ b/.gitignore
|
||||
@@ -0,0 +1,4 @@
|
||||
+dist/
|
||||
+node_modules/
|
||||
+*.zip
|
||||
+*.lock
|
||||
diff --git a/eslint.config.js b/eslint.config.js
|
||||
new file mode 100644
|
||||
index 0000000..4de7904
|
||||
--- /dev/null
|
||||
+++ b/eslint.config.js
|
||||
@@ -0,0 +1,124 @@
|
||||
+import js from "@eslint/js";
|
||||
+import jsdoc from "eslint-plugin-jsdoc";
|
||||
+import importPlugin from "eslint-plugin-import";
|
||||
+import globals from "globals";
|
||||
+import { fileURLToPath } from "url";
|
||||
+import { dirname } from "path";
|
||||
+
|
||||
+const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
+
|
||||
+export default [
|
||||
+ js.configs.recommended,
|
||||
+ {
|
||||
+ plugins: {
|
||||
+ jsdoc,
|
||||
+ import: importPlugin,
|
||||
+ },
|
||||
+ languageOptions: {
|
||||
+ globals: {
|
||||
+ // Browser built-ins (console, setTimeout, etc.)
|
||||
+ ...globals.browser,
|
||||
+ // FoundryVTT globals injected at runtime
|
||||
+ Hooks: "readonly",
|
||||
+ game: "readonly",
|
||||
+ ui: "readonly",
|
||||
+ canvas: "readonly",
|
||||
+ foundry: "readonly",
|
||||
+ CONFIG: "readonly",
|
||||
+ CONST: "readonly",
|
||||
+ },
|
||||
+ },
|
||||
+ rules: {
|
||||
+ // Require JSDoc on all exported symbols
|
||||
+ "jsdoc/require-jsdoc": [
|
||||
+ "error",
|
||||
+ {
|
||||
+ publicOnly: true,
|
||||
+ require: {
|
||||
+ FunctionDeclaration: true,
|
||||
+ MethodDefinition: true,
|
||||
+ ClassDeclaration: true,
|
||||
+ ArrowFunctionExpression: false,
|
||||
+ FunctionExpression: false,
|
||||
+ },
|
||||
+ contexts: ["ExportNamedDeclaration > FunctionDeclaration"],
|
||||
+ },
|
||||
+ ],
|
||||
+ "jsdoc/require-param": "warn",
|
||||
+ "jsdoc/require-returns": "warn",
|
||||
+
|
||||
+ // Import boundary enforcement
|
||||
+ "import/no-restricted-paths": [
|
||||
+ "error",
|
||||
+ {
|
||||
+ zones: [
|
||||
+ // src/core/ → may import src/contracts/ and src/utils/ ONLY
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/foundry",
|
||||
+ message: "src/core/ must not import from src/foundry/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/ui",
|
||||
+ message: "src/core/ must not import from src/ui/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/notifications",
|
||||
+ message: "src/core/ must not import from src/notifications/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/presets",
|
||||
+ message: "src/core/ must not import from src/presets/",
|
||||
+ },
|
||||
+ // src/foundry/ → may import src/contracts/ and src/utils/ ONLY
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/core",
|
||||
+ message: "src/foundry/ must not import from src/core/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/ui",
|
||||
+ message: "src/foundry/ must not import from src/ui/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/notifications",
|
||||
+ message: "src/foundry/ must not import from src/notifications/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/presets",
|
||||
+ message: "src/foundry/ must not import from src/presets/",
|
||||
+ },
|
||||
+ // src/contracts/ → no internal imports
|
||||
+ {
|
||||
+ target: "./src/contracts",
|
||||
+ from: "./src",
|
||||
+ message: "src/contracts/ must not import from other src/ modules",
|
||||
+ },
|
||||
+ // src/utils/ → no internal imports
|
||||
+ {
|
||||
+ target: "./src/utils",
|
||||
+ from: "./src",
|
||||
+ message: "src/utils/ must not import from other src/ modules",
|
||||
+ },
|
||||
+ ],
|
||||
+ },
|
||||
+ ],
|
||||
+ },
|
||||
+ },
|
||||
+ {
|
||||
+ files: ["tests/**/*.js"],
|
||||
+ rules: {
|
||||
+ // Relax JSDoc requirement for test files
|
||||
+ "jsdoc/require-jsdoc": "off",
|
||||
+ },
|
||||
+ },
|
||||
+ {
|
||||
+ ignores: ["dist/", "node_modules/", "*.zip"],
|
||||
+ },
|
||||
+];
|
||||
diff --git a/module.js b/module.js
|
||||
new file mode 100644
|
||||
index 0000000..a3ad2d7
|
||||
--- /dev/null
|
||||
+++ b/module.js
|
||||
@@ -0,0 +1,24 @@
|
||||
+/**
|
||||
+ * module.js — Entry point and wiring diagram for Video View Manager (Scrying Pool).
|
||||
+ *
|
||||
+ * This file is the wiring diagram ONLY. It imports all modules, constructs them
|
||||
+ * with injected dependencies, and holds NO business logic.
|
||||
+ *
|
||||
+ * Initialisation order:
|
||||
+ * Hooks.once('init') → register world settings → construct FoundryAdapter
|
||||
+ * → StateStore → SocketHandler (queue+drain)
|
||||
+ * Hooks.once('ready') → VisibilityManager → SocketHandler.setReady()
|
||||
+ * → NotificationBus → RoleRenderer → RosterStrip
|
||||
+ * → DirectorsBoard (lazy, GM only)
|
||||
+ */
|
||||
+
|
||||
+Hooks.once("init", () => {
|
||||
+ console.log("[ScryingPool] init — module loading");
|
||||
+ // Story 1.3+: register world settings, construct FoundryAdapter, StateStore, SocketHandler
|
||||
+});
|
||||
+
|
||||
+Hooks.once("ready", () => {
|
||||
+ console.log("[ScryingPool] ready — module active");
|
||||
+ // Story 1.3+: construct VisibilityManager, NotificationBus, RoleRenderer, RosterStrip
|
||||
+ // Story 1.5+: register DirectorsBoard (lazy, GM only)
|
||||
+});
|
||||
diff --git a/module.json b/module.json
|
||||
new file mode 100644
|
||||
index 0000000..e1cffdc
|
||||
--- /dev/null
|
||||
+++ b/module.json
|
||||
@@ -0,0 +1,29 @@
|
||||
+{
|
||||
+ "id": "video-view-manager",
|
||||
+ "title": "Video View Manager (Scrying Pool)",
|
||||
+ "version": "0.1.0",
|
||||
+ "description": "GM camera visibility control for FoundryVTT v14 — hide, show, and manage participant feeds in real time.",
|
||||
+ "authors": [
|
||||
+ {
|
||||
+ "name": "Morr"
|
||||
+ }
|
||||
+ ],
|
||||
+ "compatibility": {
|
||||
+ "minimum": "14",
|
||||
+ "verified": "14"
|
||||
+ },
|
||||
+ "esmodules": [
|
||||
+ "module.js"
|
||||
+ ],
|
||||
+ "styles": [
|
||||
+ "dist/styles/scrying-pool.css"
|
||||
+ ],
|
||||
+ "languages": [
|
||||
+ {
|
||||
+ "lang": "en",
|
||||
+ "name": "English",
|
||||
+ "path": "lang/en.json"
|
||||
+ }
|
||||
+ ],
|
||||
+ "flags": {}
|
||||
+}
|
||||
diff --git a/package.json b/package.json
|
||||
new file mode 100644
|
||||
index 0000000..fab7015
|
||||
--- /dev/null
|
||||
+++ b/package.json
|
||||
@@ -0,0 +1,26 @@
|
||||
+{
|
||||
+ "name": "video-view-manager",
|
||||
+ "version": "0.1.0",
|
||||
+ "description": "FoundryVTT v14 module — Scrying Pool camera visibility control",
|
||||
+ "type": "module",
|
||||
+ "scripts": {
|
||||
+ "build": "lessc styles/scrying-pool.less dist/styles/scrying-pool.css",
|
||||
+ "watch": "chokidar 'styles/**/*.less' -c 'lessc styles/scrying-pool.less dist/styles/scrying-pool.css'",
|
||||
+ "typecheck": "tsc --noEmit",
|
||||
+ "lint": "eslint src/ module.js",
|
||||
+ "test": "vitest run",
|
||||
+ "test:watch": "vitest",
|
||||
+ "release": "node scripts/package.mjs"
|
||||
+ },
|
||||
+ "devDependencies": {
|
||||
+ "@types/node": "^22.0.0",
|
||||
+ "chokidar": "5.0.0",
|
||||
+ "eslint": "^9.0.0",
|
||||
+ "eslint-plugin-import": "^2.31.0",
|
||||
+ "eslint-plugin-jsdoc": "^50.0.0",
|
||||
+ "happy-dom": "^20.0.0",
|
||||
+ "less": "4.6.4",
|
||||
+ "typescript": "5.9.3",
|
||||
+ "vitest": "2.1.8"
|
||||
+ }
|
||||
+}
|
||||
diff --git a/scripts/package.mjs b/scripts/package.mjs
|
||||
new file mode 100644
|
||||
index 0000000..9a7300e
|
||||
--- /dev/null
|
||||
+++ b/scripts/package.mjs
|
||||
@@ -0,0 +1,60 @@
|
||||
+/**
|
||||
+ * Release script — produces module.zip.
|
||||
+ *
|
||||
+ * Single version source of truth: reads version from package.json,
|
||||
+ * writes it into module.json, then zips all release artefacts.
|
||||
+ *
|
||||
+ * Usage: node scripts/package.mjs
|
||||
+ */
|
||||
+
|
||||
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
|
||||
+import { resolve, dirname } from "path";
|
||||
+import { fileURLToPath } from "url";
|
||||
+import { createGzip } from "zlib";
|
||||
+import { exec } from "child_process";
|
||||
+import { promisify } from "util";
|
||||
+
|
||||
+const execAsync = promisify(exec);
|
||||
+const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
+const ROOT = resolve(__dirname, "..");
|
||||
+
|
||||
+// Read version from package.json (single source of truth)
|
||||
+const pkg = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8"));
|
||||
+const { version } = pkg;
|
||||
+
|
||||
+// Write version into module.json
|
||||
+const moduleJsonPath = resolve(ROOT, "module.json");
|
||||
+const moduleJson = JSON.parse(readFileSync(moduleJsonPath, "utf8"));
|
||||
+moduleJson.version = version;
|
||||
+writeFileSync(moduleJsonPath, JSON.stringify(moduleJson, null, 2) + "\n", "utf8");
|
||||
+console.log(`[ScryingPool] module.json version set to ${version}`);
|
||||
+
|
||||
+// Ensure dist/ exists (build should have run first)
|
||||
+if (!existsSync(resolve(ROOT, "dist"))) {
|
||||
+ console.error("[ScryingPool] dist/ not found — run npm run build first");
|
||||
+ process.exit(1);
|
||||
+}
|
||||
+
|
||||
+// Files and directories to include in module.zip
|
||||
+const INCLUDE = [
|
||||
+ "module.json",
|
||||
+ "module.js",
|
||||
+ "lang/",
|
||||
+ "templates/",
|
||||
+ "dist/",
|
||||
+ "src/",
|
||||
+];
|
||||
+
|
||||
+// Build zip using system zip command
|
||||
+const targets = INCLUDE.filter((f) => existsSync(resolve(ROOT, f)));
|
||||
+const zipArgs = targets.map((t) => `"${t}"`).join(" ");
|
||||
+const zipCmd = `cd "${ROOT}" && zip -r module.zip ${zipArgs}`;
|
||||
+
|
||||
+console.log("[ScryingPool] Creating module.zip...");
|
||||
+try {
|
||||
+ await execAsync(zipCmd);
|
||||
+ console.log(`[ScryingPool] module.zip created (v${version})`);
|
||||
+} catch (err) {
|
||||
+ console.error("[ScryingPool] zip failed:", err instanceof Error ? err.message : String(err));
|
||||
+ process.exit(1);
|
||||
+}
|
||||
diff --git a/tsconfig.json b/tsconfig.json
|
||||
new file mode 100644
|
||||
index 0000000..7d64af8
|
||||
--- /dev/null
|
||||
+++ b/tsconfig.json
|
||||
@@ -0,0 +1,14 @@
|
||||
+{
|
||||
+ "compilerOptions": {
|
||||
+ "checkJs": true,
|
||||
+ "strict": true,
|
||||
+ "noEmit": true,
|
||||
+ "target": "ESNext",
|
||||
+ "module": "ESNext",
|
||||
+ "moduleResolution": "bundler",
|
||||
+ "allowJs": true,
|
||||
+ "lib": ["ESNext", "DOM"]
|
||||
+ },
|
||||
+ "include": ["src/**/*.js", "src/**/*.d.ts", "module.js", "scripts/**/*.mjs", "tests/**/*.js"],
|
||||
+ "exclude": ["node_modules", "dist"]
|
||||
+}
|
||||
diff --git a/vitest.config.js b/vitest.config.js
|
||||
new file mode 100644
|
||||
index 0000000..c18efc0
|
||||
--- /dev/null
|
||||
+++ b/vitest.config.js
|
||||
@@ -0,0 +1,23 @@
|
||||
+import { defineConfig } from "vitest/config";
|
||||
+
|
||||
+export default defineConfig({
|
||||
+ test: {
|
||||
+ environment: "happy-dom",
|
||||
+ globals: false,
|
||||
+ include: ["tests/**/*.test.js"],
|
||||
+ coverage: {
|
||||
+ provider: "v8",
|
||||
+ reporter: ["text", "lcov"],
|
||||
+ include: ["src/**/*.js"],
|
||||
+ exclude: ["src/contracts/**"],
|
||||
+ },
|
||||
+ },
|
||||
+ resolve: {
|
||||
+ alias: {
|
||||
+ "@src": "/src",
|
||||
+ "@contracts": "/src/contracts",
|
||||
+ "@utils": "/src/utils",
|
||||
+ "@tests": "/tests",
|
||||
+ },
|
||||
+ },
|
||||
+});
|
||||
@@ -0,0 +1,377 @@
|
||||
# Blind Hunter Review Layer
|
||||
|
||||
## ROLE
|
||||
You are **Blind Hunter** — an adversarial code reviewer. You have NO access to the project, spec, or any context. You only see the diff below.
|
||||
|
||||
## MISSION
|
||||
Find problems. Be ruthless. Assume nothing is intentional. Look for:
|
||||
- **Security vulnerabilities** (injection, XSS, path traversal, hardcoded secrets)
|
||||
- **Bugs** (logical errors, race conditions, null dereferences)
|
||||
- **Performance issues** (N+1 queries, unnecessary computations, memory leaks)
|
||||
- **Anti-patterns** (god objects, circular dependencies, mutable globals)
|
||||
- **Code smells** (duplicate code, long methods, magic numbers)
|
||||
- **Best practice violations** (error handling, input validation, coding standards)
|
||||
- **Anything suspicious** (unusual patterns, odd dependencies, weird configurations)
|
||||
|
||||
## OUTPUT FORMAT
|
||||
Output ONLY a Markdown list of findings. No preamble, no summary. Each finding:
|
||||
```markdown
|
||||
- **[SEVERITY]** Short title — file:line — evidence/quote from diff
|
||||
```
|
||||
Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO
|
||||
|
||||
## DIFF TO REVIEW
|
||||
|
||||
```diff
|
||||
diff --git a/.gitignore b/.gitignore
|
||||
new file mode 100644
|
||||
index 0000000..c2ccb26
|
||||
--- /dev/null
|
||||
+++ b/.gitignore
|
||||
@@ -0,0 +1,4 @@
|
||||
+dist/
|
||||
+node_modules/
|
||||
+*.zip
|
||||
+*.lock
|
||||
diff --git a/eslint.config.js b/eslint.config.js
|
||||
new file mode 100644
|
||||
index 0000000..4de7904
|
||||
--- /dev/null
|
||||
+++ b/eslint.config.js
|
||||
@@ -0,0 +1,124 @@
|
||||
+import js from "@eslint/js";
|
||||
+import jsdoc from "eslint-plugin-jsdoc";
|
||||
+import importPlugin from "eslint-plugin-import";
|
||||
+import globals from "globals";
|
||||
+import { fileURLToPath } from "url";
|
||||
+import { dirname } from "path";
|
||||
+
|
||||
+const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
+
|
||||
+export default [
|
||||
+ js.configs.recommended,
|
||||
+ {
|
||||
+ plugins: {
|
||||
+ jsdoc,
|
||||
+ import: importPlugin,
|
||||
+ },
|
||||
+ languageOptions: {
|
||||
+ globals: {
|
||||
+ // Browser built-ins (console, setTimeout, etc.)
|
||||
+ ...globals.browser,
|
||||
+ // FoundryVTT globals injected at runtime
|
||||
+ Hooks: "readonly",
|
||||
+ game: "readonly",
|
||||
+ ui: "readonly",
|
||||
+ canvas: "readonly",
|
||||
+ foundry: "readonly",
|
||||
+ CONFIG: "readonly",
|
||||
+ CONST: "readonly",
|
||||
+ },
|
||||
+ },
|
||||
+ rules: {
|
||||
+ // Require JSDoc on all exported symbols
|
||||
+ "jsdoc/require-jsdoc": [
|
||||
+ "error",
|
||||
+ {
|
||||
+ publicOnly: true,
|
||||
+ require: {
|
||||
+ FunctionDeclaration: true,
|
||||
+ MethodDefinition: true,
|
||||
+ ClassDeclaration: true,
|
||||
+ ArrowFunctionExpression: false,
|
||||
+ FunctionExpression: false,
|
||||
+ },
|
||||
+ contexts: ["ExportNamedDeclaration > FunctionDeclaration"],
|
||||
+ },
|
||||
+ ],
|
||||
+ "jsdoc/require-param": "warn",
|
||||
+ "jsdoc/require-returns": "warn",
|
||||
+
|
||||
+ // Import boundary enforcement
|
||||
+ "import/no-restricted-paths": [
|
||||
+ "error",
|
||||
+ {
|
||||
+ zones: [
|
||||
+ // src/core/ → may import src/contracts/ and src/utils/ ONLY
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/foundry",
|
||||
+ message: "src/core/ must not import from src/foundry/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/ui",
|
||||
+ message: "src/core/ must not import from src/ui/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/notifications",
|
||||
+ message: "src/core/ must not import from src/notifications/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/presets",
|
||||
+ message: "src/core/ must not import from src/presets/",
|
||||
+ },
|
||||
+ // src/foundry/ → may import src/contracts/ and src/utils/ ONLY
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/core",
|
||||
+ message: "src/foundry/ must not import from src/core/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/ui",
|
||||
+ message: "src/foundry/ must not import from src/ui/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/notifications",
|
||||
+ message: "src/foundry/ must not import from src/notifications/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/presets",
|
||||
+ message: "src/foundry/ must not import from src/presets/",
|
||||
+ },
|
||||
+ // src/contracts/ → no internal imports
|
||||
+ {
|
||||
+ target: "./src/contracts",
|
||||
+ from: "./src",
|
||||
+ message: "src/contracts/ must not import from other src/ modules",
|
||||
+ },
|
||||
+ // src/utils/ → no internal imports
|
||||
+ {
|
||||
+ target: "./src/utils",
|
||||
+ from: "./src",
|
||||
+ message: "src/utils/ must not import from other src/ modules",
|
||||
+ },
|
||||
+ ],
|
||||
+ },
|
||||
+ ],
|
||||
+ },
|
||||
+ },
|
||||
+ {
|
||||
+ files: ["tests/**/*.js"],
|
||||
+ rules: {
|
||||
+ // Relax JSDoc requirement for test files
|
||||
+ "jsdoc/require-jsdoc": "off",
|
||||
+ },
|
||||
+ },
|
||||
+ {
|
||||
+ ignores: ["dist/", "node_modules/", "*.zip"],
|
||||
+ },
|
||||
+];
|
||||
diff --git a/module.js b/module.js
|
||||
new file mode 100644
|
||||
index 0000000..a3ad2d7
|
||||
--- /dev/null
|
||||
+++ b/module.js
|
||||
@@ -0,0 +1,24 @@
|
||||
+/**
|
||||
+ * module.js — Entry point and wiring diagram for Video View Manager (Scrying Pool).
|
||||
+ *
|
||||
+ * This file is the wiring diagram ONLY. It imports all modules, constructs them
|
||||
+ * with injected dependencies, and holds NO business logic.
|
||||
+ *
|
||||
+ * Initialisation order:
|
||||
+ * Hooks.once('init') → register world settings → construct FoundryAdapter
|
||||
+ * → StateStore → SocketHandler (queue+drain)
|
||||
+ * Hooks.once('ready') → VisibilityManager → SocketHandler.setReady()
|
||||
+ * → NotificationBus → RoleRenderer → RosterStrip
|
||||
+ * → DirectorsBoard (lazy, GM only)
|
||||
+ */
|
||||
+
|
||||
+Hooks.once("init", () => {
|
||||
+ console.log("[ScryingPool] init — module loading");
|
||||
+ // Story 1.3+: register world settings, construct FoundryAdapter, StateStore, SocketHandler
|
||||
+});
|
||||
+
|
||||
+Hooks.once("ready", () => {
|
||||
+ console.log("[ScryingPool] ready — module active");
|
||||
+ // Story 1.3+: construct VisibilityManager, NotificationBus, RoleRenderer, RosterStrip
|
||||
+ // Story 1.5+: register DirectorsBoard (lazy, GM only)
|
||||
+});
|
||||
diff --git a/module.json b/module.json
|
||||
new file mode 100644
|
||||
index 0000000..e1cffdc
|
||||
--- /dev/null
|
||||
+++ b/module.json
|
||||
@@ -0,0 +1,29 @@
|
||||
+{
|
||||
+ "id": "video-view-manager",
|
||||
+ "title": "Video View Manager (Scrying Pool)",
|
||||
+ "version": "0.1.0",
|
||||
+ "description": "GM camera visibility control for FoundryVTT v14 — hide, show, and manage participant feeds in real time.",
|
||||
+ "authors": [
|
||||
+ {
|
||||
+ "name": "Morr"
|
||||
+ }
|
||||
+ ],
|
||||
+ "compatibility": {
|
||||
+ "minimum": "14",
|
||||
+ "verified": "14"
|
||||
+ },
|
||||
+ "esmodules": [
|
||||
+ "module.js"
|
||||
+ ],
|
||||
+ "styles": [
|
||||
+ "dist/styles/scrying-pool.css"
|
||||
+ ],
|
||||
+ "languages": [
|
||||
+ {
|
||||
+ "lang": "en",
|
||||
+ "name": "English",
|
||||
+ "path": "lang/en.json"
|
||||
+ }
|
||||
+ ],
|
||||
+ "flags": {}
|
||||
+}
|
||||
diff --git a/package.json b/package.json
|
||||
new file mode 100644
|
||||
index 0000000..fab7015
|
||||
--- /dev/null
|
||||
+++ b/package.json
|
||||
@@ -0,0 +1,26 @@
|
||||
+{
|
||||
+ "name": "video-view-manager",
|
||||
+ "version": "0.1.0",
|
||||
+ "description": "FoundryVTT v14 module — Scrying Pool camera visibility control",
|
||||
+ "type": "module",
|
||||
+ "scripts": {
|
||||
+ "build": "lessc styles/scrying-pool.less dist/styles/scrying-pool.css",
|
||||
+ "watch": "chokidar 'styles/**/*.less' -c 'lessc styles/scrying-pool.less dist/styles/scrying-pool.css'",
|
||||
+ "typecheck": "tsc --noEmit",
|
||||
+ "lint": "eslint src/ module.js",
|
||||
+ "test": "vitest run",
|
||||
+ "test:watch": "vitest",
|
||||
+ "release": "node scripts/package.mjs"
|
||||
+ },
|
||||
+ "devDependencies": {
|
||||
+ "@types/node": "^22.0.0",
|
||||
+ "chokidar": "5.0.0",
|
||||
+ "eslint": "^9.0.0",
|
||||
+ "eslint-plugin-import": "^2.31.0",
|
||||
+ "eslint-plugin-jsdoc": "^50.0.0",
|
||||
+ "happy-dom": "^20.0.0",
|
||||
+ "less": "4.6.4",
|
||||
+ "typescript": "5.9.3",
|
||||
+ "vitest": "2.1.8"
|
||||
+ }
|
||||
+}
|
||||
diff --git a/scripts/package.mjs b/scripts/package.mjs
|
||||
new file mode 100644
|
||||
index 0000000..9a7300e
|
||||
--- /dev/null
|
||||
+++ b/scripts/package.mjs
|
||||
@@ -0,0 +1,60 @@
|
||||
+/**
|
||||
+ * Release script — produces module.zip.
|
||||
+ *
|
||||
+ * Single version source of truth: reads version from package.json,
|
||||
+ * writes it into module.json, then zips all release artefacts.
|
||||
+ *
|
||||
+ * Usage: node scripts/package.mjs
|
||||
+ */
|
||||
+
|
||||
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
|
||||
+import { resolve, dirname } from "path";
|
||||
+import { fileURLToPath } from "url";
|
||||
+import { createGzip } from "zlib";
|
||||
+import { exec } from "child_process";
|
||||
+import { promisify } from "util";
|
||||
+
|
||||
+const execAsync = promisify(exec);
|
||||
+const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
+const ROOT = resolve(__dirname, "..");
|
||||
+
|
||||
+// Read version from package.json (single source of truth)
|
||||
+const pkg = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8"));
|
||||
+const { version } = pkg;
|
||||
+
|
||||
+// Write version into module.json
|
||||
+const moduleJsonPath = resolve(ROOT, "module.json");
|
||||
+const moduleJson = JSON.parse(readFileSync(moduleJsonPath, "utf8"));
|
||||
+moduleJson.version = version;
|
||||
+writeFileSync(moduleJsonPath, JSON.stringify(moduleJson, null, 2) + "\n", "utf8");
|
||||
+console.log(`[ScryingPool] module.json version set to ${version}`);
|
||||
+
|
||||
+// Ensure dist/ exists (build should have run first)
|
||||
+if (!existsSync(resolve(ROOT, "dist"))) {
|
||||
+ console.error("[ScryingPool] dist/ not found — run npm run build first");
|
||||
+ process.exit(1);
|
||||
+}
|
||||
+
|
||||
+// Files and directories to include in module.zip
|
||||
+const INCLUDE = [
|
||||
+ "module.json",
|
||||
+ "module.js",
|
||||
+ "lang/",
|
||||
+ "templates/",
|
||||
+ "dist/",
|
||||
+ "src/",
|
||||
+];
|
||||
+
|
||||
+// Build zip using system zip command
|
||||
+const targets = INCLUDE.filter((f) => existsSync(resolve(ROOT, f)));
|
||||
+const zipArgs = targets.map((t) => `"${t}"`).join(" ");
|
||||
+const zipCmd = `cd "${ROOT}" && zip -r module.zip ${zipArgs}`;
|
||||
+
|
||||
+console.log("[ScryingPool] Creating module.zip...");
|
||||
+try {
|
||||
+ await execAsync(zipCmd);
|
||||
+ console.log(`[ScryingPool] module.zip created (v${version})`);
|
||||
+} catch (err) {
|
||||
+ console.error("[ScryingPool] zip failed:", err instanceof Error ? err.message : String(err));
|
||||
+ process.exit(1);
|
||||
+}
|
||||
diff --git a/tsconfig.json b/tsconfig.json
|
||||
new file mode 100644
|
||||
index 0000000..7d64af8
|
||||
--- /dev/null
|
||||
+++ b/tsconfig.json
|
||||
@@ -0,0 +1,14 @@
|
||||
+{
|
||||
+ "compilerOptions": {
|
||||
+ "checkJs": true,
|
||||
+ "strict": true,
|
||||
+ "noEmit": true,
|
||||
+ "target": "ESNext",
|
||||
+ "module": "ESNext",
|
||||
+ "moduleResolution": "bundler",
|
||||
+ "allowJs": true,
|
||||
+ "lib": ["ESNext", "DOM"]
|
||||
+ },
|
||||
+ "include": ["src/**/*.js", "src/**/*.d.ts", "module.js", "scripts/**/*.mjs", "tests/**/*.js"],
|
||||
+ "exclude": ["node_modules", "dist"]
|
||||
+}
|
||||
diff --git a/vitest.config.js b/vitest.config.js
|
||||
new file mode 100644
|
||||
index 0000000..c18efc0
|
||||
--- /dev/null
|
||||
+++ b/vitest.config.js
|
||||
@@ -0,0 +1,23 @@
|
||||
+import { defineConfig } from "vitest/config";
|
||||
+
|
||||
+export default defineConfig({
|
||||
+ test: {
|
||||
+ environment: "happy-dom",
|
||||
+ globals: false,
|
||||
+ include: ["tests/**/*.test.js"],
|
||||
+ coverage: {
|
||||
+ provider: "v8",
|
||||
+ reporter: ["text", "lcov"],
|
||||
+ include: ["src/**/*.js"],
|
||||
+ exclude: ["src/contracts/**"],
|
||||
+ },
|
||||
+ },
|
||||
+ resolve: {
|
||||
+ alias: {
|
||||
+ "@src": "/src",
|
||||
+ "@contracts": "/src/contracts",
|
||||
+ "@utils": "/src/utils",
|
||||
+ "@tests": "/tests",
|
||||
+ },
|
||||
+ },
|
||||
+});
|
||||
@@ -0,0 +1,381 @@
|
||||
# Edge Case Hunter Review Layer
|
||||
|
||||
## ROLE
|
||||
You are **Edge Case Hunter** — a meticulous reviewer focused on boundary conditions and unusual scenarios. You have read access to the project files but ONLY for understanding context. Your primary input is the diff below.
|
||||
|
||||
## MISSION
|
||||
Walk every branching path and boundary condition. Look for:
|
||||
- **Unchecked assumptions** (what if this is null/undefined/empty/zero?)
|
||||
- **Off-by-one errors** (loop boundaries, array indices, string slicing)
|
||||
- **Type coercion issues** (== vs ===, truthy/falsy confusion)
|
||||
- **Concurrency problems** (race conditions, async/await mishandling)
|
||||
- **Edge input values** (empty strings, very long strings, special characters, unicode)
|
||||
- **State transitions** (what happens after error? after retry? after timeout?)
|
||||
- **Error handling gaps** (unhandled exceptions, missing error cases)
|
||||
- **API contract violations** (return types, parameter validation, side effects)
|
||||
|
||||
## OUTPUT FORMAT
|
||||
Output ONLY a Markdown list of findings. No preamble, no summary. Each finding:
|
||||
```markdown
|
||||
- **[SEVERITY]** Short title — file:line — edge case description + evidence
|
||||
```
|
||||
Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO
|
||||
|
||||
## PROJECT ROOT
|
||||
/home/morr/work/foundryvtt/video-view-manager
|
||||
|
||||
## DIFF TO REVIEW
|
||||
|
||||
```diff
|
||||
diff --git a/.gitignore b/.gitignore
|
||||
new file mode 100644
|
||||
index 0000000..c2ccb26
|
||||
--- /dev/null
|
||||
+++ b/.gitignore
|
||||
@@ -0,0 +1,4 @@
|
||||
+dist/
|
||||
+node_modules/
|
||||
+*.zip
|
||||
+*.lock
|
||||
diff --git a/eslint.config.js b/eslint.config.js
|
||||
new file mode 100644
|
||||
index 0000000..4de7904
|
||||
--- /dev/null
|
||||
+++ b/eslint.config.js
|
||||
@@ -0,0 +1,124 @@
|
||||
+import js from "@eslint/js";
|
||||
+import jsdoc from "eslint-plugin-jsdoc";
|
||||
+import importPlugin from "eslint-plugin-import";
|
||||
+import globals from "globals";
|
||||
+import { fileURLToPath } from "url";
|
||||
+import { dirname } from "path";
|
||||
+
|
||||
+const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
+
|
||||
+export default [
|
||||
+ js.configs.recommended,
|
||||
+ {
|
||||
+ plugins: {
|
||||
+ jsdoc,
|
||||
+ import: importPlugin,
|
||||
+ },
|
||||
+ languageOptions: {
|
||||
+ globals: {
|
||||
+ // Browser built-ins (console, setTimeout, etc.)
|
||||
+ ...globals.browser,
|
||||
+ // FoundryVTT globals injected at runtime
|
||||
+ Hooks: "readonly",
|
||||
+ game: "readonly",
|
||||
+ ui: "readonly",
|
||||
+ canvas: "readonly",
|
||||
+ foundry: "readonly",
|
||||
+ CONFIG: "readonly",
|
||||
+ CONST: "readonly",
|
||||
+ },
|
||||
+ },
|
||||
+ rules: {
|
||||
+ // Require JSDoc on all exported symbols
|
||||
+ "jsdoc/require-jsdoc": [
|
||||
+ "error",
|
||||
+ {
|
||||
+ publicOnly: true,
|
||||
+ require: {
|
||||
+ FunctionDeclaration: true,
|
||||
+ MethodDefinition: true,
|
||||
+ ClassDeclaration: true,
|
||||
+ ArrowFunctionExpression: false,
|
||||
+ FunctionExpression: false,
|
||||
+ },
|
||||
+ contexts: ["ExportNamedDeclaration > FunctionDeclaration"],
|
||||
+ },
|
||||
+ ],
|
||||
+ "jsdoc/require-param": "warn",
|
||||
+ "jsdoc/require-returns": "warn",
|
||||
+
|
||||
+ // Import boundary enforcement
|
||||
+ "import/no-restricted-paths": [
|
||||
+ "error",
|
||||
+ {
|
||||
+ zones: [
|
||||
+ // src/core/ → may import src/contracts/ and src/utils/ ONLY
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/foundry",
|
||||
+ message: "src/core/ must not import from src/foundry/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/ui",
|
||||
+ message: "src/core/ must not import from src/ui/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/notifications",
|
||||
+ message: "src/core/ must not import from src/notifications/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/core",
|
||||
+ from: "./src/presets",
|
||||
+ message: "src/core/ must not import from src/presets/",
|
||||
+ },
|
||||
+ // src/foundry/ → may import src/contracts/ and src/utils/ ONLY
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/core",
|
||||
+ message: "src/foundry/ must not import from src/core/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/ui",
|
||||
+ message: "src/foundry/ must not import from src/ui/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/notifications",
|
||||
+ message: "src/foundry/ must not import from src/notifications/",
|
||||
+ },
|
||||
+ {
|
||||
+ target: "./src/foundry",
|
||||
+ from: "./src/presets",
|
||||
+ message: "src/foundry/ must not import from src/presets/",
|
||||
+ },
|
||||
+ // src/contracts/ → no internal imports
|
||||
+ {
|
||||
+ target: "./src/contracts",
|
||||
+ from: "./src",
|
||||
+ message: "src/contracts/ must not import from other src/ modules",
|
||||
+ },
|
||||
+ // src/utils/ → no internal imports
|
||||
+ {
|
||||
+ target: "./src/utils",
|
||||
+ from: "./src",
|
||||
+ message: "src/utils/ must not import from other src/ modules",
|
||||
+ },
|
||||
+ ],
|
||||
+ },
|
||||
+ ],
|
||||
+ },
|
||||
+ },
|
||||
+ {
|
||||
+ files: ["tests/**/*.js"],
|
||||
+ rules: {
|
||||
+ // Relax JSDoc requirement for test files
|
||||
+ "jsdoc/require-jsdoc": "off",
|
||||
+ },
|
||||
+ },
|
||||
+ {
|
||||
+ ignores: ["dist/", "node_modules/", "*.zip"],
|
||||
+ },
|
||||
+];
|
||||
diff --git a/module.js b/module.js
|
||||
new file mode 100644
|
||||
index 0000000..a3ad2d7
|
||||
--- /dev/null
|
||||
+++ b/module.js
|
||||
@@ -0,0 +1,24 @@
|
||||
+/**
|
||||
+ * module.js — Entry point and wiring diagram for Video View Manager (Scrying Pool).
|
||||
+ *
|
||||
+ * This file is the wiring diagram ONLY. It imports all modules, constructs them
|
||||
+ * with injected dependencies, and holds NO business logic.
|
||||
+ *
|
||||
+ * Initialisation order:
|
||||
+ * Hooks.once('init') → register world settings → construct FoundryAdapter
|
||||
+ * → StateStore → SocketHandler (queue+drain)
|
||||
+ * Hooks.once('ready') → VisibilityManager → SocketHandler.setReady()
|
||||
+ * → NotificationBus → RoleRenderer → RosterStrip
|
||||
+ * → DirectorsBoard (lazy, GM only)
|
||||
+ */
|
||||
+
|
||||
+Hooks.once("init", () => {
|
||||
+ console.log("[ScryingPool] init — module loading");
|
||||
+ // Story 1.3+: register world settings, construct FoundryAdapter, StateStore, SocketHandler
|
||||
+});
|
||||
+
|
||||
+Hooks.once("ready", () => {
|
||||
+ console.log("[ScryingPool] ready — module active");
|
||||
+ // Story 1.3+: construct VisibilityManager, NotificationBus, RoleRenderer, RosterStrip
|
||||
+ // Story 1.5+: register DirectorsBoard (lazy, GM only)
|
||||
+});
|
||||
diff --git a/module.json b/module.json
|
||||
new file mode 100644
|
||||
index 0000000..e1cffdc
|
||||
--- /dev/null
|
||||
+++ b/module.json
|
||||
@@ -0,0 +1,29 @@
|
||||
+{
|
||||
+ "id": "video-view-manager",
|
||||
+ "title": "Video View Manager (Scrying Pool)",
|
||||
+ "version": "0.1.0",
|
||||
+ "description": "GM camera visibility control for FoundryVTT v14 — hide, show, and manage participant feeds in real time.",
|
||||
+ "authors": [
|
||||
+ {
|
||||
+ "name": "Morr"
|
||||
+ }
|
||||
+ ],
|
||||
+ "compatibility": {
|
||||
+ "minimum": "14",
|
||||
+ "verified": "14"
|
||||
+ },
|
||||
+ "esmodules": [
|
||||
+ "module.js"
|
||||
+ ],
|
||||
+ "styles": [
|
||||
+ "dist/styles/scrying-pool.css"
|
||||
+ ],
|
||||
+ "languages": [
|
||||
+ {
|
||||
+ "lang": "en",
|
||||
+ "name": "English",
|
||||
+ "path": "lang/en.json"
|
||||
+ }
|
||||
+ ],
|
||||
+ "flags": {}
|
||||
+}
|
||||
diff --git a/package.json b/package.json
|
||||
new file mode 100644
|
||||
index 0000000..fab7015
|
||||
--- /dev/null
|
||||
+++ b/package.json
|
||||
@@ -0,0 +1,26 @@
|
||||
+{
|
||||
+ "name": "video-view-manager",
|
||||
+ "version": "0.1.0",
|
||||
+ "description": "FoundryVTT v14 module — Scrying Pool camera visibility control",
|
||||
+ "type": "module",
|
||||
+ "scripts": {
|
||||
+ "build": "lessc styles/scrying-pool.less dist/styles/scrying-pool.css",
|
||||
+ "watch": "chokidar 'styles/**/*.less' -c 'lessc styles/scrying-pool.less dist/styles/scrying-pool.css'",
|
||||
+ "typecheck": "tsc --noEmit",
|
||||
+ "lint": "eslint src/ module.js",
|
||||
+ "test": "vitest run",
|
||||
+ "test:watch": "vitest",
|
||||
+ "release": "node scripts/package.mjs"
|
||||
+ },
|
||||
+ "devDependencies": {
|
||||
+ "@types/node": "^22.0.0",
|
||||
+ "chokidar": "5.0.0",
|
||||
+ "eslint": "^9.0.0",
|
||||
+ "eslint-plugin-import": "^2.31.0",
|
||||
+ "eslint-plugin-jsdoc": "^50.0.0",
|
||||
+ "happy-dom": "^20.0.0",
|
||||
+ "less": "4.6.4",
|
||||
+ "typescript": "5.9.3",
|
||||
+ "vitest": "2.1.8"
|
||||
+ }
|
||||
+}
|
||||
diff --git a/scripts/package.mjs b/scripts/package.mjs
|
||||
new file mode 100644
|
||||
index 0000000..9a7300e
|
||||
--- /dev/null
|
||||
+++ b/scripts/package.mjs
|
||||
@@ -0,0 +1,60 @@
|
||||
+/**
|
||||
+ * Release script — produces module.zip.
|
||||
+ *
|
||||
+ * Single version source of truth: reads version from package.json,
|
||||
+ * writes it into module.json, then zips all release artefacts.
|
||||
+ *
|
||||
+ * Usage: node scripts/package.mjs
|
||||
+ */
|
||||
+
|
||||
+import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
|
||||
+import { resolve, dirname } from "path";
|
||||
+import { fileURLToPath } from "url";
|
||||
+import { createGzip } from "zlib";
|
||||
+import { exec } from "child_process";
|
||||
+import { promisify } from "util";
|
||||
+
|
||||
+const execAsync = promisify(exec);
|
||||
+const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
+const ROOT = resolve(__dirname, "..");
|
||||
+
|
||||
+// Read version from package.json (single source of truth)
|
||||
+const pkg = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8"));
|
||||
+const { version } = pkg;
|
||||
+
|
||||
+// Write version into module.json
|
||||
+const moduleJsonPath = resolve(ROOT, "module.json");
|
||||
+const moduleJson = JSON.parse(readFileSync(moduleJsonPath, "utf8"));
|
||||
+moduleJson.version = version;
|
||||
+writeFileSync(moduleJsonPath, JSON.stringify(moduleJson, null, 2) + "\n", "utf8");
|
||||
+console.log(`[ScryingPool] module.json version set to ${version}`);
|
||||
+
|
||||
+// Ensure dist/ exists (build should have run first)
|
||||
+if (!existsSync(resolve(ROOT, "dist"))) {
|
||||
+ console.error("[ScryingPool] dist/ not found — run npm run build first");
|
||||
+ process.exit(1);
|
||||
+}
|
||||
+
|
||||
+// Files and directories to include in module.zip
|
||||
+const INCLUDE = [
|
||||
+ "module.json",
|
||||
+ "module.js",
|
||||
+ "lang/",
|
||||
+ "templates/",
|
||||
+ "dist/",
|
||||
+ "src/",
|
||||
+];
|
||||
+
|
||||
+// Build zip using system zip command
|
||||
+const targets = INCLUDE.filter((f) => existsSync(resolve(ROOT, f)));
|
||||
+const zipArgs = targets.map((t) => `"${t}"`).join(" ");
|
||||
+const zipCmd = `cd "${ROOT}" && zip -r module.zip ${zipArgs}`;
|
||||
+
|
||||
+console.log("[ScryingPool] Creating module.zip...");
|
||||
+try {
|
||||
+ await execAsync(zipCmd);
|
||||
+ console.log(`[ScryingPool] module.zip created (v${version})`);
|
||||
+} catch (err) {
|
||||
+ console.error("[ScryingPool] zip failed:", err instanceof Error ? err.message : String(err));
|
||||
+ process.exit(1);
|
||||
+}
|
||||
diff --git a/tsconfig.json b/tsconfig.json
|
||||
new file mode 100644
|
||||
index 0000000..7d64af8
|
||||
--- /dev/null
|
||||
+++ b/tsconfig.json
|
||||
@@ -0,0 +1,14 @@
|
||||
+{
|
||||
+ "compilerOptions": {
|
||||
+ "checkJs": true,
|
||||
+ "strict": true,
|
||||
+ "noEmit": true,
|
||||
+ "target": "ESNext",
|
||||
+ "module": "ESNext",
|
||||
+ "moduleResolution": "bundler",
|
||||
+ "allowJs": true,
|
||||
+ "lib": ["ESNext", "DOM"]
|
||||
+ },
|
||||
+ "include": ["src/**/*.js", "src/**/*.d.ts", "module.js", "scripts/**/*.mjs", "tests/**/*.js"],
|
||||
+ "exclude": ["node_modules", "dist"]
|
||||
+}
|
||||
diff --git a/vitest.config.js b/vitest.config.js
|
||||
new file mode 100644
|
||||
index 0000000..c18efc0
|
||||
--- /dev/null
|
||||
+++ b/vitest.config.js
|
||||
@@ -0,0 +1,23 @@
|
||||
+import { defineConfig } from "vitest/config";
|
||||
+
|
||||
+export default defineConfig({
|
||||
+ test: {
|
||||
+ environment: "happy-dom",
|
||||
+ globals: false,
|
||||
+ include: ["tests/**/*.test.js"],
|
||||
+ coverage: {
|
||||
+ provider: "v8",
|
||||
+ reporter: ["text", "lcov"],
|
||||
+ include: ["src/**/*.js"],
|
||||
+ exclude: ["src/contracts/**"],
|
||||
+ },
|
||||
+ },
|
||||
+ resolve: {
|
||||
+ alias: {
|
||||
+ "@src": "/src",
|
||||
+ "@contracts": "/src/contracts",
|
||||
+ "@utils": "/src/utils",
|
||||
+ "@tests": "/tests",
|
||||
+ },
|
||||
+ },
|
||||
+});
|
||||
@@ -0,0 +1,23 @@
|
||||
# Deferred Work
|
||||
|
||||
## Deferred from: code review of 1-1-module-scaffold-cicd-pipeline-and-design-token-system (2026-05-21)
|
||||
|
||||
- [ ] Vulnerable dependency CVE-2023-43645 — flat-cache-4.0.1 (needs verification)
|
||||
- [ ] Version conflicts — Multiple versions: make-dir (5.7.2, 6.3.1, 7.8.0), debug (4.4.3, 3.2.7) (npm resolution, pre-existing)
|
||||
|
||||
## Deferred from: Group 6 (Tests) - 2026-05-21
|
||||
|
||||
- [ ] MAX_PAYLOAD_BYTES size boundary test — Story 1.2+ SocketHandler responsibility (EC-001)
|
||||
- [ ] Multi-track stream test — Story 1.2+ WebRTC surface (EC-010)
|
||||
- [ ] Invalid snapshot fixtures (wrong version, null version) — Story 1.3+ StateStore (EC-012)
|
||||
- [ ] Circular reference in gameWebrtc handling — Story 1.2+ WebRTC probe (EC-020)
|
||||
|
||||
## Deferred from: Group 7 (CI/CD & i18n) - 2026-05-21
|
||||
|
||||
- [ ] Missing failure notifications — Story 1.2+ (EC-002)
|
||||
- [ ] Missing build artifact upload — Story 1.2+ (EC-006)
|
||||
- [ ] No Node.js matrix testing — Story 1.2+ (EC-004)
|
||||
- [ ] Missing concurrency control — Story 1.2+ (EC-008)
|
||||
- [ ] Missing i18n schema validation — Story 1.2+ (EC-I18N-003)
|
||||
- [ ] ubuntu-latest not pinned — Story 1.2+ (EC-003)
|
||||
- [ ] Missing coverage upload — Story 1.2+ (EC-005)
|
||||
@@ -0,0 +1,73 @@
|
||||
# generated: 2026-05-21T01:00:00+02:00
|
||||
# last_updated: 2026-05-21T01:00:00+02:00
|
||||
# project: video-view-manager
|
||||
# project_key: NOKEY
|
||||
# tracking_system: file-system
|
||||
# story_location: _bmad-output/implementation-artifacts
|
||||
|
||||
# STATUS DEFINITIONS:
|
||||
# ==================
|
||||
# Epic Status:
|
||||
# - backlog: Epic not yet started
|
||||
# - in-progress: Epic actively being worked on
|
||||
# - done: All stories in epic completed
|
||||
#
|
||||
# Epic Status Transitions:
|
||||
# - backlog → in-progress: Automatically when first story is created (via create-story)
|
||||
# - in-progress → done: Manually when all stories reach 'done' status
|
||||
#
|
||||
# Story Status:
|
||||
# - backlog: Story only exists in epic file
|
||||
# - ready-for-dev: Story file created in stories folder
|
||||
# - in-progress: Developer actively working on implementation
|
||||
# - review: Ready for code review (via Dev's code-review workflow)
|
||||
# - done: Story completed
|
||||
#
|
||||
# Retrospective Status:
|
||||
# - optional: Can be completed but not required
|
||||
# - done: Retrospective has been completed
|
||||
#
|
||||
# WORKFLOW NOTES:
|
||||
# ===============
|
||||
# - Epic transitions to 'in-progress' automatically when first story is created
|
||||
# - Stories can be worked in parallel if team capacity allows
|
||||
# - Developer typically creates next story after previous one is 'done' to incorporate learnings
|
||||
# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
|
||||
|
||||
generated: "2026-05-21T01:00:00+02:00"
|
||||
last_updated: "2026-05-22T00:00:00+02:00"
|
||||
project: video-view-manager
|
||||
project_key: NOKEY
|
||||
tracking_system: file-system
|
||||
story_location: _bmad-output/implementation-artifacts
|
||||
|
||||
development_status:
|
||||
# Epic 1: Core Camera Visibility Control
|
||||
epic-1: in-progress
|
||||
1-1-module-scaffold-cicd-pipeline-and-design-token-system: done
|
||||
1-2-webrtc-spike-track-disabling-api-validation: done
|
||||
1-3-data-layer-foundryadapter-statestore-and-socket-infrastructure: backlog
|
||||
1-4-core-logic-scryingpoolcontroller-and-visibilitymanager: backlog
|
||||
1-5-gm-control-ui-scryingpoolstrip-actionpopover-and-av-tile-integration: backlog
|
||||
1-6-player-camera-status-badge: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
# Epic 2: Player Notifications & Director's Board
|
||||
epic-2: backlog
|
||||
2-1-notificationbus-and-notification-verbosity: backlog
|
||||
2-2-directors-board-core-layout-and-participant-toggle: backlog
|
||||
2-3-directors-board-bulk-actions-spotlight-and-keyboard-shortcuts: backlog
|
||||
epic-2-retrospective: optional
|
||||
|
||||
# Epic 3: Scene-Aware Camera Automation (Scene Presets)
|
||||
epic-3: backlog
|
||||
3-1-save-and-load-scene-presets: backlog
|
||||
3-2-scene-auto-apply-and-confirmationbar: backlog
|
||||
3-3-preset-import-and-export: backlog
|
||||
epic-3-retrospective: optional
|
||||
|
||||
# Epic 4: Player Privacy Panel
|
||||
epic-4: backlog
|
||||
4-1-player-privacy-panel-and-automation-opt-ins: backlog
|
||||
4-2-custom-portrait-fallback: backlog
|
||||
epic-4-retrospective: optional
|
||||
File diff suppressed because it is too large
Load Diff
+32
@@ -0,0 +1,32 @@
|
||||
# Decision Log — Video View Manager Product Brief
|
||||
|
||||
## Session: 2026-05-19
|
||||
|
||||
### Decisions Captured
|
||||
|
||||
| # | Decision | Rationale | Source |
|
||||
|---|---|---|---|
|
||||
| 1 | Module is free / open source | User confirmed | User input |
|
||||
| 2 | Target platform: FoundryVTT v14 | User confirmed | User input |
|
||||
| 3 | North star feature: GM one-click cam toggle | Confirmed and anchored by user at end of brainstorming | Brainstorming session |
|
||||
| 4 | Progressive Enhancement as architecture (L1→L2→L3) | Emerged from SCAMPER-Eliminate; user confirmed | Brainstorming session |
|
||||
| 5 | Dedicated popout for seating chart (not sidebar) | User explicitly chose popout — "we will not do this frequently" | User input |
|
||||
| 6 | Reaction cam is opt-in at character setup | Resolved Marcus/Sofia privacy tension | User confirmed during Role Playing |
|
||||
| 7 | v1.0 scope = right-click toggle only | User reanchored to core feature; all else is additive | User input |
|
||||
| 8 | Brief purpose: FoundryVTT community pitch | User selected option [2] | User input |
|
||||
| 9 | Display name assumed as "Video View Manager" | User did not specify; derived from package ID | [ASSUMPTION] — confirm or override |
|
||||
| 10 | No known competitor modules | User described current state as "complex and not flexible" with no named alternatives | User input — [ASSUMPTION] worth validating |
|
||||
|
||||
### Open Questions
|
||||
- [ ] Confirm display/community name for the module
|
||||
- [ ] Validate: any existing FoundryVTT v14 modules that offer per-player cam visibility control?
|
||||
- [ ] Technical constraint: does FoundryVTT v14 WebRTC API support real track disabling, or is it CSS-only? This affects architecture of the core toggle.
|
||||
|
||||
| 11 | Module display name: **Scrying Pool** | User selected from proposed names; thematic, memorable, GM-perspective | User input |
|
||||
| 12 | Assumption #9 resolved: display name confirmed as "Scrying Pool" | See decision #11 | User input |
|
||||
| 13 | Assumption #10 resolved: no competitor modules confirmed | Exhaustive research of FoundryVTT registry + GitHub found zero per-player GM webcam visibility modules | Research agent |
|
||||
| 14 | Key adjacent modules noted: LiveKit (local-only hide), Camera Dock (layout only), OBS Utils (map viewport), Better Cams (CSS only) | Differentiation is confirmed genuine | Research agent |
|
||||
| 15 | Technical note: FoundryVTT native AVMaster exposes `canUserShareVideo()` and per-user `hidden` flag — but self-controlled only. GM writing to another user's setting is unexploited by any existing module. Core toggle is technically feasible. | Confirms architectural approach | Research agent |
|
||||
|
||||
## Finalized: 2026-05-19
|
||||
Doc standards applied (structural + prose). Status set to final.
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: "Product Brief: Scrying Pool"
|
||||
status: final
|
||||
created: 2026-05-19
|
||||
updated: 2026-05-19
|
||||
---
|
||||
|
||||
# Product Brief: Scrying Pool
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Scrying Pool is a free, open-source FoundryVTT v14 module that gives the GM direct control over player webcam visibility. Instead of Foundry's all-or-nothing AV behavior, the GM can show or hide individual camera feeds in one click without interrupting play.
|
||||
|
||||
The core promise is simple: **the GM can control any player's visible webcam feed at any time with minimal friction.** Everything else builds from that. At the lowest level, the module works from the existing camera tiles through a right-click menu. Over time, it grows into scene presets, spotlighting, and broader table-direction tools.
|
||||
|
||||
## The Problem
|
||||
|
||||
FoundryVTT's built-in AV support is too coarse for most online tables. Cameras are effectively either visible or not, with no practical way for the GM to manage visibility per player, per moment, or per scene.
|
||||
|
||||
That leaves GMs with bad options: tolerate a cluttered camera strip, run a second video tool beside Foundry, or stop using webcams altogether. The result is less table presence and less control over how the session feels.
|
||||
|
||||
The missing piece is not video support. It is video management.
|
||||
|
||||
## The Solution
|
||||
|
||||
Scrying Pool adds a GM-controlled visibility layer on top of FoundryVTT's existing AV system. The basic interaction is straightforward: right-click a player's camera tile and choose Show or Hide. The change applies immediately for all connected clients and persists across reconnects.
|
||||
|
||||
The module follows a progressive enhancement model:
|
||||
|
||||
- **Level 1 — Right-click controls.** No new interface, no setup barrier, immediate utility.
|
||||
- **Level 2 — Director's Board.** A compact control strip for quick live adjustments, plus scene-based presets.
|
||||
- **Level 3 — Table Manager.** A dedicated popout for bulk control, status visibility, and advanced preset handling.
|
||||
|
||||
That approach keeps v1 useful on its own while leaving room for deeper tooling later.
|
||||
|
||||
## What Makes This Different
|
||||
|
||||
- **It solves the exact missing control.** The GM manages individual webcam visibility directly from the interface they already use.
|
||||
- **It treats visibility as part of session direction.** Webcam layout becomes something the GM can prepare and apply by scene, not improvise mid-session.
|
||||
- **It respects player agency.** Privacy-sensitive features are opt-in by design, not patched in later.
|
||||
- **It fills a confirmed gap.** An exhaustive search of the FoundryVTT registry and GitHub found no module that provides GM-controlled per-player webcam visibility. Comparable modules address AV backends (LiveKit), layout changes (Camera Dock), map viewport streaming (OBS Utils), or cosmetics (Better Cams) — not visibility management.
|
||||
|
||||
## Who This Serves
|
||||
|
||||
**Primary — GMs running regular online campaigns.** They want fast control during play and predictable behavior that does not demand constant attention.
|
||||
|
||||
**Secondary — Privacy-conscious players.** They want clear expectations and protection against unwanted camera exposure.
|
||||
|
||||
**Tertiary — Actual-play streamers.** A curated broadcast view and advanced controls are on the roadmap, but not the first target.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A GM can hide or show any player's webcam in one click without disrupting the session.
|
||||
- Visibility state survives player disconnects and reconnects.
|
||||
- The v1 interaction is discoverable enough that most GMs can use it without documentation.
|
||||
- The module works reliably on FoundryVTT v14 and is maintainable enough for registry publication.
|
||||
|
||||
## Scope
|
||||
|
||||
**In for v1.0**
|
||||
- Per-player GM webcam toggle from the existing AV tile context menu
|
||||
- World-level persistence of visibility state
|
||||
- Socket-based updates so all clients stay in sync
|
||||
- Clear visual indicator for hidden tiles
|
||||
- Portrait fallback when no camera is available
|
||||
- Contextual toast notifications
|
||||
- FoundryVTT v14 compatibility
|
||||
|
||||
**Out for v1.0**
|
||||
- Director's Board
|
||||
- Table Manager popout
|
||||
- Scene-aware presets
|
||||
- Combat spotlighting
|
||||
- Player privacy preferences UI
|
||||
- Streaming or OBS-specific tooling
|
||||
- Token-anchored or stylized camera effects
|
||||
- NPC or reaction-driven camera systems
|
||||
|
||||
**Deferred pending validation**
|
||||
- True WebRTC track disabling rather than cosmetic hiding
|
||||
- Multi-GM support
|
||||
|
||||
## Vision
|
||||
|
||||
If v1.0 proves the core interaction is reliable, the next step is scene-aware presets and a lightweight Director's Board so GMs can set webcam visibility during prep and trust it during play. After that, privacy controls, spotlighting, and streaming support extend Scrying Pool into a broader table-direction tool.
|
||||
|
||||
The long-term goal is modest but useful: make webcam feeds feel like part of session design rather than a side effect of turning AV on.
|
||||
@@ -0,0 +1,894 @@
|
||||
---
|
||||
stepsCompleted: [1, 2, 3, 4]
|
||||
inputDocuments:
|
||||
- _bmad-output/planning-artifacts/prds/prd-video-view-manager-2026-05-19/prd.md
|
||||
- _bmad-output/planning-artifacts/architecture.md
|
||||
- _bmad-output/planning-artifacts/ux-design-specification.md
|
||||
---
|
||||
|
||||
# video-view-manager - Epic Breakdown
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides the complete epic and story breakdown for video-view-manager, decomposing the requirements from the PRD, UX Design, and Architecture into implementable stories.
|
||||
|
||||
## Requirements Inventory
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
FR-1: GM toggles Participant visibility via right-click context menu ("Hide from table" / "Show to table") on any AV Tile; sets target Participant's Visibility State to `hidden` or `active` for all Viewers; AV Tile indicator updates on all connected clients within 500 ms.
|
||||
|
||||
FR-2: All Visibility Matrix changes are broadcast to all connected clients in real time via FoundryVTT native socket API; new clients joining mid-session receive the current Visibility Matrix; state-change latency ≤500 ms on local network.
|
||||
|
||||
FR-3: Visibility Matrix state persists in world-level settings across page refreshes and full server restarts; a Participant who disconnects/reconnects returns to their previously set state; new Participants default to `active` on first connection.
|
||||
|
||||
FR-4: AV Tile visual indicator distinguishes all Participant States using plain-language labels and icons: `hidden` = grey overlay + lock icon + "Camera hidden by GM" tooltip; `self-muted` = camera-off icon; `offline` = disconnection icon; `cam-lost` = camera-error icon; `reconnecting` = spinner icon; all icons from FoundryVTT library, no external dependency.
|
||||
|
||||
FR-5: All eight Participant States (`active`, `hidden`, `self-muted`, `offline`, `cam-lost`, `reconnecting`, `never-connected`, `ghost`) render appropriate visual feedback without AV Tile reflow, layout shift, or disruption to other Participants' tiles.
|
||||
|
||||
FR-6: GM always sees all activated Participant feeds regardless of Visibility State (hidden tiles at reduced opacity + lock overlay); GM hears audio from all Participants; GM self-view in own interface configurable via module setting "Show my own feed to myself" (default: ON).
|
||||
|
||||
FR-7: WebRTC track disabling is the preferred implementation when the FoundryVTT v14 API allows programmatic track access (no inbound video bandwidth consumed for hidden feeds); CSS/DOM cosmetic hiding is the fallback; a world setting reports the active mode.
|
||||
|
||||
FR-8: Portrait Fallback displayed when Participant has no camera (`never-connected`) or enters `cam-lost` state; default is FoundryVTT user avatar falling back to system placeholder; renders at same dimensions as a live camera-feed tile; Participants can set custom Portrait Fallback via Player Privacy Panel (FR-26).
|
||||
|
||||
FR-9: GM opens Director's Board via a dedicated sidebar button and keyboard shortcut (default: `Ctrl+Shift+V`); Director's Board opens as a resizable, draggable `ApplicationV2` window; shortcut is configurable in module settings; opening does not change existing AV Tile strip.
|
||||
|
||||
FR-10: Director's Board displays full Visibility Matrix in a seating-chart layout; every Participant card shows name, portrait, current Participant State, and current Visibility State; Visibility State updates appear within 500 ms.
|
||||
|
||||
FR-11: Per-Participant visibility toggle from Director's Board with a single click on a Participant card; behavior and persistence match FR-1.
|
||||
|
||||
FR-12: Bulk actions "Show All" and "Hide All" in Director's Board; one-step Undo restores the Visibility Matrix immediately before the bulk action; Participants in `ghost` state excluded from bulk actions.
|
||||
|
||||
FR-13: Spotlight action shows exactly one Participant's feed and hides all others in a single action; stores current Visibility Matrix as pre-spotlight snapshot; single "Restore" action reverts to snapshot; distinct from manual Hide All + Show One.
|
||||
|
||||
FR-14: All primary Director's Board actions keyboard-accessible without a mouse: `Space`/`Enter` toggles focused Participant; arrow keys move focus between cards; `Ctrl+Shift+S` = Show All; `Ctrl+Shift+H` = Hide All; `Ctrl+Shift+P` = Spotlight focused Participant; `?` opens shortcut reference panel; all shortcuts configurable and documented.
|
||||
|
||||
FR-15: GM saves a named Scene Preset from the current Visibility Matrix (single action from Director's Board or module settings); preset captures full current matrix; names are editable and unique per world; up to 50 presets per world.
|
||||
|
||||
FR-16: GM loads a Scene Preset at any time, overriding the current Visibility Matrix; all clients receive state within 500 ms; loading generates notification "GM applied preset: [Preset Name]"; offline Participants receive stored state on reconnection.
|
||||
|
||||
FR-17: Scene Preset auto-applies on FoundryVTT Scene activation via `updateScene` hook; Scene-to-Preset association configured in Scene or module settings; configurable 0–5000 ms pre-delay; all clients receive "Scene changed: camera layout updated" notification.
|
||||
|
||||
FR-18: Scene Preset auto-apply can be disabled per-scene (without removing association) or globally via module settings; Director's Board always provides a manual override regardless of automation state.
|
||||
|
||||
FR-19: Preset import/export as JSON; export downloads all presets as one human-readable JSON file; import reads JSON and merges or replaces (user's choice); invalid JSON shows error; README documents exported format.
|
||||
|
||||
FR-20: Toast notification to all Participants when GM changes any Participant's Visibility State; message uses Participant display name ("GM hid [Name]'s camera" / "GM showed [Name]'s camera"); uses FoundryVTT native notification UI; affected Participant receives distinct personal notification.
|
||||
|
||||
FR-21: Notification verbosity configurable per user: `All` (default), `GM Only`, `Silent`; configuration stored in user-level client settings; `Silent` mode still shows personal notification to affected Participant — GM cannot suppress personal message.
|
||||
|
||||
FR-22: Persistent feed status badge on own AV Tile visible only to the owning Participant; shows "Live," "Hidden by GM," "Muted," or "No Camera"; updates within 500 ms when state changes.
|
||||
|
||||
FR-23: Player Privacy Panel accessible from module settings; lists every automation effect that can touch the owning user with current opt-in status; owning user can edit; GM can view but not edit another Participant's settings; settings persist in world-level user flags.
|
||||
|
||||
FR-24: Reaction Cam automation requires explicit Participant opt-in (default: off); Reaction Cam remains disabled until Participant enables it in Player Privacy Panel; Director's Board shows "Reaction Cam: Enabled" badge on opted-in cards; opt-in flag persists across sessions; all Reaction Cam triggers (Combat Cinematics Mode etc.) respect and skip opted-out Participants silently.
|
||||
|
||||
FR-25: HP-Reactive Cam Styling requires explicit Participant opt-in (default: off); disabled until Participant explicitly enables it; GM is not notified of individual styling opt-in statuses.
|
||||
|
||||
FR-26: Custom Portrait Fallback settable via file picker in Player Privacy Panel; accepted formats: PNG, JPG, WEBP, static GIF; falls back to FoundryVTT user avatar, then to system placeholder if no avatar exists.
|
||||
|
||||
### NonFunctional Requirements
|
||||
|
||||
NFR-1 (Compatibility): Module must not conflict with other popular FoundryVTT modules by patching shared DOM selectors or overriding core hooks without proper chaining; all hooks use `Hooks.on()` registration pattern, never `Hooks.once()` for persistent behavior.
|
||||
|
||||
NFR-2 (Performance): No Visibility Matrix operation blocks the FoundryVTT main render loop (state changes apply asynchronously); Director's Board renders and becomes interactive within 1 second with 12 Participants; socket message payload for a Visibility Matrix update ≤4 KB.
|
||||
|
||||
NFR-3 (Reliability): Socket broadcast retries up to 3 times on network interruption before surfacing an error notification; module fails gracefully when `game.webrtc` is unavailable (AV disabled) — all UI elements hidden or disabled, no uncaught errors thrown.
|
||||
|
||||
NFR-4 (Privacy): Module transmits no data outside the FoundryVTT world; no analytics, telemetry, or third-party calls; Participant names and portraits used only within the FoundryVTT session.
|
||||
|
||||
NFR-5 (Accessibility): All interactive elements in the Director's Board have ARIA labels and are keyboard navigable; state-indicator icons include tooltip text for screen-reader compatibility; WCAG AA contrast required for all state tokens against both Foundry dark and light themes; every state has a second signal beyond colour (icon, shape, or motion).
|
||||
|
||||
NFR-6 (Language / Voice): Default UI labels use plain language: "Show," "Hide," "Spotlight," "Hidden by GM," "No Camera"; technical or cinematic vocabulary reserved for documentation, tooltips in advanced mode, and developer-facing strings only; two-tier vocabulary applies to all present and future features.
|
||||
|
||||
NFR-7 (GM Override Guarantee): Every automation feature must expose an obvious one-click GM override accessible without opening configuration UI; Director's Board "Hide All" is the module's emergency path; no automation may be implemented if it cannot be interrupted or overridden immediately by the GM.
|
||||
|
||||
### Additional Requirements
|
||||
|
||||
- **Custom minimal scaffold (no external bundler/framework):** Vanilla JavaScript ES2022+ with native ESM; LESS 4.6.4 → CSS via chokidar watch; Handlebars `.hbs` templates (ApplicationV2 PARTS); no external UI libraries; no socketlib; Font Awesome 6 and Foundry CSS custom properties only.
|
||||
- **Story 0 scaffold deliverables (all are AC blockers):** `module.json` (v14 manifest), `tsconfig.json` (`checkJs+strict+noEmit`), `.eslintrc.js` (`jsdoc/require-jsdoc` on exported symbols; `import/no-restricted-paths` boundary enforcement), `vitest.config.js` (happy-dom environment), `scripts/package.mjs` (produces `module.zip`; single version source of truth), `tests/fixtures/socket-payloads.js` (socket payload contract tests), `.gitignore`, `styles/scrying-pool.less` (LESS entry point), `lang/en.json` (i18n skeleton).
|
||||
- **Dependency injection hard rule:** `StateStore`, `SocketHandler`, `VisibilityManager`, `RoleRenderer` MUST have zero direct `game.*` access; all Foundry API dependencies constructor-injected via `FoundryAdapter` interface (required for Vitest testability).
|
||||
- **FoundryAdapter surface contract:** `settings`, `socket`, `users`, `scenes`, `notifications`, `webrtc` (feature-detected; `null` if OQ-1 unresolvable), `hooks` — surfaces defined and injected at init time.
|
||||
- **Initialisation order:** `Hooks.once('init')` → register world settings → construct `FoundryAdapter` → `StateStore` → `SocketHandler` (queue+drain); `Hooks.once('ready')` → `VisibilityManager` → `SocketHandler.setReady()` → `NotificationBus` → `RoleRenderer` → `RosterStrip`/`ScryingPoolStrip` → `DirectorsBoard` (lazy, GM only).
|
||||
- **Data persistence:** Visibility Matrix → world setting `scrying-pool.visibilityMatrix` with `{ _version: 1, matrix: {...} }` wrapper; Scene Presets → Scene document flag `{ _version: 1, presets: {...} }`; notification verbosity → user-level client setting; `firstBadgeEncounter` → `game.user.setFlag('video-view-manager', 'firstBadgeEncounter')`.
|
||||
- **Socket reconciliation:** GM intent → `socket.emit(intent)` → all clients receive authoritative echo → GM clears `PendingOp`; 3s fallback timeout; retry-once before revert; stale ACK guard by `opId`/revision; `PendingOp` contract: `{ opId, userId, targetState, previousState, issuedAt, timeoutId }`.
|
||||
- **Contract files:** `src/contracts/visibility-matrix.js`, `src/contracts/socket-message.js`, `src/contracts/pending-op.js`, `src/contracts/scene-preset.js` — validated at send and receive.
|
||||
- **CI/CD:** Gitea workflows (`.gitea/workflows/`); lint + typecheck + test on every push; release via `scripts/package.mjs` → `module.zip`.
|
||||
- **OQ-1 architectural risk:** WebRTC track disabling API availability on v14 must be spiked before Level 1 is finalized; CSS fallback is the safe default until confirmed.
|
||||
- **World-vs-client persistence boundary:** Visibility Matrix and Presets → world settings; notification verbosity → client settings; `firstBadgeEncounter` → user flag; `StateStore` is the sole writer for in-memory state and sole caller of `adapter.settings.set()`.
|
||||
- **Naming/prefix conventions:** All world settings prefixed `scrying-pool.`; all socket events prefixed `scrying-pool.`; all CSS classes prefixed `.sp-` or scoped under `.scrying-pool`; public API "not found" returns `null`, never `undefined`.
|
||||
|
||||
### UX Design Requirements
|
||||
|
||||
UX-DR1: Implement 3-tier design token architecture — Layer 1: SP semantic alias tokens (`--sp-surface`, `--sp-border`, `--sp-text-primary`, `--sp-text-secondary`, `--sp-accent`, `--sp-focus`) mapping to Foundry tokens with hardcoded fallbacks; Layer 2: SP Participant State tokens for all 8 states; Layer 3: SP Urgency Tier tokens (`--sp-urgency-director` cool/deliberate, `--sp-urgency-awareness` neutral, background operations = no toast ever); Layer 4: SP Motion tokens (`--sp-fade-hide`, `--sp-pulse-reconnecting`, `--sp-shimmer-degraded`, `--sp-toast-delay`).
|
||||
|
||||
UX-DR2: All module CSS scoped under `.scrying-pool` namespace; no bare `button`, `a`, `input` selectors; forbidden to use Foundry `--color-*`/`--font-*`/`--border-*` tokens directly inside module CSS — always aliased through `--sp-*` layer; linting convention enforces this as the sole enforcement point for the semantic layer.
|
||||
|
||||
UX-DR3: Implement `StateRing` CSS primitive as the single ring implementation (no ad-hoc ring CSS anywhere else): `.sp-state-ring--solid`, `--dashed`, `--pending` (animated pulse in `no-preference`), `--revert` variants; all animations gated under `@media (prefers-reduced-motion: no-preference)`.
|
||||
|
||||
UX-DR4: Implement `ParticipantAvatar` component (44×44px container; 32px rounded avatar + `StateRing` + 12px corner badge bottom-right) with correct visual rendering for all 8 states + pending/revert; `role="button"`, `aria-label="[Name] — [state label]"`, `aria-pressed` when popover open; click → `StripOverlayLayer.openPopover()`; right-click → `ContextMenu`.
|
||||
|
||||
UX-DR5: Implement `ScryingPoolStrip` as floating `ApplicationV2` window: collapsed (avatar-only, 44px) ↔ expanded (rich rows, 240px) toggle via `.is-expanded` class + `max-width` transition (never `width` animation); `firstStripOpen` one-time onboarding tip; position/state persisted to GM User flag `{ left, top, open, expanded }`; `role="complementary"`, `aria-label="Scrying Pool"`.
|
||||
|
||||
UX-DR6: Implement `StripOverlayLayer` as single overlay container for all positioned overlays (`position: absolute; inset: 0; pointer-events: none; overflow: visible`); children restore `pointer-events: auto`; `ActionPopover` anchors via `getBoundingClientRect()` relative to strip; one-at-a-time popover enforcement via supersede pattern.
|
||||
|
||||
UX-DR7: Implement `ActionPopover` as native `<dialog>` anchored via `StripOverlayLayer`; primary CTA "Hide from table" / "Show to table"; primary CTA `disabled` + `aria-disabled="true"` during `pending`; Esc / click-outside dismiss; `aria-labelledby` → participant name h3; focus → primary CTA on open.
|
||||
|
||||
UX-DR8: Implement `AVTileAdapter` for all Foundry AV tile DOM interaction: idempotent `mount(userId, badgeElement)`, `unmount(userId)`, `onTileRerender(userId, callback)` with scoped `MutationObserver`; no-op + `console.warn` if tile not found (fail-open); `disconnect()` on module teardown.
|
||||
|
||||
UX-DR9: Implement `VisibilityBadge` injection into AV tile DOM via `AVTileAdapter`; `role="status"`, `aria-live="polite"`, `aria-label="Camera visibility: [state label]"`; tokens on `:root` (badge is mounted outside `.scrying-pool` root); `firstBadgeEncounter` stored as user flag; check for existing badge before injecting — update in place; remove-and-reinsert only if structure requires full rebuild.
|
||||
|
||||
UX-DR10: Implement `FirstEncounterPanel` with 10s auto-collapse timer, `mouseenter`/`:focus-within` timer pause, "Got it" dismiss (sets `firstBadgeEncounter`), `max-height` fold 300ms ease-out collapse animation, panel→chip transition post-collapse; `aria-modal="false"`, `role="dialog"`, not a focus trap; `clearTimeout` on "Got it", click, and `_onClose()` teardown.
|
||||
|
||||
UX-DR11: Implement `VisibilityDetailsPanel` with actor ("Hidden by: [GM name]" / "Connection issue" / "Scene preset: [name]"), action, audience (list suppressed when hidden — show reassurance copy instead), note, reassurance sections; focus trap; `aria-modal="true"`, `<dialog>`; Esc + click-outside + "Close" dismiss; stale-data indicator when controller unavailable.
|
||||
|
||||
UX-DR12: Implement `ConfirmationBar` in `StripOverlayLayer` (`position: absolute; bottom: 0`): "Preset applied — N hidden, N visible" with amber variant for partial fail; "Undo" primary affordance; 8s auto-dismiss (4s if ≥2 presets applied within 60s); `opacity` transition only — never `height`/`max-height`; instant-replace rule (zero crossfade); `clearTimeout` on click, strip close, and `_onClose()` teardown.
|
||||
|
||||
UX-DR13: Implement `ParticipantCard` (80×100px; 48px avatar + `StateRing` + name 12px 2-line truncate + hover toggle-icon overlay) for Director's Board grid; states: `default` | `hover` | `pending` | `revert`; `role="listitem"`, `aria-label="[Name] — [state label]"`; hover toggle icon is keyboard-focusable `role="button"`.
|
||||
|
||||
UX-DR14: Implement `DirectorBoard` as `ApplicationV2`: CSS grid `auto-fill, minmax(80px, 1fr)` of `ParticipantCard` components; footer with "Save Preset…" / "Load Preset…"; dumb view subscribing to `ScryingPoolController` events — no local state cache; shortcut `Ctrl+Shift+V` to open/close.
|
||||
|
||||
UX-DR15: Implement `NotificationBus` coalescing layer above `ui.notifications`: `Map<participantId, {timer, lastState, changeCount}>`; 3s quiet period before coalesced notification fires; suppresses notification entirely if net state = original state; reports final state + change count in message.
|
||||
|
||||
UX-DR16: Implement `ScryingPoolController` as module-singleton (constructed at `Hooks.once("ready")`): owns `visibilityMatrix: Map<participantId, Map<viewerId, VisibilityState>>` and `pendingOps: Map<participantId, {opId, targetState, baseRevision}>`; `action(source, participantId, targetState, opId, baseRevision)` method; latest-revision-wins guard; per-participant last-intent guard; emits change events for Strip and Board to consume; manages retry policy and revert notifications.
|
||||
|
||||
UX-DR17: Implement player-facing vocabulary partition — player labels use human-readable copy; GM UI uses technical state names; `VisibilityBadge` and `VisibilityDetailsPanel` MUST use the player label table: `hidden`→"Hidden from table", `self-muted`→"Camera paused", `offline`→"Not connected", `cam-lost`→"Camera unavailable", `reconnecting`→"Rejoining view", `never-connected`→"Not yet connected", `ghost`→"Leaving", `active`→no label shown.
|
||||
|
||||
UX-DR18: Implement `EmptyStatePanel` with slow breathing/pulse animation on eye icon (reduced motion: static); "No participants yet" header with anticipatory copy; optional "Learn how visibility works" link; low-noise centred layout — not styled as an error or broken state.
|
||||
|
||||
UX-DR19: Implement 4-tier feedback pattern strictly: (1) ambient ring/badge = stable state; (2) optimistic pending ring pulse = op in flight; (3) `ConfirmationBar` = preset/bulk-op strip-local feedback; (4) `ui.notifications` = failure/revert only. No `ui.notifications` toast on success. Revert sequence: amber ring flash (200ms) → `ui.notifications.warn()` — ring fires first. SP overlays suspended when `ui.activeWindow` is a Foundry `Dialog`; queue ops and show confirmation immediately on dialog close.
|
||||
|
||||
UX-DR20: WCAG AA colour contrast required for all 8 participant state colour tokens against both Foundry dark and light themes; every state has a second signal beyond colour (icon, shape, or motion); `hidden`, `offline`, `never-connected`, `ghost` tokens MUST NOT appear as text or small-pill foreground only.
|
||||
|
||||
UX-DR21: Canonical action label rule — "Hide from table" and "Show to table" verbatim on every interaction surface (strip hover rail, `ActionPopover`, Director's Board card, right-click context menu); same string constant, never synonyms; first-hover tooltip variant ("Hide this participant from other players.") sets `firstHideTooltip` flag and reverts to canonical label on subsequent hovers.
|
||||
|
||||
### FR Coverage Map
|
||||
|
||||
FR-1: Epic 1 — GM right-click toggle on AV Tile
|
||||
FR-2: Epic 1 — Real-time socket broadcast of Visibility Matrix changes
|
||||
FR-3: Epic 1 — Visibility Matrix persistence across refreshes and reconnects
|
||||
FR-4: Epic 1 — AV Tile visual state indicators for all Participant States
|
||||
FR-5: Epic 1 — Eight Participant States rendered without layout disruption
|
||||
FR-6: Epic 1 — GM always-visible view with configurable self-feed setting
|
||||
FR-7: Epic 1 — WebRTC track disabling with CSS fallback
|
||||
FR-8: Epic 1 — Portrait Fallback for no-camera participants
|
||||
FR-9: Epic 2 — Director's Board open via sidebar button + keyboard shortcut
|
||||
FR-10: Epic 2 — Director's Board full Visibility Matrix seating-chart layout
|
||||
FR-11: Epic 2 — Per-participant toggle from Director's Board
|
||||
FR-12: Epic 2 — Bulk Show All / Hide All with one-step Undo
|
||||
FR-13: Epic 2 — Spotlight action with pre-spotlight snapshot and Restore
|
||||
FR-14: Epic 2 — Full keyboard shortcuts for Director's Board actions
|
||||
FR-15: Epic 3 — Save named Scene Preset from current Visibility Matrix
|
||||
FR-16: Epic 3 — Load Scene Preset at any time
|
||||
FR-17: Epic 3 — Scene Preset auto-applies on Scene activation
|
||||
FR-18: Epic 3 — Disable auto-apply per-scene or globally
|
||||
FR-19: Epic 3 — Preset import/export as JSON
|
||||
FR-20: Epic 2 — Toast notification to all participants on GM visibility change
|
||||
FR-21: Epic 2 — Notification verbosity configuration per user
|
||||
FR-22: Epic 1 — Persistent self-status badge on own AV Tile
|
||||
FR-23: Epic 4 — Player Privacy Panel accessible from module settings
|
||||
FR-24: Epic 4 — Opt-in to Reaction Cam automation
|
||||
FR-25: Epic 4 — Opt-in to HP-Reactive Cam Styling
|
||||
FR-26: Epic 4 — Custom Portrait Fallback via file picker
|
||||
|
||||
## Epic List
|
||||
|
||||
### Epic 1: Core Camera Visibility Control
|
||||
|
||||
The GM can install the module, hide or show any participant's camera in one click, and every connected viewer updates in real time. Players always see the current state of their own feed via a persistent badge — with a plain-language explanation on first encounter and on demand. This epic delivers the entire Level 1 experience: module scaffold, the WebRTC spike to validate the technical approach, the tested data layer, and all core UI components including the player-facing badge.
|
||||
|
||||
**FRs covered:** FR-1, FR-2, FR-3, FR-4, FR-5, FR-6, FR-7, FR-8, FR-22
|
||||
**Architecture requirements:** All scaffold Story 0 deliverables · WebRTC spike (OQ-1) · FoundryAdapter · StateStore · SocketHandler · contract files · CI/CD pipeline · design token system · ScryingPoolController singleton
|
||||
**UX components:** ScryingPoolStrip · ActionPopover · AVTileAdapter · StateRing · ParticipantAvatar · StripOverlayLayer · VisibilityBadge · FirstEncounterPanel · VisibilityDetailsPanel · EmptyStatePanel
|
||||
**Story sequence:** Story 0 (Scaffold + CI) → Story 1 (WebRTC Spike) → Story 2 (FoundryAdapter + StateStore + SocketHandler) → Story 3 (VisibilityManager + ScryingPoolStrip + ActionPopover) → Story 4 (VisibilityBadge + FirstEncounterPanel + VisibilityDetailsPanel + FR-22)
|
||||
|
||||
---
|
||||
|
||||
### Epic 2: Player Notifications & Director's Board
|
||||
|
||||
Players receive plain-language notifications whenever camera states change — no action is ever silent. The GM gets a dedicated floating board showing all participants in a seating-chart layout, with bulk Show All / Hide All, Spotlight, and full keyboard accessibility. The NotificationBus that powers toast delivery is built here and reused by all subsequent automation.
|
||||
|
||||
**FRs covered:** FR-9, FR-10, FR-11, FR-12, FR-13, FR-14, FR-20, FR-21
|
||||
**UX components:** NotificationBus · ParticipantCard · DirectorBoard
|
||||
**Note:** FR-20/21 (toast notifications + verbosity) grouped here because NotificationBus is the shared infrastructure for Director's Board actions and all future automation notifications, matching the architecture's impl-seq Story 3.
|
||||
|
||||
---
|
||||
|
||||
### Epic 3: Scene-Aware Camera Automation (Scene Presets)
|
||||
|
||||
The GM can save named camera configurations as Scene Presets and apply them — manually or automatically on Scene activation. Preset state is shared and persisted; presets can be exported and re-used across campaigns. The ConfirmationBar gives the GM immediate strip-local feedback with a single-click Undo after every preset apply.
|
||||
|
||||
**FRs covered:** FR-15, FR-16, FR-17, FR-18, FR-19
|
||||
**UX components:** ScenePresetManager · ConfirmationBar (full use)
|
||||
|
||||
---
|
||||
|
||||
### Epic 4: Player Privacy Panel
|
||||
|
||||
Players can opt in or out of any automation effect that touches their on-screen presence — Reaction Cam and HP-Reactive Cam Styling — without waiting for the GM. Players can also set a custom Portrait Fallback image. All consent flags persist across sessions. This epic scaffolds the per-player consent layer that all future automation features gate against.
|
||||
|
||||
**FRs covered:** FR-23, FR-24, FR-25, FR-26
|
||||
|
||||
---
|
||||
|
||||
<!-- Stories populated in Step 3 -->
|
||||
|
||||
## Epic 1: Core Camera Visibility Control
|
||||
|
||||
### Story 1.1: Module Scaffold, CI/CD Pipeline & Design Token System *(Technical Foundation)*
|
||||
|
||||
As a **developer**,
|
||||
I want a fully configured module scaffold with the complete `--sp-*` design token system, contract files, tooling, and CI,
|
||||
So that every subsequent story builds on enforced boundaries, verified tooling, and a stable design language.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the repository is checked out fresh
|
||||
**When** `npm install && npm run lint && npm run typecheck && npm run test` are executed
|
||||
**Then** all commands exit 0
|
||||
**And** `npm run build` produces `module.zip` containing `module.json`, `scripts/`, `styles/`, `templates/`, `lang/`
|
||||
|
||||
**Given** the module is installed in FoundryVTT v14
|
||||
**When** FoundryVTT loads
|
||||
**Then** the module activates with no console errors and `game.modules.get('video-view-manager').active === true`
|
||||
|
||||
**Given** a developer writes an exported function without a JSDoc comment
|
||||
**When** `npm run lint` runs
|
||||
**Then** `eslint` reports a `jsdoc/require-jsdoc` violation
|
||||
|
||||
**Given** a source file imports from a restricted layer
|
||||
**When** `npm run lint` runs
|
||||
**Then** `import/no-restricted-paths` reports a boundary violation
|
||||
|
||||
**Given** a Gitea push is made
|
||||
**When** the CI workflow runs
|
||||
**Then** lint, typecheck, and test all run; a failing test fails the workflow
|
||||
|
||||
**Given** a developer writes module CSS using a Foundry `--color-*`/`--font-*`/`--border-*` token directly inside `.scrying-pool` CSS
|
||||
**When** the linting convention is enforced
|
||||
**Then** a violation is reported — all Foundry tokens must be aliased through `--sp-*`
|
||||
|
||||
**Given** a developer renders any participant state
|
||||
**When** they look up the token system in `styles/scrying-pool.less`
|
||||
**Then** all three token layers are defined:
|
||||
- Layer 1: SP semantic aliases (`--sp-surface`, `--sp-border`, `--sp-text-primary`, `--sp-text-secondary`, `--sp-accent`, `--sp-focus`) mapping to Foundry tokens with hardcoded fallbacks
|
||||
- Layer 2: SP Participant State tokens for all 8 states (`active`, `hidden`, `self-muted`, `offline`, `cam-lost`, `reconnecting`, `never-connected`, `ghost`)
|
||||
- Layer 3: SP Urgency + Motion tokens (`--sp-urgency-director`, `--sp-urgency-awareness`, `--sp-fade-hide`, `--sp-pulse-reconnecting`, `--sp-shimmer-degraded`, `--sp-toast-delay`)
|
||||
**And** the `VisibilityBadge` `:root` exception is documented: badge tokens are declared on `:root` because the badge is mounted outside the `.scrying-pool` root
|
||||
**And** all animated token usages are gated under `@media (prefers-reduced-motion: no-preference)`
|
||||
|
||||
**Given** the 4 contract files exist
|
||||
**When** a story imports `src/contracts/visibility-matrix.js`
|
||||
**Then** it exports a canonical shape constant, a factory function (`createVisibilityMatrix()`), and a guard/validator function (`isValidVisibilityMatrix(data)`)
|
||||
**And** the same factory + validator pattern applies to `socket-message.js`, `pending-op.js`, `scene-preset.js`
|
||||
|
||||
**Deliverables:** `module.json` (v14 manifest), `tsconfig.json` (checkJs+strict+noEmit), `.eslintrc.js`, `vitest.config.js` (happy-dom), `scripts/package.mjs`, `tests/fixtures/socket-payloads.js` (stub only at this stage), `.gitignore`, `styles/scrying-pool.less` (full 3-layer token system), `lang/en.json` (i18n skeleton), `src/contracts/visibility-matrix.js`, `src/contracts/socket-message.js`, `src/contracts/pending-op.js`, `src/contracts/scene-preset.js`, `.gitea/workflows/ci.yml`
|
||||
|
||||
---
|
||||
|
||||
### Story 1.2: WebRTC Spike — Track Disabling API Validation *(Spike)*
|
||||
|
||||
As a **developer**,
|
||||
I want to determine the FoundryVTT v14 WebRTC API capability and freeze the `FoundryAdapter.webrtc` interface contract,
|
||||
So that Story 1.3 can implement against a stable interface without ambiguity.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** FoundryVTT v14 running with AV enabled
|
||||
**When** the spike code executes
|
||||
**Then** the result is exactly one of three documented outcomes:
|
||||
- `"track-disable"` — `track.enabled = false` confirmed on a remote inbound stream
|
||||
- `"css-fallback"` — programmatic track access unavailable; CSS/DOM hiding is sufficient
|
||||
- `"unsupported"` — neither WebRTC track API nor reliable CSS targeting is available
|
||||
**And** the decision is recorded as a code comment in `src/adapters/foundry-adapter.js` with the FoundryVTT version tested against
|
||||
|
||||
**Given** the spike outcome is determined
|
||||
**When** `src/adapters/foundry-adapter.js` is examined
|
||||
**Then** the `FoundryAdapter.webrtc` interface contract is frozen: either `{ disableTrack(userId): void, enableTrack(userId): void }` or `null`, with capability-probe documentation
|
||||
**And** `scrying-pool.webrtcMode` world setting is registered with an enum of `["track-disable", "css-fallback", "unsupported"]` and records the active outcome
|
||||
|
||||
**Given** outcome is `"track-disable"`
|
||||
**When** a participant is hidden
|
||||
**Then** the inbound track is disabled (no inbound video bandwidth consumed)
|
||||
|
||||
**Given** outcome is `"css-fallback"` or `"unsupported"`
|
||||
**When** a participant is hidden
|
||||
**Then** CSS/DOM hiding is applied (cosmetic only)
|
||||
|
||||
**Hard exit rule:** Story 1.3 must not start until this story has a merged result and `FoundryAdapter.webrtc` interface is frozen.
|
||||
|
||||
---
|
||||
|
||||
### Story 1.3: Data Layer — FoundryAdapter, StateStore & Socket Infrastructure
|
||||
|
||||
As a **GM**,
|
||||
I want camera visibility changes to persist and broadcast to all connected clients reliably,
|
||||
So that every participant's Foundry client always shows the correct camera state, even after page refreshes or mid-session joins.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the module initialises
|
||||
**When** `Hooks.once('init')` fires
|
||||
**Then** world settings (`scrying-pool.visibilityMatrix`, `scrying-pool.webrtcMode`, `scrying-pool.showGMSelfFeed`) are registered
|
||||
**And** `FoundryAdapter` is constructed (implementing the frozen interface from Story 1.2) and injected into `StateStore` and `SocketHandler`
|
||||
|
||||
**Given** `StateStore.setVisibility(participantId, targetState)` is called
|
||||
**When** the call completes
|
||||
**Then** the in-memory `visibilityMatrix` is updated
|
||||
**And** `adapter.settings.set('scrying-pool.visibilityMatrix', { _version: 1, matrix: {...} })` is called
|
||||
|
||||
**Given** `SocketHandler.emit(intent)` is called
|
||||
**When** the message is sent
|
||||
**Then** all connected clients receive the authoritative echo within 500ms on a local network
|
||||
|
||||
**Given** a client receives a socket message
|
||||
**When** the `opId` matches a known `PendingOp`
|
||||
**Then** the `PendingOp` is cleared and state is confirmed
|
||||
**And** if the message arrives after the 3s timeout it is discarded as stale
|
||||
|
||||
**Given** a socket broadcast is unacknowledged for 3 seconds
|
||||
**When** the timeout fires
|
||||
**Then** the module retries exactly once; if still unacknowledged: logs a warning and reverts pending state to `previousState`
|
||||
|
||||
**Given** a new client joins mid-session
|
||||
**When** `Hooks.once('ready')` fires for them
|
||||
**Then** `StateStore` is hydrated from world setting `scrying-pool.visibilityMatrix`
|
||||
|
||||
**Given** the page refreshes
|
||||
**When** the module re-initialises
|
||||
**Then** all participant states are restored from the persisted world setting
|
||||
|
||||
**Given** `game.webrtc` is null (AV disabled)
|
||||
**When** the module initialises
|
||||
**Then** `FoundryAdapter.webrtc` returns `null`, no errors are thrown, no code attempts webrtc access
|
||||
|
||||
**Unit test coverage — `tests/fixtures/socket-payloads.js` must define canonical fixtures for:**
|
||||
- Valid intent payload (`scrying-pool.*` prefix, `{ opId, userId, targetState, baseRevision }`)
|
||||
- Valid authoritative echo/ack payload
|
||||
- Stale ACK (opId not in pendingOps; revision mismatch)
|
||||
- Timeout + retry + revert sequence
|
||||
- Hydrated setting payload (`{ _version: 1, matrix: {...} }`)
|
||||
- Invalid/malformed payload (fails validator)
|
||||
**And** `StateStore`, `SocketHandler`, `FoundryAdapter` are all testable via Vitest with injected mocks (zero `game.*` access in any of these classes)
|
||||
|
||||
---
|
||||
|
||||
### Story 1.4: Core Logic — ScryingPoolController & VisibilityManager *(Headless)*
|
||||
|
||||
As a **developer**,
|
||||
I want the module's core orchestration logic to be independently tested without any UI,
|
||||
So that the GM control UI (Story 1.5) can be built against a stable, verified interface.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** `Hooks.once('ready')` fires
|
||||
**When** `ScryingPoolController` is constructed as the module singleton
|
||||
**Then** it owns `visibilityMatrix: Map<participantId, Map<viewerId, VisibilityState>>` and `pendingOps: Map<participantId, PendingOp>`
|
||||
**And** it subscribes to `SocketHandler` for authoritative echoes
|
||||
|
||||
**Given** `ScryingPoolController.action(source, participantId, targetState, opId, baseRevision)` is called
|
||||
**When** the call is processed
|
||||
**Then** a `PendingOp` is created in `pendingOps`
|
||||
**And** `StateStore.setVisibility()` is called
|
||||
**And** a change event is emitted for subscribers (Strip and Board)
|
||||
**And** the latest-revision-wins guard prevents stale updates
|
||||
**And** the per-participant last-intent guard ignores duplicate intent for the same state
|
||||
|
||||
**Given** `action()` is called by a non-GM user
|
||||
**When** the call is processed
|
||||
**Then** `game.user.isGM` is checked; non-GM callers receive a `console.warn` and the call is silently dropped
|
||||
|
||||
**Given** `VisibilityManager` is constructed after `ScryingPoolController`
|
||||
**When** a participant is hidden
|
||||
**Then** it applies the strategy from `scrying-pool.webrtcMode`: calls `FoundryAdapter.webrtc.disableTrack()` if `"track-disable"`, applies CSS hiding if `"css-fallback"` or `"unsupported"`
|
||||
**And** `SocketHandler.setReady()` is called after `VisibilityManager` initialises (respecting init order: `ready → VisibilityManager → SocketHandler.setReady()`)
|
||||
|
||||
**Given** `ScryingPoolController` emits a revert event (after retry exhaustion)
|
||||
**When** `VisibilityManager` receives it
|
||||
**Then** the participant's state reverts to `previousState`
|
||||
**And** `ui.notifications.warn()` fires with a human-readable message (revert = failure → tier-4 feedback only)
|
||||
**And** NO success notification fires for normal state changes
|
||||
|
||||
**Unit test coverage:** `ScryingPoolController` and `VisibilityManager` tested via Vitest with injected mocks; test cases cover: normal toggle, latest-revision-wins, last-intent guard, retry-then-revert, non-GM authorization rejection, `webrtcMode` strategy switching
|
||||
|
||||
---
|
||||
|
||||
### Story 1.5: GM Control UI — ScryingPoolStrip, ActionPopover & AV Tile Integration
|
||||
|
||||
As a **GM**,
|
||||
I want to right-click any participant's AV tile to show or hide their camera feed, and see all feed states at a glance in the ScryingPoolStrip,
|
||||
So that I can control what the table sees in a single interaction without disrupting the session.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the module is active and the user is GM
|
||||
**When** FoundryVTT's `ready` hook completes
|
||||
**Then** `ScryingPoolStrip` appears as a floating `ApplicationV2` window showing all connected participants
|
||||
**And** its position (`left`, `top`), open state, and expanded state persist to the GM's user flag `{ left, top, open, expanded }`
|
||||
|
||||
**Given** the ScryingPoolStrip is in collapsed state
|
||||
**When** the GM clicks the expand toggle
|
||||
**Then** the strip transitions via `max-width` CSS transition (never `width` animation): collapsed = 44px avatar-only rail; expanded = 240px rich rows
|
||||
|
||||
**Given** the strip renders participants
|
||||
**When** it displays each `ParticipantAvatar`
|
||||
**Then** each avatar is a 44×44px container with a 32px rounded avatar + `StateRing` + 12px corner badge at bottom-right
|
||||
**And** `StateRing` uses the correct variant per state: `--solid` (active/hidden/offline), `--dashed` (self-muted/cam-lost), `--pending` (animated pulse), `--revert` (amber flash 200ms on revert)
|
||||
**And** all `StateRing` animations are gated under `@media (prefers-reduced-motion: no-preference)`
|
||||
|
||||
**Given** a PendingOp is in-flight for a participant
|
||||
**When** the strip renders
|
||||
**Then** that participant's `StateRing` shows the `--pending` animated pulse
|
||||
**And** NO `ui.notifications` toast fires on successful state change (success uses ambient ring only — tier-1/2 feedback)
|
||||
|
||||
**Given** a GM right-clicks a participant's AV tile
|
||||
**When** the context menu appears
|
||||
**Then** the option reads exactly **"Hide from table"** (never a synonym)
|
||||
**And** selecting it calls `ScryingPoolController.action()` and transitions state to `hidden`
|
||||
|
||||
**Given** a GM clicks a participant in the ScryingPoolStrip
|
||||
**When** the `ActionPopover` opens
|
||||
**Then** it is a native `<dialog>` anchored via `StripOverlayLayer.getBoundingClientRect()` relative to the strip
|
||||
**And** the primary CTA reads exactly **"Hide from table"** or **"Show to table"**
|
||||
**And** the primary CTA is `disabled` + `aria-disabled="true"` while a `PendingOp` is in-flight
|
||||
**And** Esc / click-outside dismiss the popover and return focus to the triggering avatar
|
||||
**And** only one `ActionPopover` is open at a time (supersede pattern)
|
||||
|
||||
**Given** `StripOverlayLayer` is the parent for all positioned overlays
|
||||
**When** any overlay is positioned
|
||||
**Then** it is a child of the single `StripOverlayLayer` (`position: absolute; inset: 0; pointer-events: none; overflow: visible`); children restore `pointer-events: auto`
|
||||
|
||||
**Given** a visibility change is dispatched
|
||||
**When** the socket broadcast completes
|
||||
**Then** all clients' AV tiles update state indicators within 500ms
|
||||
**And** no AV tile layout shift or reflow occurs for any of the 8 participant states
|
||||
**And** `AVTileAdapter.mount(userId, element)` is idempotent — calling it twice does not duplicate elements
|
||||
|
||||
**Given** a participant is `hidden`
|
||||
**When** the GM views their AV tile
|
||||
**Then** it renders at reduced opacity with a lock overlay and "Camera hidden by GM" tooltip
|
||||
**And** the GM still hears that participant's audio
|
||||
|
||||
**Given** a participant has no camera (`never-connected` or `cam-lost`)
|
||||
**When** their tile renders
|
||||
**Then** Portrait Fallback (FoundryVTT user avatar → system placeholder) displays at AV tile dimensions with no layout shift
|
||||
|
||||
**Given** no participants are connected
|
||||
**When** the ScryingPoolStrip renders
|
||||
**Then** `EmptyStatePanel` shows "No participants yet" with a slow breathing-pulse eye icon (static under `prefers-reduced-motion`)
|
||||
**And** the panel is NOT styled as an error state
|
||||
|
||||
**Given** the GM opens module settings
|
||||
**When** they locate "Show my own feed to myself" (default ON)
|
||||
**Then** toggling it hides/shows the GM's self-view immediately without errors
|
||||
|
||||
**Given** `game.webrtc` is null (AV disabled)
|
||||
**When** the module loads
|
||||
**Then** `ScryingPoolStrip` is not rendered and no console errors appear
|
||||
|
||||
**Accessibility:**
|
||||
|
||||
**Given** a screen reader user navigates to a `ParticipantAvatar`
|
||||
**When** focus lands
|
||||
**Then** `role="button"`, `aria-label="[Name] — [state label]"` is announced
|
||||
**And** `aria-pressed` reflects popover-open state
|
||||
|
||||
**Given** a keyboard user opens an `ActionPopover`
|
||||
**When** it opens
|
||||
**Then** focus moves to the primary CTA
|
||||
**And** Tab/Shift+Tab cycles through popover controls only
|
||||
**And** Esc closes it and returns focus to the triggering avatar
|
||||
|
||||
**Given** `prefers-reduced-motion: reduce` is active
|
||||
**When** any animated state occurs
|
||||
**Then** all `StateRing` animations are fully suppressed; static icons provide state information
|
||||
|
||||
**Given** any participant state is rendered
|
||||
**When** it is visually displayed
|
||||
**Then** colour is never the only signal: each state also has a distinct icon, shape, or motion indicator
|
||||
**And** all state colour tokens meet WCAG AA contrast against both Foundry dark and light themes
|
||||
|
||||
**Given** a canonical action label appears on any surface
|
||||
**When** it is displayed
|
||||
**Then** it reads exactly "Hide from table" or "Show to table" (never synonyms)
|
||||
**And** on first hover a tooltip variant sets `firstHideTooltip` flag; subsequent hovers show only the canonical label
|
||||
|
||||
---
|
||||
|
||||
### Story 1.6: Player Camera Status Badge
|
||||
|
||||
As a **player**,
|
||||
I want to always see whether my own camera feed is visible to the table, and understand what it means on first encounter,
|
||||
So that I'm never confused or surveilled without knowing it.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a player is connected with AV enabled
|
||||
**When** the module is active
|
||||
**Then** a persistent `VisibilityBadge` appears on their own AV tile
|
||||
**And** the badge is visible only to the owning player (not to other players or the GM)
|
||||
**And** `role="status"`, `aria-live="polite"`, `aria-label="Camera visibility: [state label]"` are set
|
||||
**And** badge tokens are declared on `:root` (badge mounted outside `.scrying-pool` root, using `AVTileAdapter` from Story 1.5)
|
||||
|
||||
**Given** a player's state is anything other than `active`
|
||||
**When** the badge renders
|
||||
**Then** it shows the correct vocabulary-partition label: `hidden` → "Hidden from table", `self-muted` → "Camera paused", `offline` → "Not connected", `cam-lost` → "Camera unavailable", `reconnecting` → "Rejoining view", `never-connected` → "Not yet connected", `ghost` → "Leaving"; `active` → no label shown
|
||||
|
||||
**Given** the GM changes a player's visibility state
|
||||
**When** the socket broadcast completes
|
||||
**Then** the player's `VisibilityBadge` updates within 500ms
|
||||
|
||||
**Given** `firstBadgeEncounter` user flag is not set and a state change occurs
|
||||
**When** the badge updates
|
||||
**Then** `FirstEncounterPanel` appears with a plain-language explanation
|
||||
**And** a 10s auto-collapse timer starts
|
||||
**And** `mouseenter` or `:focus-within` on the panel pauses the timer (resumes on leave/blur)
|
||||
**And** "Got it" sets `firstBadgeEncounter` and immediately closes the panel
|
||||
**And** the panel is `aria-modal="false"`, `role="dialog"`, and is NOT a focus trap
|
||||
|
||||
**Given** the 10s timer expires without interaction
|
||||
**When** auto-collapse fires
|
||||
**Then** the panel collapses via `max-height` fold animation (300ms ease-out) into a persistent chip
|
||||
**And** the chip is focusable and keyboard-activatable, re-opening `VisibilityDetailsPanel` on activation
|
||||
**And** if focus is inside the panel when collapse fires, focus is moved to the chip
|
||||
**And** subsequent state changes do NOT re-show the panel (flag is permanently set)
|
||||
**And** `clearTimeout` is called on "Got it" click and on `_onClose()` teardown to prevent ghost timers
|
||||
|
||||
**Given** a player clicks their `VisibilityBadge` or the collapsed chip
|
||||
**When** `VisibilityDetailsPanel` opens
|
||||
**Then** it shows: who changed the state ("Hidden by: [GM name]" / "Connection issue" / "Scene preset: [name]"), what the state means in plain language, and a reassurance note
|
||||
**And** when state is `hidden`, the audience list is suppressed and replaced with reassurance copy: "Other players cannot see your feed"
|
||||
**And** a stale-data indicator appears when `ScryingPoolController` is unavailable
|
||||
**And** the panel is a focus-trapped `<dialog>` with `aria-modal="true"`
|
||||
**And** Esc, click-outside, or "Close" button dismisses it and returns focus to the triggering element
|
||||
|
||||
**Given** `AVTileAdapter.mount(userId, badgeElement)` is called and the AV tile DOM node is not found
|
||||
**When** the call executes
|
||||
**Then** the adapter no-ops and logs `console.warn` without throwing (fail-open)
|
||||
|
||||
**Given** Foundry re-renders the AV tile (detected via `MutationObserver`)
|
||||
**When** the re-render is detected
|
||||
**Then** the badge is updated in-place if possible; remove-and-reinsert only if structure requires full rebuild
|
||||
**And** `AVTileAdapter.disconnect()` is called on module teardown
|
||||
|
||||
## Epic 2: Player Notifications & Director's Board
|
||||
|
||||
### Story 2.1: NotificationBus & Notification Verbosity
|
||||
|
||||
As a **player**,
|
||||
I want to receive a plain-language notification whenever the GM changes my camera's visibility, and control how many notifications I see,
|
||||
So that I'm never left wondering what happened to my feed without being overwhelmed by alerts.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the GM changes a participant's visibility state
|
||||
**When** the socket broadcast is received by all clients
|
||||
**Then** a toast notification fires via `ui.notifications` reading "GM hid [Name]'s camera" or "GM showed [Name]'s camera"
|
||||
|
||||
**Given** the affected participant's own client
|
||||
**When** any visibility change is received
|
||||
**Then** they receive a distinct personal notification regardless of their verbosity setting
|
||||
**And** this personal message cannot be suppressed by the GM
|
||||
|
||||
**Given** the GM changes the same participant's state multiple times within 3 seconds
|
||||
**When** the `NotificationBus` coalescing timer fires
|
||||
**Then** a single coalesced notification fires reporting the final state and change count
|
||||
**And** if the net state equals the original state, no notification fires at all
|
||||
|
||||
**Given** a user's verbosity setting is `GM Only`
|
||||
**When** another participant's camera is changed
|
||||
**Then** only the GM and the affected participant receive a notification (other players see nothing)
|
||||
|
||||
**Given** a user's verbosity setting is `Silent`
|
||||
**When** any participant's camera is changed
|
||||
**Then** that user receives no notification unless they are the affected participant
|
||||
|
||||
**Given** a user changes their verbosity setting in module settings
|
||||
**When** the change is saved
|
||||
**Then** it persists to their client-level user setting and takes effect immediately
|
||||
|
||||
**Given** `Hooks.once('ready')` fires
|
||||
**When** `NotificationBus` is constructed
|
||||
**Then** it subscribes to `ScryingPoolController` change events and holds `Map<participantId, {timer, lastState, changeCount}>`
|
||||
|
||||
---
|
||||
|
||||
### Story 2.2: Director's Board — Core Layout & Participant Toggle
|
||||
|
||||
As a **GM**,
|
||||
I want a dedicated floating board showing all participants in a seating-chart layout with per-participant visibility toggle,
|
||||
So that I can manage all camera states at a glance without right-clicking individual AV tiles.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the module is active and the user is GM
|
||||
**When** the GM presses `Ctrl+Shift+V` or clicks the dedicated sidebar button
|
||||
**Then** the Director's Board opens as a resizable, draggable `ApplicationV2` window
|
||||
|
||||
**Given** the Director's Board is open
|
||||
**When** it renders
|
||||
**Then** every connected participant has a `ParticipantCard` (80×100px: 48px avatar + `StateRing` + name 12px 2-line truncate + hover toggle-icon overlay)
|
||||
**And** cards are laid out in a CSS grid: `auto-fill, minmax(80px, 1fr)`
|
||||
|
||||
**Given** a participant's state changes
|
||||
**When** the socket broadcast completes
|
||||
**Then** the Director's Board updates that participant's card within 500ms
|
||||
**And** the board is a dumb view — it subscribes to `ScryingPoolController` events with no local state cache
|
||||
|
||||
**Given** the GM clicks a participant card
|
||||
**When** the click is processed
|
||||
**Then** the participant's visibility toggles between `active` and `hidden`
|
||||
**And** the behaviour and persistence match FR-1 (same as AV tile right-click)
|
||||
|
||||
**Given** the GM uses keyboard navigation
|
||||
**When** arrow keys are pressed in the board
|
||||
**Then** focus moves between participant cards
|
||||
**And** `Space` or `Enter` toggles the focused participant's visibility
|
||||
|
||||
**Given** `Ctrl+Shift+V` is pressed while the board is open
|
||||
**When** the event fires
|
||||
**Then** the board closes
|
||||
|
||||
**Given** the user is not GM
|
||||
**When** they attempt to open the Director's Board
|
||||
**Then** the sidebar button is not shown and the keyboard shortcut has no effect
|
||||
|
||||
**Accessibility:**
|
||||
**Given** a screen reader user navigates to a `ParticipantCard`
|
||||
**When** focus lands
|
||||
**Then** `role="listitem"`, `aria-label="[Name] — [state label]"` is announced
|
||||
**And** the hover toggle icon is independently focusable with `role="button"` and a descriptive `aria-label`
|
||||
|
||||
---
|
||||
|
||||
### Story 2.3: Director's Board — Bulk Actions, Spotlight & Keyboard Shortcuts
|
||||
|
||||
As a **GM**,
|
||||
I want to show or hide all participants at once, spotlight a single feed, and undo these bulk actions instantly,
|
||||
So that I can execute camera arrangements in a single action without toggling participants one by one.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the Director's Board is open
|
||||
**When** the GM clicks "Show All"
|
||||
**Then** all participants' states are set to `active` (excluding `ghost`-state participants)
|
||||
**And** the action is broadcast to all clients
|
||||
|
||||
**Given** the Director's Board is open
|
||||
**When** the GM clicks "Hide All"
|
||||
**Then** all participants' states are set to `hidden` (excluding `ghost`-state participants)
|
||||
**And** the action is broadcast to all clients
|
||||
|
||||
**Given** the GM has just executed "Show All" or "Hide All"
|
||||
**When** the GM clicks "Undo"
|
||||
**Then** the Visibility Matrix is immediately restored to the state before the bulk action
|
||||
**And** no second undo is available (single-step undo only)
|
||||
|
||||
**Given** a participant card is focused
|
||||
**When** the GM presses `Ctrl+Shift+P`
|
||||
**Then** that participant's feed is shown and all others are hidden in a single action
|
||||
**And** the pre-spotlight Visibility Matrix is stored as a snapshot
|
||||
|
||||
**Given** Spotlight is active
|
||||
**When** the GM clicks "Restore"
|
||||
**Then** the Visibility Matrix reverts to the pre-spotlight snapshot
|
||||
**And** "Restore" is distinct from the bulk action Undo affordance
|
||||
|
||||
**Given** `Ctrl+Shift+S` or `Ctrl+Shift+H` is pressed
|
||||
**When** the event fires
|
||||
**Then** "Show All" or "Hide All" executes as if the button were clicked
|
||||
|
||||
**Given** the GM presses `?` in the Director's Board
|
||||
**When** the event fires
|
||||
**Then** a shortcut reference panel opens listing all keyboard shortcuts with their current bindings
|
||||
|
||||
**Given** the GM navigates to keyboard shortcut settings
|
||||
**When** they open module settings
|
||||
**Then** `Ctrl+Shift+V`, `Ctrl+Shift+S`, `Ctrl+Shift+H`, `Ctrl+Shift+P` are all configurable
|
||||
**And** the `?` panel reflects the currently configured bindings
|
||||
|
||||
## Epic 3: Scene-Aware Camera Automation (Scene Presets)
|
||||
|
||||
### Story 3.1: Save & Load Scene Presets
|
||||
|
||||
As a **GM**,
|
||||
I want to save the current camera layout as a named preset and load it at any time,
|
||||
So that I can instantly reproduce proven camera arrangements without reconfiguring them from scratch.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the Director's Board is open
|
||||
**When** the GM clicks "Save Preset…" in the board footer
|
||||
**Then** a prompt appears for a preset name
|
||||
**And** on confirmation, the current Visibility Matrix is captured and stored on the current Scene document flag `{ _version: 1, presets: {...} }`
|
||||
|
||||
**Given** a preset name already exists
|
||||
**When** the GM saves with the same name
|
||||
**Then** the GM is asked to confirm overwrite before the preset is replaced
|
||||
|
||||
**Given** the world already has 50 presets
|
||||
**When** the GM attempts to save a 51st
|
||||
**Then** an error message shows: "Maximum of 50 presets reached. Delete an existing preset to save a new one."
|
||||
|
||||
**Given** saved presets exist
|
||||
**When** the GM clicks "Load Preset…" in the Director's Board footer
|
||||
**Then** a list of available presets is shown
|
||||
**And** selecting one overwrites the current Visibility Matrix and broadcasts to all clients within 500ms
|
||||
|
||||
**Given** a preset is loaded
|
||||
**When** all clients receive the broadcast
|
||||
**Then** a notification fires: "GM applied preset: [Preset Name]" via `ui.notifications`
|
||||
|
||||
**Given** a participant is offline when a preset is loaded
|
||||
**When** they reconnect
|
||||
**Then** they receive the state from the loaded preset (not the previous live state)
|
||||
|
||||
**Given** the GM renames a preset
|
||||
**When** the new name conflicts with an existing preset
|
||||
**Then** an error is shown and the rename is rejected
|
||||
|
||||
---
|
||||
|
||||
### Story 3.2: Scene Auto-Apply & ConfirmationBar
|
||||
|
||||
As a **GM**,
|
||||
I want a Scene Preset to automatically apply when I activate a Scene, with immediate strip-local feedback and a one-click Undo,
|
||||
So that camera layouts change seamlessly with scene transitions without manual intervention.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a Scene has a preset association configured
|
||||
**When** the GM activates that Scene (triggering `updateScene` hook)
|
||||
**Then** the associated preset applies after the configured pre-delay (0–5000ms)
|
||||
**And** all clients receive "Scene changed: camera layout updated" via `ui.notifications`
|
||||
|
||||
**Given** auto-apply fires for a Scene
|
||||
**When** the Visibility Matrix update is broadcast
|
||||
**Then** the `ConfirmationBar` appears in `StripOverlayLayer` at `position: absolute; bottom: 0` showing "Preset applied — N hidden, N visible"
|
||||
**And** an "Undo" button is present
|
||||
|
||||
**Given** the "Undo" button is clicked
|
||||
**When** the click is processed
|
||||
**Then** the Visibility Matrix immediately reverts to the state before the preset was applied
|
||||
**And** all clients receive the reverted state
|
||||
|
||||
**Given** the `ConfirmationBar` is visible and idle
|
||||
**When** 8 seconds elapse (or 4 seconds if ≥2 presets applied within 60 seconds)
|
||||
**Then** the bar dismisses via `opacity` transition only (never `height` or `max-height` animation)
|
||||
|
||||
**Given** a second `ConfirmationBar` would appear while one is already visible
|
||||
**When** the second is triggered
|
||||
**Then** it instantly replaces the first with zero crossfade (instant-replace rule)
|
||||
|
||||
**Given** auto-apply is disabled for a specific Scene
|
||||
**When** that Scene is activated
|
||||
**Then** no preset applies and no automation notification fires
|
||||
**And** the Director's Board manual override remains fully functional
|
||||
|
||||
**Given** auto-apply is disabled globally in module settings
|
||||
**When** any Scene is activated
|
||||
**Then** no preset auto-applies regardless of Scene-level associations
|
||||
|
||||
**Given** a Scene has a pre-delay of N ms configured
|
||||
**When** the Scene activates
|
||||
**Then** the preset applies exactly N ms after the `updateScene` hook fires
|
||||
|
||||
**Given** the partial-fail case (some participants unreachable)
|
||||
**When** the `ConfirmationBar` renders
|
||||
**Then** it uses the amber variant: "Preset applied — N hidden, N visible (some updates pending)"
|
||||
|
||||
---
|
||||
|
||||
### Story 3.3: Preset Import & Export
|
||||
|
||||
As a **GM**,
|
||||
I want to export all Scene Presets as a JSON file and import them into another world or campaign,
|
||||
So that I can reuse proven camera arrangements across campaigns without re-entering them manually.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** the GM opens the Preset management UI
|
||||
**When** they click "Export Presets"
|
||||
**Then** a JSON file is downloaded containing all world presets in human-readable format
|
||||
**And** the exported file matches the format documented in the module README
|
||||
|
||||
**Given** the GM clicks "Import Presets" and selects a valid JSON file
|
||||
**When** the file is parsed
|
||||
**Then** the GM is prompted to choose: "Merge" (add new, keep existing) or "Replace" (overwrite all)
|
||||
|
||||
**Given** the GM selects "Merge"
|
||||
**When** the import is processed
|
||||
**Then** new presets from the file are added; existing presets with matching names are left unchanged
|
||||
**And** a success message shows how many presets were added
|
||||
|
||||
**Given** the GM selects "Replace"
|
||||
**When** the import is processed
|
||||
**Then** a confirmation dialog warns about data loss before proceeding
|
||||
**And** on confirmation, all existing presets are removed and replaced with the imported set
|
||||
|
||||
**Given** the imported file contains invalid JSON
|
||||
**When** parsing fails
|
||||
**Then** an error notification shows: "Import failed: invalid JSON format" and no changes are made
|
||||
|
||||
**Given** the imported JSON has an unrecognised schema version or missing required fields
|
||||
**When** validation fails
|
||||
**Then** an error notification shows with specific field details and no changes are made
|
||||
|
||||
## Epic 4: Player Privacy Panel
|
||||
|
||||
### Story 4.1: Player Privacy Panel & Automation Opt-ins
|
||||
|
||||
As a **player**,
|
||||
I want to see and control every automation effect that can change my on-screen presence, and opt in or out at any time,
|
||||
So that I'm never surprised by automatic camera behaviours I didn't agree to.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a player opens FoundryVTT module settings
|
||||
**When** they navigate to the privacy section
|
||||
**Then** the Player Privacy Panel is visible, listing all automation effects with their current opt-in status
|
||||
|
||||
**Given** the panel is open for their own user
|
||||
**When** the player views it
|
||||
**Then** "Reaction Cam" (default: off) and "HP-Reactive Cam Styling" (default: off) are listed with toggle controls
|
||||
|
||||
**Given** a player toggles "Reaction Cam" to enabled
|
||||
**When** the toggle is confirmed
|
||||
**Then** the opt-in flag persists in world-level user flags and takes effect for all future Reaction Cam triggers
|
||||
|
||||
**Given** "Reaction Cam" is disabled for a player
|
||||
**When** a Reaction Cam trigger fires
|
||||
**Then** that player is silently skipped — no notification, no error, no indication to the GM
|
||||
|
||||
**Given** "Reaction Cam" is enabled for a player
|
||||
**When** a Reaction Cam trigger fires
|
||||
**Then** the Director's Board shows a "Reaction Cam: Enabled" badge on that participant's card
|
||||
|
||||
**Given** the GM opens another player's Privacy Panel
|
||||
**When** viewing it
|
||||
**Then** all controls are visible (read-only) but disabled — no editing is possible
|
||||
|
||||
**Given** a player toggles "HP-Reactive Cam Styling" to enabled
|
||||
**When** the toggle is confirmed
|
||||
**Then** the opt-in flag persists in world-level user flags
|
||||
**And** the GM is not notified of the change
|
||||
|
||||
**Given** a player refreshes or rejoins the session
|
||||
**When** the module re-initialises
|
||||
**Then** both opt-in flags return to their last configured state
|
||||
|
||||
---
|
||||
|
||||
### Story 4.2: Custom Portrait Fallback
|
||||
|
||||
As a **player**,
|
||||
I want to choose a custom image to display when my camera feed is unavailable,
|
||||
So that my on-screen presence is represented the way I prefer even when my camera isn't working.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a player opens their Player Privacy Panel
|
||||
**When** they view the "Portrait Fallback" section
|
||||
**Then** a file picker button is shown alongside a preview of the current fallback image
|
||||
|
||||
**Given** the player selects a PNG, JPG, WEBP, or static GIF file
|
||||
**When** the picker accepts it
|
||||
**Then** the file is accepted and the preview updates to the selected image
|
||||
|
||||
**Given** the player selects a file with an unsupported format (e.g. `.svg`, `.mp4`)
|
||||
**When** the picker attempts to accept it
|
||||
**Then** an error shows: "Unsupported format. Please use PNG, JPG, WEBP, or static GIF."
|
||||
**And** the previous fallback image remains unchanged
|
||||
|
||||
**Given** a custom Portrait Fallback is saved
|
||||
**When** the participant's state is `never-connected` or `cam-lost`
|
||||
**Then** the custom fallback image is displayed at AV tile dimensions (same size as a live camera feed tile) with no layout shift
|
||||
|
||||
**Given** no custom fallback is set
|
||||
**When** the fallback is needed
|
||||
**Then** the module uses the FoundryVTT user avatar; if no avatar exists, the system placeholder is used
|
||||
|
||||
**Given** the participant clicks "Remove custom image"
|
||||
**When** the action is confirmed
|
||||
**Then** the fallback reverts to the FoundryVTT user avatar (or system placeholder)
|
||||
+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.
|
||||
@@ -0,0 +1,817 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Scrying Pool — UX Design Directions</title>
|
||||
<style>
|
||||
:root {
|
||||
--sp-surface: #141618;
|
||||
--sp-surface-raised: #1c1f22;
|
||||
--sp-border: #282c30;
|
||||
--sp-text-primary: #dde2e8;
|
||||
--sp-text-secondary: #7a8390;
|
||||
--sp-accent: #4a9e6b;
|
||||
--sp-focus: #63c287;
|
||||
--sp-urgency-director: #c8982a;
|
||||
--sp-state-active: #4a9e6b;
|
||||
--sp-state-hidden: #6b7280;
|
||||
--sp-state-self-muted: #8b92a5;
|
||||
--sp-state-offline: #4b5563;
|
||||
--sp-state-cam-lost: #9ca3af;
|
||||
--sp-state-reconnecting: #c8982a;
|
||||
--sp-state-never-connected: #374151;
|
||||
--sp-state-ghost: #1f2937;
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
|
||||
body {
|
||||
background: #0e1012;
|
||||
color: var(--sp-text-primary);
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
/* ── NAV ── */
|
||||
.nav {
|
||||
position: fixed; top: 0; left: 0; right: 0; z-index: 100;
|
||||
background: #0a0c0e;
|
||||
border-bottom: 1px solid var(--sp-border);
|
||||
display: flex; align-items: center; gap: 4px;
|
||||
padding: 8px 16px;
|
||||
overflow-x: auto;
|
||||
}
|
||||
.nav h1 { font-size: 12px; font-weight: 600; color: var(--sp-accent); margin-right: 12px; white-space: nowrap; }
|
||||
.nav-btn {
|
||||
background: transparent; border: 1px solid var(--sp-border);
|
||||
color: var(--sp-text-secondary); border-radius: 4px;
|
||||
padding: 4px 10px; font-size: 11px; cursor: pointer; white-space: nowrap;
|
||||
transition: all 0.15s;
|
||||
}
|
||||
.nav-btn:hover, .nav-btn.active {
|
||||
background: var(--sp-surface-raised); border-color: var(--sp-accent);
|
||||
color: var(--sp-text-primary);
|
||||
}
|
||||
|
||||
/* ── LAYOUT ── */
|
||||
.stage { padding-top: 48px; }
|
||||
.direction {
|
||||
display: none; min-height: calc(100vh - 48px);
|
||||
padding: 24px;
|
||||
}
|
||||
.direction.visible { display: flex; gap: 24px; flex-wrap: wrap; }
|
||||
|
||||
.direction-label {
|
||||
width: 100%; padding-bottom: 8px; border-bottom: 1px solid var(--sp-border);
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
.direction-label h2 { font-size: 16px; font-weight: 600; color: var(--sp-text-primary); }
|
||||
.direction-label p { font-size: 12px; color: var(--sp-text-secondary); margin-top: 4px; }
|
||||
|
||||
/* ── FOUNDRY CHROME MOCK ── */
|
||||
.foundry-chrome {
|
||||
background: #1a1c1f;
|
||||
border: 1px solid #2a2d32;
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
.foundry-titlebar {
|
||||
background: #111315;
|
||||
padding: 6px 12px;
|
||||
font-size: 11px;
|
||||
color: #5a6070;
|
||||
border-bottom: 1px solid #222528;
|
||||
display: flex; justify-content: space-between; align-items: center;
|
||||
}
|
||||
.foundry-titlebar span { color: var(--sp-accent); font-weight: 600; }
|
||||
|
||||
/* ── COMPACT STRIP ── */
|
||||
.strip {
|
||||
background: var(--sp-surface);
|
||||
border: 1px solid var(--sp-border);
|
||||
border-radius: 4px;
|
||||
overflow: hidden;
|
||||
min-width: 200px;
|
||||
}
|
||||
.strip-header {
|
||||
padding: 6px 10px;
|
||||
font-size: 10px; font-weight: 600; text-transform: uppercase;
|
||||
letter-spacing: 0.06em; color: var(--sp-text-secondary);
|
||||
border-bottom: 1px solid var(--sp-border);
|
||||
display: flex; justify-content: space-between; align-items: center;
|
||||
}
|
||||
.strip-header .sp-tag {
|
||||
color: var(--sp-accent); font-size: 9px;
|
||||
}
|
||||
.strip-row {
|
||||
display: flex; align-items: center; gap: 10px;
|
||||
padding: 0 10px; height: 32px;
|
||||
border-bottom: 1px solid #1e2124;
|
||||
position: relative; cursor: pointer;
|
||||
transition: background 0.1s;
|
||||
}
|
||||
.strip-row:hover { background: var(--sp-surface-raised); }
|
||||
.strip-row:hover .row-actions { opacity: 1; pointer-events: all; }
|
||||
.strip-row:last-child { border-bottom: none; }
|
||||
|
||||
.avatar {
|
||||
width: 24px; height: 24px; border-radius: 50%;
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
font-size: 9px; font-weight: 700; flex-shrink: 0;
|
||||
position: relative;
|
||||
}
|
||||
.avatar.active { background: #1e3b2d; border: 2px solid var(--sp-state-active); }
|
||||
.avatar.hidden { background: #252729; border: 2px dashed var(--sp-state-hidden); opacity: 0.7; }
|
||||
.avatar.muted { background: #232530; border: 2px solid var(--sp-state-self-muted); }
|
||||
.avatar.offline { background: #1a1c1f; border: 2px solid var(--sp-state-offline); opacity: 0.5; }
|
||||
.avatar.reconnect { background: #2a2010; border: 2px solid var(--sp-state-reconnecting); }
|
||||
|
||||
.eye-slash {
|
||||
position: absolute; bottom: -1px; right: -1px;
|
||||
width: 10px; height: 10px; border-radius: 50%;
|
||||
background: var(--sp-surface);
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
font-size: 7px;
|
||||
}
|
||||
|
||||
.row-name {
|
||||
font-size: 13px; color: var(--sp-text-primary); flex: 1;
|
||||
white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
|
||||
}
|
||||
.row-name.dimmed { color: var(--sp-text-secondary); }
|
||||
|
||||
.state-chip {
|
||||
font-size: 9px; font-weight: 600; text-transform: uppercase;
|
||||
padding: 1px 5px; border-radius: 3px; letter-spacing: 0.04em;
|
||||
}
|
||||
.chip-active { background: #1e3b2d; color: var(--sp-state-active); }
|
||||
.chip-hidden { background: #252729; color: #9ca3af; }
|
||||
.chip-muted { background: #232530; color: var(--sp-state-self-muted); }
|
||||
.chip-reconnect { background: #2a2010; color: var(--sp-state-reconnecting); }
|
||||
|
||||
.row-actions {
|
||||
display: flex; gap: 4px;
|
||||
opacity: 0; pointer-events: none;
|
||||
transition: opacity 0.15s;
|
||||
position: absolute; right: 8px;
|
||||
}
|
||||
.action-btn {
|
||||
background: var(--sp-border); border: none;
|
||||
color: var(--sp-text-secondary); border-radius: 3px;
|
||||
padding: 2px 6px; font-size: 10px; cursor: pointer;
|
||||
transition: all 0.1s;
|
||||
}
|
||||
.action-btn:hover { background: var(--sp-accent); color: #000; }
|
||||
.action-btn.hide-btn:hover { background: #4b5563; color: var(--sp-text-primary); }
|
||||
|
||||
/* ── DIRECTOR'S BOARD ── */
|
||||
.board {
|
||||
background: var(--sp-surface);
|
||||
border: 1px solid var(--sp-border);
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
min-width: 340px;
|
||||
}
|
||||
.board-header {
|
||||
padding: 8px 12px;
|
||||
background: #111315;
|
||||
border-bottom: 1px solid var(--sp-border);
|
||||
display: flex; justify-content: space-between; align-items: center;
|
||||
}
|
||||
.board-title { font-size: 12px; font-weight: 600; color: var(--sp-text-primary); }
|
||||
.board-subtitle { font-size: 10px; color: var(--sp-text-secondary); margin-top: 1px; }
|
||||
.board-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(80px, 1fr));
|
||||
gap: 1px; background: var(--sp-border);
|
||||
padding: 1px;
|
||||
}
|
||||
.board-card {
|
||||
background: var(--sp-surface-raised);
|
||||
padding: 10px 8px; text-align: center;
|
||||
cursor: pointer; transition: background 0.1s;
|
||||
position: relative;
|
||||
}
|
||||
.board-card:hover { background: #252830; }
|
||||
.board-card .card-avatar {
|
||||
width: 40px; height: 40px; border-radius: 50%;
|
||||
margin: 0 auto 6px;
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
font-size: 14px; font-weight: 700;
|
||||
}
|
||||
.board-card .card-name { font-size: 10px; color: var(--sp-text-secondary); }
|
||||
.board-card .card-state { font-size: 9px; margin-top: 3px; }
|
||||
.board-card .card-toggle {
|
||||
position: absolute; top: 4px; right: 4px;
|
||||
font-size: 10px; opacity: 0;
|
||||
transition: opacity 0.1s;
|
||||
}
|
||||
.board-card:hover .card-toggle { opacity: 1; }
|
||||
|
||||
/* ── PLAYER BADGE ── */
|
||||
.player-view {
|
||||
background: #1a1c20;
|
||||
border: 1px solid var(--sp-border);
|
||||
border-radius: 6px;
|
||||
padding: 16px;
|
||||
min-width: 260px;
|
||||
}
|
||||
.player-view h3 { font-size: 11px; color: var(--sp-text-secondary); text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 12px; }
|
||||
|
||||
.video-tile {
|
||||
background: #0d0f11;
|
||||
border-radius: 4px;
|
||||
aspect-ratio: 16/9;
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
font-size: 24px;
|
||||
}
|
||||
.video-tile.dimmed { opacity: 0.35; }
|
||||
|
||||
.visibility-badge {
|
||||
position: absolute; bottom: 6px; left: 6px;
|
||||
background: rgba(20,22,24,0.9);
|
||||
border: 1px solid var(--sp-border);
|
||||
border-radius: 10px;
|
||||
padding: 3px 8px 3px 6px;
|
||||
display: flex; align-items: center; gap: 4px;
|
||||
font-size: 10px;
|
||||
backdrop-filter: blur(4px);
|
||||
cursor: pointer;
|
||||
}
|
||||
.badge-dot {
|
||||
width: 6px; height: 6px; border-radius: 50%;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
.badge-dot.active { background: var(--sp-state-active); }
|
||||
.badge-dot.hidden { background: var(--sp-state-hidden); }
|
||||
.badge-dot.muted { background: var(--sp-state-self-muted); }
|
||||
|
||||
.first-encounter {
|
||||
margin-top: 8px;
|
||||
background: var(--sp-surface-raised);
|
||||
border: 1px solid var(--sp-border);
|
||||
border-radius: 4px;
|
||||
padding: 8px 10px;
|
||||
font-size: 11px; color: var(--sp-text-secondary);
|
||||
line-height: 1.5;
|
||||
}
|
||||
.first-encounter strong { color: var(--sp-text-primary); display: block; margin-bottom: 4px; }
|
||||
.got-it-btn {
|
||||
margin-top: 6px;
|
||||
background: var(--sp-accent); border: none;
|
||||
color: #000; border-radius: 3px;
|
||||
padding: 3px 10px; font-size: 10px; font-weight: 600;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
/* ── TOAST ── */
|
||||
.toast {
|
||||
background: #1c1f22;
|
||||
border: 1px solid var(--sp-border);
|
||||
border-left: 3px solid var(--sp-urgency-director);
|
||||
border-radius: 4px;
|
||||
padding: 8px 12px;
|
||||
font-size: 12px; color: var(--sp-text-primary);
|
||||
display: flex; align-items: center; gap: 8px;
|
||||
}
|
||||
.toast-icon { color: var(--sp-urgency-director); font-size: 14px; }
|
||||
|
||||
/* ── DIRECTION-SPECIFIC ── */
|
||||
|
||||
/* Direction 1: Docked vertical strip, minimal */
|
||||
.d1-layout {
|
||||
display: flex; gap: 16px; align-items: flex-start;
|
||||
width: 100%;
|
||||
}
|
||||
.d1-foundry {
|
||||
flex: 1; background: #16181b;
|
||||
border: 1px solid #222528; border-radius: 6px;
|
||||
height: 400px; position: relative;
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
color: #3a3f48; font-size: 13px;
|
||||
}
|
||||
.d1-strip-dock {
|
||||
position: absolute; right: 0; top: 0; bottom: 0;
|
||||
width: 220px; border-left: 1px solid var(--sp-border);
|
||||
background: var(--sp-surface);
|
||||
display: flex; flex-direction: column;
|
||||
}
|
||||
|
||||
/* Direction 2: Floating strip */
|
||||
.d2-floating-strip {
|
||||
position: absolute; right: 16px; top: 16px;
|
||||
box-shadow: 0 4px 20px rgba(0,0,0,0.6);
|
||||
border-radius: 6px;
|
||||
z-index: 10;
|
||||
}
|
||||
|
||||
/* Direction 3: Avatar-only condensed strip */
|
||||
.strip-compact {
|
||||
display: flex; flex-direction: column; gap: 2px;
|
||||
padding: 6px;
|
||||
background: var(--sp-surface);
|
||||
border: 1px solid var(--sp-border);
|
||||
border-radius: 6px;
|
||||
width: 44px;
|
||||
}
|
||||
.avatar-only {
|
||||
width: 32px; height: 32px; border-radius: 50%;
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
font-size: 11px; font-weight: 700;
|
||||
cursor: pointer; position: relative;
|
||||
transition: transform 0.1s;
|
||||
}
|
||||
.avatar-only:hover { transform: scale(1.1); }
|
||||
.avatar-only.active { background: #1e3b2d; border: 2px solid var(--sp-state-active); }
|
||||
.avatar-only.hidden { background: #252729; border: 2px dashed var(--sp-state-hidden); opacity: 0.65; }
|
||||
.avatar-only.reconnect { background: #2a2010; border: 2px solid var(--sp-state-reconnecting); }
|
||||
.avatar-only.offline { background: #1a1c1f; border: 2px solid var(--sp-state-offline); opacity: 0.4; }
|
||||
|
||||
/* ── ANNOTATION ── */
|
||||
.annotation {
|
||||
background: #0f1113;
|
||||
border: 1px solid #222528;
|
||||
border-radius: 4px;
|
||||
padding: 10px 14px;
|
||||
font-size: 11px;
|
||||
color: var(--sp-text-secondary);
|
||||
line-height: 1.6;
|
||||
min-width: 220px;
|
||||
max-width: 300px;
|
||||
}
|
||||
.annotation strong { color: var(--sp-text-primary); display: block; margin-bottom: 4px; font-size: 12px; }
|
||||
.annotation .pro { color: var(--sp-state-active); }
|
||||
.annotation .con { color: #e57373; }
|
||||
.annotation ul { padding-left: 14px; margin: 4px 0; }
|
||||
.annotation li { margin-bottom: 2px; }
|
||||
|
||||
/* ── SECTION HEADERS ── */
|
||||
.section-row {
|
||||
display: flex; gap: 16px; align-items: flex-start;
|
||||
flex-wrap: wrap; width: 100%;
|
||||
}
|
||||
|
||||
/* PULSE ANIMATION */
|
||||
@keyframes pulse-ring {
|
||||
0%, 100% { opacity: 1; }
|
||||
50% { opacity: 0.4; }
|
||||
}
|
||||
.avatar.reconnect { animation: pulse-ring 2s ease-in-out infinite; }
|
||||
.avatar-only.reconnect { animation: pulse-ring 2s ease-in-out infinite; }
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.avatar.reconnect, .avatar-only.reconnect { animation: none; }
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<nav class="nav">
|
||||
<h1>🔮 Scrying Pool</h1>
|
||||
<button class="nav-btn active" onclick="show(1)">D1 · Docked Strip</button>
|
||||
<button class="nav-btn" onclick="show(2)">D2 · Floating Strip</button>
|
||||
<button class="nav-btn" onclick="show(3)">D3 · Avatar-Only Strip</button>
|
||||
<button class="nav-btn" onclick="show(4)">D4 · Director's Board Primary</button>
|
||||
<button class="nav-btn" onclick="show(5)">D5 · Rich Row Strip</button>
|
||||
<button class="nav-btn" onclick="show(6)">D6 · Player View</button>
|
||||
</nav>
|
||||
|
||||
<div class="stage">
|
||||
|
||||
<!-- ════════════════════════════════════════════ DIRECTION 1 ═══ -->
|
||||
<div class="direction visible" id="d1">
|
||||
<div class="direction-label" style="width:100%">
|
||||
<h2>Direction 1 — Docked Vertical Strip (Expert Path)</h2>
|
||||
<p>Compact strip permanently docked to Foundry's right panel. Always visible, zero chrome, ambient authority. Expert-first; novice learns through Learning Bridge.</p>
|
||||
</div>
|
||||
|
||||
<div style="position:relative; width:600px; height:400px; flex-shrink:0;">
|
||||
<div class="d1-foundry" style="width:100%; height:100%;">
|
||||
← Canvas / Map area →
|
||||
<div class="d1-strip-dock">
|
||||
<div class="strip-header">
|
||||
Scrying Pool <span class="sp-tag">● Live</span>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar active">M</div>
|
||||
<span class="row-name">Marcus</span>
|
||||
<span class="state-chip chip-active">Live</span>
|
||||
<div class="row-actions">
|
||||
<button class="action-btn hide-btn">Hide</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar hidden">
|
||||
S
|
||||
<span class="eye-slash">👁</span>
|
||||
</div>
|
||||
<span class="row-name dimmed">Sofia</span>
|
||||
<span class="state-chip chip-hidden">Hidden</span>
|
||||
<div class="row-actions">
|
||||
<button class="action-btn">Show</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar muted">J</div>
|
||||
<span class="row-name">Jake</span>
|
||||
<span class="state-chip chip-muted">Muted</span>
|
||||
<div class="row-actions">
|
||||
<button class="action-btn hide-btn">Hide</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar reconnect">A</div>
|
||||
<span class="row-name">Alex</span>
|
||||
<span class="state-chip chip-reconnect">Rejoining</span>
|
||||
<div class="row-actions">
|
||||
<button class="action-btn hide-btn">Hide</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar offline">?</div>
|
||||
<span class="row-name dimmed">Player 5</span>
|
||||
<span class="state-chip" style="color:#4b5563">Offline</span>
|
||||
</div>
|
||||
<div style="padding:8px 10px; margin-top:auto; border-top:1px solid var(--sp-border);">
|
||||
<button style="width:100%; padding:5px; background:var(--sp-surface-raised); border:1px solid var(--sp-border); border-radius:3px; color:var(--sp-text-secondary); font-size:10px; cursor:pointer;">
|
||||
Open Director's Board ↗
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div style="display:flex; flex-direction:column; gap:12px; max-width:280px;">
|
||||
<div class="annotation">
|
||||
<strong>Direction 1 — Docked Strip</strong>
|
||||
Key behaviours:
|
||||
<ul>
|
||||
<li>Hover row → action rail slides in from right</li>
|
||||
<li>Right-click → context menu (fast path)</li>
|
||||
<li>Strip always open; no toggle needed</li>
|
||||
<li>Strip → Director's Board via footer CTA</li>
|
||||
</ul>
|
||||
<br>
|
||||
<span class="pro">✓ Zero extra chrome; ambient state overview always visible</span><br>
|
||||
<span class="pro">✓ Expert path natively; strip teaches itself on first hover</span><br>
|
||||
<span class="con">✗ Requires docking API support in v14</span><br>
|
||||
<span class="con">✗ Competes with Foundry's native right panel</span>
|
||||
</div>
|
||||
<div class="toast">
|
||||
<span class="toast-icon">◈</span>
|
||||
<span>Scrying Pool: Sofia visibility updated</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ════════════════════════════════════════════ DIRECTION 2 ═══ -->
|
||||
<div class="direction" id="d2">
|
||||
<div class="direction-label" style="width:100%">
|
||||
<h2>Direction 2 — Floating Strip (ApplicationV2 Default)</h2>
|
||||
<p>Strip as a small floating ApplicationV2 window. Draggable, resizable, position persisted. Keyboard shortcut to open/close. Default open state true.</p>
|
||||
</div>
|
||||
|
||||
<div style="position:relative; width:600px; height:420px; flex-shrink:0; background:#16181b; border:1px solid #222528; border-radius:6px; overflow:hidden; display:flex; align-items:center; justify-content:center; color:#3a3f48; font-size:13px;">
|
||||
← Canvas / Map area →
|
||||
|
||||
<div class="d2-floating-strip strip" style="min-width:200px;">
|
||||
<div class="strip-header" style="cursor:move;">
|
||||
🔮 Scrying Pool <span class="sp-tag">● 4 live</span>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar active">M</div>
|
||||
<span class="row-name">Marcus</span>
|
||||
<div class="row-actions"><button class="action-btn hide-btn">Hide</button></div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar hidden">S<span class="eye-slash">👁</span></div>
|
||||
<span class="row-name dimmed">Sofia</span>
|
||||
<div class="row-actions"><button class="action-btn">Show</button></div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar muted">J</div>
|
||||
<span class="row-name">Jake</span>
|
||||
<div class="row-actions"><button class="action-btn hide-btn">Hide</button></div>
|
||||
</div>
|
||||
<div class="strip-row">
|
||||
<div class="avatar reconnect">A</div>
|
||||
<span class="row-name">Alex</span>
|
||||
<div class="row-actions"><button class="action-btn hide-btn">Hide</button></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div style="display:flex; flex-direction:column; gap:12px; max-width:280px;">
|
||||
<div class="annotation">
|
||||
<strong>Direction 2 — Floating Strip</strong>
|
||||
Key behaviours:
|
||||
<ul>
|
||||
<li>Opens with keyboard shortcut (single chord)</li>
|
||||
<li>Draggable titlebar; resize from edges</li>
|
||||
<li>Position/open state → GM User flag</li>
|
||||
<li>Stays on top of canvas; can be minimised</li>
|
||||
</ul>
|
||||
<br>
|
||||
<span class="pro">✓ Zero footprint until opened; no panel conflict</span><br>
|
||||
<span class="pro">✓ Standard ApplicationV2 pattern — trivial to implement</span><br>
|
||||
<span class="con">✗ GM must remember shortcut; discoverability gap</span><br>
|
||||
<span class="con">✗ Occludes map when open at wrong position</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ════════════════════════════════════════════ DIRECTION 3 ═══ -->
|
||||
<div class="direction" id="d3">
|
||||
<div class="direction-label" style="width:100%">
|
||||
<h2>Direction 3 — Avatar-Only Condensed Strip</h2>
|
||||
<p>Ultra-compact vertical strip showing only 32px avatars with state rings. Click to expand to a full-detail popover. Maximum density, minimum screen real-estate.</p>
|
||||
</div>
|
||||
|
||||
<div style="display:flex; gap:16px; align-items:flex-start;">
|
||||
<div>
|
||||
<div style="font-size:10px; color:var(--sp-text-secondary); text-transform:uppercase; letter-spacing:.06em; margin-bottom:8px;">Collapsed state</div>
|
||||
<div class="strip-compact">
|
||||
<div class="avatar-only active">M</div>
|
||||
<div class="avatar-only hidden" style="position:relative;">
|
||||
S
|
||||
<span style="position:absolute;bottom:-1px;right:-1px;font-size:7px;background:var(--sp-surface);border-radius:50%;width:10px;height:10px;display:flex;align-items:center;justify-content:center;">👁</span>
|
||||
</div>
|
||||
<div class="avatar-only" style="background:#232530;border:2px solid var(--sp-state-self-muted);">J</div>
|
||||
<div class="avatar-only reconnect">A</div>
|
||||
<div class="avatar-only offline" style="font-size:9px;">?</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<div style="font-size:10px; color:var(--sp-text-secondary); text-transform:uppercase; letter-spacing:.06em; margin-bottom:8px;">On avatar click → popover</div>
|
||||
<div style="background:var(--sp-surface); border:1px solid var(--sp-border); border-radius:6px; padding:10px 12px; min-width:200px; box-shadow:0 4px 16px rgba(0,0,0,.5);">
|
||||
<div style="display:flex; align-items:center; gap:8px; margin-bottom:10px;">
|
||||
<div class="avatar hidden" style="width:32px;height:32px;font-size:13px;">S<span class="eye-slash">👁</span></div>
|
||||
<div>
|
||||
<div style="font-size:13px; font-weight:600;">Sofia</div>
|
||||
<div style="font-size:10px; color:var(--sp-text-secondary);">Not visible to others</div>
|
||||
</div>
|
||||
</div>
|
||||
<button style="width:100%; padding:6px; background:var(--sp-accent); border:none; border-radius:3px; color:#000; font-size:11px; font-weight:600; cursor:pointer;">Show to table</button>
|
||||
<button style="width:100%; padding:6px; background:var(--sp-surface-raised); border:1px solid var(--sp-border); border-radius:3px; color:var(--sp-text-secondary); font-size:11px; cursor:pointer; margin-top:4px;">Add note…</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="annotation">
|
||||
<strong>Direction 3 — Avatar-Only</strong>
|
||||
Key behaviours:
|
||||
<ul>
|
||||
<li>Strip width: 44px — near-zero footprint</li>
|
||||
<li>All detail in popover on click/hover</li>
|
||||
<li>State ring + icon only — no text labels</li>
|
||||
<li>Works inside Foundry AV strip space</li>
|
||||
</ul>
|
||||
<br>
|
||||
<span class="pro">✓ Absolute minimum screen real-estate</span><br>
|
||||
<span class="pro">✓ At-a-glance state by ring shape/colour</span><br>
|
||||
<span class="con">✗ Copy/state labels hidden by default — accessibility concern</span><br>
|
||||
<span class="con">✗ Popover adds click cost for every action</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ════════════════════════════════════════════ DIRECTION 4 ═══ -->
|
||||
<div class="direction" id="d4">
|
||||
<div class="direction-label" style="width:100%">
|
||||
<h2>Direction 4 — Director's Board as Primary Surface</h2>
|
||||
<p>Director's Board (Level 2) promoted as the main GM control surface. Compact strip becomes a secondary summary-only view. Board-first = more information density per action.</p>
|
||||
</div>
|
||||
|
||||
<div class="board" style="min-width:360px; max-width:440px;">
|
||||
<div class="board-header">
|
||||
<div>
|
||||
<div class="board-title">🔮 Director's Board</div>
|
||||
<div class="board-subtitle">Scrying Pool · 5 participants · 3 visible</div>
|
||||
</div>
|
||||
<button style="background:var(--sp-accent);border:none;border-radius:3px;color:#000;font-size:10px;font-weight:600;padding:3px 8px;cursor:pointer;">Hide All</button>
|
||||
</div>
|
||||
<div class="board-grid">
|
||||
<div class="board-card">
|
||||
<div class="card-avatar active" style="background:#1e3b2d;border:2px solid var(--sp-state-active);">M</div>
|
||||
<div class="card-name">Marcus</div>
|
||||
<div class="card-state" style="color:var(--sp-state-active);">● Live</div>
|
||||
<div class="card-toggle">👁</div>
|
||||
</div>
|
||||
<div class="board-card">
|
||||
<div class="card-avatar" style="background:#252729;border:2px dashed var(--sp-state-hidden);opacity:.65;">S</div>
|
||||
<div class="card-name" style="color:var(--sp-text-secondary);">Sofia</div>
|
||||
<div class="card-state" style="color:#9ca3af;">✕ Hidden</div>
|
||||
<div class="card-toggle">🚫</div>
|
||||
</div>
|
||||
<div class="board-card">
|
||||
<div class="card-avatar" style="background:#232530;border:2px solid var(--sp-state-self-muted);">J</div>
|
||||
<div class="card-name">Jake</div>
|
||||
<div class="card-state" style="color:var(--sp-state-self-muted);">🔇 Muted</div>
|
||||
<div class="card-toggle">👁</div>
|
||||
</div>
|
||||
<div class="board-card">
|
||||
<div class="card-avatar reconnect" style="background:#2a2010;border:2px solid var(--sp-state-reconnecting);width:40px;height:40px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:14px;font-weight:700;animation:pulse-ring 2s ease-in-out infinite;">A</div>
|
||||
<div class="card-name">Alex</div>
|
||||
<div class="card-state" style="color:var(--sp-state-reconnecting);">↺ Rejoining</div>
|
||||
<div class="card-toggle">👁</div>
|
||||
</div>
|
||||
<div class="board-card" style="opacity:.5;">
|
||||
<div class="card-avatar" style="background:#1a1c1f;border:2px solid var(--sp-state-offline);width:40px;height:40px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:14px;font-weight:700;">?</div>
|
||||
<div class="card-name" style="color:var(--sp-text-secondary);">Player 5</div>
|
||||
<div class="card-state" style="color:#4b5563;">✕ Offline</div>
|
||||
</div>
|
||||
</div>
|
||||
<div style="padding:8px 12px; border-top:1px solid var(--sp-border); display:flex; gap:8px;">
|
||||
<button style="flex:1; padding:5px; background:var(--sp-surface-raised); border:1px solid var(--sp-border); border-radius:3px; color:var(--sp-text-secondary); font-size:10px; cursor:pointer;">Show All</button>
|
||||
<button style="flex:1; padding:5px; background:var(--sp-surface-raised); border:1px solid var(--sp-border); border-radius:3px; color:var(--sp-text-secondary); font-size:10px; cursor:pointer;">Save Preset…</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="annotation">
|
||||
<strong>Direction 4 — Board Primary</strong>
|
||||
Key behaviours:
|
||||
<ul>
|
||||
<li>Board is default open surface for GMs</li>
|
||||
<li>Card click = toggle visibility</li>
|
||||
<li>Hover → card-level toggle icon</li>
|
||||
<li>Compact strip = read-only summary</li>
|
||||
</ul>
|
||||
<br>
|
||||
<span class="pro">✓ Optimal for bulk operations (Level 2)</span><br>
|
||||
<span class="pro">✓ Video thumbnails can live here</span><br>
|
||||
<span class="con">✗ Heavier to open than strip for single-player changes</span><br>
|
||||
<span class="con">✗ Board should remain Level 2 opt-in — making it primary changes the product story</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ════════════════════════════════════════════ DIRECTION 5 ═══ -->
|
||||
<div class="direction" id="d5">
|
||||
<div class="direction-label" style="width:100%">
|
||||
<h2>Direction 5 — Rich Row Strip with Inline State Labels</h2>
|
||||
<p>Wider strip showing avatar + name + full state label + action. Maximum information at a glance. Best for novice GMs who need copy to orient them.</p>
|
||||
</div>
|
||||
|
||||
<div style="display:flex; gap:16px; align-items:flex-start;">
|
||||
<div class="strip" style="min-width:260px;">
|
||||
<div class="strip-header">
|
||||
🔮 Scrying Pool
|
||||
<span class="sp-tag">5 participants</span>
|
||||
</div>
|
||||
|
||||
<!-- Rich rows with state label column -->
|
||||
<div class="strip-row" style="height:36px;">
|
||||
<div class="avatar active">M</div>
|
||||
<div style="flex:1; display:flex; flex-direction:column; justify-content:center;">
|
||||
<span style="font-size:12px; color:var(--sp-text-primary); line-height:1.2;">Marcus</span>
|
||||
<span style="font-size:10px; color:var(--sp-state-active);">Visible to all</span>
|
||||
</div>
|
||||
<div class="row-actions"><button class="action-btn hide-btn">Hide from table</button></div>
|
||||
</div>
|
||||
|
||||
<div class="strip-row" style="height:36px; background:rgba(107,114,128,0.05);">
|
||||
<div class="avatar hidden">S<span class="eye-slash">👁</span></div>
|
||||
<div style="flex:1; display:flex; flex-direction:column; justify-content:center;">
|
||||
<span style="font-size:12px; color:var(--sp-text-secondary); line-height:1.2;">Sofia</span>
|
||||
<span style="font-size:10px; color:#9ca3af;">Not visible to others</span>
|
||||
</div>
|
||||
<div class="row-actions"><button class="action-btn">Show to table</button></div>
|
||||
</div>
|
||||
|
||||
<div class="strip-row" style="height:36px;">
|
||||
<div class="avatar muted">J</div>
|
||||
<div style="flex:1; display:flex; flex-direction:column; justify-content:center;">
|
||||
<span style="font-size:12px; color:var(--sp-text-primary); line-height:1.2;">Jake</span>
|
||||
<span style="font-size:10px; color:var(--sp-state-self-muted);">Camera off (player choice)</span>
|
||||
</div>
|
||||
<div class="row-actions"><button class="action-btn hide-btn">Hide from table</button></div>
|
||||
</div>
|
||||
|
||||
<div class="strip-row" style="height:36px;">
|
||||
<div class="avatar reconnect">A</div>
|
||||
<div style="flex:1; display:flex; flex-direction:column; justify-content:center;">
|
||||
<span style="font-size:12px; color:var(--sp-text-primary); line-height:1.2;">Alex</span>
|
||||
<span style="font-size:10px; color:var(--sp-state-reconnecting);">Rejoining view…</span>
|
||||
</div>
|
||||
<div class="row-actions"><button class="action-btn hide-btn">Hide from table</button></div>
|
||||
</div>
|
||||
|
||||
<div class="strip-row" style="height:36px; opacity:.5;">
|
||||
<div class="avatar offline">?</div>
|
||||
<div style="flex:1; display:flex; flex-direction:column; justify-content:center;">
|
||||
<span style="font-size:12px; color:var(--sp-text-secondary); line-height:1.2;">Player 5</span>
|
||||
<span style="font-size:10px; color:#4b5563;">Disconnected</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="annotation">
|
||||
<strong>Direction 5 — Rich Row Strip</strong>
|
||||
Key behaviours:
|
||||
<ul>
|
||||
<li>Row height 36px (vs 32px) for two-line label</li>
|
||||
<li>State copy uses player-facing vocabulary</li>
|
||||
<li>Action label is canonical: "Hide from table"</li>
|
||||
<li>Best combined with novice primary path</li>
|
||||
</ul>
|
||||
<br>
|
||||
<span class="pro">✓ Self-teaching — no tooltip or docs needed</span><br>
|
||||
<span class="pro">✓ Canonical copy reinforced in GM strip</span><br>
|
||||
<span class="con">✗ Wider strip (240–280px) — larger screen footprint</span><br>
|
||||
<span class="con">✗ Copy density may feel verbose at 8+ participants</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ════════════════════════════════════════════ DIRECTION 6 ═══ -->
|
||||
<div class="direction" id="d6">
|
||||
<div class="direction-label" style="width:100%">
|
||||
<h2>Direction 6 — Player View: VisibilityBadge & First Encounter</h2>
|
||||
<p>The player's experience: badge on their own video tile; first-encounter explanation; ongoing state legibility. This is what Sofia sees.</p>
|
||||
</div>
|
||||
|
||||
<div style="display:flex; gap:20px; flex-wrap:wrap; align-items:flex-start;">
|
||||
|
||||
<div>
|
||||
<div style="font-size:10px; color:var(--sp-text-secondary); text-transform:uppercase; letter-spacing:.06em; margin-bottom:8px;">State: Active (visible)</div>
|
||||
<div class="player-view" style="max-width:240px;">
|
||||
<div class="video-tile" style="height:135px;">
|
||||
👤
|
||||
<div class="visibility-badge">
|
||||
<div class="badge-dot active"></div>
|
||||
<span style="color:var(--sp-text-primary);">Visible to all</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<div style="font-size:10px; color:var(--sp-text-secondary); text-transform:uppercase; letter-spacing:.06em; margin-bottom:8px;">State: Hidden (first encounter)</div>
|
||||
<div class="player-view" style="max-width:260px;">
|
||||
<div class="video-tile dimmed" style="height:135px;">
|
||||
👤
|
||||
<div class="visibility-badge" style="border-color:var(--sp-state-hidden);">
|
||||
<div class="badge-dot hidden"></div>
|
||||
<span style="color:var(--sp-text-secondary);">Not visible to others</span>
|
||||
<span style="color:var(--sp-text-secondary); font-size:9px; margin-left:2px;">?</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="first-encounter">
|
||||
<strong>What is this badge?</strong>
|
||||
This badge shows who can currently see your camera. Click anytime to learn more.
|
||||
<br>
|
||||
<button class="got-it-btn">Got it</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<div style="font-size:10px; color:var(--sp-text-secondary); text-transform:uppercase; letter-spacing:.06em; margin-bottom:8px;">State: Reconnecting</div>
|
||||
<div class="player-view" style="max-width:240px;">
|
||||
<div class="video-tile" style="height:135px; background:#0f110d;">
|
||||
👤
|
||||
<div class="visibility-badge" style="border-color:var(--sp-state-reconnecting); animation:pulse-ring 2s ease-in-out infinite;">
|
||||
<div class="badge-dot" style="background:var(--sp-state-reconnecting);"></div>
|
||||
<span style="color:var(--sp-urgency-director);">Rejoining view…</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="annotation" style="max-width:260px;">
|
||||
<strong>Direction 6 — Player View</strong>
|
||||
Key behaviours:
|
||||
<ul>
|
||||
<li>Badge: <code>position:absolute</code> bottom-left of tile</li>
|
||||
<li>Fade: 300–500ms on player's own tile only</li>
|
||||
<li>First encounter: pulsed badge + "Got it" panel</li>
|
||||
<li>Badge always clickable for state explanation</li>
|
||||
<li>Audio never affected by any state change</li>
|
||||
<li>Copy: dignity-first vocabulary throughout</li>
|
||||
</ul>
|
||||
<br>
|
||||
<span class="pro">✓ Player always informed; never blindsided</span><br>
|
||||
<span class="pro">✓ "Got it" sets firstGMActivation (not dismiss)</span><br>
|
||||
<span class="con">✗ Badge must not obscure face at 24px tile size</span><br>
|
||||
<em style="font-size:10px; color:#7a8390;">Consider: bottom-left vs bottom-right placement based on AV grid layout testing</em>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div><!-- /stage -->
|
||||
|
||||
<script>
|
||||
function show(n) {
|
||||
document.querySelectorAll('.direction').forEach(d => d.classList.remove('visible'));
|
||||
document.getElementById('d' + n).classList.add('visible');
|
||||
document.querySelectorAll('.nav-btn').forEach((b, i) => {
|
||||
b.classList.toggle('active', i === n - 1);
|
||||
});
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,44 @@
|
||||
module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
|
||||
BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
|
||||
BMad Method,bmad-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report,
|
||||
BMad Method,bmad-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,1-analysis,,,false,planning_artifacts,brainstorming session
|
||||
BMad Method,bmad-market-research,Market Research,MR,Market analysis competitive landscape customer needs and trends.,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
|
||||
BMad Method,bmad-domain-research,Domain Research,DR,Industry domain deep dive subject matter expertise and terminology.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
|
||||
BMad Method,bmad-technical-research,Technical Research,TR,Technical feasibility architecture options and implementation approaches.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
|
||||
BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,1-analysis,,,false,planning_artifacts,product brief
|
||||
BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
|
||||
BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
|
||||
BMad Method,bmad-create-ux-design,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
|
||||
BMad Method,bmad-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
|
||||
BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-create-architecture,,true,planning_artifacts,epics and stories
|
||||
BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report
|
||||
BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
|
||||
BMad Method,bmad-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,bmad-sprint-planning,,false,,
|
||||
BMad Method,bmad-create-story,Create Story,CS,Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.,create,,4-implementation,bmad-sprint-planning,bmad-create-story:validate,true,implementation_artifacts,story
|
||||
BMad Method,bmad-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,bmad-create-story:create,bmad-dev-story,false,implementation_artifacts,story validation report
|
||||
BMad Method,bmad-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,,4-implementation,bmad-create-story:validate,,true,,
|
||||
BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,,4-implementation,bmad-dev-story,,false,,
|
||||
BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,4-implementation,,,false,,
|
||||
BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite
|
||||
BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
|
||||
BMad Method,bmad-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
|
||||
BMad Method,bmad-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
|
||||
BMad Method,bmad-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
|
||||
BMad Method,bmad-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
|
||||
BMad Method,bmad-agent-tech-writer,Write Document,WD,"Describe in detail what you want, and the agent will follow documentation best practices. Multi-turn conversation with subprocess for research/review.",write,,anytime,,,false,project-knowledge,document
|
||||
BMad Method,bmad-agent-tech-writer,Update Standards,US,Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.,update-standards,,anytime,,,false,_bmad/_memory/tech-writer-sidecar,standards
|
||||
BMad Method,bmad-agent-tech-writer,Mermaid Generate,MG,Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.,mermaid,,anytime,,,false,planning_artifacts,mermaid diagram
|
||||
BMad Method,bmad-agent-tech-writer,Validate Document,VD,Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.,validate,[path],anytime,,,false,planning_artifacts,validation report
|
||||
BMad Method,bmad-agent-tech-writer,Explain Concept,EC,Create clear technical explanations with examples and diagrams for complex concepts.,explain,[topic],anytime,,,false,project_knowledge,explanation
|
||||
Core,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
|
||||
Core,bmad-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
|
||||
Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,,anytime,,,false,,
|
||||
Core,bmad-help,BMad Help,BH,,,,anytime,,,false,,
|
||||
Core,bmad-index-docs,Index Docs,ID,Use when LLM needs to understand available docs without loading everything.,,,anytime,,,false,,
|
||||
Core,bmad-shard-doc,Shard Document,SD,Use when doc becomes too large (>500 lines) to manage effectively.,,[path],anytime,,,false,,
|
||||
Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting to polish written content.,,[path],anytime,,,false,report located with target document,three-column markdown table with suggested fixes
|
||||
Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
|
||||
Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
|
||||
Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
|
||||
Core,bmad-distillator,Distillator,DG,Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.,,[path],anytime,,,false,adjacent to source document or specified output_path,distillate markdown file(s)
|
||||
Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
|
||||
|
@@ -0,0 +1,232 @@
|
||||
type,name,module,path,hash
|
||||
"yaml","manifest","_config","_config/manifest.yaml","4353ae9cec8d178973a5ec07703880dd600ea6ec39ee2bb7ac52a9619df67250"
|
||||
"csv","documentation-requirements","bmm","bmm/1-analysis/bmad-document-project/documentation-requirements.csv","d1253b99e88250f2130516b56027ed706e643bfec3d99316727a4c6ec65c6c1d"
|
||||
"csv","domain-complexity","bmm","bmm/3-solutioning/bmad-create-architecture/data/domain-complexity.csv","3dc34ed39f1fc79a51f7b8fc92087edb7cd85c4393a891d220f2e8dd5a101c70"
|
||||
"csv","module-help","bmm","bmm/module-help.csv","b8c199e3bb160060887211772af2d21b785ce7a3d646699e39520f867af5400f"
|
||||
"csv","project-types","bmm","bmm/3-solutioning/bmad-create-architecture/data/project-types.csv","12343635a2f11343edb1d46906981d6f5e12b9cad2f612e13b09460b5e5106e7"
|
||||
"html","validation-report-template","bmm","bmm/2-plan-workflows/bmad-prd/assets/validation-report-template.html","a80becdd8205d2d7c18738855830b096172a496b96b5ca8a0820ec55c9bb8bf9"
|
||||
"json","bmad-manifest","bmm","bmm/1-analysis/bmad-prfaq/bmad-manifest.json","7908cab6f0cd66f1f3427b4cc659975b4737bdc44f789b23c6a895fcd084c4bc"
|
||||
"json","project-scan-report-schema","bmm","bmm/1-analysis/bmad-document-project/templates/project-scan-report-schema.json","8466965321f1db22f5013869636199f67e0113706283c285a7ffbbf5efeea321"
|
||||
"md","architecture-decision-template","bmm","bmm/3-solutioning/bmad-create-architecture/architecture-decision-template.md","5d9adf90c28df61031079280fd2e49998ec3b44fb3757c6a202cda353e172e9f"
|
||||
"md","artifact-analyzer","bmm","bmm/1-analysis/bmad-prfaq/agents/artifact-analyzer.md","7bdc44830f8d593346ec0ee15e36e1e431432fcc6c38b70bb861999315c9cfa4"
|
||||
"md","brief-template","bmm","bmm/1-analysis/bmad-product-brief/assets/brief-template.md","bb28edf75d023067551c8d417b19b8803324e7acfb2ad0c80f882e9134f4c1f1"
|
||||
"md","case-file-template","bmm","bmm/4-implementation/bmad-investigate/references/case-file-template.md","9dccb41f3f3fc796b42411966e51b32c4231aaceb4b6bb1880a16225a990002e"
|
||||
"md","checklist","bmm","bmm/1-analysis/bmad-document-project/checklist.md","581b0b034c25de17ac3678db2dbafedaeb113de37ddf15a4df6584cf2324a7d7"
|
||||
"md","checklist","bmm","bmm/4-implementation/bmad-correct-course/checklist.md","3e082b95def90ccb876e3101ce0bbaf797a0f03a9471e1347361897f27977327"
|
||||
"md","checklist","bmm","bmm/4-implementation/bmad-create-story/checklist.md","b94e28e774c3be0288f04ea163424bece4ddead5cd3f3680d1603ed07383323a"
|
||||
"md","checklist","bmm","bmm/4-implementation/bmad-dev-story/checklist.md","630b68c6824a8785003a65553c1f335222b17be93b1bd80524c23b38bde1d8af"
|
||||
"md","checklist","bmm","bmm/4-implementation/bmad-qa-generate-e2e-tests/checklist.md","b58f810aeb1040c2f6758c88aa133afce72f8cc178d3d97ff0fbaa3d943057dc"
|
||||
"md","checklist","bmm","bmm/4-implementation/bmad-sprint-planning/checklist.md","80b10aedcf88ab1641b8e5f99c9a400c8fd9014f13ca65befc5c83992e367dd7"
|
||||
"md","compile-epic-context","bmm","bmm/4-implementation/bmad-quick-dev/compile-epic-context.md","5cfda02f252941e415b80c57b4528f46226b3cbf456ad45d78fcb5a7ef4816e2"
|
||||
"md","customer-faq","bmm","bmm/1-analysis/bmad-prfaq/references/customer-faq.md","96f8565197649c58908a1d61b6cd805fd01f57da7945ba889c18d087ad597aeb"
|
||||
"md","deep-dive-instructions","bmm","bmm/1-analysis/bmad-document-project/workflows/deep-dive-instructions.md","a79e24b93a25ab456062916a9dad7b6a16dc43ac0b4b555700d3c3751cff0d25"
|
||||
"md","deep-dive-template","bmm","bmm/1-analysis/bmad-document-project/templates/deep-dive-template.md","6198aa731d87d6a318b5b8d180fc29b9aa53ff0966e02391c17333818e94ffe9"
|
||||
"md","deep-dive-workflow","bmm","bmm/1-analysis/bmad-document-project/workflows/deep-dive-workflow.md","a64d98dfa3b771df2853c4fa19a4e9c90d131e409e13b4c6f5e494d6ac715125"
|
||||
"md","discover-inputs","bmm","bmm/4-implementation/bmad-create-story/discover-inputs.md","dfedba6a8ea05c9a91c6d202c4b29ee3ea793d8ef77575034787ae0fef280507"
|
||||
"md","epics-template","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/templates/epics-template.md","a804f740155156d89661fa04e7a4264a8f712c4dc227c44fd8ae804a9b0f6b72"
|
||||
"md","explain-concept","bmm","bmm/1-analysis/bmad-agent-tech-writer/explain-concept.md","6ea82dbe4e41d4bb8880cbaa62d936e40cef18f8c038be73ae6e09c462abafc9"
|
||||
"md","full-scan-instructions","bmm","bmm/1-analysis/bmad-document-project/workflows/full-scan-instructions.md","2235945df2ae261265187447ce593238e132a026a9b88d3507a1f1d6808a0263"
|
||||
"md","full-scan-workflow","bmm","bmm/1-analysis/bmad-document-project/workflows/full-scan-workflow.md","3bff88a392c16602bd44730f32483505e73e65e46e82768809c13a0a5f55608b"
|
||||
"md","generate-trail","bmm","bmm/4-implementation/bmad-checkpoint-preview/generate-trail.md","4a5936d86fbe5a85285b4535097b1e2edda8849da35586f4b588a982d7224459"
|
||||
"md","headless","bmm","bmm/2-plan-workflows/bmad-prd/references/headless.md","bb7ef8900d6af6a60eb6a72c596bb3c113dde2dfbee703b99bc4ea25eabba40e"
|
||||
"md","headless-schemas","bmm","bmm/2-plan-workflows/bmad-prd/assets/headless-schemas.md","66a5b1f0ce22c7baf3a6b6a14feb7458491b1106bef437389cd6291f81eebd7f"
|
||||
"md","index-template","bmm","bmm/1-analysis/bmad-document-project/templates/index-template.md","42c8a14f53088e4fda82f26a3fe41dc8a89d4bcb7a9659dd696136378b64ee90"
|
||||
"md","instructions","bmm","bmm/1-analysis/bmad-document-project/instructions.md","9f4bc3a46559ffd44289b0d61a0f8f26f829783aa1c0e2a09dfa807fa93eb12f"
|
||||
"md","internal-faq","bmm","bmm/1-analysis/bmad-prfaq/references/internal-faq.md","26eb83f844cda1ed8efb50f4703d61713ada8a64bd27eb387f759f858b5748de"
|
||||
"md","mermaid-gen","bmm","bmm/1-analysis/bmad-agent-tech-writer/mermaid-gen.md","1d83fcc5fa842bc31ecd9fd7e45fbf013fabcadf0022d3391fff5b53b48e4b5d"
|
||||
"md","prd-template","bmm","bmm/2-plan-workflows/bmad-prd/assets/prd-template.md","ebba04ba47740d9127e9bcb30f9a829c7018014208e015e8b727180d12694b14"
|
||||
"md","prd-validation-checklist","bmm","bmm/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md","c5def5aa51aba5b7497f3552e06e86d86d15b9d94be26d056c0bbd1b9375c50a"
|
||||
"md","press-release","bmm","bmm/1-analysis/bmad-prfaq/references/press-release.md","c406adb0e2d2cc326cbc45d0174f89d014523448ad82bc272293999d22aec596"
|
||||
"md","prfaq-template","bmm","bmm/1-analysis/bmad-prfaq/assets/prfaq-template.md","b27e6964f0437ab4e78c8c0ffbe5052c28e3b3ef2fc811726cbb394d5a5c7559"
|
||||
"md","project-context-template","bmm","bmm/3-solutioning/bmad-generate-project-context/project-context-template.md","54e351394ceceb0ac4b5b8135bb6295cf2c37f739c7fd11bb895ca16d79824a5"
|
||||
"md","project-overview-template","bmm","bmm/1-analysis/bmad-document-project/templates/project-overview-template.md","a7c7325b75a5a678dca391b9b69b1e3409cfbe6da95e70443ed3ace164e287b2"
|
||||
"md","readiness-report-template","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/templates/readiness-report-template.md","0da97ab1e38818e642f36dc0ef24d2dae69fc6e0be59924dc2dbf44329738ff6"
|
||||
"md","research.template","bmm","bmm/1-analysis/research/bmad-domain-research/research.template.md","507bb6729476246b1ca2fca4693986d286a33af5529b6cd5cb1b0bb5ea9926ce"
|
||||
"md","research.template","bmm","bmm/1-analysis/research/bmad-market-research/research.template.md","507bb6729476246b1ca2fca4693986d286a33af5529b6cd5cb1b0bb5ea9926ce"
|
||||
"md","research.template","bmm","bmm/1-analysis/research/bmad-technical-research/research.template.md","507bb6729476246b1ca2fca4693986d286a33af5529b6cd5cb1b0bb5ea9926ce"
|
||||
"md","SKILL","bmm","bmm/1-analysis/bmad-agent-analyst/SKILL.md","dff8fbd39de875ccc6735204561f2b7b877788843ecd6e8b6001e7ca7f39641e"
|
||||
"md","SKILL","bmm","bmm/1-analysis/bmad-agent-tech-writer/SKILL.md","d39ffa2a931361e9fea11ef5eb96da0fc6b8dbab70dc200142404a50b78e7665"
|
||||
"md","SKILL","bmm","bmm/1-analysis/bmad-document-project/SKILL.md","efe25c8c27116faeeef119078953c38e827db787338fdb2dca65c086f42e0c4b"
|
||||
"md","SKILL","bmm","bmm/1-analysis/bmad-prfaq/SKILL.md","9e864f574cc2e1411284edb625a17268aab1f894c46baac2edc3bcf1383adaca"
|
||||
"md","SKILL","bmm","bmm/1-analysis/bmad-product-brief/SKILL.md","6078a95cf9500c4c9010e834adc290fa2c793cd4e0e6f2d47e36dc477be24112"
|
||||
"md","SKILL","bmm","bmm/1-analysis/research/bmad-domain-research/SKILL.md","53d2ee5ccbd1d73290e752cff0235bfdb4928dc5ee70f347992ef15621341124"
|
||||
"md","SKILL","bmm","bmm/1-analysis/research/bmad-market-research/SKILL.md","720183e577a5f6f307f320703a5ec522190723e957cfe6ad7821d8d833dea0c7"
|
||||
"md","SKILL","bmm","bmm/1-analysis/research/bmad-technical-research/SKILL.md","1c4b61afaeedd3191db65923253be56084c64e4f832f0e2b9179671f91b5bf20"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-agent-pm/SKILL.md","3a8550daac2df2f01a7c04b66148c1e30b50f81730f043415f2a1aba6314f8a4"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-agent-ux-designer/SKILL.md","3ac99856f0ee9bae3ba05cefab32e90920b4a1fdf0e8c4bf9c440be31f9e5a1f"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-create-prd/SKILL.md","143c5c2d85734021db343ff3dbf143e804eddbf9fb519fb824b70f1a9154767d"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-create-ux-design/SKILL.md","24a4123035194bd3517a059417dcd8114db90f99314ed1a51cfdbbaff02860b2"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-edit-prd/SKILL.md","31ecfe3c16513d994e44e648a7f2d4f4a6ccf297ca6c1826aa68ef7b053e7ff2"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-prd/SKILL.md","aac7b30d01f9d9275fb8339e65c58e4b21c4ae22ddc5810a05a464da5951dec0"
|
||||
"md","SKILL","bmm","bmm/2-plan-workflows/bmad-validate-prd/SKILL.md","931439b8c84bc454d0596a1ad35d6583c1926c941f2928c54b31aea702c24b53"
|
||||
"md","SKILL","bmm","bmm/3-solutioning/bmad-agent-architect/SKILL.md","1bb79ab9d9ae3180a6142d9d20c2a5cb15ad5d5f28e38a7f847295dd04d2299f"
|
||||
"md","SKILL","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/SKILL.md","c683db5628781e6dba6fad388ed65cf7561a208e773f72c786918743e379abef"
|
||||
"md","SKILL","bmm","bmm/3-solutioning/bmad-create-architecture/SKILL.md","b12711f1655cb809bb74a3e11e40943dce225ccba9d01974d5bf521a5867ba23"
|
||||
"md","SKILL","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/SKILL.md","9db05e4a63ead6e416009fdec250bb9b749b361331964b601559ffeedd2f1c0f"
|
||||
"md","SKILL","bmm","bmm/3-solutioning/bmad-generate-project-context/SKILL.md","3d8c20e13e62981464365509fc5e1dfd31e70a94e8c08b048a3e3866ea00ff43"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-agent-dev/SKILL.md","ab47a75e3031bc58a9783e4f8dece8d44dfdacb7ba74cd56f766b260f9993218"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-checkpoint-preview/SKILL.md","fcdd92af6b97ae64f99a89c37deef0074a974ffa577263e6c79c4b6734c63bda"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-code-review/SKILL.md","6801f6742156f125185b1eb6e10c58dfde4ff6545b2e6278acf68cbcfbe0abe4"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-correct-course/SKILL.md","25be5dd528b5c3996e5fa02fc30b72377f688436742c6962f4a1e9a2dac46e55"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-create-story/SKILL.md","81517ba8ef137a15002d6d21ef18a1e88190c74ac9e0c5b29227e4059870809a"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-dev-story/SKILL.md","5e7d3bca5051ff8f009bcf608e3fdac3260c2aa6faa8df170a954fe03a4a03f8"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-investigate/SKILL.md","79905849c7ce4ef4c1c647365c52837a8ede2af01a25ce6267dfe8ba64683652"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-qa-generate-e2e-tests/SKILL.md","ad6025f0279ef9fac2f6c76d8f612c37ccc23f8062b7ac0ac40708b49cc7db80"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-quick-dev/SKILL.md","2b2e57e5327fc69962e6529a0c17498185b571646a9c7360e5c15be14ea7e63b"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-retrospective/SKILL.md","997308d999545fa6c82b8652a2973e1d89d82cfbf892531e25e491291a95c33e"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-sprint-planning/SKILL.md","21946cdaef8115deee6ce322c460e8af39368509d700c778cd7109f50a6821eb"
|
||||
"md","SKILL","bmm","bmm/4-implementation/bmad-sprint-status/SKILL.md","2fe141bc2033ea341a73fb93349fcee0296d8d8714fcf984ab056bc0abae0a19"
|
||||
"md","source-tree-template","bmm","bmm/1-analysis/bmad-document-project/templates/source-tree-template.md","109bc335ebb22f932b37c24cdc777a351264191825444a4d147c9b82a1e2ad7a"
|
||||
"md","spec-template","bmm","bmm/4-implementation/bmad-quick-dev/spec-template.md","3ee15d5a63cf5eeee74149c590668fc61d0e44023eac12988a1ca2a9438a9d39"
|
||||
"md","step-01-clarify-and-route","bmm","bmm/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md","b5eb9f0cecf2a462885b8e7b4c21abbaec1e95c8abbd76bc410d9090fd8379f0"
|
||||
"md","step-01-discover","bmm","bmm/3-solutioning/bmad-generate-project-context/steps/step-01-discover.md","8b2c8c7375f8a3c28411250675a28c0d0a9174e6c4e67b3d53619888439c4613"
|
||||
"md","step-01-document-discovery","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md","c763b512d55906122433cb65c1bcd5b5b283e45eacdc07281c8ec7596b6b3980"
|
||||
"md","step-01-gather-context","bmm","bmm/4-implementation/bmad-code-review/steps/step-01-gather-context.md","d0ee7558605e9d48b5b6f15d9b535542eb6d922613f529bb520326eacade4171"
|
||||
"md","step-01-init","bmm","bmm/1-analysis/research/bmad-domain-research/domain-steps/step-01-init.md","efee243f13ef54401ded88f501967b8bc767460cec5561b2107fc03fe7b7eab1"
|
||||
"md","step-01-init","bmm","bmm/1-analysis/research/bmad-market-research/steps/step-01-init.md","64d5501aea0c0005db23a0a4d9ee84cf4e9239f553c994ecc6b1356917967ccc"
|
||||
"md","step-01-init","bmm","bmm/1-analysis/research/bmad-technical-research/technical-steps/step-01-init.md","c9a1627ecd26227e944375eb691e7ee6bc9f5db29a428a5d53e5d6aef8bb9697"
|
||||
"md","step-01-init","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-01-init.md","0b257533a0ce34d792f621da35325ec11cb883653e3ad546221ee1f0dee5edcd"
|
||||
"md","step-01-init","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-01-init.md","5119205b712ebda0cd241c3daad217bb0f6fa9e6cb41d6635aec6b7fe83b838a"
|
||||
"md","step-01-orientation","bmm","bmm/4-implementation/bmad-checkpoint-preview/step-01-orientation.md","d9e3b949c36d49a025f3535773af2b51888fe4ce616b6d6d69683a122716b1d2"
|
||||
"md","step-01-validate-prerequisites","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md","5c2aabc871363d84fc2e12fd83a3889e9d752b6bd330e31a0067c96204dd4880"
|
||||
"md","step-01b-continue","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-01b-continue.md","4d42c6b83eaa720975bf2206a7eea1a8c73ae922668cc2ef03d34c49ab066c19"
|
||||
"md","step-01b-continue","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-01b-continue.md","4bf216008297dcea25f8be693109cf17879c621865b302c994cdd15aa5124e5f"
|
||||
"md","step-02-context","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-02-context.md","4381c5128de7d5c02ac806a1263e3965754bd2598954f3188219fbd87567e5c9"
|
||||
"md","step-02-customer-behavior","bmm","bmm/1-analysis/research/bmad-market-research/steps/step-02-customer-behavior.md","bac4de244049f90d1f2eb95e2cc9389cc84966d9538077fef1ec9c35e4533849"
|
||||
"md","step-02-design-epics","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/steps/step-02-design-epics.md","7c66987808c1f84e853fe54b7aff26d209196d450b5644704110f124a15179bc"
|
||||
"md","step-02-discovery","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-02-discovery.md","9ffd5b31cc869b564e4d78cdc70767f0fb1b04db4c40201ccfa9dde75739fa8d"
|
||||
"md","step-02-domain-analysis","bmm","bmm/1-analysis/research/bmad-domain-research/domain-steps/step-02-domain-analysis.md","385a288d9bbb0adf050bcce4da4dad198a9151822f9766900404636f2b0c7f9d"
|
||||
"md","step-02-generate","bmm","bmm/3-solutioning/bmad-generate-project-context/steps/step-02-generate.md","b1f063edae66a74026b67a79a245cec7ee85438bafcacfc70dcf6006b495e060"
|
||||
"md","step-02-plan","bmm","bmm/4-implementation/bmad-quick-dev/step-02-plan.md","72f4df415adceaaf554166983559e058c6a019d783d0f87cf42c401db3c5f52c"
|
||||
"md","step-02-prd-analysis","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md","38be2bf4b924c0b5b395b57d68f685d790ade7b1a6c10993d3c550675f87d954"
|
||||
"md","step-02-review","bmm","bmm/4-implementation/bmad-code-review/steps/step-02-review.md","1883758e0e91fba439497d04417f03d778f3f6fb12754f49aa8cfa5e15489f70"
|
||||
"md","step-02-technical-overview","bmm","bmm/1-analysis/research/bmad-technical-research/technical-steps/step-02-technical-overview.md","9c7582241038b16280cddce86f2943216541275daf0a935dcab78f362904b305"
|
||||
"md","step-02-walkthrough","bmm","bmm/4-implementation/bmad-checkpoint-preview/step-02-walkthrough.md","66cf893f8f968ee81034e9ccd8c20415692c3a8c23a9a143c2245fe6c800acdc"
|
||||
"md","step-03-competitive-landscape","bmm","bmm/1-analysis/research/bmad-domain-research/domain-steps/step-03-competitive-landscape.md","f10aa088ba00c59491507f6519fb314139f8be6807958bb5fd1b66bff2267749"
|
||||
"md","step-03-complete","bmm","bmm/3-solutioning/bmad-generate-project-context/steps/step-03-complete.md","e61463db76a8fa060411aa24127aee936d646b97564e9e2a883494ea50e68464"
|
||||
"md","step-03-core-experience","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-03-core-experience.md","1f58c8a2f6872f468629ecb67e94f793af9d10d2804fe3e138eba03c090e00c5"
|
||||
"md","step-03-create-stories","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md","c5b787a82e4e49ed9cd9c028321ee1689f32b8cd69d89eea609b37cd3d481afc"
|
||||
"md","step-03-customer-pain-points","bmm","bmm/1-analysis/research/bmad-market-research/steps/step-03-customer-pain-points.md","5b2418ccaaa89291c593efed0311b3895faad1e9181800d382da823a8eb1312a"
|
||||
"md","step-03-detail-pass","bmm","bmm/4-implementation/bmad-checkpoint-preview/step-03-detail-pass.md","d48163b9f305f15af57729a8443142e47beb6c3e977554afe12b39ee49cb9fc0"
|
||||
"md","step-03-epic-coverage-validation","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md","7b187f03a47cba0325fcfd10240410db9c59d93768342fc2dd3de2a01ec23356"
|
||||
"md","step-03-implement","bmm","bmm/4-implementation/bmad-quick-dev/step-03-implement.md","4d848865eafe5eeba7d83529c766bd410a9cc20a05de1d6a764954c7275b4749"
|
||||
"md","step-03-integration-patterns","bmm","bmm/1-analysis/research/bmad-technical-research/technical-steps/step-03-integration-patterns.md","005d517a2f962e2172e26b23d10d5e6684c7736c0d3982e27b2e72d905814ad9"
|
||||
"md","step-03-starter","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-03-starter.md","b7727e0f37bc5325e15abad1c54bef716d617df423336090189efd1d307a0b3f"
|
||||
"md","step-03-triage","bmm","bmm/4-implementation/bmad-code-review/steps/step-03-triage.md","91eaa27f6a167702ead00da9e93565c9bff79dce92c02eccbca61b1d1ed39a80"
|
||||
"md","step-04-architectural-patterns","bmm","bmm/1-analysis/research/bmad-technical-research/technical-steps/step-04-architectural-patterns.md","4636f23e9c585a7a0c90437a660609d913f16362c3557fc2e71d408d6b9f46ce"
|
||||
"md","step-04-customer-decisions","bmm","bmm/1-analysis/research/bmad-market-research/steps/step-04-customer-decisions.md","f0bc25f2179b7490e7a6704159a32fc9e83ab616022355ed53acfe8e2f7059d5"
|
||||
"md","step-04-decisions","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-04-decisions.md","7fc0ebb63ab5ad0efc470f1063c15f14f52f5d855da2382fd17576cf060a8763"
|
||||
"md","step-04-emotional-response","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-04-emotional-response.md","75724811b170c8897e230a49e968e1db357fef3387008b0906b5ff79a43dbff9"
|
||||
"md","step-04-final-validation","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md","6b83fcf177c24c6b43c2eb0df2efc1430cb0f357b3ab20ee8a5c5483c3fee079"
|
||||
"md","step-04-present","bmm","bmm/4-implementation/bmad-code-review/steps/step-04-present.md","eee5687e9d7da9a0aeffd78180b8289fca804fc2d59896db5f65a8dd476e4869"
|
||||
"md","step-04-regulatory-focus","bmm","bmm/1-analysis/research/bmad-domain-research/domain-steps/step-04-regulatory-focus.md","d22035529efe91993e698b4ebf297bf2e7593eb41d185a661c357a8afc08977b"
|
||||
"md","step-04-review","bmm","bmm/4-implementation/bmad-quick-dev/step-04-review.md","e62a50a37ab20eb426f5abd44179dfac51548707b5e85e6fe7817c144cbe3dae"
|
||||
"md","step-04-testing","bmm","bmm/4-implementation/bmad-checkpoint-preview/step-04-testing.md","28a56e868968ea2d18add0df8c4bccced0f94b698e218df3d45ddac072ce369c"
|
||||
"md","step-04-ux-alignment","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md","f71e5f0d77615e885ae40fdee6b04c1dd6e472c871f87b515fe869cb5f6966fb"
|
||||
"md","step-05-competitive-analysis","bmm","bmm/1-analysis/research/bmad-market-research/steps/step-05-competitive-analysis.md","17532051ad232cfc859f09ac3b44f9f4d542eb24cff8d07317126ccdff0d225a"
|
||||
"md","step-05-epic-quality-review","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md","d8a84e57f4e3a321734b5b5d093458ceb1e338744f18954c5a204f5ce3576185"
|
||||
"md","step-05-implementation-research","bmm","bmm/1-analysis/research/bmad-technical-research/technical-steps/step-05-implementation-research.md","e2b8a2c79bcebadc85f3823145980fa47d7e7be8d1c112f686c6223c8c138608"
|
||||
"md","step-05-inspiration","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-05-inspiration.md","b0cadcd4665c46d2e6e89bdb45ddfdd4e4aac47b901e59aa156b935878a2b124"
|
||||
"md","step-05-patterns","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-05-patterns.md","3c80aba507aa46893ef43f07c5c321b985632ef57abc82d5ee93c3d9c2911134"
|
||||
"md","step-05-present","bmm","bmm/4-implementation/bmad-quick-dev/step-05-present.md","ea49ce8703d4946ec54a59ff428d52ad64ab2649f49c43230bec1f3d09e85b55"
|
||||
"md","step-05-technical-trends","bmm","bmm/1-analysis/research/bmad-domain-research/domain-steps/step-05-technical-trends.md","fd6c577010171679f630805eb76e09daf823c2b9770eb716986d01f351ce1fb4"
|
||||
"md","step-05-wrapup","bmm","bmm/4-implementation/bmad-checkpoint-preview/step-05-wrapup.md","c2d4dbc17fed4f8ecbfcb09a2f9c77f0d4562bd27397270e2c27ba37cf4fe073"
|
||||
"md","step-06-design-system","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-06-design-system.md","1c71e452916c5b9ed000af4dd1b83954ae16887463c73776251e1e734e7d7641"
|
||||
"md","step-06-final-assessment","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/steps/step-06-final-assessment.md","1b9c8c2a21950f85e052e05309bfcb3bfe38157ba6fca402ccf37444e7f1cee3"
|
||||
"md","step-06-research-completion","bmm","bmm/1-analysis/research/bmad-market-research/steps/step-06-research-completion.md","4f5d3158a8462656d6959d29544ed5c92cb925641e2205e47af05c124fcd7666"
|
||||
"md","step-06-research-synthesis","bmm","bmm/1-analysis/research/bmad-domain-research/domain-steps/step-06-research-synthesis.md","805f2cb7005a4fb0c4da52ea38d45de863f3e840e0f2de1456c414831cdbdf59"
|
||||
"md","step-06-research-synthesis","bmm","bmm/1-analysis/research/bmad-technical-research/technical-steps/step-06-research-synthesis.md","64d9303ef0c9ce839dc3b2d72e94e3e5b4673e82dc7fc9f1571bd0b03b3a43a7"
|
||||
"md","step-06-structure","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-06-structure.md","f8333ca290b62849c1e2eb2f770b46705b09fe0322217b699b13be047efdd03e"
|
||||
"md","step-07-defining-experience","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-07-defining-experience.md","17f78d679a187cfb703c2cd30eea84d9dd683f3708d24885421239338eea4edd"
|
||||
"md","step-07-validation","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-07-validation.md","dde4cd93a3015011da9a8a3237aafa2d15d0935205686231e58bf7064f81cc28"
|
||||
"md","step-08-complete","bmm","bmm/3-solutioning/bmad-create-architecture/steps/step-08-complete.md","6466e5196be63e9e21b81d6fed45f1ff547d6ac739271201d6180febc857473d"
|
||||
"md","step-08-visual-foundation","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-08-visual-foundation.md","985b4da65435114529056f33ff583ec4d1b29feb3550494ae741b6dbb89798a9"
|
||||
"md","step-09-design-directions","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-09-design-directions.md","07962c637e69a612a904efccf6188b7f08c9e484d4d7369c74cd0de7da0cb1e3"
|
||||
"md","step-10-user-journeys","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-10-user-journeys.md","eabe15745e6b68df06833bca103c704d31094c8f070c84e35f1ee9b0c28d10bd"
|
||||
"md","step-11-component-strategy","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-11-component-strategy.md","52a1d0230160124496467ddbe26dd9cc4ae7d9afceaea987aad658e1bb195f59"
|
||||
"md","step-12-ux-patterns","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-12-ux-patterns.md","37215fe8ea33247e9a31b5f8b8fe3b36448d7f743c18803e4d5054c201348be8"
|
||||
"md","step-13-responsive-accessibility","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-13-responsive-accessibility.md","cd4d4e2a307b4cbc805c6954860c93c14a11b74b1e206c45ff89f8b81ab03a62"
|
||||
"md","step-14-complete","bmm","bmm/2-plan-workflows/bmad-create-ux-design/steps/step-14-complete.md","47880f82ada9f2edff8be144328f86fb683fd78aba64ec0ea9dfbff71732be00"
|
||||
"md","step-oneshot","bmm","bmm/4-implementation/bmad-quick-dev/step-oneshot.md","d68648848bb8277f5b762c3528c2aa42122268037b97d252a8f4faf4edb2830e"
|
||||
"md","sync-sprint-status","bmm","bmm/4-implementation/bmad-quick-dev/sync-sprint-status.md","c0f2fdb940984206a4b7aa2467fbcb7c4811f648634e43a488593974e9efff5e"
|
||||
"md","template","bmm","bmm/4-implementation/bmad-create-story/template.md","29ba697368d77e88e88d0e7ac78caf7a78785a7dcfc291082aa96a62948afb67"
|
||||
"md","ux-design-template","bmm","bmm/2-plan-workflows/bmad-create-ux-design/ux-design-template.md","ffa4b89376cd9db6faab682710b7ce755990b1197a8b3e16b17748656d1fca6a"
|
||||
"md","validate","bmm","bmm/2-plan-workflows/bmad-prd/references/validate.md","689387606f3df71641a619e42d2841c815de1e05f8ceb87d2198383e3cb0f98b"
|
||||
"md","validate-doc","bmm","bmm/1-analysis/bmad-agent-tech-writer/validate-doc.md","3b8d25f60be191716266726393f2d44b77262301b785a801631083b610d6acc5"
|
||||
"md","verdict","bmm","bmm/1-analysis/bmad-prfaq/references/verdict.md","1a1cbc34090114d3a2b928456edec1563b73d84fea66c58e98780bf680f172ec"
|
||||
"md","web-researcher","bmm","bmm/1-analysis/bmad-prfaq/agents/web-researcher.md","6e9127bb9bd3e4b15c701e4ced9eef328769262cd34eadc221bebe954c1f3aef"
|
||||
"md","write-document","bmm","bmm/1-analysis/bmad-agent-tech-writer/write-document.md","c0ddfd981f765b82cba0921dad331cd1fa32bacdeea1f02320edfd60a0ae7e6f"
|
||||
"toml","customize","bmm","bmm/1-analysis/bmad-agent-analyst/customize.toml","7191f4a60ada7dbabe083699b2461f35778af7688924dc6ce05911cf1ffc9054"
|
||||
"toml","customize","bmm","bmm/1-analysis/bmad-agent-tech-writer/customize.toml","bb828f2d26a136870099226f07c61297ce88ddd335823b7549592932bbe14a2e"
|
||||
"toml","customize","bmm","bmm/1-analysis/bmad-document-project/customize.toml","3bbb5044fafdd865a5fe0863df116a479f30de7fb95c9cf4213f0b87ba1ba924"
|
||||
"toml","customize","bmm","bmm/1-analysis/bmad-prfaq/customize.toml","8994f925bab65bd310e5ab38781286b6137f3e0c9e89f3ab8a2f480eb05e0de5"
|
||||
"toml","customize","bmm","bmm/1-analysis/bmad-product-brief/customize.toml","cdd7b417de5b280ab5bd3af65f69654b05980b5efb48077563827c16391f42d6"
|
||||
"toml","customize","bmm","bmm/1-analysis/research/bmad-domain-research/customize.toml","462ef14dc1e1f6d145fdfe25e315168fd1fa278ea5f87fe0fa86689234daec2f"
|
||||
"toml","customize","bmm","bmm/1-analysis/research/bmad-market-research/customize.toml","f47af9158893dd3f7ab81ac03cb07d8c76342eead61ec7c9a8a463066b7db9af"
|
||||
"toml","customize","bmm","bmm/1-analysis/research/bmad-technical-research/customize.toml","7f567fddb04674f817398addbc06e6d1620883d89dcc7ac643c5a56eef5ac337"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-agent-pm/customize.toml","afc2250de25241ac3577c9827e1ee62d8c7a1913de8eb23aadfffb0aadbadc37"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-agent-ux-designer/customize.toml","0d36c8ce31fe332770b2755a7e952dc102f184fb3275448bf6ac2ebc783ed03b"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-create-prd/customize.toml","0c990af4c0a755402abbef893850bd542744a8b6f36c0587c9f3fb6dab6bf5e7"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-create-ux-design/customize.toml","e51d02120e5e79788b183f1fb377f823f7626bac7702a6aa4dc6ddd0a3b00000"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-edit-prd/customize.toml","35cc2dfb3eda73a0ae4dc987cac58867b25c43ce5c5a1bf552e215826ede6c22"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-prd/customize.toml","c30f48939b558a0e7e4c0a4d4f6eb08e50bad4464ca64c652247d114a398d459"
|
||||
"toml","customize","bmm","bmm/2-plan-workflows/bmad-validate-prd/customize.toml","bfb3c8af5b81b2cdb9bb84f844f1b0dafc40d8c283effa6ad48db966b9446cef"
|
||||
"toml","customize","bmm","bmm/3-solutioning/bmad-agent-architect/customize.toml","32e8074896a569ce59e4db62ab3b4af396798b8fa50c67449a5d90c2a7a7e074"
|
||||
"toml","customize","bmm","bmm/3-solutioning/bmad-check-implementation-readiness/customize.toml","571d81087b7a6d914cf7c2f21aa26354eac385bb2f5cfeabc591892cbb98d036"
|
||||
"toml","customize","bmm","bmm/3-solutioning/bmad-create-architecture/customize.toml","618be49b0286f18dfb4b6bac3d96bf1cf062994fa5278cd327be9898e651b43c"
|
||||
"toml","customize","bmm","bmm/3-solutioning/bmad-create-epics-and-stories/customize.toml","da9e43605bc6aec83173050b5d37ede6aebfa9a17c5959a5029681d73e744ba3"
|
||||
"toml","customize","bmm","bmm/3-solutioning/bmad-generate-project-context/customize.toml","00b6e893b93a1be7c04408f1824dad72c2c43ee02ba29210725e34394bf8225e"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-agent-dev/customize.toml","b56c0af68e2234dc57d9ebe765049ebd9df9e24909d0d9b2b4b12ddefe5291a7"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-checkpoint-preview/customize.toml","1a1e0c3a8914adda3cec925eed51287e067c7f84120de64a8df53348e7b77de5"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-code-review/customize.toml","94ad662fdf3fda372c6e24b2cbda629d0b2aa851097d02afb5905c768b1a1cde"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-correct-course/customize.toml","78095d25afb5b2d4844956f61e9ac640a62d0245174fab9406e9c289f33fd84b"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-create-story/customize.toml","1204f6de064436922f2813069778eb4eaa5f1f945aa8ea5a5ffb87897a2ba8fe"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-dev-story/customize.toml","592fa7948c4614609a59b152518f518d35e0178d6aa7c22e169d78157fd9f5aa"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-investigate/customize.toml","7ec009a4a0a9b476de98de99938f58e319dc6f410b9176910c9ed725e80519e1"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-qa-generate-e2e-tests/customize.toml","04a99926b2d79318b927434c7344dc666f143026ed99c7fcc0d6e3d68263ae66"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-quick-dev/customize.toml","5ba463713de51762eb381be787cbd657932333b808be370d851fc3e40f139e2f"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-retrospective/customize.toml","0b032c342129732820ca2db386d2d5e26d033d8ac296388fc9f2e78765fab9fb"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-sprint-planning/customize.toml","f7bde2f792e8604f26122ee792c5493e270710296044b07680db7d90e886caf3"
|
||||
"toml","customize","bmm","bmm/4-implementation/bmad-sprint-status/customize.toml","96261fd227befaa4685b0a5091d3e85299d4ae8e4404176b42f5ef2e2fb501bd"
|
||||
"yaml","config","bmm","bmm/config.yaml","32ee517eb45769ad48da8ccd77b4ebddf92b31db0965ce2a9f9768be2e8365c4"
|
||||
"yaml","sprint-status-template","bmm","bmm/4-implementation/bmad-sprint-planning/sprint-status-template.yaml","deeec135d875b107618dd41278349689b5f3dcb5894d7509909417a570f46fd9"
|
||||
"toml","config","config.toml","config.toml","1acc13121bd8f58c6fe4e4568e5d0c64ed42c3dd26c6f868ea4b95a4c4004139"
|
||||
"toml","config.user","config.user.toml","config.user.toml","549442482884536bb9cbbc122ab6b70163ed274926323f3930cd790ae93f970d"
|
||||
"csv","brain-methods","core","core/bmad-brainstorming/brain-methods.csv","0ab5878b1dbc9e3fa98cb72abfc3920a586b9e2b42609211bb0516eefd542039"
|
||||
"csv","methods","core","core/bmad-advanced-elicitation/methods.csv","e08b2e22fec700274982e37be608d6c3d1d4d0c04fa0bae05aa9dba2454e6141"
|
||||
"csv","module-help","core","core/module-help.csv","6677d8aaeaae3ed92185ea51094bfb08c5f2fb059faf88029da30d3313c36273"
|
||||
"md","compression-rules","core","core/bmad-distillator/resources/compression-rules.md","86e53d6a2072b379864766681d1cc4e1aad3d4428ecca8c46010f7364da32724"
|
||||
"md","distillate-compressor","core","core/bmad-distillator/agents/distillate-compressor.md","c00da33b39a43207a224c4043d1aa4158e90e41ab421fff0ea7cc55beec81ef8"
|
||||
"md","distillate-format-reference","core","core/bmad-distillator/resources/distillate-format-reference.md","47b6734ab8c327215e3578f98c3b7ef3772332dcf6710d92f5599ffb4d03a085"
|
||||
"md","round-trip-reconstructor","core","core/bmad-distillator/agents/round-trip-reconstructor.md","47c83f4a37249ddac38460d8c95d162f6fc175a8919888e8090aed71bd9383bc"
|
||||
"md","SKILL","core","core/bmad-advanced-elicitation/SKILL.md","705cc827cab892855d07dcc926f5c9f749c3abab33e915d6ac1574aec174896b"
|
||||
"md","SKILL","core","core/bmad-brainstorming/SKILL.md","f4a2c22b40ed34cdbd3282dd6161a3b869902f3bc75b58e181fc9faf78eedd9d"
|
||||
"md","SKILL","core","core/bmad-customize/SKILL.md","6461073f9322f5f2ec64477d6ae5e79c601e36e3160e492fef4bc2d928d4a9a8"
|
||||
"md","SKILL","core","core/bmad-distillator/SKILL.md","756ee0706ff6b8a3d5726b465e81ba244e4eaeba21b7de0d2390473acebb5ddc"
|
||||
"md","SKILL","core","core/bmad-editorial-review-prose/SKILL.md","b3687fe80567378627bc2a0c5034ae8d65dfeedcf2b6c90da077f4feca462d0c"
|
||||
"md","SKILL","core","core/bmad-editorial-review-structure/SKILL.md","164444359d74f695a84faf7ea558d0eef39c75561e6b26669f97a165c6f75538"
|
||||
"md","SKILL","core","core/bmad-help/SKILL.md","a766c6bd76bcfc4a49a683417440d39978a2e10bb5618dfd469fff03f96b4b4d"
|
||||
"md","SKILL","core","core/bmad-index-docs/SKILL.md","a855d7060414e73ca4fe8e1a3e1cc4d0f2ce394846e52340bdf5a1317e0d234a"
|
||||
"md","SKILL","core","core/bmad-party-mode/SKILL.md","bd13fd6cb0b0c61d215e4c394cf4b7cac3a465394c3918f4dc14910513ddb898"
|
||||
"md","SKILL","core","core/bmad-review-adversarial-general/SKILL.md","7bffc39e6dba4d9123648c5d4d79e17c3c5b1efbd927c3fe0026c2dbb8d99cff"
|
||||
"md","SKILL","core","core/bmad-review-edge-case-hunter/SKILL.md","f49ed9976f46b4cefa1fc8b4f0a495f16089905e6a7bbf4ce73b8f05c9ae3ee6"
|
||||
"md","SKILL","core","core/bmad-shard-doc/SKILL.md","3a1538536514725fd4f31aded280ee56b9645fc61d114fd94aacb3ac52304e52"
|
||||
"md","splitting-strategy","core","core/bmad-distillator/resources/splitting-strategy.md","26d3ed05f912cf99ff9ebe2353f2d84d70e3e852e23a32b1215c13416ad708b5"
|
||||
"md","step-01-session-setup","core","core/bmad-brainstorming/steps/step-01-session-setup.md","7fd2aed9527ccdf35fc86bd4c9b27b4a530b5cfdfb90ae2b7385d3185bcd60bc"
|
||||
"md","step-01b-continue","core","core/bmad-brainstorming/steps/step-01b-continue.md","49f8d78290291f974432bc8e8fce340de58ed62aa946e9e3182858bf63829920"
|
||||
"md","step-02a-user-selected","core","core/bmad-brainstorming/steps/step-02a-user-selected.md","7ff3bca27286d17902ecea890494599796633e24a25ea6b31bbd6c3d2e54eba2"
|
||||
"md","step-02b-ai-recommended","core","core/bmad-brainstorming/steps/step-02b-ai-recommended.md","cb77b810e0c98e080b4378999f0e250bacba4fb74c1bcb0a144cffe9989d2cbd"
|
||||
"md","step-02c-random-selection","core","core/bmad-brainstorming/steps/step-02c-random-selection.md","91c6e16213911a231a41b1a55be7c939e7bbcd1463bd49cb03b5b669a90c0868"
|
||||
"md","step-02d-progressive-flow","core","core/bmad-brainstorming/steps/step-02d-progressive-flow.md","6b6fbbd34bcf334d79f09e8c36ed3c9d55ddd3ebb8f8f77aa892643d1a4e3436"
|
||||
"md","step-03-technique-execution","core","core/bmad-brainstorming/steps/step-03-technique-execution.md","b97afefd4ccc5234e554a3dfc5555337269ce171e730b250c756718235e9df60"
|
||||
"md","step-04-idea-organization","core","core/bmad-brainstorming/steps/step-04-idea-organization.md","acb7eb6a54161213bb916cabf7d0d5084316704e792a880968fc340855cdcbbb"
|
||||
"md","template","core","core/bmad-brainstorming/template.md","5c99d76963eb5fc21db96c5a68f39711dca7c6ed30e4f7d22aedee9e8bb964f9"
|
||||
"md","workflow","core","core/bmad-brainstorming/workflow.md","74c87846a5cda7a4534ea592ea3125a8d8a1a88d19c94f5f4481fb28d0d16bf2"
|
||||
"py","analyze_sources","core","core/bmad-distillator/scripts/analyze_sources.py","31e2a8441c3c43c2536739c580cdef6abecb18ff20e7447f42dd868875783166"
|
||||
"py","list_customizable_skills","core","core/bmad-customize/scripts/list_customizable_skills.py","8787f542930b927789e7fdf12bc5a67ff08e19865903a5ad05ff2cc8fc426b66"
|
||||
"py","test_analyze_sources","core","core/bmad-distillator/scripts/tests/test_analyze_sources.py","d90525311f8010aaf8d7d9212a370468a697866190bae78c35d0aae9b7f23fdf"
|
||||
"py","test_list_customizable_skills","core","core/bmad-customize/scripts/tests/test_list_customizable_skills.py","b55fc2e454f245753874f359c18ade9f3ad04debd66176c6e6bf3e403ca9c812"
|
||||
"yaml","config","core","core/config.yaml","7cdd623292c489ccdeba26f49634ea821a3a877d1f42dd8a5d1ab284571a2e4a"
|
||||
"file",".gitignore","custom","custom/.gitignore","973b03a33f142c22cf9b65be285bebadd85790b6b55be04637d2f8c716f58fab"
|
||||
"py","resolve_config","scripts","scripts/resolve_config.py","8e326149d9170477ecc21aa2aa2389d8fbaa5d1cd95db2de2ad33029ce8ae528"
|
||||
"py","resolve_customization","scripts","scripts/resolve_customization.py","6dbf36a2fea13392426fdbaf4f074b6d9b93488a964d2d1bff2a5c1c3a1d506e"
|
||||
|
@@ -0,0 +1,22 @@
|
||||
installation:
|
||||
version: 6.7.1
|
||||
installDate: 2026-05-19T20:12:58.981Z
|
||||
lastUpdated: 2026-05-19T20:12:58.981Z
|
||||
modules:
|
||||
- name: core
|
||||
version: 6.7.1
|
||||
installDate: 2026-05-19T20:12:58.881Z
|
||||
lastUpdated: 2026-05-19T20:12:58.980Z
|
||||
source: built-in
|
||||
npmPackage: null
|
||||
repoUrl: null
|
||||
- name: bmm
|
||||
version: 6.7.1
|
||||
installDate: 2026-05-19T20:12:58.862Z
|
||||
lastUpdated: 2026-05-19T20:12:58.981Z
|
||||
source: built-in
|
||||
npmPackage: null
|
||||
repoUrl: null
|
||||
ides:
|
||||
- claude-code
|
||||
- mistral-vibe
|
||||
@@ -0,0 +1,45 @@
|
||||
canonicalId,name,description,module,path
|
||||
"bmad-advanced-elicitation","bmad-advanced-elicitation","Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.","core","_bmad/core/bmad-advanced-elicitation/SKILL.md"
|
||||
"bmad-brainstorming","bmad-brainstorming","Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.","core","_bmad/core/bmad-brainstorming/SKILL.md"
|
||||
"bmad-customize","bmad-customize","Authors and updates customization overrides for installed BMad skills. Use when the user says 'customize bmad', 'override a skill', 'change agent behavior', or 'customize a workflow'.","core","_bmad/core/bmad-customize/SKILL.md"
|
||||
"bmad-distillator","bmad-distillator","Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.","core","_bmad/core/bmad-distillator/SKILL.md"
|
||||
"bmad-editorial-review-prose","bmad-editorial-review-prose","Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose","core","_bmad/core/bmad-editorial-review-prose/SKILL.md"
|
||||
"bmad-editorial-review-structure","bmad-editorial-review-structure","Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure","core","_bmad/core/bmad-editorial-review-structure/SKILL.md"
|
||||
"bmad-help","bmad-help","Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.","core","_bmad/core/bmad-help/SKILL.md"
|
||||
"bmad-index-docs","bmad-index-docs","Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder","core","_bmad/core/bmad-index-docs/SKILL.md"
|
||||
"bmad-party-mode","bmad-party-mode","Orchestrates group discussions between installed BMAD agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project.","core","_bmad/core/bmad-party-mode/SKILL.md"
|
||||
"bmad-review-adversarial-general","bmad-review-adversarial-general","Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something","core","_bmad/core/bmad-review-adversarial-general/SKILL.md"
|
||||
"bmad-review-edge-case-hunter","bmad-review-edge-case-hunter","Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs.","core","_bmad/core/bmad-review-edge-case-hunter/SKILL.md"
|
||||
"bmad-shard-doc","bmad-shard-doc","Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document","core","_bmad/core/bmad-shard-doc/SKILL.md"
|
||||
"bmad-agent-analyst","bmad-agent-analyst","Strategic business analyst and requirements expert. Use when the user asks to talk to Mary or requests the business analyst.","bmm","_bmad/bmm/1-analysis/bmad-agent-analyst/SKILL.md"
|
||||
"bmad-agent-tech-writer","bmad-agent-tech-writer","Technical documentation specialist and knowledge curator. Use when the user asks to talk to Paige or requests the tech writer.","bmm","_bmad/bmm/1-analysis/bmad-agent-tech-writer/SKILL.md"
|
||||
"bmad-document-project","bmad-document-project","Document brownfield projects for AI context. Use when the user says ""document this project"" or ""generate project docs""","bmm","_bmad/bmm/1-analysis/bmad-document-project/SKILL.md"
|
||||
"bmad-prfaq","bmad-prfaq","Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.","bmm","_bmad/bmm/1-analysis/bmad-prfaq/SKILL.md"
|
||||
"bmad-product-brief","bmad-product-brief","Create, update, or validate a product brief. Use when the user wants help producing, editing, or validating a brief.","bmm","_bmad/bmm/1-analysis/bmad-product-brief/SKILL.md"
|
||||
"bmad-domain-research","bmad-domain-research","Conduct domain and industry research. Use when the user says wants to do domain research for a topic or industry","bmm","_bmad/bmm/1-analysis/research/bmad-domain-research/SKILL.md"
|
||||
"bmad-market-research","bmad-market-research","Conduct market research on competition and customers. Use when the user says they need market research","bmm","_bmad/bmm/1-analysis/research/bmad-market-research/SKILL.md"
|
||||
"bmad-technical-research","bmad-technical-research","Conduct technical research on technologies and architecture. Use when the user says they would like to do or produce a technical research report","bmm","_bmad/bmm/1-analysis/research/bmad-technical-research/SKILL.md"
|
||||
"bmad-agent-pm","bmad-agent-pm","Product manager for PRD creation and requirements discovery. Use when the user asks to talk to John or requests the product manager.","bmm","_bmad/bmm/2-plan-workflows/bmad-agent-pm/SKILL.md"
|
||||
"bmad-agent-ux-designer","bmad-agent-ux-designer","UX designer and UI specialist. Use when the user asks to talk to Sally or requests the UX designer.","bmm","_bmad/bmm/2-plan-workflows/bmad-agent-ux-designer/SKILL.md"
|
||||
"bmad-create-prd","bmad-create-prd","DEPRECATED — consolidated into bmad-prd create intent - this skill will be removed in v7 in favor of `bmad-prd`.","bmm","_bmad/bmm/2-plan-workflows/bmad-create-prd/SKILL.md"
|
||||
"bmad-create-ux-design","bmad-create-ux-design","Plan UX patterns and design specifications. Use when the user says ""lets create UX design"" or ""create UX specifications"" or ""help me plan the UX""","bmm","_bmad/bmm/2-plan-workflows/bmad-create-ux-design/SKILL.md"
|
||||
"bmad-edit-prd","bmad-edit-prd","DEPRECATED — consolidated into bmad-prd update intent - this skill will be removed in v7 in favor of `bmad-prd`.","bmm","_bmad/bmm/2-plan-workflows/bmad-edit-prd/SKILL.md"
|
||||
"bmad-prd","bmad-prd","Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.","bmm","_bmad/bmm/2-plan-workflows/bmad-prd/SKILL.md"
|
||||
"bmad-validate-prd","bmad-validate-prd","DEPRECATED — consolidated into bmad-prd validate intent - this skill will be removed in v7 in favor of `bmad-prd`.","bmm","_bmad/bmm/2-plan-workflows/bmad-validate-prd/SKILL.md"
|
||||
"bmad-agent-architect","bmad-agent-architect","System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect.","bmm","_bmad/bmm/3-solutioning/bmad-agent-architect/SKILL.md"
|
||||
"bmad-check-implementation-readiness","bmad-check-implementation-readiness","Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says ""check implementation readiness"".","bmm","_bmad/bmm/3-solutioning/bmad-check-implementation-readiness/SKILL.md"
|
||||
"bmad-create-architecture","bmad-create-architecture","Create architecture solution design decisions for AI agent consistency. Use when the user says ""lets create architecture"" or ""create technical architecture"" or ""create a solution design""","bmm","_bmad/bmm/3-solutioning/bmad-create-architecture/SKILL.md"
|
||||
"bmad-create-epics-and-stories","bmad-create-epics-and-stories","Break requirements into epics and user stories. Use when the user says ""create the epics and stories list""","bmm","_bmad/bmm/3-solutioning/bmad-create-epics-and-stories/SKILL.md"
|
||||
"bmad-generate-project-context","bmad-generate-project-context","Create project-context.md with AI rules. Use when the user says ""generate project context"" or ""create project context""","bmm","_bmad/bmm/3-solutioning/bmad-generate-project-context/SKILL.md"
|
||||
"bmad-agent-dev","bmad-agent-dev","Senior software engineer for story execution and code implementation. Use when the user asks to talk to Amelia or requests the developer agent.","bmm","_bmad/bmm/4-implementation/bmad-agent-dev/SKILL.md"
|
||||
"bmad-checkpoint-preview","bmad-checkpoint-preview","LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says ""checkpoint"", ""human review"", or ""walk me through this change"".","bmm","_bmad/bmm/4-implementation/bmad-checkpoint-preview/SKILL.md"
|
||||
"bmad-code-review","bmad-code-review","Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says ""run code review"" or ""review this code""","bmm","_bmad/bmm/4-implementation/bmad-code-review/SKILL.md"
|
||||
"bmad-correct-course","bmad-correct-course","Manage significant changes during sprint execution. Use when the user says ""correct course"" or ""propose sprint change""","bmm","_bmad/bmm/4-implementation/bmad-correct-course/SKILL.md"
|
||||
"bmad-create-story","bmad-create-story","Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says ""create the next story"" or ""create story [story identifier]""","bmm","_bmad/bmm/4-implementation/bmad-create-story/SKILL.md"
|
||||
"bmad-dev-story","bmad-dev-story","Execute story implementation following a context filled story spec file. Use when the user says ""dev this story [story file]"" or ""implement the next story in the sprint plan""","bmm","_bmad/bmm/4-implementation/bmad-dev-story/SKILL.md"
|
||||
"bmad-investigate","bmad-investigate","Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model of a code area before working on it.","bmm","_bmad/bmm/4-implementation/bmad-investigate/SKILL.md"
|
||||
"bmad-qa-generate-e2e-tests","bmad-qa-generate-e2e-tests","Generate end to end automated tests for existing features. Use when the user says ""create qa automated tests for [feature]""","bmm","_bmad/bmm/4-implementation/bmad-qa-generate-e2e-tests/SKILL.md"
|
||||
"bmad-quick-dev","bmad-quick-dev","Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project's existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.","bmm","_bmad/bmm/4-implementation/bmad-quick-dev/SKILL.md"
|
||||
"bmad-retrospective","bmad-retrospective","Post-epic review to extract lessons and assess success. Use when the user says ""run a retrospective"" or ""lets retro the epic [epic]""","bmm","_bmad/bmm/4-implementation/bmad-retrospective/SKILL.md"
|
||||
"bmad-sprint-planning","bmad-sprint-planning","Generate sprint status tracking from epics. Use when the user says ""run sprint planning"" or ""generate sprint plan""","bmm","_bmad/bmm/4-implementation/bmad-sprint-planning/SKILL.md"
|
||||
"bmad-sprint-status","bmad-sprint-status","Summarize sprint status and surface risks. Use when the user says ""check sprint status"" or ""show sprint status""","bmm","_bmad/bmm/4-implementation/bmad-sprint-status/SKILL.md"
|
||||
|
@@ -0,0 +1,16 @@
|
||||
# BMM Module Configuration
|
||||
# Generated by BMAD installer
|
||||
# Version: 6.7.1
|
||||
# Date: 2026-05-19T20:12:58.895Z
|
||||
|
||||
user_skill_level: intermediate
|
||||
planning_artifacts: "{project-root}/_bmad-output/planning-artifacts"
|
||||
implementation_artifacts: "{project-root}/_bmad-output/implementation-artifacts"
|
||||
project_knowledge: "{project-root}/docs"
|
||||
|
||||
# Core Configuration Values
|
||||
user_name: Morr
|
||||
project_name: video-view-manager
|
||||
communication_language: English
|
||||
document_output_language: English
|
||||
output_folder: "{project-root}/_bmad-output"
|
||||
@@ -0,0 +1,32 @@
|
||||
module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
|
||||
BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
|
||||
BMad Method,bmad-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
|
||||
BMad Method,bmad-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
|
||||
BMad Method,bmad-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
|
||||
BMad Method,bmad-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
|
||||
BMad Method,bmad-agent-tech-writer,Write Document,WD,"Describe in detail what you want, and the agent will follow documentation best practices. Multi-turn conversation with subprocess for research/review.",write,,anytime,,,false,project-knowledge,document
|
||||
BMad Method,bmad-agent-tech-writer,Update Standards,US,Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.,update-standards,,anytime,,,false,_bmad/_memory/tech-writer-sidecar,standards
|
||||
BMad Method,bmad-agent-tech-writer,Mermaid Generate,MG,Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.,mermaid,,anytime,,,false,planning_artifacts,mermaid diagram
|
||||
BMad Method,bmad-agent-tech-writer,Validate Document,VD,Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.,validate,[path],anytime,,,false,planning_artifacts,validation report
|
||||
BMad Method,bmad-agent-tech-writer,Explain Concept,EC,Create clear technical explanations with examples and diagrams for complex concepts.,explain,[topic],anytime,,,false,project_knowledge,explanation
|
||||
BMad Method,bmad-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,1-analysis,,,false,planning_artifacts,brainstorming session
|
||||
BMad Method,bmad-market-research,Market Research,MR,Market analysis competitive landscape customer needs and trends.,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
|
||||
BMad Method,bmad-domain-research,Domain Research,DR,Industry domain deep dive subject matter expertise and terminology.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
|
||||
BMad Method,bmad-technical-research,Technical Research,TR,Technical feasibility architecture options and implementation approaches.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
|
||||
BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,1-analysis,,,false,planning_artifacts,product brief
|
||||
BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
|
||||
BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
|
||||
BMad Method,bmad-create-ux-design,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
|
||||
BMad Method,bmad-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
|
||||
BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-create-architecture,,true,planning_artifacts,epics and stories
|
||||
BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report
|
||||
BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
|
||||
BMad Method,bmad-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,bmad-sprint-planning,,false,,
|
||||
BMad Method,bmad-create-story,Create Story,CS,Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.,create,,4-implementation,bmad-sprint-planning,bmad-create-story:validate,true,implementation_artifacts,story
|
||||
BMad Method,bmad-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,bmad-create-story:create,bmad-dev-story,false,implementation_artifacts,story validation report
|
||||
BMad Method,bmad-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,,4-implementation,bmad-create-story:validate,,true,,
|
||||
BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,,4-implementation,bmad-dev-story,,false,,
|
||||
BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,4-implementation,,,false,,
|
||||
BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite
|
||||
BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
|
||||
BMad Method,bmad-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report
|
||||
|
@@ -0,0 +1,69 @@
|
||||
# ─────────────────────────────────────────────────────────────────
|
||||
# Installer-managed. Regenerated on every install — treat as read-only.
|
||||
#
|
||||
# Direct edits to this file will be overwritten on the next install.
|
||||
# To change an install answer durably, re-run the installer (your prior
|
||||
# answers are remembered as defaults). To pin a value regardless of
|
||||
# install answers, or to add custom agents / override descriptors, use:
|
||||
# _bmad/custom/config.toml (team, committed)
|
||||
# _bmad/custom/config.user.toml (personal, gitignored)
|
||||
# Those files are never touched by the installer.
|
||||
# ─────────────────────────────────────────────────────────────────
|
||||
|
||||
[core]
|
||||
project_name = "video-view-manager"
|
||||
document_output_language = "English"
|
||||
output_folder = "{project-root}/_bmad-output"
|
||||
|
||||
[modules.bmm]
|
||||
planning_artifacts = "{project-root}/_bmad-output/planning-artifacts"
|
||||
implementation_artifacts = "{project-root}/_bmad-output/implementation-artifacts"
|
||||
project_knowledge = "{project-root}/docs"
|
||||
|
||||
[agents.bmad-agent-analyst]
|
||||
module = "bmm"
|
||||
team = "software-development"
|
||||
name = "Mary"
|
||||
title = "Business Analyst"
|
||||
icon = "📊"
|
||||
description = "Channels Porter's strategic rigor and Minto's Pyramid Principle, grounds every finding in verifiable evidence, represents every stakeholder voice. Speaks like a treasure hunter narrating the find: thrilled by every clue, precise once the pattern emerges."
|
||||
|
||||
[agents.bmad-agent-tech-writer]
|
||||
module = "bmm"
|
||||
team = "software-development"
|
||||
name = "Paige"
|
||||
title = "Technical Writer"
|
||||
icon = "📚"
|
||||
description = "Master of CommonMark, DITA, and OpenAPI; turns complex concepts into accessible structured docs, favors diagrams over walls of text, every word earning its place. Speaks like the patient teacher you wish you'd had, using analogies that make complex things feel simple."
|
||||
|
||||
[agents.bmad-agent-pm]
|
||||
module = "bmm"
|
||||
team = "software-development"
|
||||
name = "John"
|
||||
title = "Product Manager"
|
||||
icon = "📋"
|
||||
description = "Drives Jobs-to-be-Done over template filling, user value first, technical feasibility is a constraint not the driver. Speaks like a detective interrogating a cold case: short questions, sharper follow-ups, every 'why?' tightening the net."
|
||||
|
||||
[agents.bmad-agent-ux-designer]
|
||||
module = "bmm"
|
||||
team = "software-development"
|
||||
name = "Sally"
|
||||
title = "UX Designer"
|
||||
icon = "🎨"
|
||||
description = "Balances empathy with edge-case rigor, starts simple and evolves through feedback, every decision serves a genuine user need. Speaks like a filmmaker pitching the scene before the code exists, painting user stories that make you feel the problem."
|
||||
|
||||
[agents.bmad-agent-architect]
|
||||
module = "bmm"
|
||||
team = "software-development"
|
||||
name = "Winston"
|
||||
title = "System Architect"
|
||||
icon = "🏗️"
|
||||
description = "Favors boring technology for stability, developer productivity as architecture, ties every decision to business value. Speaks like a seasoned engineer at the whiteboard: measured, always laying out trade-offs rather than verdicts."
|
||||
|
||||
[agents.bmad-agent-dev]
|
||||
module = "bmm"
|
||||
team = "software-development"
|
||||
name = "Amelia"
|
||||
title = "Senior Software Engineer"
|
||||
icon = "💻"
|
||||
description = "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."
|
||||
@@ -0,0 +1,17 @@
|
||||
# ─────────────────────────────────────────────────────────────────
|
||||
# Installer-managed. Regenerated on every install — treat as read-only.
|
||||
# Holds install answers scoped to YOU personally.
|
||||
#
|
||||
# Direct edits to this file will be overwritten on the next install.
|
||||
# To change an answer durably, re-run the installer (your prior answers
|
||||
# are remembered as defaults). For pinned overrides or custom sections
|
||||
# the installer does not know about, use _bmad/custom/config.user.toml
|
||||
# — it is never touched by the installer.
|
||||
# ─────────────────────────────────────────────────────────────────
|
||||
|
||||
[core]
|
||||
user_name = "Morr"
|
||||
communication_language = "English"
|
||||
|
||||
[modules.bmm]
|
||||
user_skill_level = "intermediate"
|
||||
@@ -0,0 +1,10 @@
|
||||
# CORE Module Configuration
|
||||
# Generated by BMAD installer
|
||||
# Version: 6.7.1
|
||||
# Date: 2026-05-19T20:12:58.897Z
|
||||
|
||||
user_name: Morr
|
||||
project_name: video-view-manager
|
||||
communication_language: English
|
||||
document_output_language: English
|
||||
output_folder: "{project-root}/_bmad-output"
|
||||
@@ -0,0 +1,13 @@
|
||||
module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
|
||||
Core,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
|
||||
Core,bmad-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
|
||||
Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,,anytime,,,false,,
|
||||
Core,bmad-help,BMad Help,BH,,,,anytime,,,false,,
|
||||
Core,bmad-index-docs,Index Docs,ID,Use when LLM needs to understand available docs without loading everything.,,,anytime,,,false,,
|
||||
Core,bmad-shard-doc,Shard Document,SD,Use when doc becomes too large (>500 lines) to manage effectively.,,[path],anytime,,,false,,
|
||||
Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting to polish written content.,,[path],anytime,,,false,report located with target document,three-column markdown table with suggested fixes
|
||||
Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
|
||||
Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
|
||||
Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
|
||||
Core,bmad-distillator,Distillator,DG,Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.,,[path],anytime,,,false,adjacent to source document or specified output_path,distillate markdown file(s)
|
||||
Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
|
||||
|
@@ -0,0 +1 @@
|
||||
*.user.toml
|
||||
@@ -0,0 +1,7 @@
|
||||
# Team / enterprise overrides for _bmad/config.toml.
|
||||
# Committed to the repo — applies to every developer on the project.
|
||||
# Tables deep-merge over base config; keyed entries merge by key.
|
||||
# Example: override an agent descriptor, or add a new agent.
|
||||
#
|
||||
# [agents.bmad-agent-pm]
|
||||
# description = "Prefers short, bulleted PRDs over narrative drafts."
|
||||
@@ -0,0 +1,176 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Resolve BMad's central config using four-layer TOML merge.
|
||||
|
||||
Reads from four layers (highest priority last):
|
||||
1. {project-root}/_bmad/config.toml (installer-owned team)
|
||||
2. {project-root}/_bmad/config.user.toml (installer-owned user)
|
||||
3. {project-root}/_bmad/custom/config.toml (human-authored team, committed)
|
||||
4. {project-root}/_bmad/custom/config.user.toml (human-authored user, gitignored)
|
||||
|
||||
Outputs merged JSON to stdout. Errors go to stderr.
|
||||
|
||||
Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
|
||||
no virtualenv — plain `python3` is sufficient.
|
||||
|
||||
python3 resolve_config.py --project-root /abs/path/to/project
|
||||
python3 resolve_config.py --project-root ... --key core
|
||||
python3 resolve_config.py --project-root ... --key agents
|
||||
|
||||
Merge rules (same as resolve_customization.py):
|
||||
- Scalars: override wins
|
||||
- Tables: deep merge
|
||||
- Arrays of tables where every item shares `code` or `id`: merge by that key
|
||||
- All other arrays: append
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
except ImportError:
|
||||
sys.stderr.write(
|
||||
"error: Python 3.11+ is required (stdlib `tomllib` not found).\n"
|
||||
)
|
||||
sys.exit(3)
|
||||
|
||||
|
||||
_MISSING = object()
|
||||
_KEYED_MERGE_FIELDS = ("code", "id")
|
||||
|
||||
|
||||
def load_toml(file_path: Path, required: bool = False) -> dict:
|
||||
if not file_path.exists():
|
||||
if required:
|
||||
sys.stderr.write(f"error: required config file not found: {file_path}\n")
|
||||
sys.exit(1)
|
||||
return {}
|
||||
try:
|
||||
with file_path.open("rb") as f:
|
||||
parsed = tomllib.load(f)
|
||||
if not isinstance(parsed, dict):
|
||||
return {}
|
||||
return parsed
|
||||
except tomllib.TOMLDecodeError as error:
|
||||
level = "error" if required else "warning"
|
||||
sys.stderr.write(f"{level}: failed to parse {file_path}: {error}\n")
|
||||
if required:
|
||||
sys.exit(1)
|
||||
return {}
|
||||
except OSError as error:
|
||||
level = "error" if required else "warning"
|
||||
sys.stderr.write(f"{level}: failed to read {file_path}: {error}\n")
|
||||
if required:
|
||||
sys.exit(1)
|
||||
return {}
|
||||
|
||||
|
||||
def _detect_keyed_merge_field(items):
|
||||
if not items or not all(isinstance(item, dict) for item in items):
|
||||
return None
|
||||
for candidate in _KEYED_MERGE_FIELDS:
|
||||
if all(item.get(candidate) is not None for item in items):
|
||||
return candidate
|
||||
return None
|
||||
|
||||
|
||||
def _merge_by_key(base, override, key_name):
|
||||
result = []
|
||||
index_by_key = {}
|
||||
for item in base:
|
||||
if not isinstance(item, dict):
|
||||
continue
|
||||
if item.get(key_name) is not None:
|
||||
index_by_key[item[key_name]] = len(result)
|
||||
result.append(dict(item))
|
||||
for item in override:
|
||||
if not isinstance(item, dict):
|
||||
result.append(item)
|
||||
continue
|
||||
key = item.get(key_name)
|
||||
if key is not None and key in index_by_key:
|
||||
result[index_by_key[key]] = dict(item)
|
||||
else:
|
||||
if key is not None:
|
||||
index_by_key[key] = len(result)
|
||||
result.append(dict(item))
|
||||
return result
|
||||
|
||||
|
||||
def _merge_arrays(base, override):
|
||||
base_arr = base if isinstance(base, list) else []
|
||||
override_arr = override if isinstance(override, list) else []
|
||||
keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
|
||||
if keyed_field:
|
||||
return _merge_by_key(base_arr, override_arr, keyed_field)
|
||||
return base_arr + override_arr
|
||||
|
||||
|
||||
def deep_merge(base, override):
|
||||
if isinstance(base, dict) and isinstance(override, dict):
|
||||
result = dict(base)
|
||||
for key, over_val in override.items():
|
||||
if key in result:
|
||||
result[key] = deep_merge(result[key], over_val)
|
||||
else:
|
||||
result[key] = over_val
|
||||
return result
|
||||
if isinstance(base, list) and isinstance(override, list):
|
||||
return _merge_arrays(base, override)
|
||||
return override
|
||||
|
||||
|
||||
def extract_key(data, dotted_key: str):
|
||||
parts = dotted_key.split(".")
|
||||
current = data
|
||||
for part in parts:
|
||||
if isinstance(current, dict) and part in current:
|
||||
current = current[part]
|
||||
else:
|
||||
return _MISSING
|
||||
return current
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Resolve BMad central config using four-layer TOML merge.",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--project-root", "-p", required=True,
|
||||
help="Absolute path to the project root (contains _bmad/)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--key", "-k", action="append", default=[],
|
||||
help="Dotted field path to resolve (repeatable). Omit for full dump.",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
project_root = Path(args.project_root).resolve()
|
||||
bmad_dir = project_root / "_bmad"
|
||||
|
||||
base_team = load_toml(bmad_dir / "config.toml", required=True)
|
||||
base_user = load_toml(bmad_dir / "config.user.toml")
|
||||
custom_team = load_toml(bmad_dir / "custom" / "config.toml")
|
||||
custom_user = load_toml(bmad_dir / "custom" / "config.user.toml")
|
||||
|
||||
merged = deep_merge(base_team, base_user)
|
||||
merged = deep_merge(merged, custom_team)
|
||||
merged = deep_merge(merged, custom_user)
|
||||
|
||||
if args.key:
|
||||
output = {}
|
||||
for key in args.key:
|
||||
value = extract_key(merged, key)
|
||||
if value is not _MISSING:
|
||||
output[key] = value
|
||||
else:
|
||||
output = merged
|
||||
|
||||
sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Executable
+230
@@ -0,0 +1,230 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Resolve customization for a BMad skill using three-layer TOML merge.
|
||||
|
||||
Reads customization from three layers (highest priority first):
|
||||
1. {project-root}/_bmad/custom/{name}.user.toml (personal, gitignored)
|
||||
2. {project-root}/_bmad/custom/{name}.toml (team/org, committed)
|
||||
3. {skill-root}/customize.toml (skill defaults)
|
||||
|
||||
Skill name is derived from the basename of the skill directory.
|
||||
|
||||
Outputs merged JSON to stdout. Errors go to stderr.
|
||||
|
||||
Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
|
||||
no virtualenv — plain `python3` is sufficient.
|
||||
|
||||
python3 resolve_customization.py --skill /abs/path/to/skill-dir
|
||||
python3 resolve_customization.py --skill ... --key agent
|
||||
python3 resolve_customization.py --skill ... --key agent.menu
|
||||
|
||||
Merge rules (purely structural — no field-name special-casing):
|
||||
- Scalars (string, int, bool, float): override wins
|
||||
- Tables: deep merge (recursively apply these rules)
|
||||
- Arrays of tables where every item shares the *same* identifier
|
||||
field (every item has `code`, or every item has `id`):
|
||||
merge by that key (matching keys replace, new keys append)
|
||||
- All other arrays — including arrays where only some items have
|
||||
`code` or `id`, or where items mix the two keys:
|
||||
append (base items followed by override items)
|
||||
|
||||
No removal mechanism — overrides cannot delete base items. To suppress
|
||||
a default, fork the skill or override the item by code with a no-op
|
||||
description/prompt.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
except ImportError:
|
||||
sys.stderr.write(
|
||||
"error: Python 3.11+ is required (stdlib `tomllib` not found).\n"
|
||||
"Install a newer Python or run the resolution manually per the\n"
|
||||
"fallback instructions in the skill's SKILL.md.\n"
|
||||
)
|
||||
sys.exit(3)
|
||||
|
||||
|
||||
_MISSING = object()
|
||||
_KEYED_MERGE_FIELDS = ("code", "id")
|
||||
|
||||
|
||||
def find_project_root(start: Path):
|
||||
current = start.resolve()
|
||||
while True:
|
||||
if (current / "_bmad").exists() or (current / ".git").exists():
|
||||
return current
|
||||
parent = current.parent
|
||||
if parent == current:
|
||||
return None
|
||||
current = parent
|
||||
|
||||
|
||||
def load_toml(file_path: Path, required: bool = False) -> dict:
|
||||
if not file_path.exists():
|
||||
if required:
|
||||
sys.stderr.write(f"error: required customization file not found: {file_path}\n")
|
||||
sys.exit(1)
|
||||
return {}
|
||||
try:
|
||||
with file_path.open("rb") as f:
|
||||
parsed = tomllib.load(f)
|
||||
if not isinstance(parsed, dict):
|
||||
if required:
|
||||
sys.stderr.write(f"error: {file_path} did not parse to a table\n")
|
||||
sys.exit(1)
|
||||
return {}
|
||||
return parsed
|
||||
except tomllib.TOMLDecodeError as error:
|
||||
level = "error" if required else "warning"
|
||||
sys.stderr.write(f"{level}: failed to parse {file_path}: {error}\n")
|
||||
if required:
|
||||
sys.exit(1)
|
||||
return {}
|
||||
except OSError as error:
|
||||
level = "error" if required else "warning"
|
||||
sys.stderr.write(f"{level}: failed to read {file_path}: {error}\n")
|
||||
if required:
|
||||
sys.exit(1)
|
||||
return {}
|
||||
|
||||
|
||||
def _detect_keyed_merge_field(items):
|
||||
"""Return 'code' or 'id' if every table item carries that *same* field.
|
||||
|
||||
All items must share the same identifier (all `code`, or all `id`).
|
||||
Mixed arrays — where some items use `code` and others use `id` —
|
||||
return None and fall through to append semantics. This is intentional:
|
||||
mixing identifier keys within one array is a schema smell, and
|
||||
append-fallback is safer than guessing which key should merge.
|
||||
"""
|
||||
if not items or not all(isinstance(item, dict) for item in items):
|
||||
return None
|
||||
for candidate in _KEYED_MERGE_FIELDS:
|
||||
if all(item.get(candidate) is not None for item in items):
|
||||
return candidate
|
||||
return None
|
||||
|
||||
|
||||
def _merge_by_key(base, override, key_name):
|
||||
result = []
|
||||
index_by_key = {}
|
||||
|
||||
for item in base:
|
||||
if not isinstance(item, dict):
|
||||
continue
|
||||
if item.get(key_name) is not None:
|
||||
index_by_key[item[key_name]] = len(result)
|
||||
result.append(dict(item))
|
||||
|
||||
for item in override:
|
||||
if not isinstance(item, dict):
|
||||
result.append(item)
|
||||
continue
|
||||
key = item.get(key_name)
|
||||
if key is not None and key in index_by_key:
|
||||
result[index_by_key[key]] = dict(item)
|
||||
else:
|
||||
if key is not None:
|
||||
index_by_key[key] = len(result)
|
||||
result.append(dict(item))
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def _merge_arrays(base, override):
|
||||
"""Shape-aware array merge. Base + override combined tables may opt into
|
||||
keyed merge if every item has `code` or `id`. Otherwise: append."""
|
||||
base_arr = base if isinstance(base, list) else []
|
||||
override_arr = override if isinstance(override, list) else []
|
||||
keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
|
||||
if keyed_field:
|
||||
return _merge_by_key(base_arr, override_arr, keyed_field)
|
||||
return base_arr + override_arr
|
||||
|
||||
|
||||
def deep_merge(base, override):
|
||||
"""Recursively merge override into base using structural rules.
|
||||
- Table + table: deep merge
|
||||
- Array + array: shape-aware (keyed merge if all items have code/id, else append)
|
||||
- Anything else: override wins
|
||||
"""
|
||||
if isinstance(base, dict) and isinstance(override, dict):
|
||||
result = dict(base)
|
||||
for key, over_val in override.items():
|
||||
if key in result:
|
||||
result[key] = deep_merge(result[key], over_val)
|
||||
else:
|
||||
result[key] = over_val
|
||||
return result
|
||||
if isinstance(base, list) and isinstance(override, list):
|
||||
return _merge_arrays(base, override)
|
||||
return override
|
||||
|
||||
|
||||
def extract_key(data, dotted_key: str):
|
||||
parts = dotted_key.split(".")
|
||||
current = data
|
||||
for part in parts:
|
||||
if isinstance(current, dict) and part in current:
|
||||
current = current[part]
|
||||
else:
|
||||
return _MISSING
|
||||
return current
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Resolve customization for a BMad skill using three-layer TOML merge.",
|
||||
add_help=True,
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill", "-s", required=True,
|
||||
help="Absolute path to the skill directory (must contain customize.toml)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--key", "-k", action="append", default=[],
|
||||
help="Dotted field path to resolve (repeatable). Omit for full dump.",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
skill_dir = Path(args.skill).resolve()
|
||||
skill_name = skill_dir.name
|
||||
defaults_path = skill_dir / "customize.toml"
|
||||
|
||||
defaults = load_toml(defaults_path, required=True)
|
||||
|
||||
# Prefer the project that contains this skill. Only fall back to cwd if
|
||||
# the skill isn't inside a recognizable project tree (unusual but possible
|
||||
# for standalone skills invoked directly). Using cwd first is unsafe when
|
||||
# an ancestor of cwd happens to have a stray _bmad/ from another project.
|
||||
project_root = find_project_root(skill_dir) or find_project_root(Path.cwd())
|
||||
|
||||
team = {}
|
||||
user = {}
|
||||
if project_root:
|
||||
custom_dir = project_root / "_bmad" / "custom"
|
||||
team = load_toml(custom_dir / f"{skill_name}.toml")
|
||||
user = load_toml(custom_dir / f"{skill_name}.user.toml")
|
||||
|
||||
merged = deep_merge(defaults, team)
|
||||
merged = deep_merge(merged, user)
|
||||
|
||||
if args.key:
|
||||
output = {}
|
||||
for key in args.key:
|
||||
value = extract_key(merged, key)
|
||||
if value is not _MISSING:
|
||||
output[key] = value
|
||||
else:
|
||||
output = merged
|
||||
|
||||
sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,132 @@
|
||||
import js from "@eslint/js";
|
||||
import jsdoc from "eslint-plugin-jsdoc";
|
||||
import importPlugin from "eslint-plugin-import";
|
||||
import globals from "globals";
|
||||
import { fileURLToPath } from "url";
|
||||
import { dirname } from "path";
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export default [
|
||||
js.configs.recommended,
|
||||
{
|
||||
plugins: {
|
||||
jsdoc,
|
||||
import: importPlugin,
|
||||
},
|
||||
languageOptions: {
|
||||
globals: {
|
||||
// Browser built-ins (console, setTimeout, etc.)
|
||||
...globals.browser,
|
||||
// FoundryVTT globals injected at runtime
|
||||
Hooks: "readonly",
|
||||
game: "readonly",
|
||||
ui: "readonly",
|
||||
canvas: "readonly",
|
||||
foundry: "readonly",
|
||||
CONFIG: "readonly",
|
||||
CONST: "readonly",
|
||||
},
|
||||
},
|
||||
settings: {
|
||||
// Support path aliases for import resolution
|
||||
"import/resolver": {
|
||||
node: {
|
||||
extensions: [".js", ".mjs"],
|
||||
},
|
||||
},
|
||||
},
|
||||
rules: {
|
||||
// Require JSDoc on all exported symbols
|
||||
"jsdoc/require-jsdoc": [
|
||||
"error",
|
||||
{
|
||||
publicOnly: true,
|
||||
require: {
|
||||
FunctionDeclaration: true,
|
||||
MethodDefinition: true,
|
||||
ClassDeclaration: true,
|
||||
ArrowFunctionExpression: false,
|
||||
FunctionExpression: false,
|
||||
},
|
||||
contexts: ["ExportNamedDeclaration > FunctionDeclaration"],
|
||||
},
|
||||
],
|
||||
"jsdoc/require-param": "warn",
|
||||
"jsdoc/require-returns": "warn",
|
||||
|
||||
// Import boundary enforcement
|
||||
"import/no-restricted-paths": [
|
||||
"error",
|
||||
{
|
||||
zones: [
|
||||
// src/core/ → may import src/contracts/ and src/utils/ ONLY
|
||||
{
|
||||
target: "./src/core",
|
||||
from: "./src/foundry",
|
||||
message: "src/core/ must not import from src/foundry/",
|
||||
},
|
||||
{
|
||||
target: "./src/core",
|
||||
from: "./src/ui",
|
||||
message: "src/core/ must not import from src/ui/",
|
||||
},
|
||||
{
|
||||
target: "./src/core",
|
||||
from: "./src/notifications",
|
||||
message: "src/core/ must not import from src/notifications/",
|
||||
},
|
||||
{
|
||||
target: "./src/core",
|
||||
from: "./src/presets",
|
||||
message: "src/core/ must not import from src/presets/",
|
||||
},
|
||||
// src/foundry/ → may import src/contracts/ and src/utils/ ONLY
|
||||
{
|
||||
target: "./src/foundry",
|
||||
from: "./src/core",
|
||||
message: "src/foundry/ must not import from src/core/",
|
||||
},
|
||||
{
|
||||
target: "./src/foundry",
|
||||
from: "./src/ui",
|
||||
message: "src/foundry/ must not import from src/ui/",
|
||||
},
|
||||
{
|
||||
target: "./src/foundry",
|
||||
from: "./src/notifications",
|
||||
message: "src/foundry/ must not import from src/notifications/",
|
||||
},
|
||||
{
|
||||
target: "./src/foundry",
|
||||
from: "./src/presets",
|
||||
message: "src/foundry/ must not import from src/presets/",
|
||||
},
|
||||
// src/contracts/ → no internal imports
|
||||
{
|
||||
target: "./src/contracts",
|
||||
from: "./src",
|
||||
message: "src/contracts/ must not import from other src/ modules",
|
||||
},
|
||||
// src/utils/ → no internal imports
|
||||
{
|
||||
target: "./src/utils",
|
||||
from: "./src",
|
||||
message: "src/utils/ must not import from other src/ modules",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
files: ["tests/**/*.js"],
|
||||
rules: {
|
||||
// Relax JSDoc requirement for test files
|
||||
"jsdoc/require-jsdoc": "off",
|
||||
},
|
||||
},
|
||||
{
|
||||
ignores: ["dist/", "node_modules/", "*.zip"],
|
||||
},
|
||||
];
|
||||
@@ -0,0 +1,3 @@
|
||||
{
|
||||
"video-view-manager": {}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
// @ts-nocheck — Module entry point with FoundryVTT globals, no exports needed
|
||||
/**
|
||||
* module.js — Entry point and wiring diagram for Video View Manager (Scrying Pool).
|
||||
*
|
||||
* This file is the wiring diagram ONLY. It imports all modules, constructs them
|
||||
* with injected dependencies, and holds NO business logic.
|
||||
*
|
||||
* Initialisation order:
|
||||
* Hooks.once('init') → register world settings → construct FoundryAdapter
|
||||
* → StateStore → SocketHandler (queue+drain)
|
||||
* Hooks.once('ready') → VisibilityManager → SocketHandler.setReady()
|
||||
* → NotificationBus → RoleRenderer → RosterStrip
|
||||
* → DirectorsBoard (lazy, GM only)
|
||||
*/
|
||||
|
||||
Hooks.once("init", () => {
|
||||
console.log("[ScryingPool] init — module loading");
|
||||
|
||||
// OQ-1 resolved (Story 1.2 spike): probe result is 'css-fallback' — see FoundryAdapter.js
|
||||
game.settings.register("scrying-pool", "webrtcMode", {
|
||||
scope: "world",
|
||||
config: false,
|
||||
type: String,
|
||||
default: "css-fallback",
|
||||
choices: {
|
||||
"track-disable": "Track Disable (bandwidth-saving)",
|
||||
"css-fallback": "CSS Fallback (cosmetic hiding)",
|
||||
"unsupported": "Unsupported (AV not available)",
|
||||
},
|
||||
});
|
||||
|
||||
// Story 1.3+: register remaining world settings, construct FoundryAdapter, StateStore, SocketHandler
|
||||
});
|
||||
|
||||
Hooks.once("ready", () => {
|
||||
console.log("[ScryingPool] ready — module active");
|
||||
// Story 1.3+: construct VisibilityManager, NotificationBus, RoleRenderer, RosterStrip
|
||||
// Story 1.5+: register DirectorsBoard (lazy, GM only)
|
||||
});
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"id": "video-view-manager",
|
||||
"title": "Video View Manager (Scrying Pool)",
|
||||
"version": "0.1.0",
|
||||
"description": "GM camera visibility control for FoundryVTT v14 — hide, show, and manage participant feeds in real time.",
|
||||
"authors": [
|
||||
{
|
||||
"name": "Morr"
|
||||
}
|
||||
],
|
||||
"compatibility": {
|
||||
"minimum": "14",
|
||||
"verified": "14"
|
||||
},
|
||||
"esmodules": [
|
||||
"module.js"
|
||||
],
|
||||
"styles": [
|
||||
"dist/styles/scrying-pool.css"
|
||||
],
|
||||
"languages": [
|
||||
{
|
||||
"lang": "en",
|
||||
"name": "English",
|
||||
"path": "lang/en.json"
|
||||
}
|
||||
],
|
||||
"flags": {}
|
||||
}
|
||||
Generated
+4972
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,28 @@
|
||||
{
|
||||
"name": "video-view-manager",
|
||||
"version": "0.1.0",
|
||||
"description": "FoundryVTT v14 module — Scrying Pool camera visibility control",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"build": "lessc styles/scrying-pool.less dist/styles/scrying-pool.css",
|
||||
"watch": "chokidar 'styles/**/*.less' -c 'lessc styles/scrying-pool.less dist/styles/scrying-pool.css'",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"lint": "eslint src/ module.js scripts/ tests/",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"release": "node scripts/package.mjs"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@league-of-foundry-developers/foundry-vtt-types": "9.280.1",
|
||||
"@types/node": "22.x",
|
||||
"chokidar": "5.0.0",
|
||||
"eslint": "^9.0.0",
|
||||
"eslint-plugin-import": "^2.31.0",
|
||||
"eslint-plugin-jsdoc": "^50.0.0",
|
||||
"happy-dom": "^20.0.0",
|
||||
"less": "4.6.4",
|
||||
"typescript": "5.9.3",
|
||||
"vitest": "2.1.8",
|
||||
"zip": "^1.0.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* Release script — produces module.zip.
|
||||
*
|
||||
* Single version source of truth: reads version from package.json,
|
||||
* writes it into module.json, then zips all release artefacts.
|
||||
*
|
||||
* Usage: node scripts/package.mjs
|
||||
*/
|
||||
|
||||
import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
|
||||
import { resolve, dirname } from "path";
|
||||
import { fileURLToPath } from "url";
|
||||
import { createGzip } from "zlib";
|
||||
import { exec } from "child_process";
|
||||
import { promisify } from "util";
|
||||
|
||||
const execAsync = promisify(exec);
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const ROOT = resolve(__dirname, "..");
|
||||
|
||||
// Read version from package.json (single source of truth)
|
||||
let pkg;
|
||||
try {
|
||||
pkg = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8"));
|
||||
} catch (err) {
|
||||
console.error("[ScryingPool] Failed to read package.json:", err instanceof Error ? err.message : String(err));
|
||||
process.exit(1);
|
||||
}
|
||||
const { version } = pkg;
|
||||
|
||||
// Write version into module.json
|
||||
const moduleJsonPath = resolve(ROOT, "module.json");
|
||||
let moduleJson;
|
||||
try {
|
||||
moduleJson = JSON.parse(readFileSync(moduleJsonPath, "utf8"));
|
||||
} catch (err) {
|
||||
console.error("[ScryingPool] Failed to read module.json:", err instanceof Error ? err.message : String(err));
|
||||
process.exit(1);
|
||||
}
|
||||
moduleJson.version = version;
|
||||
writeFileSync(moduleJsonPath, JSON.stringify(moduleJson, null, 2) + "\n", "utf8");
|
||||
console.log(`[ScryingPool] module.json version set to ${version}`);
|
||||
|
||||
// Ensure dist/ exists (build should have run first)
|
||||
if (!existsSync(resolve(ROOT, "dist"))) {
|
||||
console.error("[ScryingPool] dist/ not found — run npm run build first");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Files and directories to include in module.zip
|
||||
const INCLUDE = [
|
||||
"module.json",
|
||||
"module.js",
|
||||
"lang/",
|
||||
"templates/",
|
||||
"dist/",
|
||||
"src/",
|
||||
];
|
||||
|
||||
// Build zip using system zip command
|
||||
const targets = INCLUDE.filter((f) => existsSync(resolve(ROOT, f)));
|
||||
// Escape each target path properly for shell execution
|
||||
const zipArgs = targets.map((t) => t.replace(/'/g, "'\\''")).map((t) => `"${t}"`).join(" ");
|
||||
const zipCmd = `cd "${ROOT.replace(/'/g, "'\\''")}" && zip -r module.zip ${zipArgs}`;
|
||||
|
||||
console.log("[ScryingPool] Creating module.zip...");
|
||||
try {
|
||||
await execAsync(zipCmd);
|
||||
console.log(`[ScryingPool] module.zip created (v${version})`);
|
||||
} catch (err) {
|
||||
console.error("[ScryingPool] zip failed:", err instanceof Error ? err.message : String(err));
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
/**
|
||||
* PendingOp contract.
|
||||
*
|
||||
* A PendingOp tracks an in-flight visibility state change from the moment
|
||||
* the GM issues the intent until the authoritative echo is received (or
|
||||
* the 3-second timeout fires and triggers a revert).
|
||||
*
|
||||
* Lifecycle:
|
||||
* create → register in Map<opId, PendingOp>
|
||||
* echo received → delete from map + clearTimeout(timeoutId)
|
||||
* 3s timeout fires → revert to previousState + GM notification
|
||||
*
|
||||
* @module contracts/pending-op
|
||||
*/
|
||||
|
||||
/** @typedef {Object} PendingOp */
|
||||
|
||||
/** Shape version constant for PendingOp. @type {1} */
|
||||
export const PENDING_OP_VERSION = 1;
|
||||
|
||||
/**
|
||||
* @typedef {Object} PendingOp
|
||||
* @property {string} opId - Unique operation identifier (non-empty string).
|
||||
* @property {string} userId - Target participant userId (non-empty string).
|
||||
* @property {string} targetState - Desired VisibilityState (non-empty string).
|
||||
* @property {string} previousState - State before this op; used for revert (non-empty string).
|
||||
* @property {number} issuedAt - Timestamp (ms) when op was issued — Date.now() integer.
|
||||
* @property {number|null} timeoutId - setTimeout handle; null if timeout not yet set.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Creates a new PendingOp.
|
||||
* @param {string} opId - Unique operation identifier.
|
||||
* @param {string} userId - Target participant userId.
|
||||
* @param {string} targetState - Desired VisibilityState.
|
||||
* @param {string} previousState - State before this op.
|
||||
* @param {number} [issuedAt] - Timestamp; defaults to Date.now().
|
||||
* @returns {PendingOp}
|
||||
*/
|
||||
export function createPendingOp(opId, userId, targetState, previousState, issuedAt = Date.now()) {
|
||||
return { opId, userId, targetState, previousState, issuedAt, timeoutId: null };
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a PendingOp DTO. Throws TypeError on any violation.
|
||||
* @param {unknown} data - Value to validate.
|
||||
* @returns {PendingOp} The validated PendingOp.
|
||||
* @throws {TypeError} If data fails validation.
|
||||
*/
|
||||
export function isValidPendingOp(data) {
|
||||
if (data === null || typeof data !== "object") {
|
||||
throw new TypeError("PendingOp: must be an object");
|
||||
}
|
||||
const obj = /** @type {Record<string, unknown>} */ (data);
|
||||
const { opId, userId, targetState, previousState, issuedAt, timeoutId, ...rest } = obj;
|
||||
if (Object.keys(rest).length > 0) {
|
||||
throw new TypeError(`PendingOp: unknown keys: ${Object.keys(rest).join(", ")}`);
|
||||
}
|
||||
if (typeof opId !== "string" || opId.trim().length === 0) {
|
||||
throw new TypeError("PendingOp: opId must be a non-empty string");
|
||||
}
|
||||
if (typeof userId !== "string" || userId.trim().length === 0) {
|
||||
throw new TypeError("PendingOp: userId must be a non-empty string");
|
||||
}
|
||||
if (typeof targetState !== "string" || targetState.trim().length === 0) {
|
||||
throw new TypeError("PendingOp: targetState must be a non-empty string");
|
||||
}
|
||||
if (typeof previousState !== "string" || previousState.trim().length === 0) {
|
||||
throw new TypeError("PendingOp: previousState must be a non-empty string");
|
||||
}
|
||||
if (typeof issuedAt !== "number" || !Number.isFinite(issuedAt) || issuedAt < 0 || !Number.isInteger(issuedAt)) {
|
||||
throw new TypeError("PendingOp: issuedAt must be a finite non-negative integer");
|
||||
}
|
||||
if (timeoutId !== null) {
|
||||
if (typeof timeoutId !== "number") {
|
||||
throw new TypeError("PendingOp: timeoutId must be a number or null");
|
||||
}
|
||||
if (!Number.isFinite(timeoutId) || timeoutId < 0) {
|
||||
throw new TypeError("PendingOp: timeoutId must be a finite non-negative number");
|
||||
}
|
||||
}
|
||||
return /** @type {PendingOp} */ (data);
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
/**
|
||||
* Scene Preset contract.
|
||||
*
|
||||
* A Scene Preset is a named snapshot of the Visibility Matrix, stored as a
|
||||
* flag on a FoundryVTT Scene document. Up to 50 presets per world.
|
||||
*
|
||||
* Storage key: scene.getFlag('video-view-manager', 'preset')
|
||||
* Shape: { _version: 1, presets: { [name: string]: ScenePreset } }
|
||||
*
|
||||
* @module contracts/scene-preset
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {Object} ScenePreset
|
||||
* @property {1} _version - Schema version; always 1 for v1.
|
||||
* @property {string} name - Unique preset name (non-empty string).
|
||||
* @property {Object.<string, string>} matrix - userId→VisibilityState snapshot.
|
||||
* @property {number} createdAt - Timestamp (ms) when preset was created.
|
||||
* @property {number} updatedAt - Timestamp (ms) when preset was last updated.
|
||||
*/
|
||||
|
||||
export const SCENE_PRESET_VERSION = 1;
|
||||
export const MAX_PRESETS_PER_WORLD = 50;
|
||||
|
||||
/**
|
||||
* Creates a new ScenePreset.
|
||||
* @param {string} name - Unique preset name.
|
||||
* @param {Object.<string, string>} [matrix={}] - userId→VisibilityState snapshot.
|
||||
* @param {number} [now] - Timestamp; defaults to Date.now().
|
||||
* @returns {ScenePreset}
|
||||
*/
|
||||
export function createScenePreset(name, matrix = {}, now = Date.now()) {
|
||||
return {
|
||||
_version: SCENE_PRESET_VERSION,
|
||||
name,
|
||||
matrix: { ...matrix },
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a ScenePreset DTO. Throws TypeError on any violation.
|
||||
* @param {unknown} data - Value to validate.
|
||||
* @returns {ScenePreset} The validated preset.
|
||||
* @throws {TypeError} If data fails validation.
|
||||
*/
|
||||
export function isValidScenePreset(data) {
|
||||
if (data === null || typeof data !== "object") {
|
||||
throw new TypeError("ScenePreset: must be an object");
|
||||
}
|
||||
const obj = /** @type {Record<string, unknown>} */ (data);
|
||||
const { _version, name, matrix, createdAt, updatedAt, ...rest } = obj;
|
||||
if (Object.keys(rest).length > 0) {
|
||||
throw new TypeError(`ScenePreset: unknown keys: ${Object.keys(rest).join(", ")}`);
|
||||
}
|
||||
if (_version !== SCENE_PRESET_VERSION) {
|
||||
throw new TypeError(`ScenePreset: _version must be ${SCENE_PRESET_VERSION}, got ${_version}`);
|
||||
}
|
||||
if (typeof name !== "string" || name.length === 0) {
|
||||
throw new TypeError("ScenePreset: name must be a non-empty string");
|
||||
}
|
||||
if (matrix === null || typeof matrix !== "object" || Array.isArray(matrix)) {
|
||||
throw new TypeError("ScenePreset: matrix must be a plain object");
|
||||
}
|
||||
const matrixObj = /** @type {Record<string, unknown>} */ (matrix);
|
||||
for (const [userId, state] of Object.entries(matrixObj)) {
|
||||
if (typeof userId !== "string" || userId.length === 0) {
|
||||
throw new TypeError(`ScenePreset: userId key must be non-empty string, got "${userId}"`);
|
||||
}
|
||||
if (typeof state !== "string" || state.length === 0) {
|
||||
throw new TypeError(`ScenePreset: state for "${userId}" must be a non-empty string`);
|
||||
}
|
||||
}
|
||||
if (typeof createdAt !== "number" || !Number.isFinite(createdAt) || createdAt < 0) {
|
||||
throw new TypeError("ScenePreset: createdAt must be a finite non-negative integer");
|
||||
}
|
||||
if (typeof updatedAt !== "number" || !Number.isFinite(updatedAt) || updatedAt < 0) {
|
||||
throw new TypeError("ScenePreset: updatedAt must be a finite non-negative integer");
|
||||
}
|
||||
return /** @type {ScenePreset} */ (data);
|
||||
}
|
||||
@@ -0,0 +1,132 @@
|
||||
/**
|
||||
* Socket message contract.
|
||||
*
|
||||
* Two message directions:
|
||||
* Intent (GM → all): scrying-pool.visibility.set { opId, userId, targetState }
|
||||
* Echo (all ← GM): scrying-pool.visibility.updated { opId, userId, state, revision }
|
||||
*
|
||||
* Validated at both send and receive. Payload ≥ 4096 bytes → throw before emit.
|
||||
*
|
||||
* @module contracts/socket-message
|
||||
*/
|
||||
|
||||
/** @typedef {'scrying-pool.visibility.set'|'scrying-pool.visibility.updated'|'scrying-pool.preset.apply'|'scrying-pool.preset.applied'} SocketEventName */
|
||||
|
||||
/**
|
||||
* @typedef {Object} SocketIntentPayload
|
||||
* @property {string} opId - Unique operation ID (non-empty string).
|
||||
* @property {string} userId - Target participant userId (non-empty string).
|
||||
* @property {string} targetState - Desired VisibilityState.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {Object} SocketEchoPayload
|
||||
* @property {string} opId - Matches the originating intent opId.
|
||||
* @property {string} userId - Affected participant userId.
|
||||
* @property {string} state - Authoritative VisibilityState after this operation.
|
||||
* @property {number} revision - Monotonically increasing revision counter.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {Object} SocketMessage
|
||||
* @property {SocketEventName} event - Socket event name.
|
||||
* @property {SocketIntentPayload|SocketEchoPayload} payload - Message payload.
|
||||
*/
|
||||
|
||||
export const SOCKET_EVENTS = Object.freeze({
|
||||
VISIBILITY_SET: "scrying-pool.visibility.set",
|
||||
VISIBILITY_UPDATED: "scrying-pool.visibility.updated",
|
||||
PRESET_APPLY: "scrying-pool.preset.apply",
|
||||
PRESET_APPLIED: "scrying-pool.preset.applied",
|
||||
});
|
||||
|
||||
export const MAX_PAYLOAD_BYTES = 4096;
|
||||
|
||||
/**
|
||||
* Creates a socket intent message (GM → all clients).
|
||||
* @param {string} opId - Unique operation ID.
|
||||
* @param {string} userId - Target participant userId.
|
||||
* @param {string} targetState - Desired VisibilityState.
|
||||
* @returns {SocketMessage}
|
||||
*/
|
||||
export function createSocketIntentMessage(opId, userId, targetState) {
|
||||
return {
|
||||
event: SOCKET_EVENTS.VISIBILITY_SET,
|
||||
payload: { opId, userId, targetState },
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a socket echo message (authoritative broadcast to all clients).
|
||||
* @param {string} opId - Originating intent opId.
|
||||
* @param {string} userId - Affected participant userId.
|
||||
* @param {string} state - Authoritative VisibilityState.
|
||||
* @param {number} revision - Revision counter.
|
||||
* @returns {SocketMessage}
|
||||
*/
|
||||
export function createSocketEchoMessage(opId, userId, state, revision) {
|
||||
return {
|
||||
event: SOCKET_EVENTS.VISIBILITY_UPDATED,
|
||||
payload: { opId, userId, state, revision },
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a SocketMessage DTO. Throws TypeError on any violation.
|
||||
* @param {unknown} data - Value to validate.
|
||||
* @returns {SocketMessage} The validated message.
|
||||
* @throws {TypeError} If data fails validation.
|
||||
*/
|
||||
export function isValidSocketMessage(data) {
|
||||
if (data === null || typeof data !== "object") {
|
||||
throw new TypeError("SocketMessage: must be an object");
|
||||
}
|
||||
const obj = /** @type {Record<string, unknown>} */ (data);
|
||||
const { event, payload, ...rest } = obj;
|
||||
if (Object.keys(rest).length > 0) {
|
||||
throw new TypeError(`SocketMessage: unknown keys: ${Object.keys(rest).join(", ")}`);
|
||||
}
|
||||
if (!Object.values(SOCKET_EVENTS).includes(/** @type {any} */ (event))) {
|
||||
throw new TypeError(`SocketMessage: unknown event "${event}"`);
|
||||
}
|
||||
if (payload === null || typeof payload !== "object") {
|
||||
throw new TypeError("SocketMessage: payload must be an object");
|
||||
}
|
||||
const p = /** @type {Record<string, unknown>} */ (payload);
|
||||
// Validate intent payload
|
||||
if (event === SOCKET_EVENTS.VISIBILITY_SET) {
|
||||
const { opId, userId, targetState, ...payloadRest } = p;
|
||||
if (Object.keys(payloadRest).length > 0) {
|
||||
throw new TypeError(`SocketMessage intent: unknown payload keys: ${Object.keys(payloadRest).join(", ")}`);
|
||||
}
|
||||
if (typeof opId !== "string" || opId.length === 0) {
|
||||
throw new TypeError("SocketMessage: opId must be a non-empty string");
|
||||
}
|
||||
if (typeof userId !== "string" || userId.length === 0) {
|
||||
throw new TypeError("SocketMessage: userId must be a non-empty string");
|
||||
}
|
||||
if (typeof targetState !== "string" || targetState.length === 0) {
|
||||
throw new TypeError("SocketMessage: targetState must be a non-empty string");
|
||||
}
|
||||
}
|
||||
// Validate echo payload
|
||||
if (event === SOCKET_EVENTS.VISIBILITY_UPDATED) {
|
||||
const { opId, userId, state, revision, ...payloadRest } = p;
|
||||
if (Object.keys(payloadRest).length > 0) {
|
||||
throw new TypeError(`SocketMessage echo: unknown payload keys: ${Object.keys(payloadRest).join(", ")}`);
|
||||
}
|
||||
if (typeof opId !== "string" || opId.length === 0) {
|
||||
throw new TypeError("SocketMessage: opId must be a non-empty string");
|
||||
}
|
||||
if (typeof userId !== "string" || userId.length === 0) {
|
||||
throw new TypeError("SocketMessage: userId must be a non-empty string");
|
||||
}
|
||||
if (typeof state !== "string" || state.length === 0) {
|
||||
throw new TypeError("SocketMessage: state must be a non-empty string");
|
||||
}
|
||||
if (typeof revision !== "number" || !Number.isFinite(revision) || revision < 0) {
|
||||
throw new TypeError("SocketMessage: revision must be a finite non-negative number");
|
||||
}
|
||||
}
|
||||
return /** @type {SocketMessage} */ (data);
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* Visibility Matrix contract.
|
||||
*
|
||||
* Canonical shape: { _version: 1, matrix: { [userId: string]: VisibilityState } }
|
||||
* where VisibilityState ∈ VISIBILITY_STATES.
|
||||
*
|
||||
* StateStore is the sole writer of this structure. All other modules treat it as read-only.
|
||||
*
|
||||
* @module contracts/visibility-matrix
|
||||
*/
|
||||
|
||||
/** @typedef {'active'|'hidden'|'self-muted'|'offline'|'cam-lost'|'reconnecting'|'never-connected'|'ghost'} VisibilityState */
|
||||
|
||||
/**
|
||||
* @typedef {Object} VisibilityMatrix
|
||||
* @property {1} _version - Schema version; always 1 for v1.
|
||||
* @property {Object.<string, VisibilityState>} matrix - userId → VisibilityState map.
|
||||
*/
|
||||
|
||||
export const VISIBILITY_STATES = Object.freeze([
|
||||
"active",
|
||||
"hidden",
|
||||
"self-muted",
|
||||
"offline",
|
||||
"cam-lost",
|
||||
"reconnecting",
|
||||
"never-connected",
|
||||
"ghost",
|
||||
]);
|
||||
|
||||
export const VISIBILITY_MATRIX_VERSION = 1;
|
||||
|
||||
/**
|
||||
* Creates a new VisibilityMatrix with an optional initial matrix.
|
||||
* @param {Object.<string, VisibilityState>} [matrix={}] - Initial userId→state entries.
|
||||
* @returns {VisibilityMatrix}
|
||||
*/
|
||||
export function createVisibilityMatrix(matrix = {}) {
|
||||
return { _version: VISIBILITY_MATRIX_VERSION, matrix: { ...matrix } };
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a VisibilityMatrix DTO. Throws TypeError on any violation.
|
||||
* @param {unknown} data - Value to validate.
|
||||
* @returns {VisibilityMatrix} The validated matrix.
|
||||
* @throws {TypeError} If data fails validation.
|
||||
*/
|
||||
export function isValidVisibilityMatrix(data) {
|
||||
if (data === null || typeof data !== "object") {
|
||||
throw new TypeError("VisibilityMatrix: must be an object");
|
||||
}
|
||||
const obj = /** @type {Record<string, unknown>} */ (data);
|
||||
const { _version, matrix, ...rest } = obj;
|
||||
if (Object.keys(rest).length > 0) {
|
||||
throw new TypeError(`VisibilityMatrix: unknown keys: ${Object.keys(rest).join(", ")}`);
|
||||
}
|
||||
if (_version !== VISIBILITY_MATRIX_VERSION) {
|
||||
throw new TypeError(`VisibilityMatrix: _version must be ${VISIBILITY_MATRIX_VERSION}, got ${_version}`);
|
||||
}
|
||||
if (matrix === null || typeof matrix !== "object" || Array.isArray(matrix)) {
|
||||
throw new TypeError("VisibilityMatrix: matrix must be a plain object");
|
||||
}
|
||||
const matrixObj = /** @type {Record<string, unknown>} */ (matrix);
|
||||
for (const [userId, state] of Object.entries(matrixObj)) {
|
||||
if (typeof userId !== "string" || userId.length === 0) {
|
||||
throw new TypeError(`VisibilityMatrix: userId must be a non-empty string, got "${userId}"`);
|
||||
}
|
||||
if (!VISIBILITY_STATES.includes(/** @type {any} */ (state))) {
|
||||
throw new TypeError(`VisibilityMatrix: invalid state "${state}" for userId "${userId}"`);
|
||||
}
|
||||
}
|
||||
return /** @type {VisibilityMatrix} */ (data);
|
||||
}
|
||||
@@ -0,0 +1,118 @@
|
||||
// OQ-1 Spike Result: css-fallback — FoundryVTT v14 — 2026-05-21
|
||||
//
|
||||
// Investigation findings (Story 1.2 spike):
|
||||
// - game.webrtc is foundry.av.AVMaster — no getConnection(userId) method exists.
|
||||
// - Remote stream access: game.webrtc.client.getMediaStreamForUser(userId)
|
||||
// via the abstract AVClient public interface.
|
||||
// - track.enabled = false on remote inbound tracks does NOT stop WebRTC bandwidth.
|
||||
// RTP packets continue arriving from the remote peer regardless.
|
||||
// - True bandwidth elimination requires SDP renegotiation (not in AVMaster public API).
|
||||
// - LiveKit backend (CONFIG.WebRTC.clientClass override) removes peers/remoteStreams;
|
||||
// only getMediaStreamForUser() remains safe across backends.
|
||||
//
|
||||
// Conclusion: this.webrtc = null. scrying-pool.webrtcMode = 'css-fallback' (world default).
|
||||
// CSS/DOM cosmetic hiding is the only honest implementation path for Story 1.3+.
|
||||
|
||||
/**
|
||||
* Sole gateway to game.* APIs for the Scrying Pool module.
|
||||
*
|
||||
* Feature-detects WebRTC track-disabling capability at init time via
|
||||
* {@link FoundryAdapter.probeCapability}. Exposes a `webrtc` surface
|
||||
* ({disableTrack, enableTrack}) if track-disable is confirmed; `null` otherwise.
|
||||
*
|
||||
* Construction is side-effect-free. The webrtc property must be set by the
|
||||
* caller (at Hooks.once('ready') when game.webrtc is available) via
|
||||
* {@link FoundryAdapter.buildWebRTCSurface}. Story 1.3 wires this up.
|
||||
*/
|
||||
export class FoundryAdapter {
|
||||
/** Settings namespace for all scrying-pool world settings. */
|
||||
static SETTINGS_NS = 'scrying-pool';
|
||||
|
||||
/**
|
||||
* World setting key for the resolved WebRTC capability mode.
|
||||
* Full identifier: `scrying-pool.webrtcMode`.
|
||||
* Value is one of: `'track-disable'` | `'css-fallback'` | `'unsupported'`
|
||||
*/
|
||||
static SETTING_WEBRTC_MODE = 'webrtcMode';
|
||||
|
||||
/**
|
||||
* Creates a FoundryAdapter. Side-effect-free — no game.* access in constructor.
|
||||
*/
|
||||
constructor() {
|
||||
/**
|
||||
* WebRTC track-disabling surface, or null on the css-fallback/unsupported path.
|
||||
*
|
||||
* Set to `{ disableTrack, enableTrack }` only if probeCapability returns
|
||||
* `'track-disable'`. As of FoundryVTT v14, the probe always returns
|
||||
* `'css-fallback'` or `'unsupported'` — see OQ-1 spike comment at top of file.
|
||||
*
|
||||
* @type {{ disableTrack(userId: string): void, enableTrack(userId: string): void } | null}
|
||||
*/
|
||||
this.webrtc = null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Probes the game.webrtc (AVMaster) instance for WebRTC track-disabling capability.
|
||||
*
|
||||
* Probe logic and results (FoundryVTT v14, 2026-05-21):
|
||||
* - If game.webrtc is null/falsy → AV disabled or not yet initialised → `'unsupported'`
|
||||
* - If game.webrtc.client lacks getMediaStreamForUser() → non-standard backend → `'unsupported'`
|
||||
* - Otherwise: tracks are technically reachable but track.enabled = false does NOT reduce
|
||||
* inbound WebRTC bandwidth (RTP packets keep arriving). The `'track-disable'` outcome
|
||||
* requires true bandwidth elimination, so the result is `'css-fallback'`.
|
||||
*
|
||||
* The `'track-disable'` branch in buildWebRTCSurface is kept for forward compatibility
|
||||
* in case a future FoundryVTT version or custom AVClient exposes real bandwidth control.
|
||||
*
|
||||
* @param {unknown} gameWebrtc - The game.webrtc value at ready time (may be null/undefined)
|
||||
* @returns {'track-disable'|'css-fallback'|'unsupported'}
|
||||
*/
|
||||
static probeCapability(gameWebrtc) {
|
||||
if (!gameWebrtc) return 'unsupported';
|
||||
const client = /** @type {any} */ (gameWebrtc).client;
|
||||
if (!client || typeof client.getMediaStreamForUser !== 'function') return 'unsupported';
|
||||
// track.enabled = false on remote inbound tracks does NOT stop WebRTC bandwidth.
|
||||
// The 'track-disable' branch is unreachable with the current FoundryVTT v14 API.
|
||||
return 'css-fallback';
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds the webrtc surface object for the `'track-disable'` capability path.
|
||||
*
|
||||
* NOTE: As of FoundryVTT v14, {@link FoundryAdapter.probeCapability} never returns
|
||||
* `'track-disable'` because `track.enabled = false` does not stop inbound RTP bandwidth.
|
||||
* This method is kept for forward compatibility and as tested documentation of the
|
||||
* interface contract that Story 1.3+ consumers expect.
|
||||
*
|
||||
* @param {{ client: { getMediaStreamForUser(userId: string): (MediaStream|null|undefined) } }} gameWebrtc
|
||||
* @returns {{ disableTrack(userId: string): void, enableTrack(userId: string): void }}
|
||||
*/
|
||||
static buildWebRTCSurface(gameWebrtc) {
|
||||
return {
|
||||
disableTrack(userId) {
|
||||
try {
|
||||
const stream = gameWebrtc.client.getMediaStreamForUser(userId);
|
||||
const tracks = stream?.getVideoTracks() ?? [];
|
||||
for (const track of tracks) track.enabled = false;
|
||||
if (tracks.length === 0) {
|
||||
console.warn('[ScryingPool] disableTrack: no video tracks found for', userId);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error('[ScryingPool] disableTrack failed:', err);
|
||||
}
|
||||
},
|
||||
enableTrack(userId) {
|
||||
try {
|
||||
const stream = gameWebrtc.client.getMediaStreamForUser(userId);
|
||||
const tracks = stream?.getVideoTracks() ?? [];
|
||||
for (const track of tracks) track.enabled = true;
|
||||
if (tracks.length === 0) {
|
||||
console.warn('[ScryingPool] enableTrack: no video tracks found for', userId);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error('[ScryingPool] enableTrack failed:', err);
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
Vendored
+12
@@ -0,0 +1,12 @@
|
||||
/**
|
||||
* Minimal FoundryVTT global type declarations for type-checking the module entry point.
|
||||
* The `Hooks` object is provided by FoundryVTT at runtime as a browser global.
|
||||
*/
|
||||
|
||||
declare const Hooks: {
|
||||
once(event: string, fn: (...args: unknown[]) => void): void;
|
||||
on(event: string, fn: (...args: unknown[]) => void): void;
|
||||
off(event: string, fn: (...args: unknown[]) => void): void;
|
||||
call(event: string, ...args: unknown[]): boolean;
|
||||
callAll(event: string, ...args: unknown[]): boolean;
|
||||
};
|
||||
@@ -0,0 +1,7 @@
|
||||
/**
|
||||
* Generates a unique operation ID for PendingOp tracking.
|
||||
* @returns {string} A unique identifier string.
|
||||
*/
|
||||
export function generateOpId() {
|
||||
return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,3 @@
|
||||
// All selectors MUST be scoped under .scrying-pool.
|
||||
// Use --sp-* tokens only — no Foundry --color-* / --font-* / --border-* tokens allowed.
|
||||
// Implemented in story 1.5+.
|
||||
@@ -0,0 +1,55 @@
|
||||
/**
|
||||
* styles/scrying-pool.less — Entry point (@imports only)
|
||||
*
|
||||
* Build: npm run build → dist/styles/scrying-pool.css
|
||||
* Watch: npm run watch (chokidar detects changes in @import-ed partials)
|
||||
*
|
||||
* Import order: tokens (base → states → motion → focus) → components
|
||||
*/
|
||||
|
||||
// ── Token layers ─────────────────────────────────────────────────────────────
|
||||
@import "tokens/_base.less";
|
||||
@import "tokens/_states.less";
|
||||
@import "tokens/_motion.less";
|
||||
@import "tokens/_focus.less";
|
||||
|
||||
// ── Component styles ──────────────────────────────────────────────────────────
|
||||
@import "components/_participant-card.less";
|
||||
@import "components/_roster-strip.less";
|
||||
@import "components/_directors-board.less";
|
||||
@import "components/_scene-preset-panel.less";
|
||||
@import "components/_notification.less";
|
||||
@import "components/_player-badge.less";
|
||||
@import "components/_player-panel.less";
|
||||
|
||||
/*
|
||||
* VisibilityBadge :root exception
|
||||
* ─────────────────────────────────────────────────────────────────────────────
|
||||
* PlayerStatusBadge (FR-22) is mounted directly onto Foundry's AV tile DOM,
|
||||
* OUTSIDE the .scrying-pool root element. Its state tokens must therefore be
|
||||
* declared on :root rather than scoped under .scrying-pool.
|
||||
*
|
||||
* This is an intentional architectural exception — all other module CSS MUST
|
||||
* remain scoped under .scrying-pool. Do not add additional :root declarations
|
||||
* without documenting the architectural reason here.
|
||||
*
|
||||
* The badge tokens are a subset of the Layer 2 state tokens declared in
|
||||
* _states.less, re-exported on :root for badge accessibility outside the root.
|
||||
*/
|
||||
:root {
|
||||
--sp-badge-state-active-bg: var(--sp-state-active-bg);
|
||||
--sp-badge-state-active-text: var(--sp-state-active-text);
|
||||
--sp-badge-state-hidden-bg: var(--sp-state-hidden-bg);
|
||||
--sp-badge-state-hidden-text: var(--sp-state-hidden-text);
|
||||
--sp-badge-state-self-muted-bg: var(--sp-state-self-muted-bg);
|
||||
--sp-badge-state-self-muted-text: var(--sp-state-self-muted-text);
|
||||
--sp-badge-state-offline-bg: var(--sp-state-offline-bg);
|
||||
--sp-badge-state-offline-text: var(--sp-state-offline-text);
|
||||
--sp-badge-state-cam-lost-bg: var(--sp-state-cam-lost-bg);
|
||||
--sp-badge-state-cam-lost-text: var(--sp-state-cam-lost-text);
|
||||
--sp-badge-state-reconnecting-bg: var(--sp-state-reconnecting-bg);
|
||||
--sp-badge-state-reconnecting-text: var(--sp-state-reconnecting-text);
|
||||
/* Badge surface & text (badge mounts outside .scrying-pool root) */
|
||||
--sp-badge-surface: var(--sp-badge-bg, rgba(0, 0, 0, 0.72));
|
||||
--sp-badge-color: var(--sp-badge-text, #dde2e8);
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
/**
|
||||
* styles/tokens/_base.less
|
||||
*
|
||||
* Layer 1 — SP Semantic Alias Tokens
|
||||
*
|
||||
* Thin alias layer mapping to Foundry CSS tokens in one place.
|
||||
* If Foundry renames or shifts token semantics between versions,
|
||||
* only this layer needs updating.
|
||||
*
|
||||
* RULE: All Foundry --color-* / --font-* / --border-* tokens are FORBIDDEN
|
||||
* inside .scrying-pool CSS. Always use --sp-* aliases. This is the sole
|
||||
* enforcement point for the semantic layer.
|
||||
*
|
||||
* Every token includes a hardcoded fallback for environments where the
|
||||
* upstream Foundry token is absent.
|
||||
*/
|
||||
|
||||
:root {
|
||||
/* Surface & structure */
|
||||
--sp-surface: var(--sp-theme-surface, var(--color-bg-option, #141618));
|
||||
--sp-surface-raised: var(--sp-theme-surface-raised, #1c1f22);
|
||||
--sp-border: var(--sp-theme-border, var(--color-border, #282c30));
|
||||
|
||||
/* Typography */
|
||||
--sp-text-primary: var(--sp-theme-text-primary, var(--color-text-primary, #dde2e8));
|
||||
--sp-text-secondary: var(--sp-theme-text-secondary,var(--color-text-secondary, #7a8390));
|
||||
--sp-text-muted: var(--sp-theme-text-muted, #555d66);
|
||||
|
||||
/* Accent & interaction */
|
||||
--sp-accent: var(--sp-theme-accent, var(--color-warm-2, #4a9e6b));
|
||||
--sp-surface-interactive: var(--sp-theme-interactive, #242830);
|
||||
--sp-control-bg: var(--sp-theme-control, #1a1d20);
|
||||
|
||||
/* Focus ring — module-wide keyboard navigation anchor */
|
||||
--sp-focus: var(--sp-theme-focus, var(--color-focus-outline, #63c287));
|
||||
--sp-focus-ring: 0 0 0 2px var(--sp-focus);
|
||||
|
||||
/* Badge */
|
||||
--sp-badge-bg: rgba(0, 0, 0, 0.72);
|
||||
--sp-badge-text: var(--sp-text-primary);
|
||||
|
||||
/* Background operations = no toast ever (silent by design) */
|
||||
}
|
||||
|
||||
/* Theme overrides — dark theme defaults */
|
||||
.scrying-pool,
|
||||
:root[data-color-scheme="dark"] {
|
||||
--sp-theme-surface: #141618;
|
||||
--sp-theme-surface-raised: #1c1f22;
|
||||
--sp-theme-border: #282c30;
|
||||
--sp-theme-text-primary: #dde2e8;
|
||||
--sp-theme-text-secondary: #7a8390;
|
||||
--sp-theme-text-muted: #555d66;
|
||||
--sp-theme-accent: #4a9e6b;
|
||||
--sp-theme-interactive: #242830;
|
||||
--sp-theme-control: #1a1d20;
|
||||
--sp-theme-focus: #63c287;
|
||||
--sp-theme-urgency: #c8982a;
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
/**
|
||||
* styles/tokens/_focus.less
|
||||
*
|
||||
* Module-wide focus ring pattern.
|
||||
*
|
||||
* High-contrast outer ring + inner offset that must survive all 9 state
|
||||
* background combinations and both Foundry dark/light themes.
|
||||
* Never rely on browser default focus outline alone.
|
||||
*
|
||||
* Applied via: .scrying-pool *:focus-visible
|
||||
*/
|
||||
|
||||
.scrying-pool {
|
||||
*:focus-visible {
|
||||
outline: none; /* suppress browser default - visible fallback via box-shadow */
|
||||
box-shadow: var(--sp-focus-ring), 0 0 0 4px var(--sp-surface);
|
||||
/* Inner offset (--sp-surface) creates separation so the ring is visible
|
||||
against any state background. The outer ring uses --sp-focus (#63c287).
|
||||
NOTE: Parent containers must NOT have overflow:hidden to avoid clipping. */
|
||||
}
|
||||
|
||||
/* Elevated contrast for interactive elements with state backgrounds */
|
||||
[role="button"]:focus-visible,
|
||||
button:focus-visible {
|
||||
outline: none;
|
||||
box-shadow:
|
||||
0 0 0 2px var(--sp-surface), /* inner offset */
|
||||
0 0 0 4px var(--sp-focus); /* outer ring */
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,80 @@
|
||||
/**
|
||||
* styles/tokens/_motion.less
|
||||
*
|
||||
* Layer 3/4 — SP Urgency Tier & Motion Tokens
|
||||
*
|
||||
* ALL animated token usages MUST be inside:
|
||||
* @media (prefers-reduced-motion: no-preference) { ... }
|
||||
*
|
||||
* Fallback (reduced motion): instant state change with icon/state signal only.
|
||||
* No layout/size animations — only opacity, background-color, border-color.
|
||||
*
|
||||
* Motion tokens:
|
||||
* --sp-fade-hide : Player client opacity fade on hide (300–500ms ease-out)
|
||||
* --sp-pulse-reconnecting : StateRing pulse for reconnecting state (lighthouse rhythm)
|
||||
* --sp-shimmer-degraded : cam-lost shimmer (single blink, not looping)
|
||||
* --sp-toast-delay : Director-cue toast delay after hide action
|
||||
*/
|
||||
|
||||
/* ─── Motion token values ─────────────────────────────────────────────────── */
|
||||
|
||||
:root {
|
||||
--sp-fade-hide: 300ms ease-out; /* Player only — GM sees instant state change */
|
||||
--sp-pulse-reconnecting: 1.5s ease-in-out infinite;
|
||||
--sp-shimmer-degraded: 800ms ease-in-out 1; /* single blink, not looping */
|
||||
--sp-toast-delay: 1s; /* Director-cue toast delay */
|
||||
--sp-transition-state: 200ms ease-out; /* Generic state token transition */
|
||||
|
||||
/* Urgency tokens (Layer 3 per AC7) — NEVER inherit Foundry error/warn colours */
|
||||
/* Director cues = deliberate stage direction, not a failure. */
|
||||
--sp-urgency-director: var(--sp-theme-urgency, #c8982a);
|
||||
--sp-urgency-awareness: var(--sp-text-secondary);
|
||||
}
|
||||
|
||||
/* ─── Keyframe animations ─────────────────────────────────────────────────── */
|
||||
|
||||
@media (prefers-reduced-motion: no-preference) {
|
||||
@keyframes sp-pulse {
|
||||
0%, 100% { opacity: 1; }
|
||||
50% { opacity: 0.45; }
|
||||
}
|
||||
|
||||
@keyframes sp-shimmer {
|
||||
0% { opacity: 1; }
|
||||
50% { opacity: 0.3; }
|
||||
100% { opacity: 1; }
|
||||
}
|
||||
|
||||
@keyframes sp-fade-out {
|
||||
from { opacity: 1; }
|
||||
to { opacity: 0; }
|
||||
}
|
||||
|
||||
/* Reconnecting ring pulse — applied via .sp-state-ring--pulse */
|
||||
.sp-state-ring--pulse {
|
||||
animation: sp-pulse var(--sp-pulse-reconnecting);
|
||||
}
|
||||
|
||||
/* cam-lost shimmer — applied via .sp-state-cam-lost */
|
||||
.sp-state-cam-lost .sp-state-ring--dashed {
|
||||
animation: sp-shimmer var(--sp-shimmer-degraded);
|
||||
}
|
||||
}
|
||||
|
||||
/* ─── Reduced motion overrides (global) ──────────────────────────────────── */
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
/* Target specific animated elements instead of universal selector */
|
||||
.sp-state-ring--pulse,
|
||||
.sp-state-cam-lost .sp-state-ring--dashed {
|
||||
animation: none;
|
||||
transition: none;
|
||||
}
|
||||
}
|
||||
|
||||
/* ─── Allowed transitions (opacity, background-color, border-color only) ─── */
|
||||
/*
|
||||
Transitions on layout properties (width, height, max-height, transform) are
|
||||
forbidden except for the ScryingPoolStrip collapsed ↔ expanded toggle which
|
||||
uses max-width exclusively (never width animation).
|
||||
*/
|
||||
@@ -0,0 +1,101 @@
|
||||
/**
|
||||
* styles/tokens/_states.less
|
||||
*
|
||||
* Layer 2 — SP Participant State Tokens
|
||||
*
|
||||
* All 8 participant states + 1 pending state (9 total).
|
||||
* Each state provides three CSS custom properties:
|
||||
* --sp-state-{name}-text — foreground / icon colour
|
||||
* --sp-state-{name}-border — ring / border colour
|
||||
* --sp-state-{name}-bg — background tint colour
|
||||
*
|
||||
* SECOND-SIGNAL RULE (WCAG):
|
||||
* Every state conveys meaning via THREE independent channels:
|
||||
* colour + icon (Font Awesome codepoint) + shape (ring variant).
|
||||
* States marked ⚠️ below have low contrast ratios and MUST NOT
|
||||
* appear as text or small-pill foreground — icon + shape carry the signal.
|
||||
*
|
||||
* State precedence (VisibilityManager/RoleRenderer resolves; CSS never handles multi-state):
|
||||
* pending > cam-lost > reconnecting > offline > never-connected > self-muted > hidden > ghost > active
|
||||
*
|
||||
* LESS state map — single source of truth for loop-generated component CSS.
|
||||
*/
|
||||
|
||||
/* ─── State colour variables ─────────────────────────────────────────────── */
|
||||
|
||||
:root {
|
||||
/* active — Intentional / positive */
|
||||
/* ✅ WCAG AA safe */
|
||||
--sp-state-active-text: #4a9e6b;
|
||||
--sp-state-active-border: #4a9e6b;
|
||||
--sp-state-active-bg: rgba(74, 158, 107, 0.12);
|
||||
|
||||
/* hidden — Intentional / deliberate (GM action) */
|
||||
/* ⚠️ Low contrast (~3.75:1) — icon + dashed ring carry the signal */
|
||||
--sp-state-hidden-text: #6b7280;
|
||||
--sp-state-hidden-border: #6b7280;
|
||||
--sp-state-hidden-bg: rgba(107, 114, 128, 0.10);
|
||||
|
||||
/* self-muted — Self / player's own choice */
|
||||
/* ✅ WCAG AA safe */
|
||||
--sp-state-self-muted-text: #8b92a5;
|
||||
--sp-state-self-muted-border: #8b92a5;
|
||||
--sp-state-self-muted-bg: rgba(139, 146, 165, 0.10);
|
||||
|
||||
/* offline — Technical / disconnected */
|
||||
/* ⚠️ Low contrast (~2.4:1) — icon + no-ring shape carry the signal */
|
||||
--sp-state-offline-text: #4b5563;
|
||||
--sp-state-offline-border: #4b5563;
|
||||
--sp-state-offline-bg: rgba(75, 85, 99, 0.08);
|
||||
|
||||
/* cam-lost — Technical / camera failure */
|
||||
/* ✅ WCAG AA safe */
|
||||
--sp-state-cam-lost-text: #9ca3af;
|
||||
--sp-state-cam-lost-border: #9ca3af;
|
||||
--sp-state-cam-lost-bg: rgba(156, 163, 175, 0.10);
|
||||
|
||||
/* reconnecting — Technical / in-progress */
|
||||
/* ✅ WCAG AA safe */
|
||||
--sp-state-reconnecting-text: #c8982a;
|
||||
--sp-state-reconnecting-border: #c8982a;
|
||||
--sp-state-reconnecting-bg: rgba(200, 152, 42, 0.12);
|
||||
|
||||
/* never-connected — Passive / never joined */
|
||||
/* ⚠️ Low contrast (~1.76:1) — empty circle + no icon carries the signal */
|
||||
--sp-state-never-connected-text: #374151;
|
||||
--sp-state-never-connected-border: #374151;
|
||||
--sp-state-never-connected-bg: rgba(55, 65, 81, 0.06);
|
||||
|
||||
/* ghost — Passive / placeholder slot */
|
||||
/* ⚠️ Very low contrast (~1.24:1) — ghost icon + dotted ring, lowest opacity */
|
||||
--sp-state-ghost-text: #1f2937;
|
||||
--sp-state-ghost-border: #1f2937;
|
||||
--sp-state-ghost-bg: rgba(31, 41, 55, 0.04);
|
||||
|
||||
/* pending — Optimistic UI in-flight (transient; never persisted) */
|
||||
--sp-state-pending-text: #7a8390;
|
||||
--sp-state-pending-border: #7a8390;
|
||||
--sp-state-pending-bg: rgba(122, 131, 144, 0.10);
|
||||
}
|
||||
|
||||
/* ─── Font Awesome icon codepoints (used in component CSS via content: "\f...") ── */
|
||||
/*
|
||||
active: '\f06e' (eye)
|
||||
hidden: '\f070' (eye-slash)
|
||||
self-muted: '\f131' (microphone-slash)
|
||||
offline: '\f00d' (times / user-slash)
|
||||
cam-lost: '\f03d' (video-slash / film)
|
||||
reconnecting: '\f021' (sync/spinner)
|
||||
never-connected: '\f068' (minus / em-dash)
|
||||
ghost: '\f2be' (ghost / user-secret)
|
||||
pending: '\f110' (spinner)
|
||||
*/
|
||||
|
||||
/* ─── State ring shape variants (applied via sp-state-ring--* modifier) ──── */
|
||||
/*
|
||||
solid → active, self-muted
|
||||
dashed → hidden, cam-lost
|
||||
pulse → reconnecting, pending (animation in _motion.less)
|
||||
dotted → ghost
|
||||
none → offline, never-connected
|
||||
*/
|
||||
@@ -0,0 +1,2 @@
|
||||
{{!-- Directors Board - primary GM camera-management UI --}}
|
||||
<div class="scrying-pool directors-board" role="region" aria-label="Directors Board" data-component="directors-board"></div>
|
||||
@@ -0,0 +1,2 @@
|
||||
{{!-- Participant Card - single participant row in the Directors Board --}}
|
||||
<div class="scrying-pool participant-card" role="region" aria-label="Participant Card" data-component="participant-card"></div>
|
||||
@@ -0,0 +1,2 @@
|
||||
{{!-- Player Panel - read-only player-facing visibility badge panel --}}
|
||||
<div class="scrying-pool player-panel" role="region" aria-label="Player Panel" data-component="player-panel"></div>
|
||||
@@ -0,0 +1,2 @@
|
||||
{{!-- Roster Strip - compact inline visibility strip (outside .scrying-pool root) --}}
|
||||
<div class="scrying-pool roster-strip" role="region" aria-label="Roster Strip" data-component="roster-strip"></div>
|
||||
@@ -0,0 +1,2 @@
|
||||
{{!-- Scene Preset Panel - preset save-load interface --}}
|
||||
<div class="scrying-pool scene-preset-panel" role="region" aria-label="Scene Preset Panel" data-component="scene-preset-panel"></div>
|
||||
Vendored
+46
@@ -0,0 +1,46 @@
|
||||
/**
|
||||
* tests/fixtures/pending-op.js
|
||||
*
|
||||
* PendingOp fixtures — frozen. Includes: valid, timeoutId null, expired issuedAt.
|
||||
*/
|
||||
|
||||
export const PENDING_OP_FIXTURES = Object.freeze({
|
||||
valid: Object.freeze({
|
||||
opId: "op-001",
|
||||
userId: "user-abc",
|
||||
targetState: "hidden",
|
||||
previousState: "active",
|
||||
issuedAt: 1700000000000,
|
||||
timeoutId: 42,
|
||||
}),
|
||||
|
||||
// timeoutId: null — timeout not yet set
|
||||
timeoutNull: Object.freeze({
|
||||
opId: "op-002",
|
||||
userId: "user-abc",
|
||||
targetState: "active",
|
||||
previousState: "hidden",
|
||||
issuedAt: 1700000000000,
|
||||
timeoutId: null,
|
||||
}),
|
||||
|
||||
// expired issuedAt — very old timestamp (still valid per contract; age check is VisibilityManager's job)
|
||||
expiredIssuedAt: Object.freeze({
|
||||
opId: "op-003",
|
||||
userId: "user-xyz",
|
||||
targetState: "hidden",
|
||||
previousState: "active",
|
||||
issuedAt: 0,
|
||||
timeoutId: null,
|
||||
}),
|
||||
|
||||
// Invalid: empty opId
|
||||
emptyOpId: Object.freeze({
|
||||
opId: "",
|
||||
userId: "user-abc",
|
||||
targetState: "hidden",
|
||||
previousState: "active",
|
||||
issuedAt: 1700000000000,
|
||||
timeoutId: null,
|
||||
}),
|
||||
});
|
||||
Vendored
+42
@@ -0,0 +1,42 @@
|
||||
/**
|
||||
* tests/fixtures/scene-preset.js
|
||||
*
|
||||
* ScenePreset fixtures — frozen. Includes edge case: empty matrix {}.
|
||||
*/
|
||||
|
||||
export const SCENE_PRESET_FIXTURES = Object.freeze({
|
||||
valid: Object.freeze({
|
||||
_version: 1,
|
||||
name: "Combat Scene",
|
||||
matrix: Object.freeze({ "user-001": "active", "user-002": "hidden" }),
|
||||
createdAt: 1700000000000,
|
||||
updatedAt: 1700000000000,
|
||||
}),
|
||||
|
||||
// Edge case: empty matrix (all participants in default state)
|
||||
emptyMatrix: Object.freeze({
|
||||
_version: 1,
|
||||
name: "Empty Preset",
|
||||
matrix: Object.freeze({}),
|
||||
createdAt: 1700000000000,
|
||||
updatedAt: 1700000000001,
|
||||
}),
|
||||
|
||||
// Invalid: missing name
|
||||
missingName: Object.freeze({
|
||||
_version: 1,
|
||||
name: "",
|
||||
matrix: Object.freeze({}),
|
||||
createdAt: 1700000000000,
|
||||
updatedAt: 1700000000000,
|
||||
}),
|
||||
|
||||
// Invalid: wrong version
|
||||
wrongVersion: Object.freeze({
|
||||
_version: 2,
|
||||
name: "Future Preset",
|
||||
matrix: Object.freeze({}),
|
||||
createdAt: 1700000000000,
|
||||
updatedAt: 1700000000000,
|
||||
}),
|
||||
});
|
||||
Vendored
+79
@@ -0,0 +1,79 @@
|
||||
/**
|
||||
* tests/fixtures/socket-payloads.js
|
||||
*
|
||||
* Socket payload fixtures — frozen; include valid and invalid variants.
|
||||
* Used by socket-message contract tests and SocketHandler tests.
|
||||
*
|
||||
* All exports are Object.freeze'd — never mutate fixture data in tests.
|
||||
*/
|
||||
|
||||
export const SOCKET_PAYLOADS = Object.freeze({
|
||||
// ── Valid intent (GM → all clients) ──────────────────────────────────────
|
||||
validIntent: Object.freeze({
|
||||
event: "scrying-pool.visibility.set",
|
||||
payload: Object.freeze({
|
||||
opId: "op-001",
|
||||
userId: "user-abc",
|
||||
targetState: "hidden",
|
||||
}),
|
||||
}),
|
||||
|
||||
// ── Valid echo (broadcast ← GM) ───────────────────────────────────────────
|
||||
validEcho: Object.freeze({
|
||||
event: "scrying-pool.visibility.updated",
|
||||
payload: Object.freeze({
|
||||
opId: "op-001",
|
||||
userId: "user-abc",
|
||||
state: "hidden",
|
||||
revision: 1,
|
||||
}),
|
||||
}),
|
||||
|
||||
// ── Malformed: missing opId ───────────────────────────────────────────────
|
||||
missingOpId: Object.freeze({
|
||||
event: "scrying-pool.visibility.set",
|
||||
payload: Object.freeze({
|
||||
userId: "user-abc",
|
||||
targetState: "hidden",
|
||||
// opId intentionally omitted
|
||||
}),
|
||||
}),
|
||||
|
||||
// ── Malformed: wrong enum value for targetState ───────────────────────────
|
||||
invalidState: Object.freeze({
|
||||
event: "scrying-pool.visibility.set",
|
||||
payload: Object.freeze({
|
||||
opId: "op-002",
|
||||
userId: "user-abc",
|
||||
targetState: "invisible", // not a valid VisibilityState
|
||||
}),
|
||||
}),
|
||||
|
||||
// ── Malformed: extra unknown keys in payload ──────────────────────────────
|
||||
extraKeys: Object.freeze({
|
||||
event: "scrying-pool.visibility.set",
|
||||
payload: Object.freeze({
|
||||
opId: "op-003",
|
||||
userId: "user-abc",
|
||||
targetState: "hidden",
|
||||
extraField: "should-not-be-here",
|
||||
}),
|
||||
}),
|
||||
|
||||
// ── Malformed: unknown event name ─────────────────────────────────────────
|
||||
unknownEvent: Object.freeze({
|
||||
event: "sp:stateChange", // violates naming convention
|
||||
payload: Object.freeze({ opId: "op-004", userId: "user-abc" }),
|
||||
}),
|
||||
|
||||
// ── Malformed: echo message missing revision field ───────────────────────
|
||||
missingRevision: Object.freeze({
|
||||
event: "scrying-pool.visibility.updated",
|
||||
payload: Object.freeze({
|
||||
opId: "op-005",
|
||||
userId: "user-abc",
|
||||
state: "hidden",
|
||||
// revision intentionally omitted
|
||||
}),
|
||||
}),
|
||||
});
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
/**
|
||||
* tests/fixtures/state-store-snapshots.js
|
||||
*
|
||||
* StateStore snapshot fixtures — frozen.
|
||||
* Used by StateStore and VisibilityManager tests (Story 1.3+).
|
||||
*/
|
||||
|
||||
export const STATE_STORE_SNAPSHOTS = Object.freeze({
|
||||
empty: Object.freeze({ _version: 1, matrix: Object.freeze({}) }),
|
||||
|
||||
threeParticipants: Object.freeze({
|
||||
_version: 1,
|
||||
matrix: Object.freeze({
|
||||
"user-001": "active",
|
||||
"user-002": "hidden",
|
||||
"user-003": "self-muted",
|
||||
}),
|
||||
}),
|
||||
|
||||
allStates: Object.freeze({
|
||||
_version: 1,
|
||||
matrix: Object.freeze({
|
||||
"u-active": "active",
|
||||
"u-hidden": "hidden",
|
||||
"u-self-muted": "self-muted",
|
||||
"u-offline": "offline",
|
||||
"u-cam-lost": "cam-lost",
|
||||
"u-reconnecting": "reconnecting",
|
||||
"u-never-connected": "never-connected",
|
||||
"u-ghost": "ghost",
|
||||
}),
|
||||
}),
|
||||
});
|
||||
Vendored
+37
@@ -0,0 +1,37 @@
|
||||
/**
|
||||
* tests/fixtures/visibility-states.js
|
||||
*
|
||||
* Visibility state fixtures — frozen.
|
||||
*/
|
||||
|
||||
export const VISIBILITY_STATE_FIXTURES = Object.freeze({
|
||||
validMatrix: Object.freeze({
|
||||
_version: 1,
|
||||
matrix: Object.freeze({
|
||||
"user-001": "active",
|
||||
"user-002": "hidden",
|
||||
"user-003": "offline",
|
||||
}),
|
||||
}),
|
||||
|
||||
emptyMatrix: Object.freeze({
|
||||
_version: 1,
|
||||
matrix: Object.freeze({}),
|
||||
}),
|
||||
|
||||
// Invalid: userId maps to null (not a valid state)
|
||||
invalidNullState: Object.freeze({
|
||||
_version: 1,
|
||||
matrix: Object.freeze({
|
||||
"user-001": null,
|
||||
}),
|
||||
}),
|
||||
|
||||
// Invalid: unknown state value
|
||||
invalidUnknownState: Object.freeze({
|
||||
_version: 1,
|
||||
matrix: Object.freeze({
|
||||
"user-001": "invisible",
|
||||
}),
|
||||
}),
|
||||
});
|
||||
@@ -0,0 +1,78 @@
|
||||
// @ts-nocheck
|
||||
/**
|
||||
* tests/helpers/foundryAdapterMock.js
|
||||
*
|
||||
* Canonical FoundryAdapter mock factory.
|
||||
* ALL tests in this project MUST use this factory — no ad-hoc stubs.
|
||||
*
|
||||
* Usage:
|
||||
* import { createFoundryAdapterMock } from '../helpers/foundryAdapterMock.js'
|
||||
* const adapter = createFoundryAdapterMock()
|
||||
* const adapter = createFoundryAdapterMock({ settings: { get: () => 'custom' } })
|
||||
*
|
||||
* Surface contract mirrors FoundryAdapter (src/foundry/FoundryAdapter.js):
|
||||
* settings, socket, users, scenes, notifications, webrtc, hooks
|
||||
*/
|
||||
|
||||
/**
|
||||
* Creates a mock FoundryAdapter with optional overrides.
|
||||
*
|
||||
* All methods are vi.fn() stubs by default; pass overrides to customise.
|
||||
*
|
||||
* @param {Partial<FoundryAdapterSurface>} [overrides={}]
|
||||
* @returns {FoundryAdapterSurface}
|
||||
*/
|
||||
export function createFoundryAdapterMock(overrides = {}) {
|
||||
const defaults = {
|
||||
settings: {
|
||||
register: () => {},
|
||||
get: () => null,
|
||||
set: () => Promise.resolve(),
|
||||
...overrides.settings,
|
||||
},
|
||||
socket: {
|
||||
emit: () => {},
|
||||
on: () => {},
|
||||
off: () => {},
|
||||
...overrides.socket,
|
||||
},
|
||||
users: {
|
||||
get: () => null,
|
||||
all: () => [],
|
||||
isGM: () => false,
|
||||
current: () => overrides.users?.get?.("test-user") ?? null,
|
||||
...overrides.users,
|
||||
},
|
||||
scenes: {
|
||||
current: () => null,
|
||||
get: () => null,
|
||||
...overrides.scenes,
|
||||
},
|
||||
notifications: {
|
||||
info: () => {},
|
||||
warn: () => {},
|
||||
error: () => {},
|
||||
...overrides.notifications,
|
||||
},
|
||||
/**
|
||||
* WebRTC track-disabling surface, or null when OQ-1 resolved to css-fallback.
|
||||
*
|
||||
* Default is null (CSS fallback path). FoundryVTT v14 spike (Story 1.2) confirmed
|
||||
* that track.enabled = false does not stop inbound RTP bandwidth, so the probe
|
||||
* always returns 'css-fallback' and this.webrtc remains null in production.
|
||||
*
|
||||
* To simulate the track-disable path in tests, override with:
|
||||
* createFoundryAdapterMock({ webrtc: { disableTrack: vi.fn(), enableTrack: vi.fn() } })
|
||||
*/
|
||||
webrtc: overrides.webrtc !== undefined ? overrides.webrtc : null,
|
||||
hooks: {
|
||||
on: () => {},
|
||||
once: () => {},
|
||||
off: () => {},
|
||||
callAll: () => {},
|
||||
...overrides.hooks,
|
||||
},
|
||||
};
|
||||
|
||||
return defaults;
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
createPendingOp,
|
||||
isValidPendingOp,
|
||||
} from "../../../src/contracts/pending-op.js";
|
||||
import { PENDING_OP_FIXTURES } from "../../fixtures/pending-op.js";
|
||||
|
||||
describe("pending-op contract", () => {
|
||||
describe("createPendingOp()", () => {
|
||||
it("creates a pending op with required fields", () => {
|
||||
const op = createPendingOp("op-1", "user-1", "hidden", "active");
|
||||
expect(op.opId).toBe("op-1");
|
||||
expect(op.userId).toBe("user-1");
|
||||
expect(op.targetState).toBe("hidden");
|
||||
expect(op.previousState).toBe("active");
|
||||
expect(typeof op.issuedAt).toBe("number");
|
||||
expect(Number.isFinite(op.issuedAt)).toBe(true);
|
||||
expect(op.issuedAt).toBeGreaterThan(0);
|
||||
expect(op.timeoutId).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("isValidPendingOp()", () => {
|
||||
it("accepts valid fixture", () => {
|
||||
expect(() => isValidPendingOp(PENDING_OP_FIXTURES.valid)).not.toThrow();
|
||||
});
|
||||
|
||||
it("accepts timeoutId: null", () => {
|
||||
expect(() => isValidPendingOp(PENDING_OP_FIXTURES.timeoutNull)).not.toThrow();
|
||||
});
|
||||
|
||||
it("accepts expired issuedAt (age check is caller's job)", () => {
|
||||
expect(() => isValidPendingOp(PENDING_OP_FIXTURES.expiredIssuedAt)).not.toThrow();
|
||||
});
|
||||
|
||||
it("throws on empty opId", () => {
|
||||
expect(() => isValidPendingOp(PENDING_OP_FIXTURES.emptyOpId)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on non-finite issuedAt", () => {
|
||||
const bad = { ...PENDING_OP_FIXTURES.valid, issuedAt: NaN };
|
||||
expect(() => isValidPendingOp(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on negative issuedAt", () => {
|
||||
const bad = { ...PENDING_OP_FIXTURES.valid, issuedAt: -1 };
|
||||
expect(() => isValidPendingOp(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws if not an object", () => {
|
||||
expect(() => isValidPendingOp(null)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on unknown keys", () => {
|
||||
const bad = { ...PENDING_OP_FIXTURES.valid, extra: true };
|
||||
expect(() => isValidPendingOp(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on string timeoutId", () => {
|
||||
const bad = { ...PENDING_OP_FIXTURES.valid, timeoutId: "not-a-number" };
|
||||
expect(() => isValidPendingOp(bad)).toThrow(TypeError);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,78 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
createScenePreset,
|
||||
isValidScenePreset,
|
||||
} from "../../../src/contracts/scene-preset.js";
|
||||
import { SCENE_PRESET_FIXTURES } from "../../fixtures/scene-preset.js";
|
||||
|
||||
describe("scene-preset contract", () => {
|
||||
describe("createScenePreset()", () => {
|
||||
it("creates a preset with required fields", () => {
|
||||
const p = createScenePreset("My Preset", { "user-1": "active" });
|
||||
expect(p.name).toBe("My Preset");
|
||||
expect(p.matrix).toEqual({ "user-1": "active" });
|
||||
expect(typeof p.createdAt).toBe("number");
|
||||
expect(typeof p.updatedAt).toBe("number");
|
||||
expect(p.createdAt).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it("creates a preset with empty matrix", () => {
|
||||
const p = createScenePreset("Empty", {});
|
||||
expect(p.matrix).toEqual({});
|
||||
});
|
||||
|
||||
it("returns a shallow copy of the matrix", () => {
|
||||
const input = { "user-1": "active" };
|
||||
const p = createScenePreset("Test", input);
|
||||
input["user-1"] = "hidden";
|
||||
expect(p.matrix["user-1"]).toBe("active"); // not mutated
|
||||
});
|
||||
});
|
||||
|
||||
describe("isValidScenePreset()", () => {
|
||||
it("accepts valid fixture", () => {
|
||||
expect(() => isValidScenePreset(SCENE_PRESET_FIXTURES.valid)).not.toThrow();
|
||||
});
|
||||
|
||||
it("accepts empty matrix edge case", () => {
|
||||
expect(() => isValidScenePreset(SCENE_PRESET_FIXTURES.emptyMatrix)).not.toThrow();
|
||||
});
|
||||
|
||||
it("throws on empty name", () => {
|
||||
expect(() => isValidScenePreset(SCENE_PRESET_FIXTURES.missingName)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on wrong _version", () => {
|
||||
expect(() => isValidScenePreset(SCENE_PRESET_FIXTURES.wrongVersion)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws if not an object", () => {
|
||||
expect(() => isValidScenePreset(null)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on unknown keys", () => {
|
||||
const bad = { ...SCENE_PRESET_FIXTURES.valid, extra: true };
|
||||
expect(() => isValidScenePreset(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on non-finite createdAt", () => {
|
||||
const bad = { ...SCENE_PRESET_FIXTURES.valid, createdAt: NaN };
|
||||
expect(() => isValidScenePreset(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on negative createdAt", () => {
|
||||
const bad = { ...SCENE_PRESET_FIXTURES.valid, createdAt: -1 };
|
||||
expect(() => isValidScenePreset(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on NaN updatedAt", () => {
|
||||
const bad = { ...SCENE_PRESET_FIXTURES.valid, updatedAt: NaN };
|
||||
expect(() => isValidScenePreset(bad)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on Infinity updatedAt", () => {
|
||||
const bad = { ...SCENE_PRESET_FIXTURES.valid, updatedAt: Infinity };
|
||||
expect(() => isValidScenePreset(bad)).toThrow(TypeError);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,114 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
createSocketIntentMessage,
|
||||
createSocketEchoMessage,
|
||||
isValidSocketMessage,
|
||||
SOCKET_EVENTS,
|
||||
MAX_PAYLOAD_BYTES,
|
||||
} from "../../../src/contracts/socket-message.js";
|
||||
import { SOCKET_PAYLOADS } from "../../fixtures/socket-payloads.js";
|
||||
|
||||
describe("socket-message contract", () => {
|
||||
describe("createSocketIntentMessage()", () => {
|
||||
it("creates a valid intent message", () => {
|
||||
const msg = createSocketIntentMessage("op-1", "user-1", "hidden");
|
||||
expect(msg.event).toBe(SOCKET_EVENTS.VISIBILITY_SET);
|
||||
const p = /** @type {any} */ (msg.payload);
|
||||
expect(p.opId).toBe("op-1");
|
||||
expect(p.userId).toBe("user-1");
|
||||
expect(p.targetState).toBe("hidden");
|
||||
});
|
||||
});
|
||||
|
||||
describe("createSocketEchoMessage()", () => {
|
||||
it("creates a valid echo message", () => {
|
||||
const msg = createSocketEchoMessage("op-1", "user-1", "hidden", 1);
|
||||
expect(msg.event).toBe(SOCKET_EVENTS.VISIBILITY_UPDATED);
|
||||
const p = /** @type {any} */ (msg.payload);
|
||||
expect(p.opId).toBe("op-1");
|
||||
expect(p.state).toBe("hidden");
|
||||
expect(p.revision).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("isValidSocketMessage()", () => {
|
||||
it("accepts a valid intent from fixture", () => {
|
||||
expect(() => isValidSocketMessage(SOCKET_PAYLOADS.validIntent)).not.toThrow();
|
||||
});
|
||||
|
||||
it("accepts a valid echo from fixture", () => {
|
||||
expect(() => isValidSocketMessage(SOCKET_PAYLOADS.validEcho)).not.toThrow();
|
||||
});
|
||||
|
||||
it("throws on missing opId", () => {
|
||||
expect(() => isValidSocketMessage(SOCKET_PAYLOADS.missingOpId)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on unknown event", () => {
|
||||
expect(() => isValidSocketMessage(SOCKET_PAYLOADS.unknownEvent)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on extra payload keys (intent)", () => {
|
||||
expect(() => isValidSocketMessage(SOCKET_PAYLOADS.extraKeys)).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws if not an object", () => {
|
||||
expect(() => isValidSocketMessage(null)).toThrow(TypeError);
|
||||
expect(() => isValidSocketMessage("string")).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on unknown top-level keys", () => {
|
||||
expect(() =>
|
||||
isValidSocketMessage({ event: SOCKET_EVENTS.VISIBILITY_SET, payload: { opId: "x", userId: "y", targetState: "active" }, extra: true })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on empty event string", () => {
|
||||
expect(() =>
|
||||
isValidSocketMessage({ event: "", payload: {} })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on non-finite revision in echo", () => {
|
||||
expect(() =>
|
||||
isValidSocketMessage({
|
||||
event: SOCKET_EVENTS.VISIBILITY_UPDATED,
|
||||
payload: { opId: "op-1", userId: "u-1", state: "active", revision: NaN },
|
||||
})
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on negative revision in echo", () => {
|
||||
expect(() =>
|
||||
isValidSocketMessage({
|
||||
event: SOCKET_EVENTS.VISIBILITY_UPDATED,
|
||||
payload: { opId: "op-1", userId: "u-1", state: "active", revision: -1 },
|
||||
})
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on missing revision in echo", () => {
|
||||
expect(() =>
|
||||
isValidSocketMessage(SOCKET_PAYLOADS.missingRevision)
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
});
|
||||
|
||||
describe("SOCKET_EVENTS", () => {
|
||||
it("is frozen", () => {
|
||||
expect(Object.isFrozen(SOCKET_EVENTS)).toBe(true);
|
||||
});
|
||||
|
||||
it("uses scrying-pool. prefix for all events", () => {
|
||||
for (const event of Object.values(SOCKET_EVENTS)) {
|
||||
expect(event.startsWith("scrying-pool.")).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("MAX_PAYLOAD_BYTES", () => {
|
||||
it("is 4096", () => {
|
||||
expect(MAX_PAYLOAD_BYTES).toBe(4096);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,117 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
createVisibilityMatrix,
|
||||
isValidVisibilityMatrix,
|
||||
VISIBILITY_STATES,
|
||||
VISIBILITY_MATRIX_VERSION,
|
||||
} from "../../../src/contracts/visibility-matrix.js";
|
||||
|
||||
describe("visibility-matrix contract", () => {
|
||||
describe("createVisibilityMatrix()", () => {
|
||||
it("creates a matrix with default empty state", () => {
|
||||
const m = createVisibilityMatrix();
|
||||
expect(m._version).toBe(VISIBILITY_MATRIX_VERSION);
|
||||
expect(m.matrix).toEqual({});
|
||||
});
|
||||
|
||||
it("creates a matrix with provided entries", () => {
|
||||
const m = createVisibilityMatrix({ "user-1": "active", "user-2": "hidden" });
|
||||
expect(m.matrix["user-1"]).toBe("active");
|
||||
expect(m.matrix["user-2"]).toBe("hidden");
|
||||
});
|
||||
|
||||
it("returns a shallow copy of the provided matrix", () => {
|
||||
const input = /** @type {{ "user-1": import("../../../src/contracts/visibility-matrix.js").VisibilityState }} */ ({ "user-1": "active" });
|
||||
const m = createVisibilityMatrix(input);
|
||||
input["user-1"] = "hidden";
|
||||
expect(m.matrix["user-1"]).toBe("active"); // not mutated
|
||||
});
|
||||
});
|
||||
|
||||
describe("isValidVisibilityMatrix()", () => {
|
||||
it("accepts a valid matrix with all known states", () => {
|
||||
for (const state of VISIBILITY_STATES) {
|
||||
const data = { _version: 1, matrix: { "user-1": state } };
|
||||
expect(() => isValidVisibilityMatrix(data)).not.toThrow();
|
||||
}
|
||||
});
|
||||
|
||||
it("accepts an empty matrix", () => {
|
||||
expect(() => isValidVisibilityMatrix({ _version: 1, matrix: {} })).not.toThrow();
|
||||
});
|
||||
|
||||
it("throws if not an object", () => {
|
||||
expect(() => isValidVisibilityMatrix(null)).toThrow(TypeError);
|
||||
expect(() => isValidVisibilityMatrix("string")).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on unknown top-level keys", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: {}, extra: true })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on wrong _version", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 2, matrix: {} })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws if matrix is not a plain object", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: null })
|
||||
).toThrow(TypeError);
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: ["active"] })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on empty userId key", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: { "": "active" } })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on invalid state value", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: { "user-1": "invisible" } })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on null state value", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: { "user-1": null } })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on non-string state value (Symbol)", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: { "user-1": Symbol("test") } })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("throws on non-string state value (object)", () => {
|
||||
expect(() =>
|
||||
isValidVisibilityMatrix({ _version: 1, matrix: { "user-1": { value: "active" } } })
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
});
|
||||
|
||||
describe("VISIBILITY_STATES", () => {
|
||||
it("contains exactly 8 states", () => {
|
||||
expect(VISIBILITY_STATES).toHaveLength(8);
|
||||
});
|
||||
|
||||
it("is frozen", () => {
|
||||
expect(Object.isFrozen(VISIBILITY_STATES)).toBe(true);
|
||||
});
|
||||
|
||||
it("contains the 8 expected state values", () => {
|
||||
const expected = [
|
||||
"active", "hidden", "self-muted", "offline",
|
||||
"cam-lost", "reconnecting", "never-connected", "ghost",
|
||||
];
|
||||
expect([...VISIBILITY_STATES].sort()).toEqual(expected.sort());
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,224 @@
|
||||
// @ts-nocheck
|
||||
/**
|
||||
* tests/unit/foundry/FoundryAdapter.test.js
|
||||
*
|
||||
* Story 1.2 — WebRTC spike: FoundryAdapter probe tests.
|
||||
*
|
||||
* OQ-1 spike result: css-fallback (FoundryVTT v14, 2026-05-21)
|
||||
* track.enabled = false does NOT stop inbound WebRTC bandwidth.
|
||||
* Probe returns 'css-fallback' when AVClient is available, 'unsupported' otherwise.
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import { FoundryAdapter } from '../../../src/foundry/FoundryAdapter.js';
|
||||
import { createFoundryAdapterMock } from '../../helpers/foundryAdapterMock.js';
|
||||
|
||||
// ─── Helpers ─────────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Returns a minimal mock game.webrtc object whose client exposes getMediaStreamForUser.
|
||||
* @param {MediaStream|null} [stream=null]
|
||||
* @returns {{ client: { getMediaStreamForUser: import('vitest').MockedFunction<() => MediaStream|null> } }}
|
||||
*/
|
||||
function makeGameWebrtc(stream = null) {
|
||||
return {
|
||||
client: {
|
||||
getMediaStreamForUser: vi.fn().mockReturnValue(stream),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a minimal MediaStream mock with one video track.
|
||||
* @param {boolean} [enabled=true]
|
||||
* @returns {{ getVideoTracks: import('vitest').MockedFunction<() => object[]>, _track: { enabled: boolean, kind: string } }}
|
||||
*/
|
||||
function makeStream(enabled = true) {
|
||||
const track = { enabled, kind: 'video' };
|
||||
return {
|
||||
getVideoTracks: vi.fn().mockReturnValue([track]),
|
||||
_track: track,
|
||||
};
|
||||
}
|
||||
|
||||
// ─── probeCapability ─────────────────────────────────────────────────────────
|
||||
|
||||
describe('FoundryAdapter.probeCapability', () => {
|
||||
it('returns "unsupported" when gameWebrtc is null', () => {
|
||||
expect(FoundryAdapter.probeCapability(null)).toBe('unsupported');
|
||||
});
|
||||
|
||||
it('returns "unsupported" when gameWebrtc is undefined', () => {
|
||||
expect(FoundryAdapter.probeCapability(undefined)).toBe('unsupported');
|
||||
});
|
||||
|
||||
it('returns "unsupported" when gameWebrtc has no client', () => {
|
||||
expect(FoundryAdapter.probeCapability({})).toBe('unsupported');
|
||||
});
|
||||
|
||||
it('returns "unsupported" when client lacks getMediaStreamForUser', () => {
|
||||
expect(FoundryAdapter.probeCapability({ client: {} })).toBe('unsupported');
|
||||
});
|
||||
|
||||
it('returns "css-fallback" when client has getMediaStreamForUser (OQ-1 spike result)', () => {
|
||||
// track.enabled = false does NOT stop bandwidth → probe returns css-fallback, not track-disable
|
||||
const gameWebrtc = makeGameWebrtc();
|
||||
expect(FoundryAdapter.probeCapability(gameWebrtc)).toBe('css-fallback');
|
||||
});
|
||||
});
|
||||
|
||||
// ─── buildWebRTCSurface ───────────────────────────────────────────────────────
|
||||
|
||||
describe('FoundryAdapter.buildWebRTCSurface', () => {
|
||||
let consoleWarnSpy;
|
||||
let consoleErrorSpy;
|
||||
|
||||
beforeEach(() => {
|
||||
consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
|
||||
consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe('disableTrack', () => {
|
||||
it('sets track.enabled = false on all video tracks for the user', () => {
|
||||
const stream = makeStream(true);
|
||||
const gameWebrtc = makeGameWebrtc(stream);
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
surface.disableTrack('user-123');
|
||||
|
||||
expect(gameWebrtc.client.getMediaStreamForUser).toHaveBeenCalledWith('user-123');
|
||||
expect(stream._track.enabled).toBe(false);
|
||||
});
|
||||
|
||||
it('logs [ScryingPool] warning when no video tracks found (stream has none)', () => {
|
||||
const emptyStream = { getVideoTracks: vi.fn().mockReturnValue([]) };
|
||||
const gameWebrtc = makeGameWebrtc(emptyStream);
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
surface.disableTrack('user-456');
|
||||
|
||||
expect(consoleWarnSpy).toHaveBeenCalledWith(
|
||||
'[ScryingPool] disableTrack: no video tracks found for',
|
||||
'user-456',
|
||||
);
|
||||
});
|
||||
|
||||
it('logs [ScryingPool] warning when getMediaStreamForUser returns null', () => {
|
||||
const gameWebrtc = makeGameWebrtc(null);
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
surface.disableTrack('user-789');
|
||||
|
||||
expect(consoleWarnSpy).toHaveBeenCalledWith(
|
||||
'[ScryingPool] disableTrack: no video tracks found for',
|
||||
'user-789',
|
||||
);
|
||||
});
|
||||
|
||||
it('catches errors and logs [ScryingPool] error without throwing', () => {
|
||||
const gameWebrtc = {
|
||||
client: {
|
||||
getMediaStreamForUser: vi.fn().mockImplementation(() => {
|
||||
throw new Error('AV backend unavailable');
|
||||
}),
|
||||
},
|
||||
};
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
expect(() => surface.disableTrack('user-err')).not.toThrow();
|
||||
expect(consoleErrorSpy).toHaveBeenCalledWith(
|
||||
'[ScryingPool] disableTrack failed:',
|
||||
expect.any(Error),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('enableTrack', () => {
|
||||
it('sets track.enabled = true on all video tracks for the user', () => {
|
||||
const stream = makeStream(false);
|
||||
const gameWebrtc = makeGameWebrtc(stream);
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
surface.enableTrack('user-123');
|
||||
|
||||
expect(gameWebrtc.client.getMediaStreamForUser).toHaveBeenCalledWith('user-123');
|
||||
expect(stream._track.enabled).toBe(true);
|
||||
});
|
||||
|
||||
it('logs [ScryingPool] warning when no video tracks found', () => {
|
||||
const emptyStream = { getVideoTracks: vi.fn().mockReturnValue([]) };
|
||||
const gameWebrtc = makeGameWebrtc(emptyStream);
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
surface.enableTrack('user-456');
|
||||
|
||||
expect(consoleWarnSpy).toHaveBeenCalledWith(
|
||||
'[ScryingPool] enableTrack: no video tracks found for',
|
||||
'user-456',
|
||||
);
|
||||
});
|
||||
|
||||
it('catches errors and logs [ScryingPool] error without throwing', () => {
|
||||
const gameWebrtc = {
|
||||
client: {
|
||||
getMediaStreamForUser: vi.fn().mockImplementation(() => {
|
||||
throw new Error('AV backend unavailable');
|
||||
}),
|
||||
},
|
||||
};
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(gameWebrtc);
|
||||
|
||||
expect(() => surface.enableTrack('user-err')).not.toThrow();
|
||||
expect(consoleErrorSpy).toHaveBeenCalledWith(
|
||||
'[ScryingPool] enableTrack failed:',
|
||||
expect.any(Error),
|
||||
);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// ─── Constructor + interface shape parity ─────────────────────────────────────
|
||||
|
||||
describe('FoundryAdapter constructor', () => {
|
||||
it('is side-effect-free — instantiates without accessing game.*', () => {
|
||||
expect(() => new FoundryAdapter()).not.toThrow();
|
||||
});
|
||||
|
||||
it('has webrtc = null by default (css-fallback path)', () => {
|
||||
const adapter = new FoundryAdapter();
|
||||
expect(adapter.webrtc).toBeNull();
|
||||
});
|
||||
|
||||
it('exposes SETTINGS_NS and SETTING_WEBRTC_MODE static constants', () => {
|
||||
expect(typeof FoundryAdapter.SETTINGS_NS).toBe('string');
|
||||
expect(FoundryAdapter.SETTINGS_NS).toBe('scrying-pool');
|
||||
expect(typeof FoundryAdapter.SETTING_WEBRTC_MODE).toBe('string');
|
||||
expect(FoundryAdapter.SETTING_WEBRTC_MODE).toBe('webrtcMode');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Interface shape parity with canonical mock', () => {
|
||||
it('canonical mock webrtc default matches FoundryAdapter default (null)', () => {
|
||||
const mock = createFoundryAdapterMock();
|
||||
const adapter = new FoundryAdapter();
|
||||
expect(mock.webrtc).toBe(adapter.webrtc); // both null
|
||||
});
|
||||
|
||||
it('canonical mock can override webrtc to simulate track-disable surface', () => {
|
||||
const mockSurface = { disableTrack: vi.fn(), enableTrack: vi.fn() };
|
||||
const mock = createFoundryAdapterMock({ webrtc: mockSurface });
|
||||
expect(mock.webrtc).toBe(mockSurface);
|
||||
expect(typeof mock.webrtc.disableTrack).toBe('function');
|
||||
expect(typeof mock.webrtc.enableTrack).toBe('function');
|
||||
});
|
||||
|
||||
it('buildWebRTCSurface returns object with disableTrack and enableTrack', () => {
|
||||
const surface = FoundryAdapter.buildWebRTCSurface(makeGameWebrtc());
|
||||
expect(typeof surface.disableTrack).toBe('function');
|
||||
expect(typeof surface.enableTrack).toBe('function');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"checkJs": true,
|
||||
"strict": true,
|
||||
"noEmit": true,
|
||||
"target": "ESNext",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"allowJs": true,
|
||||
"lib": ["ESNext", "DOM"]
|
||||
},
|
||||
"include": ["src/**/*.js", "src/**/*.d.ts", "module.js", "scripts/**/*.mjs", "tests/**/*.js"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: "happy-dom",
|
||||
globals: false,
|
||||
include: ["tests/**/*.test.js"],
|
||||
coverage: {
|
||||
provider: "v8",
|
||||
reporter: ["text", "lcov"],
|
||||
include: ["src/**/*.js"],
|
||||
exclude: ["src/contracts/**"],
|
||||
},
|
||||
},
|
||||
resolve: {
|
||||
alias: {
|
||||
"@src": "/src",
|
||||
"@contracts": "/src/contracts",
|
||||
"@utils": "/src/utils",
|
||||
"@tests": "/tests",
|
||||
},
|
||||
},
|
||||
});
|
||||
Reference in New Issue
Block a user