`CLAUDE.md`

165 lines
# 3D War Room — Room Architecture & Rendering Specs

## Build System
- Source modules in `/public/js/modules/` (15 MAIN + 1 STANDALONE)
- Build: `node build-warroom.js` → concatenates into single IIFE `warroom.js` (~24,810 lines)
- Validate: `node validate-warroom.js [--verbose] [--json]` — 20 checks across build/navigation/culling/scene/css/performance
- Module order: wr-core → wr-audio → wr-ui → wr-scene → wr-animate → wr-effects → wr-effects2 → wr-effects3 → wr-effects4 → wr-office → wr-rooms → wr-doors → wr-meeting → wr-nav → wr-lincoln → (standalone) wr-wallpicker
- HTML loads ONLY `/js/warroom.js?v=251` — modular files are NOT loaded by browser
- **After ANY code change**: edit module → `node build-warroom.js` → `node validate-warroom.js` → bump cache version in index.html
- Global state exposed via `window._*` pattern (e.g., `window._camera`, `window._controls`)
- Variable names MUST be room-prefixed to avoid IIFE scope collisions (e.g., `djVinyl` not `vinyl`)

---

## Boardroom (Main Conference Room)
- **Dimensions**: 24w x 18d x 4.2h (ROOM_W=24, ROOM_D=18, WALL_H=4.2)
- **Table**: center (0, 0.95, 0), 10w x 3.2d x 0.95h
- **Podium**: (-8.5, 0, 0), facing table (rotation Math.PI/2)
- **Back wall**: (0, 2.1, -9), 24w x 4.2h
- **Front wall**: (0, 2.1, 9), 24w x 4.2h — has 5 transparisteel windows
- **Left wall**: (-12, 2.1, 0), 18d x 4.2h
- **Right wall**: (12, 2.1, 0), 18d x 4.2h
- **Seating**: 50 positions (16 at table, 2 head/foot, 20 back rows, 12 side walls)
- **Executives only**: EXEC_IDS = Set(['ceo', 'cfo', 'coo', 'cto', 'vp-ops'])

## Garcia Room
- **Center**: (0, 0, -42), width 14, depth 10, height 4.2
- **Front wall**: z = -37 (guitar at x=3.5, SYF at x=-3.5, volume slider at x=5.5)
- **Back wall**: z = -47 (neon GARCIA sign, NOW PLAYING display, SYF banner)
- **Left wall**: x = -7 (Puppy TV — full wall screen)
- **Right wall**: x = +7 (Met Museum art)
- **Turntable**: (3.5, 1.0, -44.5) with GD/JGB/G&G collection buttons below
- **Eames chair**: (0, 0, -41)
- **Camera start**: (0, 1.6, -46) looking at (0, 1.8, -40) — back of room facing forward
- **Key globals**: `window._garciaHitbox`, `window._garciaGuitar`, `window._garciaVolumeSlider`, `window._garciaSYF`, `window._garciaJukebox`, `window._garciaNowPlayingCanvas`

## Showroom / Gallery Wings
- **Showroom**: cam (22, 2, -20), center (22, 0, -22)
- **Gallery 2**: cam (42, 2, -20), center (42, 0, -22)
- **Gallery 3**: cam (62, 2, -20), center (62, 0, -22)
- **Lazy loaded**: Products built on first navigation visit
- **Culling**: `_setShowroomVisibility(roomIdx)` hides distant gallery boards

## MET Gallery
- **Center**: (0, 0, -22), width 14, depth 8, height 4.2
- **Location**: Between breakout rooms corridor and Garcia
- **Features**: 100 contemporary paintings (procedural canvas textures), museum bench, black grasscloth walls
- **Key globals**: `window._metPaintings`, `window._metGalleryGroup`

## Claudette's Lab
- **Center**: (0, 0, -56), width 16, depth 14, height 4.2
- **Location**: South of Garcia via 3.6m corridor through back wall
- **Features**: 3D printer (wireframe IcosahedronGeometry), holographic globe with orbital rings, neural network visualization (4 layers of spheres + cylinder connections), Matrix code rain (canvas), server rack with LED indicators, floating thought bubbles, workstation desk with terminal, energy orb ceiling fixture
- **Floor**: Circuit board (MeshStandardMaterial + procedural CanvasTexture)
- **Animations**: All registered in `window._claudetteAnimations[]`, called from wr-animate.js every 2 frames
- **Lighting**: 4 PointLights (cyan, purple, green, warm) + 4 tech sconces

---

## Room Navigation (ROOM_NAV)

| Room | Camera Position | Look Target |
|------|----------------|-------------|
| podium | (-8.5, 3, 5) | (-8.5, 1.2, 0) |
| boardroom | (0, 3.2, 10) | (0, 1.2, 0) |
| lounge | (-8, 3, -13) | (-8, 1, -18) |
| cafe | (8, 3, -13) | (8, 1, -18) |
| dancehall | (-8, 3, -23) | (-8, 1, -28) |
| thinktank | (8, 3, -23) | (8, 1, -28) |
| garcia | (0, 2.5, -46) | (0, 1.8, -40) |
| showroom | (22, 2, -20) | (22, 1.5, -28) |
| metgallery | (0, 2.5, -30) | (0, 1.5, -22) |
| claudettelab | (0, 2.5, -48) | (0, 1.5, -56) |

## Camera Presets (Keys 1-8, 0 to reset)
1=Wide, 2=Executive, 3=Bird's Eye, 4=Ground, 5=Front Row, 6=Head of Table, 7=Balcony, 8=Over Shoulder

---

## Avatar System
- 50 humanoid robot avatars, HIDDEN by default (zero draw calls)
- Only execs materialize for meetings (5 agents)
- FSM states: seated-idle, seated-speaking, standing-up, walking, moonwalking, sitting-down, chatting, on-break, at-lunch, dancing
- Dance party: `startWarRoomDanceParty()` materializes ALL agents
- Agent count display: `document.getElementById('agent-count')`

## Meeting System
- Trigger: `triggerMeeting('adhoc'|'standup'|'operations'|'eod')`
- Halt: `haltMeeting()`
- Backend: boardroom-agent at port 9815 (proxied via `/api/proxy/meeting/trigger/:type`)
- Ad-hoc: visual assembly only, user-driven
- Std/Ops/EOD: backend-driven with TTS speaking turns

## Performance Budget
- Target: 20+ FPS
- Default draw calls: ~67 (no agents, lazy showroom)
- With 5 execs: ~267 draw calls (+200)
- All 50 agents: ~2067 draw calls
- Auto-rotate pauses on user interaction (8s timeout)

---

## Figma-Driven Design System Rules

### Design Token Architecture
All UI styling uses CSS custom properties defined in `/public/css/style.css` `:root` section.
IMPORTANT: Never hardcode colors, fonts, spacing, or shadows in inline styles. Always use `var(--ds-*)` tokens.

| Category | Token Pattern | Example |
|----------|--------------|---------|
| Typography | `--ds-font`, `--ds-text-{xs..3xl}`, `--ds-weight-{normal..bold}` | `font-family:var(--ds-font)` |
| Colors | `--ds-gray-{50..900}`, `--ds-{success,warning,error,info}` | `color:var(--ds-gray-700)` |
| Surfaces | `--ds-glass`, `--ds-glass-strong`, `--ds-glass-subtle` | `background:var(--ds-glass)` |
| Blur | `--ds-blur`, `--ds-blur-sm`, `--ds-blur-lg` | `backdrop-filter:var(--ds-blur)` |
| Borders | `--ds-border`, `--ds-border-strong`, `--ds-border-interactive` | `border:1px solid var(--ds-border)` |
| Radius | `--ds-radius-{xs..full}` | `border-radius:var(--ds-radius-md)` |
| Shadows | `--ds-shadow-{xs..xl}` | `box-shadow:var(--ds-shadow-md)` |
| Spacing | `--ds-space-{1..12}` (4px base) | `padding:var(--ds-space-4)` |
| Transitions | `--ds-ease`, `--ds-duration-{fast,normal,slow}` | `transition:all var(--ds-duration-fast) var(--ds-ease)` |

### Glass Morphism Pattern (all overlays, modals, toolbars)
```css
background: var(--ds-glass-strong);
backdrop-filter: var(--ds-blur);
border: 1px solid var(--ds-border);
border-radius: var(--ds-radius-lg);
box-shadow: var(--ds-shadow-lg);
```

### Component Styling Rules
- IMPORTANT: System font stack: `-apple-system, BlinkMacSystemFont, Inter, sans-serif` — never use Georgia or serif
- IMPORTANT: Primary action buttons use `--ds-gray-900` bg + white text, secondary use `--ds-gray-50` bg + `--ds-border-strong`
- IMPORTANT: Muted/secondary text uses `--ds-gray-500`, not brown tones
- Hover states: buttons lighten to `--ds-gray-700` (primary) or `--ds-gray-100` (secondary)
- Active/selected items: `--ds-gray-100` background
- Toast success/warning/error use `--ds-success`/`--ds-warning`/`--ds-error` for accent colors on white glass bg

### Canvas2D Text (3D labels, plaques, signs)
Font string: `-apple-system, BlinkMacSystemFont, Inter, sans-serif` (NO quotes around Inter — breaks JS string escaping)
Light backgrounds: `#f5f0eb` (warm gallery white)
Dark text: `#1a1a1a` (primary), `#666` (secondary), `#888` (tertiary), `#999` (muted)

### PBR Material Standards
- Wing panels: `MeshStandardMaterial({ roughness: 0.35, metalness: 0.0, envMapIntensity: 0.5 })`
- Frames: `MeshStandardMaterial({ roughness: 0.3, metalness: 0.4 })` — brushed aluminum look
- Spine: `MeshStandardMaterial({ roughness: 0.2, metalness: 0.6 })` — chrome-like
- Environment map: Procedural PMREMGenerator from canvas gradient (no external files)
- Tone mapping: ACES Filmic, exposure 1.6 in showroom rooms, 1.2 elsewhere

### Showroom Texture Pipeline
- Canvas slices: 512x768 (2:3 aspect, center-cropped)
- Fallback texture: light `#f0ebe4` with system font product name
- Texture queue: 4 concurrent loaders, generation-stamped for page-change safety
- Cache: Map keyed by product handle/SKU

### CSS Vignette
`#canvas-container::after` applies a radial gradient vignette for photographic depth (zero GPU cost)

### Forbidden Patterns
- NEVER use `Georgia, serif` font anywhere
- NEVER use gold `#d4a574` for UI text or backgrounds (reserved only for 3D material highlight: `wingsFrameHoverMat`)
- NEVER use dark brown `#1a0f08` backgrounds
- NEVER hardcode hex colors in inline styles — use CSS variable tokens
- NEVER use `rgba(42,26,10,*)` — this is the old dark theme