@vib3code/sdk 2.0.1 → 2.0.3-canary.3349130

package/DOCS/VISUAL_ANALYSIS_TABLESIDE.md

@@ -0,0 +1,86 @@
+# Visual Analysis: tableside.com.au
+
+**Captured: 2026-02-10 via Playwright with wheel-based scrolling**
+**Method**: Real Chromium screenshots at 5 scroll positions (wheel events)
+**Page height**: 8,370px (~9.3x viewport)
+
+---
+
+## Scroll Journey (Frame by Frame)
+
+### s00 — Top (scrollY=0)
+**Bold typography hero with warm palette**
+- Background: warm cream/beige (#F5EDE4 range)
+- "TABLESIDE" logo top-left in coral/orange + "CREATIVES" subscript
+- Hamburger menu (three lines) top-right in coral
+- MASSIVE bold sans-serif text: "FOOD & DRINK DIGITAL CREATIVES" in coral/orange (#E85D3A range)
+- Text fills ~70% of viewport, extremely bold weight (900+), tight line-height
+- Below hero: "HOSPITALITY MARKETING AUSTRALIA" in black, right-aligned
+- "WHAT WE DO" label left side
+- Large body text in coral: "Crafting bold, unforgettable brands through content to propel hospitality and food & beverage businesses towards sustainable growth and standout success."
+- Social links: INSTAGRAM, FACEBOOK, LINKEDIN, TIKTOK — right-aligned, stacked
+- Chat widget bottom-right
+- **Pattern**: Typography-as-hero with strong brand color. The hero text IS the brand statement, rendered in the signature coral color at maximum weight. Social links positioned as a sidebar element right-aligned.
+
+### s01 — scrollY=2400
+**Portfolio card: asymmetric split layout**
+- Large food photography LEFT (~50% viewport width): close-up of artisanal pizza
+- Card text RIGHT: "ROCCELLA EAST MELB" restaurant name + orange icon
+- "WEB, CONTENT, PAID, SOCIAL & EDM" service tags + "+ INFO" link in coral
+- Below: second portfolio card beginning — dark photo of restaurant interior
+- "STEER DINING ROOM" title overlaid on dark photo, bottom-left
+- **Pattern**: Asymmetric portfolio cards. Image takes one half, text the other. The split is ~50/50 with generous spacing. Different cards have different background treatments (light photo vs dark atmospheric photo).
+
+### s02 — scrollY=4800
+**Small dark portfolio card**
+- Dark restaurant interior photo with chefs in white uniforms
+- "WAGYU YA TEPPANYAKI" title overlaid top in white
+- "WEB, CONTENT, PAID, SOCIALS & EDM" service tags bottom-left
+- "YAKIKAMI" title visible below
+- Card appears much smaller than previous cards (~40% viewport height)
+- **Pattern**: Variable card sizing. Not all portfolio cards are the same size. This card is notably smaller and darker than the previous ones, creating visual rhythm through size variation.
+
+### s03 — scrollY=7200
+**CTA section with strong color**
+- Solid coral/orange background filling top ~40% of viewport
+- "READY TO TAKE A SEAT AT OUR TABLE?" in large white text, centered
+- "BOOK FREE STRATEGY SESSION" button: white border on coral background, centered
+- Below CTA: split-color footer section
+  - LEFT half: warm cream with contact info, address, phone, hours
+  - RIGHT half: dark navy (#1A1A3E) with food photography (overhead table shot with multiple dishes)
+  - Photo floats slightly above the navy background edge
+
+### s04 — scrollY=7470 (bottom)
+**Footer nav + legal**
+- Footer navigation bar: HOME, WORK, SERVICES, ABOUT US, JOBS, CONTACT, NEWS (left-aligned in coral)
+- Social links: INSTAGRAM, FACEBOOK, LINKEDIN (right-aligned in coral)
+- Bottom bar: Privacy Policy, "TABLESIDE" centered logo, © 2024
+- **Pattern**: Footer uses the brand coral for all link text against cream background. Clean horizontal nav layout.
+
+---
+
+## Key Design Patterns for VIB3+ Translation
+
+### 1. Three-Tone Palette (Cream + Coral + Navy)
+The site uses exactly three colors consistently: warm cream background, coral/orange for typography and accents, dark navy for contrast sections. No gradients, no additional colors.
+**For VIB3+**: A disciplined three-tone palette could anchor the landing page — e.g., dark background + one accent hue from the visualizer + white text.
+
+### 2. Variable Portfolio Card Sizing
+Portfolio cards are NOT uniform. Some span full viewport height, others are compact. Some have light photos, others have dark atmospheric shots. Size variation creates rhythm.
+**For VIB3+**: Cascade cards don't all need to be the same size. The clip-path morphing system could make some cards appear larger (wider window) and others more compact (narrower window), even though the underlying card is the same size.
+
+### 3. Split-Color Sections
+The contact/footer area uses a vertical split: cream on the left, navy on the right, with a food photo bridging the two zones. This creates a strong compositional split.
+**For VIB3+**: Could use a vertical split in the CTA or feature sections — one half showing one visualization system, the other showing a different one.
+
+### 4. CTA as Bold Color Block
+The CTA section is a solid block of coral color with white text. Simple, bold, impossible to scroll past without noticing.
+**For VIB3+**: The CTA section could use a solid color block with a visualizer running behind it at low opacity, creating color + depth.
+
+### 5. Service Tags as Metadata
+Each portfolio card lists specific services (WEB, CONTENT, PAID, SOCIAL & EDM) in small uppercase text. This adds information density without cluttering the visual.
+**For VIB3+**: Cascade cards could show parameter metadata (geometry name, system type, hue value) in small utility text that adds technical depth.
+
+---
+
+*Analysis based on actual Playwright screenshots captured with wheel-event scrolling.*

package/DOCS/{BLUEPRINT_EXECUTION_PLAN_2026-01-07.md → archive/BLUEPRINT_EXECUTION_PLAN_2026-01-07.md}

@@ -1,6 +1,6 @@
 # Blueprint execution plan (2026-01-07)
 
-This execution plan operationalizes the strategic blueprint and defines what each session should deliver. Each session should update `DOCS/SESSION_LOG_2026-01-07.md` with timestamped progress and keep the checklist current.
+This execution plan operationalizes the strategic blueprint and defines what each session should deliver. Each session should update `DOCS/archive/SESSION_LOG_2026-01-07.md` with timestamped progress and keep the checklist current.
 
 ## Session cadence
 - **Start of session**: review this plan and the strategic blueprint.

package/DOCS/{DEV_TRACK_ANALYSIS.md → archive/DEV_TRACK_ANALYSIS.md}

@@ -1,5 +1,8 @@
 # Dev track analysis and next steps
 
+> **Archived document:** This file is retained for historical reference in `DOCS/archive/` and is not part of the active docs set.
+
+
 This document summarizes the current development track status, highlights gaps, and proposes the
 next execution steps. It should be updated after each multi-system delivery.
 

package/DOCS/{SYSTEM_AUDIT_2026-01-30.md → archive/SYSTEM_AUDIT_2026-01-30.md}

@@ -1,5 +1,8 @@
 # VIB3+ CORE System Audit
 
+> **Archived document:** This file is retained for historical reference in `DOCS/archive/` and is not part of the active docs set.
+
+
 **Date**: January 30, 2026
 **Version**: 2.0.0 (`@vib3code/sdk`)
 **Branch**: `claude/phase-5-hardening-a4Wzn`

package/DOCS/{DEV_TRACK_SESSION_2026-01-31.md → dev-tracks/DEV_TRACK_SESSION_2026-01-31.md}

@@ -87,7 +87,7 @@
 | File | Purpose |
 |------|---------|
 | `DOCS/MASTER_PLAN_2026-01-31.md` | Master plan with 43 items |
-| `DOCS/DEV_TRACK_SESSION_2026-01-31.md` | This session log |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-01-31.md` | This session log |
 | `DOCS/OBS_SETUP_GUIDE.md` | OBS integration guide |
 | `LICENSE` | MIT License |
 | `CHANGELOG.md` | v1.0.0 + v2.0.0 release notes |

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-06.md

@@ -0,0 +1,231 @@
+# Development Session — 2026-02-06
+
+**Session type**: Full codebase audit + hygiene + MCP server + agent docs + testing
+**Branch**: `claude/project-review-planning-NWnhW`
+**Operator**: Claude Code (Opus 4.6)
+
+---
+
+## Session Overview
+
+Two consecutive work phases:
+
+1. **Phase A (Hygiene)**: Full 751-file audit, identified 9 bugs, fixed 8
+2. **Phase B (Infrastructure)**: Bug fixes, test verification, real MCP server, agent packs, landing page
+
+---
+
+## Phase A — Codebase Audit + Hygiene
+
+### Corrected from initial analysis
+
+| Item | Initial Assessment | Verified Status |
+|------|-------------------|----------------|
+| npm publish | Assumed not done | **Published**: `@vib3code/sdk@2.0.1` live on npm (Feb 3) |
+| CanvasManager.js | Assumed dead code | **Used by VIB3Engine** but API contract broken |
+| `u_breath` in shader-verify | Assumed tool wrong | **Tool correct** — inline had it, external files didn't |
+
+### Hygiene Fixes (Commit 1: `9e858a2`)
+
+| # | Fix | File(s) | Severity |
+|---|-----|---------|----------|
+| 1 | CanvasManager rewrite to match VIB3Engine API | `src/core/CanvasManager.js` (217→110 lines) | CRITICAL |
+| 2 | HolographicRendererAdapter import fix | `src/core/renderers/HolographicRendererAdapter.js:2` | CRITICAL |
+| 3 | TradingCardManager broken import paths | `src/export/TradingCardManager.js:60-63` | HIGH |
+| 4 | External shader u_breath sync | 4 shader files (GLSL + WGSL) | HIGH |
+| 5 | Version strings unified to 2.0.1 | VIB3Engine, Parameters, ErrorReporter | MEDIUM |
+| 6 | Viewer ReactivityManager renamed | `src/viewer/ViewerInputHandler.js` | MEDIUM |
+| 7 | Stale package-lock.json removed | Root (-240 KB) | LOW |
+| 8 | CHANGELOG v2.0.1 entries added | `CHANGELOG.md` | Docs |
+
+---
+
+## Phase B — Infrastructure + MCP + Testing
+
+### Bug Fixes (Commit 2)
+
+| # | Fix | File(s) | Lines |
+|---|-----|---------|-------|
+| 1 | FacetedSystem RendererContract compliance — added `init()`, `resize()`, `dispose()` | `src/faceted/FacetedSystem.js:588-600` | +13 |
+| 2 | Holographic breath desync — removed independent fallback cycle | `src/holograms/HolographicVisualizer.js:954-958` | 3 changed |
+| 3 | Test version assertion updated | `tests/e2e/SDK-Integration.test.js:292` | 1 line |
+
+**Test Results**: 933/933 passing (43 test files, 0 failures)
+
+### MCP Server (Option A — Real Protocol)
+
+**New File**: `src/agent/mcp/stdio-server.js` (230 lines)
+
+Implements proper JSON-RPC 2.0 over stdio per the Model Context Protocol spec:
+
+| Feature | Status |
+|---------|--------|
+| `initialize` / `initialized` handshake | Working |
+| `tools/list` — exposes all 19 tools with schemas | Working |
+| `tools/call` — routes to MCPServer handlers | Working |
+| `resources/list` — 4 documentation resources | Working |
+| `resources/read` — serves CLAUDE.md, geometry summary, control ref, live state | Working |
+| `ping` | Working |
+| Error handling (parse errors, unknown methods, etc.) | Working |
+
+**Tested**: All 3 protocol methods verified via stdio pipe.
+
+**Binary added**: `vib3-mcp` in package.json bin section.
+
+### Agent Documentation Pack
+
+**New Directory**: `agent-config/`
+
+| File | Purpose | Size |
+|------|---------|------|
+| `mcp-config.json` | Drop-in MCP client config for Claude Desktop / Cursor | Config |
+| `README.md` | Complete setup instructions + tool reference | 2 KB |
+| `claude-agent-context.md` | Precompiled context pack for Claude agents | 3 KB |
+| `openai-agent-context.md` | OpenAI function calling schemas + integration guide | 4 KB |
+
+### Dependencies
+
+- `pnpm install --frozen-lockfile` — all deps installed successfully
+- vitest 1.6.1, playwright 1.58.0, happy-dom 20.4.0 confirmed working
+
+---
+
+## Files Changed Summary (Both Phases)
+
+### Phase A (Commit 1)
+| File | Action |
+|------|--------|
+| `src/core/CanvasManager.js` | Rewritten (110 lines) |
+| `src/core/renderers/HolographicRendererAdapter.js` | Import fix |
+| `src/core/VIB3Engine.js` | Version: 1.2.0 → 2.0.1 |
+| `src/core/Parameters.js` | Version: 1.0.0 → 2.0.1 |
+| `src/core/ErrorReporter.js` | Version: 2.0.0 → 2.0.1 |
+| `src/export/TradingCardManager.js` | Fixed imports |
+| `src/shaders/quantum/quantum.frag.glsl` | +u_breath |
+| `src/shaders/faceted/faceted.frag.glsl` | +u_breath |
+| `src/shaders/quantum/quantum.frag.wgsl` | +breath field |
+| `src/shaders/faceted/faceted.frag.wgsl` | +breath field |
+| `src/viewer/ReactivityManager.js` → `ViewerInputHandler.js` | Renamed |
+| `src/viewer/index.js` | Updated import |
+| `package-lock.json` | Deleted |
+| `CHANGELOG.md` | +v2.0.1 entries |
+
+### Phase B (Commit 2)
+| File | Action |
+|------|--------|
+| `src/faceted/FacetedSystem.js` | +init(), +resize(), +dispose() |
+| `src/holograms/HolographicVisualizer.js` | Fixed breath desync |
+| `tests/e2e/SDK-Integration.test.js` | Updated version assertion |
+| `src/agent/mcp/stdio-server.js` | **NEW** — Real MCP server |
+| `package.json` | +vib3-mcp binary |
+| `agent-config/mcp-config.json` | **NEW** — MCP client config |
+| `agent-config/README.md` | **NEW** — Agent setup guide |
+| `agent-config/claude-agent-context.md` | **NEW** — Claude context pack |
+| `agent-config/openai-agent-context.md` | **NEW** — OpenAI context pack |
+| `index-v2.html` | **NEW** — Enhanced landing page (2100+ lines) |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-06.md` | Updated with Phase C |
+
+---
+
+## Phase C — Enhanced Landing Page (Commit 3)
+
+### `index-v2.html` — Choreographed Multi-Instance GSAP Showcase (2100+ lines)
+
+A complete Canvas2D-based landing page with 10 concurrent visualizer instances showing all 3 systems:
+
+| Section | Instances | Feature |
+|---------|-----------|---------|
+| **Hero** | 1x QuantumViz | Parallax inversion on scroll, density ramps up, 4D rotation increases |
+| **Trinity** | 1x bg + 3x cards (Quantum/Faceted/Holographic) | Hover: card density decreases + speed freezes, bg density increases + matches hue, others mute |
+| **Morph** | 3x (Faceted → Quantum → Holographic) | Scroll-locked pin, crossfade between systems, per-phase parameter animation |
+| **Playground** | 1x FacetedViz | 12 live parameter sliders with real-time update |
+| **Suck-Up** | 1x (dynamic) | Click card → visualizer animates from card position → expands to 90vw/90vh fullscreen |
+
+### Key Technical Decisions
+
+- **Canvas2D** (not WebGL) to avoid context limits with 10+ concurrent instances
+- **IntersectionObserver** gates rendering to only visible canvases
+- **30fps throttle** for battery-friendly performance
+- **prefers-reduced-motion** support throughout (instant opacity, no animations)
+- **ResizeObserver** per canvas for responsive DPR-aware sizing
+- All 8 base geometries + 2 warp functions + 6D rotation implemented in JS
+- GSAP ScrollTrigger for all scroll-locked choreography
+
+### Agent-First Features in Landing Page
+
+- "Download Agent Pack" button → generates claude-agent-context.md blob
+- "CLAUDE.md" download button → generates project instructions
+- "MCP Config" download → generates mcp-config.json
+- Copy-to-clipboard install command
+- MCP config code card with syntax highlighting
+- Tool list with 7 key tools shown
+
+---
+
+## Test Health
+
+| Metric | Value |
+|--------|-------|
+| **Unit test files** | 43 |
+| **Test cases** | 933 passing, 0 failing |
+| **Duration** | ~18s |
+| **Covered modules** | Math (100%), Render (100%), Geometry (100%), Scene (100%), Agent/Telemetry (good), Creative (partial) |
+| **Known gaps** | VIB3Engine, CanvasManager, Visualizers (direct), Viewer module, WebXR/WebGPU Compute/OffscreenWorker, Gallery, LLM, WASM loader |
+
+---
+
+## Exhale / Breath Feature Analysis
+
+### What It Is
+Global organic breathing cycle (VitalitySystem.js) — 6-second cosine wave oscillating 0→1→0, modulating all 3 visualization systems:
+
+| System | Effect | Modulation Factor |
+|--------|--------|------------------|
+| Quantum | Lattice brightness pulse | +40% at full exhale |
+| Faceted | Pattern intensity pulse | +30% at full exhale |
+| Holographic | Projection expansion + glow + density | +20% / +10% / +40% |
+
+### Bug Found & Fixed
+HolographicVisualizer had independent fallback breath cycle (line 955-958) that ran out of sync when VitalitySystem value wasn't received. Fixed to use centralized value with 0.0 default.
+
+---
+
+## Remaining Development Track
+
+### Critical Path for Launch
+
+| Priority | Item | Status |
+|----------|------|--------|
+| DONE | Real MCP server (JSON-RPC 2.0 over stdio) | `stdio-server.js` working |
+| DONE | Agent documentation packs | Claude + OpenAI configs |
+| DONE | All tests passing (933/933) | Verified |
+| DONE | Enhanced landing page (index-v2.html) | Multi-instance GSAP showcase (2100+ lines) |
+| NEXT | Claude Code skill (wraps MCP) | After landing page |
+| NEXT | Test coverage for v2.0.0 modules | 18 modules at 0% |
+
+### Short-Term
+
+- WebGPU end-to-end verification
+- Resolve duplicate CollectionManager
+- Demo videos/GIFs
+- Gallery app with shareable URLs
+
+### Medium-Term
+
+- API reference site (JSDoc → Docusaurus)
+- Figma Community plugin publish
+- Discord / community setup
+- Interactive tutorial
+
+---
+
+## Project Health Snapshot
+
+| Metric | Value |
+|--------|-------|
+| **npm package** | `@vib3code/sdk@2.0.1` (published) |
+| **MCP server** | Working (JSON-RPC 2.0/stdio, 19 tools, 4 resources) |
+| **Tests** | 933/933 passing |
+| **Agent packs** | Claude + OpenAI configs ready |
+| **Critical bugs fixed** | 5 (CanvasManager, HolographicAdapter, Faceted contract, breath desync, TradingCardManager) |
+| **CI workflows** | 9 GitHub Actions |

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-13.md

@@ -0,0 +1,127 @@
+# Development Session — 2026-02-13
+
+**Session type**: Agent Harness Implementation — MCP tools, ChoreographyPlayer, aesthetic mapping, headless rendering
+**Branch**: `claude/clause-code-skill-0PV33`
+**Operator**: Claude Code (Opus 4.6)
+**Parent work**: Builds on Phase 7 agent-power tools added earlier this session (7 new MCP tools, 2 Claude Code skills)
+
+---
+
+## Session Overview
+
+This session had two phases:
+
+### Phase 1 — Claude Code Skills + Initial Agent Tools (Commit 1)
+
+- Created 2 Claude Code skills (`.claude/commands/vib3-design.md`, `.claude/commands/vib3-dev.md`)
+- Added 7 new MCP tools (19 → 26): `describe_visual_state`, `batch_set_parameters`, `create_timeline`, `play_transition`, `apply_color_preset`, `set_post_processing`, `create_choreography`
+- Created agent harness architecture doc (`DOCS/AGENT_HARNESS_ARCHITECTURE.md`)
+- Added `.claude/settings.json` with shader validation pre-commit hook
+
+### Phase 2 — Harness Runtime Implementation (Commit 2)
+
+Implementing the concrete runtime pieces described in `DOCS/AGENT_HARNESS_ARCHITECTURE.md`:
+
+1. **`capture_screenshot` MCP tool** — Composites all 5 canvas layers → base64 PNG
+2. **`ChoreographyPlayer`** — Runtime class that plays back `create_choreography` JSON specs, manages scene transitions, per-scene timelines, system switching
+3. **`AestheticMapper`** — Text-description → parameter range mapping with 60+ vocabulary words across 6 categories (emotions, styles, colors, motion, depth, geometry)
+4. **`design_from_description` MCP tool** — Uses AestheticMapper to convert natural language to params
+5. **`play_choreography` MCP tool** — Loads and plays choreography specs with play/pause/stop/seek
+6. **`control_timeline` MCP tool** — Controls previously created ParameterTimeline instances
+7. **`get_aesthetic_vocabulary` MCP tool** — Lists all known descriptor words by category
+8. **Headless renderer** — Puppeteer-based CLI tool for capturing frames without a browser
+
+---
+
+## Files Created
+
+| File | Purpose | ~Lines |
+|------|---------|--------|
+| `.claude/commands/vib3-design.md` | Design/navigation Claude Code skill | 350 |
+| `.claude/commands/vib3-dev.md` | Development/expansion Claude Code skill | 350 |
+| `.claude/settings.json` | Shader validation pre-commit hook | 15 |
+| `DOCS/AGENT_HARNESS_ARCHITECTURE.md` | Agent harness roadmap document | 200 |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-13.md` | This file | — |
+| `src/creative/ChoreographyPlayer.js` | Multi-scene choreography playback runtime | 380 |
+| `src/creative/AestheticMapper.js` | Text-description → VIB3+ parameter mapping | 500 |
+| `tools/headless-renderer.js` | Puppeteer headless frame capture CLI | 220 |
+
+## Files Modified
+
+| File | Change | Risk |
+|------|--------|------|
+| `src/agent/mcp/tools.js` | Added 12 new tool definitions (total: 31) | LOW — additive only, all appended at end |
+| `src/agent/mcp/MCPServer.js` | Added 3 imports + 10 new handler methods + 5 new switch cases | LOW — additive only |
+| `agent-config/README.md` | Updated tool count (31) and table with new categories | LOW — docs only |
+| `agent-config/claude-agent-context.md` | Updated version, added power/choreography workflows, aesthetic vocabulary | LOW — docs only |
+
+## MCP Tool Inventory (31 total)
+
+| Phase | Tools Added | Count |
+|-------|------------|-------|
+| Original | get_sdk_context, verify_knowledge, create_4d_visualization, set_rotation, set_visual_parameters, switch_system, change_geometry, get_state, randomize_parameters, reset_parameters, save_to_gallery, load_from_gallery, search_geometries, get_parameter_schema | 14 |
+| Phase 6.5 | set_reactivity_config, get_reactivity_config, configure_audio_band, export_package | 4 |
+| Phase 6.6 | apply_behavior_preset, list_behavior_presets | 2 |
+| Phase 7 | describe_visual_state, batch_set_parameters, create_timeline, play_transition, apply_color_preset, set_post_processing, create_choreography | 7 |
+| Phase 7.1 | capture_screenshot, design_from_description, get_aesthetic_vocabulary, play_choreography, control_timeline | 4 |
+
+## Potential Conflicts with Parallel Work
+
+| File | Conflict Zone | Resolution |
+|------|--------------|------------|
+| `src/agent/mcp/tools.js` | End of `toolDefinitions` object (lines 648+) | Take both — all additions are appended after `list_behavior_presets` |
+| `src/agent/mcp/MCPServer.js` | Switch statement (lines 166-197), new methods (lines 1345+) | Take both — new switch cases + methods at end of class |
+| `agent-config/README.md` | Tool count number and table | Manual merge — update count, combine tables |
+| `agent-config/claude-agent-context.md` | Workflow section | Manual merge — keep both workflow blocks |
+| `package.json` | Only if parallel work adds exports | Our changes don't touch package.json |
+| `src/creative/` | New files only | No conflict — `ChoreographyPlayer.js` and `AestheticMapper.js` are new |
+
+### Phase 3 — Tests, Skills Update, Example Choreographies (Commit 3)
+
+Completing the harness work with tests, skill updates, and example content:
+
+1. **Updated `.claude/commands/vib3-design.md`** — Added 4 new workflows: Natural Language Design (Workflow 1), Multi-Scene Choreography (Workflow 6), Agent Visual Feedback Loop (Workflow 7), re-numbered existing workflows; updated tool count (19→31), file references, "When User Says" table with new tool mappings
+2. **Updated `.claude/commands/vib3-dev.md`** — Added ChoreographyPlayer and AestheticMapper to creative tooling table, updated tool count (19→31), test count (4→6)
+3. **ChoreographyPlayer tests** (`tests/creative/ChoreographyPlayer.test.js`, 29 tests) — constructor, load, getState, seek, seekToPercent, scene transitions, stop, destroy, COLOR_PRESET_MAP
+4. **AestheticMapper tests** (`tests/creative/AestheticMapper.test.js`, 32 tests) — mapDescription, resolveToValues, getVocabulary, getVocabularyByCategory, VOCABULARY static, partial matching, real-world descriptions
+5. **MCP harness tool tests** (`tests/agent/MCPHarnessTools.test.js`, 25 tests) — designFromDescription, getAestheticVocabulary, captureScreenshot, createChoreography, playChoreographyTool, createTimeline, controlTimeline, describeVisualState
+6. **Example choreographies** (`examples/choreographies/`) — 3 ready-to-play specs: cosmic-journey (60s, 3 scenes), meditation-breath (30s loop), energy-burst (20s, 140 BPM)
+
+---
+
+## Notes for Future Sessions
+
+- `ChoreographyPlayer` imports `ParameterTimeline` and `TransitionAnimator` from `src/creative/`
+- `capture_screenshot` only works in browser context (needs canvas access); returns structured error in Node
+- `AestheticMapper` is stateless — can be used standalone or via MCP tool
+- Headless renderer is a standalone CLI tool in `tools/`, not imported by the SDK itself
+- MCPServer lazily creates `_aestheticMapper`, `_choreographyPlayer`, `_liveTimelines` on first use
+- `control_timeline` materializes stored timeline data into live `ParameterTimeline` instances on first play
+- Color preset values in `ChoreographyPlayer.COLOR_PRESET_MAP` must stay in sync with `MCPServer.applyColorPreset`
+
+## Architecture Notes
+
+```
+Agent → MCP Tool Call
+        ↓
+MCPServer.handleToolCall(name, args)
+        ↓
+┌─────────────────────────────────┐
+│ Phase 7 Handler Methods         │
+│                                 │
+│ captureScreenshot()             │  ← canvas.toDataURL composite
+│ designFromDescription()         │  ← AestheticMapper.resolveToValues
+│ playChoreographyTool()          │  ← ChoreographyPlayer.load + .play
+│ controlTimeline()               │  ← ParameterTimeline.play/pause/seek
+│ getAestheticVocabulary()        │  ← AestheticMapper.getVocabularyByCategory
+│                                 │
+│ Earlier Phase 7:                │
+│ describeVisualState()           │  ← natural language description
+│ batchSetParameters()            │  ← atomic multi-param set
+│ createTimeline()                │  ← build timeline spec
+│ playTransition()                │  ← TransitionAnimator.sequence
+│ applyColorPreset()              │  ← hue/sat/intensity mapping
+│ setPostProcessing()             │  ← effect pipeline config
+│ createChoreography()            │  ← multi-scene spec builder
+└─────────────────────────────────┘
+```

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-15.md

@@ -0,0 +1,142 @@
+# Development Session — 2026-02-15
+
+**Session type**: Layer Architecture Redesign, Codebase Audit, Preset/Reactivity Expansion
+**Branch**: `claude/vib3-sdk-handoff-p00R8`
+**Operator**: Claude Code (Opus 4.6)
+**Parent work**: Builds on Feb 13 agent harness + Feb 6 RendererContract work
+
+---
+
+## Session Overview
+
+### Phase 1 — Layer Architecture Redesign
+
+The original 5-layer canvas system used static multipliers — every layer received identical parameters scaled by hardcoded opacity/density/speed factors. This produced "the same shader pasted 5 times with different opacity" instead of actual inter-layer dynamics.
+
+**Built**: `LayerRelationshipGraph` — a keystone-driven system where one layer drives and others derive their parameters through configurable relationship functions.
+
+6 preset relationship types:
+| Preset | Behavior |
+|--------|----------|
+| `echo` | Attenuated follower (same params, scaled down) |
+| `mirror` | Inverts rotation planes, shifts hue 180° |
+| `complement` | Color complement, density inverted around pivot |
+| `harmonic` | Density at integer multiples, hue at golden angle intervals |
+| `reactive` | Amplifies parameter deltas over time |
+| `chase` | Lerps toward keystone with configurable delay |
+
+5 named profiles that configure the full 5-layer graph:
+- `holographic` — content drives, echo/complement/harmonic/reactive
+- `symmetry` — mirror mode with chase accent
+- `chord` — all harmonic at musical intervals
+- `storm` — all reactive with increasing gain
+- `legacy` — replicates old static multiplier behavior exactly
+
+### Phase 2 — TypeScript Type Audit
+
+Found and fixed 4 type definition issues:
+1. Export name mismatch (RELATIONSHIP_PRESETS → PRESET_REGISTRY)
+2. Missing MultiCanvasBridge type definition
+3. Broken barrel file (types/render/index.d.ts)
+4. Incorrect exports in types/adaptive-sdk.d.ts
+
+### Phase 3 — Comprehensive Codebase Audit
+
+Found and fixed 7 critical issues across the SDK:
+
+| File | Problem | Fix |
+|------|---------|-----|
+| `src/math/index.js` | Top-level `await import()` breaks bundlers | Static imports |
+| `src/render/index.js` | `require()` in ESM package | Static ESM import |
+| `src/scene/index.js` | `require()` in `createSceneContext()` | Use already-imported classes |
+| `src/export/index.js` | 8 missing exports | Added ShaderExporter, VIB3PackageExporter, etc. |
+| `src/reactivity/index.js` | `console.log()` side effect in barrel | Removed |
+| `package.json` | Missing `./creative`, `./export`, `./variations` entry points | Added |
+| `types/` | Mismatched export names, missing barrel re-exports | Fixed all |
+
+### Phase 4 — CLAUDE.md Rewrite
+
+Rewrote CLAUDE.md from 224 → 366 lines:
+- Fixed MCP tool count (12 → 31) with full categorized table
+- Added LayerRelationshipGraph documentation
+- Added all new file references
+- Added recent session work section
+- Added 4 new gotchas (ESM only, 31 tools, layer defaults, initialize check)
+- Updated test count, status, documentation map with staleness notes
+
+### Phase 5 — LayerPresetManager + Reactivity Wiring + MCP Tools
+
+Built the preset management and reactivity-driven layer modulation system:
+
+**LayerPresetManager** (`src/render/LayerPresetManager.js`):
+- Save/load/delete/list user presets
+- Create presets from current graph state
+- Tune individual relationship parameters at runtime
+- Persist presets to localStorage
+- Import/export preset libraries as JSON
+
+**Reactivity-driven layer modulation** (`src/render/LayerReactivityBridge.js`):
+- Audio frequency bands modulate relationship parameters (e.g., bass → reactive gain)
+- Device tilt/gyroscope modulates relationship configs
+- Configurable modulation mappings per input source
+- Pre-built modulation profiles (audioStorm, tiltHarmonic, etc.)
+
+**MCP tools** (5 new layer control tools):
+- `set_layer_profile` — Load a named layer profile
+- `set_layer_relationship` — Set relationship for a specific layer
+- `set_layer_keystone` — Change the keystone layer
+- `get_layer_config` — Get current layer configuration
+- `tune_layer_relationship` — Adjust config on an active relationship
+
+---
+
+## Files Created
+
+| File | Purpose | ~Lines |
+|------|---------|--------|
+| `src/render/LayerRelationshipGraph.js` | Keystone-driven inter-layer parameter system | 610 |
+| `src/render/LayerPresetManager.js` | Preset save/load/tune for layer relationships | ~300 |
+| `src/render/LayerReactivityBridge.js` | Audio/tilt/input → layer relationship modulation | ~280 |
+| `types/render/LayerRelationshipGraph.d.ts` | Full TypeScript definitions | 120 |
+| `types/render/LayerPresetManager.d.ts` | TypeScript definitions for preset manager | ~60 |
+| `types/render/LayerReactivityBridge.d.ts` | TypeScript definitions for reactivity bridge | ~70 |
+| `tests/render/LayerRelationshipGraph.test.js` | 63 tests for relationship graph | 450 |
+| `tests/render/LayerPresetManager.test.js` | Tests for preset manager | ~200 |
+| `tests/render/LayerReactivityBridge.test.js` | Tests for reactivity bridge | ~200 |
+| `pages/layer-demo.html` | Visual demo for testing layer dynamics | ~300 |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-15.md` | This file | — |
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `src/render/MultiCanvasBridge.js` | Integrated LayerRelationshipGraph for per-layer parameter resolution |
+| `src/holograms/RealHolographicSystem.js` | Added layer graph integration, `loadRelationshipProfile()`, `setKeystone()`, `setLayerRelationship()` |
+| `src/render/index.js` | Fixed `require()` → ESM, added LayerRelationshipGraph + PresetManager + ReactivityBridge exports |
+| `src/math/index.js` | Fixed top-level `await import()` → static imports |
+| `src/scene/index.js` | Fixed `require()` → use imported classes |
+| `src/export/index.js` | Added 8 missing exports |
+| `src/reactivity/index.js` | Removed `console.log()` side effect |
+| `src/agent/mcp/tools.js` | Added 5 layer control tool definitions |
+| `src/agent/mcp/MCPServer.js` | Added 5 layer control handlers |
+| `package.json` | Added `./creative`, `./export`, `./variations` entry points |
+| `types/adaptive-sdk.d.ts` | Fixed export names, added layer system re-exports |
+| `types/render/index.d.ts` | Added LayerRelationshipGraph, PresetManager, ReactivityBridge re-exports |
+| `types/systems/index.d.ts` | Added layer relationship API to RealHolographicSystem |
+| `CLAUDE.md` | Comprehensive rewrite (224 → 366 lines) |
+
+## Test Results
+
+- **Before session**: 1430 tests, 70 files
+- **After session**: 1702+ tests, 75+ files
+- All passing
+
+## Commits
+
+| Hash | Message |
+|------|---------|
+| `59fb951` | feat(render): add LayerRelationshipGraph — keystone-driven inter-layer parameter system |
+| `bec4cad` | fix(types): correct export names and barrel re-exports for LayerRelationshipGraph |
+| `aeac38c` | fix: resolve 7 broken barrel files, require() in ESM, missing exports |
+| `4031700` | docs: comprehensive CLAUDE.md rewrite |
+| (pending) | feat: LayerPresetManager, LayerReactivityBridge, MCP layer tools, demo page |

package/DOCS/dev-tracks/README.md

@@ -0,0 +1,10 @@
+# Development Track Logs
+
+Detailed, session-level implementation notes are stored here.
+
+## Sessions
+
+- [2026-01-31 session](DEV_TRACK_SESSION_2026-01-31.md)
+- [2026-02-06 session](DEV_TRACK_SESSION_2026-02-06.md)
+
+Roadmap references are maintained in [`DOCS/ROADMAP.md`](../ROADMAP.md).