`docs/plans/2026-03-02-figma-threejs-photorealism-design.md`

168 lines
# Figma + Three.js Photorealistic Showroom Pipeline

**Date:** 2026-03-02
**Status:** Approved
**Target Systems:** War Room (port 4060) + Boardroom-3D Showroom (port 7681)

---

## Vision

Transform the existing 3D showroom into a photorealistic architectural trade showroom with:
- Endless vendor wings (50 wings, lazy-loaded)
- Exposed brick corridor with track lighting
- PBR materials with normal/roughness maps
- Full post-processing pipeline (SSAO, DOF, bloom, color grading)
- Figma MCP-driven layout pipeline

## Architecture

### Pipeline Flow
```
Figma Design → MCP get_design_context → Claude Transform → TypeScript Modules → Vite Build → Live 3D
```

### Approach: MCP-Native
- Uses existing Figma MCP tools in Claude Code
- Zero custom infrastructure
- Real-time design iteration

---

## Showroom Layout: Endless Wings Corridor

### Structure
```
Entry → Central Corridor → 50 Vendor Wings (extending in +X)
                         → Side Walls: wallpaper samples + book displays
                         → Overhead: industrial track lighting
```

### Key Elements

1. **Central Corridor** — Long exposed-brick hallway, polished concrete floor, industrial ceiling with exposed ductwork
2. **50 Vendor Wings** — Perpendicular from corridor. Each = 1 vendor. Clicking opens to reveal 20-50 product panels. Lazy-loaded on first visit.
3. **Side Walls** — Between wings: large-format wallpaper samples (4ft x 8ft mounted panels) + glass-front sample book shelves
4. **Track Lighting** — Continuous rail along corridor ceiling + dedicated spots per wing bay entrance
5. **Wing Interior** — Each vendor wing: 3 walls of product panels, sample table, vendor branding, warm accent lighting
6. **Navigation** — WASD walking + click-to-teleport. Minimap shows corridor + wing positions.

### Performance: Endless Illusion
- Render only 3 wings at a time (current + adjacent)
- Fog/atmosphere fades distant wings
- Frustum culling hides everything beyond visible range
- Lazy-load product textures only when wing approached

---

## Photorealism Rendering Pipeline

### Material System

| Surface | Color | Metalness | Roughness | Normal Map | Notes |
|---------|-------|-----------|-----------|------------|-------|
| Polished concrete floor | #8a8580 | 0.15 | 0.55 | Procedural micro-texture | Contact shadows |
| Brick walls | #8b4513 | 0.0 | 0.85 | Procedural brick pattern | Mortar darkening via SSAO |
| Steel ceiling/ducts | #2a2a2a | 0.6 | 0.3 | Metal panel grid | Exposed duct geometry |
| Wing frames | #c0c0c0 | 0.7 | 0.25 | Brushed aluminum | Sharp reflections |
| Product panels | Texture | 0.0 | 0.4 | Fabric/paper subtle | Matte wallcovering |
| Book shelves | #8b6914 | 0.0 | 0.65 | Wood grain | Glass fronts (transmission 0.9) |
| Track lights | #ffffff | 0.9 | 0.1 | Chrome | Emissive + SpotLight |

### Post-Processing Stack
```
RenderPass → SSAOPass → UnrealBloomPass → BokehPass → ColorGradingPass → FilmGrainPass → Output
```

1. **SSAO** — radius 0.5, bias 0.025, intensity 1.2
2. **Bloom** — strength 0.25, radius 0.5, threshold 0.65
3. **Depth of Field** — focus on look target, aperture 0.02
4. **Color Grading** — warm architectural tones, contrast boost
5. **Film Grain** — opacity 0.008, temporal

### Environment Lighting
- HDR environment map (Polyhaven CC0 gallery/studio HDRI)
- RGBELoader → PMREMGenerator for IBL
- ACES Filmic tone mapping, exposure 1.4 (corridor) / 1.6 (wing interior)
- Shadows: PCF soft, 2048x2048 from main directional
- Track lights: SpotLight with cone + penumbra
- Volumetric light cones (additive-blend geometry + dust particles)

---

## MCP Integration Flow

### Step 1: Figma Design Creation
- Create showroom floor plan in Figma
- Define vendor wings, walls, lighting positions
- Set material swatches as image fills
- Use Figma variables for design tokens

### Step 2: MCP Extraction
```typescript
// Extract design context
get_design_context(nodeId, fileKey) → structured layout data

// Extract design tokens
get_variable_defs(nodeId, fileKey) → color/spacing tokens
```

### Step 3: Claude Transform
- Map Figma frames → Three.js scene graph (positions, dimensions)
- Map image fills → TextureLoader URLs
- Map text nodes → canvas-rendered labels
- Map component instances → reusable objects

### Step 4: TypeScript Module Generation
```
src/showroom/
├── ShowroomLayout.ts      — corridor, wings, walls geometry
├── ShowroomMaterials.ts   — PBR material definitions + normal maps
├── ShowroomLighting.ts    — track lights, spots, ambient, HDRI
├── ShowroomTextures.ts    — texture pipeline (lazy-load, fallback)
├── ShowroomNavigation.ts  — WASD, teleport, wing selection
├── ShowroomCulling.ts     — visibility management, LOD
└── ShowroomPostProcess.ts — SSAO + DOF + bloom + grading
```

### Step 5: Integration
- War Room (4060): new showroom room accessible via navigation
- Boardroom-3D (7681): upgraded gallery rendering with shared materials

---

## Performance Budget

| Metric | Target |
|--------|--------|
| FPS | 30+ at 1080p |
| Draw calls (base) | < 100 |
| Draw calls (wing open) | < 300 |
| Texture memory | < 256MB |
| Initial load | < 3 seconds |
| Wing load (lazy) | < 1 second |

---

## Implementation Phases

### Phase 1: Figma Design + MCP Pipeline
- Create showroom layout in Figma
- Build MCP extraction → transform pipeline
- Generate base TypeScript modules

### Phase 2: Photorealism Rendering
- Implement SSAO, HDR env map, normal maps
- Add DOF, color grading, volumetric lights
- Upgrade materials to full PBR with detail maps

### Phase 3: Endless Wings System
- Build lazy-loaded wing architecture
- Implement culling and LOD
- Connect to product database for real textures

### Phase 4: Integration
- Merge into War Room (4060)
- Upgrade Boardroom-3D (7681)
- Performance optimization pass