@vib3code/sdk 2.0.1 → 2.0.3-canary.3349130

package/DOCS/HANDOFF_LANDING_PAGE.md

@@ -0,0 +1,154 @@
+# VIB3+ Landing Page & Marketing Handoff Prompt
+
+**Copy this entire document as the initial prompt when starting a new session focused on the landing page, marketing site, and forward-facing aspects.**
+
+---
+
+## Context
+
+You are continuing development on the **VIB3+ landing page** — the marketing/showcase site for the `@vib3code/sdk` npm package (a 4D visualization SDK). The landing page demonstrates the SDK's three rendering systems (Quantum, Faceted, Holographic) through an immersive scroll-driven experience with GSAP choreography.
+
+**Repository:** `Domusgpt/vib34d-xr-quaternion-sdk`
+**Landing page location:** `site/` directory (separated from SDK code as of 2026-02-13)
+**Live URL:** GitHub Pages deploy from `docs/` + root
+**Owner:** Clear Seas Solutions LLC / Paul Phillips
+
+## Architecture
+
+```
+site/
+├── index.html                    # Landing page (1977 lines, 9 scroll sections)
+├── styles/
+│   ├── overlay-accents.css       # CSS-only accent overlays (gradient washes, mirrors, particles)
+│   └── reveal-layers.css         # Multi-layer parallax reveal system (NEW)
+└── js/
+    ├── main.js                   # Boot script — GPU context pool + section initialization
+    ├── config.js                 # Section parameter presets (hero, morph stages, etc.)
+    ├── adapters.js               # SDK system adapters (Quantum/Holographic/Faceted + AmbientLattice)
+    ├── ContextPool.js            # WebGL context budget manager (max 3 concurrent)
+    ├── CardTiltSystem.js         # Mouse/touch → CSS 3D tilt + visualizer param mapping
+    ├── choreography.js           # Main GSAP ScrollTrigger choreography (83KB, all sections)
+    ├── overlay-choreography.js   # CSS accent overlays (gradient wash, mirror, glow, particles)
+    └── reveal-choreography.js    # Multi-layer parallax reveal transitions (NEW)
+
+Root SDK demo (separate):
+├── index.html                    # Clean SDK demo with toolbar (NOT the landing page)
+```
+
+**CDN Dependencies:** Lenis smooth scroll, GSAP 3.12.5, ScrollTrigger 3.12.5 (loaded dynamically with 5s timeout fallback)
+
+**SDK Imports:** `site/js/adapters.js` imports directly from `../src/` (Quantum, Holographic, Faceted engines). This is intentional since the site lives in the monorepo.
+
+## Current Page Sections (9 total, ~3050vh scroll)
+
+| Section | Height | GPU Contexts | Systems | Key Feature |
+|---------|--------|--------------|---------|-------------|
+| Opening Cinematic | 800vh | 1 | Quantum | SVG text mask ("VIB3CODE") + lattice parallax |
+| Hero | 100vh | 1 | Quantum | Title reveal + badge |
+| Morph Experience | 1200vh | 1 (swaps) | Q→H→F | 6-stage card morphing with system swaps |
+| Playground | static | 1 | User choice | Full parameter control (all 6D rotation planes) |
+| Triptych | 200vh | 3 | Q+H+F | 3-system split-screen simultaneous render |
+| Geometry Cascade | 400vh | 2+C2D | Q+H bg | Horizontal scroll cards with geometry showcase |
+| Energy Transfer | 250vh | 2 | Q bg + F card | Interactive sweep demo |
+| Agent Integration | static | 1 | Holographic | Download packs (MCP, Claude, OpenAI) |
+| CTA | 100vh | 2 | Q+F diagonal | Installation code + links |
+
+**Total GPU budget:** Max 3 concurrent WebGL contexts. ContextPool auto-evicts oldest.
+
+## What's Working
+
+### Choreography Engine (choreography.js — 83KB)
+- **Depth Illusion Engine** — gridDensity = distance metaphor + CSS scale/blur/shadow
+- **6 Coordination Modes** — opposition, convergence, call-response, heartbeat, energy-conservation, crossfade
+- **Mathematical parameter curves** — Lissajous rotation, sine interference, exponential ramps
+- **Section-specific timelines** — Each section has a pinned ScrollTrigger with multi-phase choreography
+- **System swaps** — Morph section smoothly transitions Q→H→F with flash effects
+
+### Overlay System (overlay-choreography.js — 35KB)
+- 5 accent systems: GradientWash, MirrorReflection, EdgeGlowRing, ParticleField, CrossfadeBridge
+- Quaternion-to-CSS bridge (feeds 4D rotation to CSS custom properties)
+- AccentChoreographer master controller
+
+### NEW: Reveal Layer System (reveal-choreography.js + reveal-layers.css)
+- **Replaces ugly SVG section dividers** with dynamic transitions
+- **8 transition patterns:** Iris aperture, diagonal bars, column split, glass panel retraction, bezel bar criss-cross, checkerboard dissolve
+- **Persistent parallax field** — Subtle geometric depth texture at 0.3x scroll speed
+- **Floating glassmorphic accent strips** — 3 colored lines at different parallax rates
+- **Glow lines** — Luminous accent lines at section boundaries (replace SVG curves)
+- **Section edge blending** — CSS gradient fades at section top/bottom (replace hard seams)
+
+## Known Issues & Priorities
+
+### HIGH PRIORITY — Visual Quality
+1. **Rectangular layout problem** — Despite excellent choreography math, everything is constrained to rectangular cards. Need organic shapes (SVG blob paths, fluid bezier boundaries, non-rectilinear clip-paths).
+2. **Predictable symmetry** — Triptych is perfect 33/33/33, CTA is 50/50 diagonal, energy is centered. Need asymmetry and visual tension.
+3. **Universal accent treatment** — Every card gets the same vignette+shadow+glow+chroma. Differentiate: some sections should get unique treatments while others stay minimal.
+4. **Mobile experience** — 3050vh total scroll on mobile is excessive. Canvas count should drop to 1 concurrent. Cascade horizontal scroll breaks at small viewports (6 cards at 88vw).
+
+### MEDIUM PRIORITY — Functionality
+5. **AmbientLattice anti-pattern** — 580-line Canvas2D renderer in adapters.js duplicates SDK geometry. Should use SDK's FacetedSystem with reduced GPU overhead instead.
+6. **No audio demo** — Audio reactivity is a key SDK feature but not demonstrated anywhere on the landing page. Add a toggle or auto-detect section.
+7. **No SpatialInput demo** — Device tilt/gyroscope is a selling point but not shown. Consider a "tilt your phone" section.
+8. **Agent section download links** — Point to `agent-config/` which may not exist in the site/ directory. Verify paths.
+
+### LOW PRIORITY — Polish
+9. **Performance profiling** — Mirror/MultiInstance overlays copy canvases via 2D context (CPU-bound). Profile on low-end devices.
+10. **Accessibility** — Many decorative elements lack `aria-hidden`. Heading hierarchy has duplicate `<h1>`. Keyboard navigation untested.
+11. **Cascade card clip-path morphing** — The 8-point polygon system (rect/hex/diamond/oct) is clever but all shapes share the same bounding box. More dramatic shape variation needed.
+
+## GSAP Pattern Reference (From Visual Codex)
+
+These patterns were studied and should inform future development:
+
+### Stagger Patterns
+- `from: "center"` with elastic easing for outward reveals
+- Grid-based: `stagger: { grid: [rows, cols], from: "edges", amount: 1.2 }`
+- Function-based: `each: (i) => i * 0.05 + Math.random() * 0.1`
+
+### 3D Transforms
+- Z-depth emergence: `fromTo(el, { z: -500, scale: 0 }, { z: 0, scale: 1 })`
+- Multi-axis spin: `{ rotationX: 720, rotationY: 540, rotationZ: 360 }` with elastic
+- `perspective: 1000px` on body, `transform-style: preserve-3d` on containers
+
+### Filter/Blur
+- Progressive blur reveal: `fromTo(el, { filter: "blur(20px)" }, { filter: "blur(0px)" })`
+- Layered blur stack: 3 layers at different blur levels, stagger `"<0.2"` relative timing
+- Glassmorphism: `backdrop-filter: blur(20px)` on panels
+
+### Multi-Visualizer Choreography
+- 5-phase scroll modes: Intro→Grid→Carousel→Expand→Finale
+- Impulse system: `targets.impulse = Math.min(targets.impulse + intensity, 1.5)`, decays at 92%/frame
+- Scrub smoothing: `scrub: 0.3` (300ms delay)
+
+## Design Direction
+
+The current page has **world-class mathematical choreography** trapped in a **rigid rectangular grid**. The goal is to break free with:
+
+1. **Multiple parallax layers** — Not just 2. Different areas should have different layer counts and behaviors (columns in one area, concentric iris in another, diagonal bars in a third).
+2. **Negative space** — Solid layers with cutouts that reveal visualizers. The visualizers shine THROUGH the design, not inside rectangular boxes.
+3. **Organic boundaries** — SVG blob paths, fluid beziers, non-rectangular clip-paths. Nothing should be a perfect rectangle.
+4. **Asymmetrical compositions** — Break the grid. Unequal column widths, off-center elements, visual tension.
+5. **Varied visual vocabulary** — Not every section needs every effect. Some should be minimal and clean, others dramatic and layered.
+6. **Glass morphism as a design language** — Frosted glass panels that slide, morph, and shatter to reveal content.
+
+## Commands
+
+```bash
+# From project root:
+pnpm dev                         # Opens dev server (default: docs gallery)
+# Then navigate to /site/index.html for landing page
+# Or / for SDK demo
+
+# To verify no SDK regressions:
+pnpm test
+```
+
+## Session Instructions
+
+1. Read `site/index.html` for the full HTML structure
+2. Read `site/js/choreography.js` for the existing scroll timeline (it's 83KB — skim the section-level functions)
+3. Read `site/js/reveal-choreography.js` for the new overlay layer system
+4. **Do not break existing choreography** — the new system layers ON TOP
+5. Test in browser after changes — the page relies on CDN-loaded GSAP
+6. Focus on the visual quality issues listed above
+7. Use the GSAP pattern reference for implementation guidance

package/DOCS/HANDOFF_SDK_DEVELOPMENT.md

@@ -0,0 +1,493 @@
+# VIB3+ SDK — Comprehensive Agent Handoff
+
+**Copy this entire document as the initial prompt when starting a new session focused on SDK development.**
+
+Last updated: 2026-02-13
+
+---
+
+## 1. What VIB3+ Actually Is
+
+VIB3+ is a **programmable 4D visualization SDK** — a JavaScript library that renders interactive, audio-reactive visualizations of four-dimensional geometry in real-time on the web.
+
+The core idea: objects in four spatial dimensions (X, Y, Z, W) are mathematically rotated using six independent rotation planes, then projected down to 3D and rendered on-screen. This produces visual effects that are impossible to achieve with standard 3D graphics — objects that fold through themselves, invert, breathe, and transform in ways that feel alien and captivating.
+
+It's not a toy or a demo. It's an SDK intended for production use — with framework adapters (React, Vue, Svelte), creative tools (color presets, post-processing, BPM-synced timelines), platform integrations (Figma, Three.js, TouchDesigner, OBS), advanced features (WebXR, MIDI, AI presets), and an agentic control layer (MCP server with 19 tools, CLI).
+
+**Repository**: `Domusgpt/vib34d-xr-quaternion-sdk`
+**Package**: `@vib3code/sdk` v2.0.3 (published on npm)
+**Owner**: Clear Seas Solutions LLC / Paul Phillips (pallasite)
+**License**: MIT (open-core — see `DOCS/LICENSING_TIERS.md` for commercial tier plans)
+**Stack**: ES Modules, Vite, pnpm, Vitest, Playwright, C++ WASM (Emscripten)
+
+### Why It Exists
+
+Paul's vision: a **visual engine for the fourth dimension** that anyone can embed, control, and ship with. The differentiation vs. standard WebGL demos:
+
+1. **Unified mathematical model** — Not one-off shader toys. A coherent 6D rotation system backed by Clifford algebra that works identically across WASM, GLSL, and WGSL.
+2. **Multiple rendering aesthetics** — Three visual systems (Quantum, Faceted, Holographic) that share the same geometry/rotation math but produce completely different visual outputs.
+3. **Production SDK structure** — Real npm package with 80+ export paths, TypeScript types, framework components, CI/CD, versioning, changelogs.
+4. **Agent-first operability** — MCP server, CLI, telemetry. AI agents can create, tune, and operate visualizations programmatically.
+5. **Breadth of integration** — Figma plugin, Three.js material, TouchDesigner export, OBS mode, WebXR, MIDI. It meets creators where they already work.
+
+### Who Uses It
+
+| Persona | What they care about |
+|---|---|
+| **Creative developers** | Shipping differentiated visual experiences — landing pages, dashboards, interactive art. They want stable APIs, fast iteration, framework adapters. |
+| **Technical artists / VJs** | Driving visuals via presets, timelines, audio reactivity, and MIDI for live performance. They want rich control and real-time feedback. |
+| **Product teams** | Embedding performant, controllable visualizations into production apps. They want clear lifecycle models, testability, long-term compatibility. |
+| **AI/agent builders** | Automating scene generation, tuning, and operation. They want MCP tools, CLI, machine-readable schemas, guardrails. |
+| **XR teams** | Extending 4D visuals into VR/AR. They want GPU-aware architecture, input abstraction, spatial rendering paths. |
+
+---
+
+## 2. The Three Visualization Systems — What They Actually Are
+
+This is the heart of VIB3+. Each system takes the same 24 geometries and 6D rotation math but renders them with a fundamentally different aesthetic and technical approach. Understanding what makes each one visually distinct is critical for anyone working on the project.
+
+### Quantum System (`src/quantum/`)
+
+**Files**: `QuantumEngine.js` (system manager), `QuantumVisualizer.js` (WebGL renderer)
+
+**Visual character**: Dense, complex, scientific. Think crystalline lattices, energy field interference patterns, particle grids pulsing with life. This is the system that looks most like looking through a microscope at something alien.
+
+**Technical approach**: Single procedural fragment shader running entirely on the GPU. Every pixel is computed mathematically from the rotation state, geometry type, and time. No mesh geometry — it's all raymarching and distance field math in the shader. This makes it incredibly flexible but means the visual complexity is bounded by fragment shader performance.
+
+**When you'd choose Quantum**: Abstract backgrounds, scientific visualizations, anything where visual density and complexity are assets. It's the most "impressive at first glance" system.
+
+**Audio reactivity**: Bass drives density pulsing, mid drives color shift, high drives edge definition. All wired through shader uniforms.
+
+### Faceted System (`src/faceted/`)
+
+**File**: `FacetedSystem.js` (complete system — shader and rendering in one file)
+
+**Visual character**: Clean, precise, geometric. Think kaleidoscopic symmetry, sacred geometry tiles, wireframe patterns with perfect edges. Where Quantum feels organic and noisy, Faceted feels designed and intentional.
+
+**Technical approach**: Also a procedural fragment shader, but the geometry functions produce clean 2D patterns projected from 4D rotation rather than 3D volumetric effects. Uses HSL color pipeline with full hue + saturation control — this was a v2.0.0 fix (originally missing saturation).
+
+**When you'd choose Faceted**: UI elements, design-forward applications, polished product surfaces, anywhere clarity and elegance matter more than visual density. Also the best system for demonstrating how 4D rotation works — the 2D patterns make the dimensional folding intuitive.
+
+**Audio reactivity**: Bass modulates density, mid modulates morph factor, high shifts hue. Click intensity provides interaction feedback. All wired via shader uniforms (this was also a v2.0.0 fix — audio was originally unwired).
+
+### Holographic System (`src/holograms/`)
+
+**Files**: `RealHolographicSystem.js` (system manager, 652 LOC), `HolographicVisualizer.js` (per-layer renderer)
+
+**IMPORTANT**: The class name is `RealHolographicSystem`. Not `HolographicSystem`. This trips people up constantly.
+
+**Visual character**: Layered, atmospheric, immersive. Think holographic trading cards, glassmorphic interfaces, aurora-like effects with depth and transparency. This is the system that feels most like holding a physical holographic object.
+
+**Technical approach**: The key differentiator — a **5-layer canvas stack** where each layer has its own `HolographicVisualizer` instance with independent parameters:
+
+```
+background-canvas  — Base layer, lowest opacity, sets the scene
+shadow-canvas      — Depth/shadow effects, creates perceived volume
+content-canvas     — Primary visual content, the main show
+highlight-canvas   — Bright accents that pop above the content
+accent-canvas      — Top layer effects, sparkle and shimmer
+```
+
+Each layer gets per-layer uniforms (`u_layerScale`, `u_layerOpacity`, `u_layerColor`, `u_densityMult`, `u_speedMult`) on top of the standard parameter set. The layers composite with CSS opacity to create the glassmorphic depth effect.
+
+**Audio reactivity**: Native microphone input. Beat detection on bass, melody detection on mid/high. Per-layer reactivity multipliers — so bass can punch the background while melody sparkles the accent layer.
+
+**When you'd choose Holographic**: Trading card effects, immersive backgrounds, music visualizers, anything where depth and atmosphere matter. It's the most "physical feeling" system.
+
+### Polychora (NOT ACTIVE)
+
+Planned fourth system for rendering true 4D polytopes (5-cell, tesseract as wireframe, 16-cell, 24-cell, 600-cell, 120-cell). Files are archived in `archive/polychora/`. The 1,065-line system stub exists but is **not production-ready, not enabled in UI, and should not be built against**. It's a future roadmap item.
+
+---
+
+## 3. Core Mathematical Architecture
+
+### The 24 Geometry System
+
+Every visualization system renders 24 geometry variants. The encoding is:
+
+```
+geometry_index = core_type * 8 + base_geometry
+```
+
+**8 base geometries** (index 0-7):
+| Index | Name | What it looks like |
+|---|---|---|
+| 0 | Tetrahedron | Sharp, minimal — the simplest 3D solid extended to 4D |
+| 1 | Hypercube | The iconic tesseract — a cube within a cube, 16 vertices, 32 edges |
+| 2 | Sphere | Smooth, radial harmonics — a hypersphere projected down |
+| 3 | Torus | Donut topology — continuous surface that wraps |
+| 4 | Klein Bottle | Non-orientable — a surface that passes through itself (4D required!) |
+| 5 | Fractal | Self-similar recursive subdivision — infinite detail at every scale |
+| 6 | Wave | Sinusoidal interference — multiple waves interacting |
+| 7 | Crystal | Octahedral lattice — geometric precision, sharp facets |
+
+**3 core warps** that modify each base:
+| Core | Index Range | What it does |
+|---|---|---|
+| Base (0) | 0-7 | Pure geometry, no warp |
+| Hypersphere (1) | 8-15 | Wraps the geometry onto a 3-sphere (S3) using stereographic-like projection. Creates toroidal structures via Hopf fibration. |
+| Hypertetrahedron (2) | 16-23 | Warps the geometry onto a pentatope (5-cell). Points cluster near pentatope vertices and edges, creating a tetrahedral skeleton. |
+
+The warp functions live in `src/geometry/HypersphereCore.js` and `src/geometry/HypertetraCore.js`.
+
+### The 6D Rotation System
+
+This is mathematically the most important part of VIB3+. In 4D space, there are six independent rotation planes (not three like in 3D):
+
+| Plane | Type | Intuitive effect |
+|---|---|---|
+| XY | 3D | Familiar rotation around Z axis |
+| XZ | 3D | Familiar rotation around Y axis |
+| YZ | 3D | Familiar rotation around X axis |
+| XW | 4D | Rotates X into the fourth dimension — objects appear to stretch/compress in X |
+| YW | 4D | Rotates Y into the fourth dimension |
+| ZW | 4D | Rotates Z into the fourth dimension |
+
+**Application order MATTERS**: XY, XZ, YZ, XW, YW, ZW. Rotation is not commutative in 4D. Changing the order produces different results. This is enforced in all three implementations:
+
+1. **C++ WASM rotors** (`cpp/Rotor4D.cpp`): Uses Clifford algebra Cl(4,0). Mathematically exact. The "ground truth" implementation. An 8-component rotor (scalar + 6 bivectors + pseudoscalar) represents the rotation, applied via the sandwich product `v' = R * v * R_dagger`.
+
+2. **GLSL matrices** (inline in visualizer `.js` files): GPU-accelerated, computed per-pixel in fragment shaders. Six 4x4 rotation matrices multiplied together. This is what actually renders on screen.
+
+3. **WGSL matrices** (WebGPU path): Same math as GLSL but in WGSL syntax for the WebGPU backend.
+
+All three must produce identical results. If they disagree, you have a bug.
+
+### 4D to 3D Projection
+
+After rotation, 4D points must be projected to 3D for display:
+
+- **Perspective** (default): `P = xyz / (distance - w)`. The `dimension` parameter (3.0-4.5) controls the projection distance. Lower values = more dramatic distortion.
+- **Stereographic**: `P = xyz / (1 - w)`. Conformal — preserves angles. Produces smoother deformations.
+- **Orthographic**: `P = xyz`. Just drops W. Parallel projection — no foreshortening.
+
+---
+
+## 4. Development History & Arc
+
+Understanding where the project has been is essential for knowing where it's going.
+
+### Phase 1-3: Foundation (pre-2026)
+The core engine was built: 3 visualization systems, 24 geometry encoding, 6D rotation with WASM + GLSL, MCP agent tools, CLI, telemetry. This was ~60K lines of working code.
+
+### Phase A: Parity & Polish (v2.0.0)
+Fixed critical gaps discovered in audit:
+- Quantum system had no color control — added
+- Faceted system was missing saturation control and audio reactivity — added `hsl2rgb()` pipeline + bass/mid/high uniforms
+- `clickIntensity` was mapped to wrong uniform — fixed
+- Inline shaders could drift from external files — created `shader-sync-verify.js` tool (937 lines)
+
+### Phase B-D: Feature Expansion (v2.0.0)
+Added four major capability layers:
+- **Creative Tooling** (`src/creative/`): 22 color presets, 14 easing functions, 14 post-processing effects, BPM-synced parameter timeline
+- **Platform Integrations** (`src/integrations/`): React/Vue/Svelte components, Figma plugin generator, Three.js ShaderMaterial, TouchDesigner GLSL export, OBS transparent mode
+- **Advanced Features** (`src/advanced/`): WebXR 6DOF renderer, WebGPU compute shaders, MIDI controller with learn mode, AI preset generator, OffscreenCanvas worker
+- **SpatialInputSystem** (`src/reactivity/SpatialInputSystem.js`): Universal spatial input with 8 sources and 6 profiles
+
+### January 31, 2026: Master Plan Execution
+Full 570-file codebase audit revealed:
+- 14 broken package exports (quaternion, pose, sensors etc. referencing nonexistent files) — removed
+- No LICENSE file — created MIT
+- No CHANGELOG — created
+- No TypeScript barrel — created `types/adaptive-sdk.d.ts`
+- No CI publish workflow — created
+- `npm run dev` alias missing — added
+- Created landing page, CLI `init` command, React/Vanilla/Three.js examples, Storybook config, cross-browser Playwright, accessibility CSS, WASM build CI, OBS setup guide, CONTRIBUTING.md, SECURITY.md, ErrorReporter
+
+**Result**: 43 action items across 6 execution phases, ~25 files created.
+
+### February 6, 2026: Hygiene + MCP + Landing Page
+Two-phase session:
+
+**Phase A (Hygiene)**:
+- `CanvasManager.js` completely rewritten (217 to 110 lines) — API contract was broken against VIB3Engine
+- `HolographicRendererAdapter.js` import was broken — fixed
+- `TradingCardManager.js` had broken import paths — fixed
+- External shader files missing `u_breath` uniform — synced across 4 shader files
+- Version strings unified to 2.0.1 across all 4 locations
+- `ViewerInputHandler.js` renamed from `ReactivityManager` (the viewer one, not the reactivity one)
+- Stale `package-lock.json` removed (240KB)
+
+**Phase B (Infrastructure)**:
+- FacetedSystem RendererContract compliance (added `init()`, `resize()`, `dispose()`)
+- HolographicVisualizer breath desync bug fixed
+- Real MCP server created (`stdio-server.js`, 230 lines) — JSON-RPC 2.0 over stdio
+- Agent documentation packs created (Claude + OpenAI configs)
+- Enhanced landing page (`index-v2.html`, 2100+ lines)
+- Test count: 933/933 passing
+
+### February 13, 2026: Site Refactor + Documentation Overhaul
+- Separated landing page into `site/` directory
+- Extracted 1,318 lines of inline CSS to `site/styles/main.css`
+- Updated hero/messaging to emphasize C++ WASM core, WebGPU, TypeScript, MCP
+- Created product strategy, roadmap, system inventory, documentation index
+- Root `index.html` now redirects to `site/index.html`; SDK demo moved to `demo/index.html`
+- Rewrote `CLAUDE.md` from raw technical dump to proper project brief
+- Rewrote this handoff document from skeleton to comprehensive reference
+
+---
+
+## 5. Current State — Honest Assessment
+
+### What Works Well
+- **Core rendering pipeline**: All three systems render correctly. 24 geometries work. 6D rotation works.
+- **Math foundation**: WASM rotors and JS fallback produce correct results. Projections are solid.
+- **Test suite**: 933+ unit tests passing across 43 files. Math, render, geometry, scene, agent/telemetry all covered.
+- **69 E2E tests**: Playwright browser tests running.
+- **MCP server**: Real JSON-RPC 2.0 implementation with 19 tools and 4 documentation resources.
+- **npm package**: Published and installable. 80+ export paths.
+- **CI/CD**: 9 GitHub Actions workflows including auto-publish, WASM build, Pages deploy.
+- **Shader sync tooling**: `shader-sync-verify.js` catches inline/external drift.
+
+### What's Incomplete or Fragile
+- **TypeScript types**: `types/adaptive-sdk.d.ts` is a basic barrel. Most v2.0 modules (creative, integrations, advanced, SpatialInput) have NO type definitions. IDE experience is poor for ~15,500 lines of new code.
+- **WebGPU backend**: Scaffold exists (adapter, device, clear pass). Missing: pipeline creation, WGSL shader compilation, buffer binding, feature gating. WebGL is the tested path.
+- **RendererContract compliance**: Not all systems fully implement the contract interface. FacetedSystem got `init()/resize()/dispose()` in Feb 2026 but compliance is inconsistent.
+- **Test coverage for v2.0 modules**: 18 modules totaling ~15,500 lines have ZERO tests. Creative, integrations, advanced, SpatialInput, shader-sync-verify — all untested.
+- **Polychora**: 1,065-line stub that's not production-ready. Decision needed: implement or remove.
+
+### What's Aspirational (Described But Not Built)
+- **Licensing/activation system**: Detailed tier/pricing/flow/schema defined in `DOCS/LICENSING_TIERS.md`. Zero implementation. No `LicenseManager`, `FeatureGate`, or server.
+- **Figma Community publish**: Plugin code generator exists. Plugin is not published.
+- **API documentation site**: No generated docs. JSDoc exists in source but no Docusaurus/TypeDoc pipeline.
+- **Gallery web app**: Static gallery of HTML pages exists. No shareable permalinks, embed codes, or user-created presets.
+- **Performance benchmarks as CI gates**: Benchmark runner exists. No threshold assertions. Benchmarks don't fail CI on regression.
+
+---
+
+## 6. Current Priorities (Q1-Q2 2026)
+
+### Q1 2026 — Shipping Now
+| Milestone | Status | What it means |
+|---|---|---|
+| Stabilize core rendering + lifecycle contracts | In Progress | Harden RendererContract, fix edge cases in system switching, ensure destroy/dispose paths are clean |
+| MCP/agent integration hardening | In Progress | Make the 19 MCP tools robust, improve error handling, add validation |
+| Eliminate export + packaging regressions | Done | Broken exports removed, package.json cleaned up |
+
+### Q2 2026 — Next
+| Milestone | Status | Blocked by |
+|---|---|---|
+| Advanced viz subsystem parity (WebGPU, XR) | Planned | WebGPU backend completion |
+| Cross-platform SDK examples refresh | Planned | Framework adapter stabilization |
+| Observability + telemetry baseline | Blocked | Telemetry pipeline architecture decisions |
+
+### The Honest Priority Stack
+1. **Test coverage for critical path** — VIB3Engine.js, CanvasManager.js, system switching, 6D rotation end-to-end
+2. **TypeScript types** — The main entry point's types field works but most modules have no types
+3. **WebGPU backend** — Scaffold to real pipeline. This is the performance differentiator.
+4. **Landing page quality** — Currently functional but visually rigid (see `DOCS/HANDOFF_LANDING_PAGE.md` for the full breakdown)
+5. **Test coverage for v2.0 modules** — 18 modules at 0%. Not blocking launch but blocking confidence.
+
+See `DOCS/ROADMAP.md` for the full quarterly milestone plan with owner assignments and evidence links.
+
+---
+
+## 7. Architecture Details That Matter
+
+### File Structure
+```
+/
+├── src/                          # SDK source (~95K lines)
+│   ├── core/                     # Engine orchestration
+│   │   ├── VIB3Engine.js         # THE main file. System switching, params, canvas, spatial input.
+│   │   ├── CanvasManager.js      # 5-layer canvas lifecycle (rewritten Feb 2026)
+│   │   ├── Parameters.js         # Parameter definitions and validation
+│   │   ├── ParameterMapper.js    # Maps abstract params to system-specific values
+│   │   ├── UnifiedResourceManager.js  # GPU resource tracking + disposal
+│   │   ├── ErrorReporter.js      # Opt-in error reporting (v2.0.1)
+│   │   └── renderers/            # Per-system adapter classes
+│   ├── quantum/                  # Quantum visualization system
+│   ├── faceted/                  # Faceted visualization system
+│   ├── holograms/                # Holographic visualization system
+│   ├── geometry/                 # 24-geometry library + generators + warps
+│   ├── math/                     # Vec4, Rotor4D, Mat4x4, Projection (JS fallback for WASM)
+│   ├── render/                   # ShaderProgram, RenderState, WebGL/WebGPU backends
+│   ├── scene/                    # Node4D, Scene4D, ResourceManager, MemoryPool
+│   ├── reactivity/               # ReactivityManager + SpatialInputSystem
+│   ├── creative/                 # ColorPresets, Transitions, PostProcessing, Timeline
+│   ├── integrations/             # React, Vue, Svelte, Figma, Three.js, TouchDesigner, OBS
+│   ├── advanced/                 # WebXR, WebGPU Compute, MIDI, AI Presets, OffscreenWorker
+│   ├── agent/                    # MCP server, CLI, telemetry
+│   ├── viewer/                   # ViewerPortal, GalleryUI, CardBending, audio reactivity
+│   ├── export/                   # VIB3PackageExporter, TradingCardGenerator
+│   ├── gallery/                  # GallerySystem (save/load states)
+│   ├── wasm/                     # WasmLoader (optional C++ core)
+│   ├── llm/                      # LLMParameterInterface (text-to-params)
+│   ├── schemas/                  # JSON Schema validation
+│   └── shaders/                  # External shader files (GLSL + WGSL)
+├── cpp/                          # C++ WASM core (Rotor4D, Mat4x4, embind)
+├── site/                         # Landing page (HTML + GSAP choreography)
+├── demo/                         # SDK controls demo (moved from root)
+├── docs/                         # Static gallery pages (GitHub Pages)
+├── tools/                        # shader-sync-verify.js, CI scripts
+├── tests/                        # Vitest unit tests + Playwright E2E
+├── types/                        # TypeScript definitions
+├── agent-config/                 # MCP config, Claude/OpenAI context packs
+├── examples/                     # React, Vanilla, Three.js example apps
+└── .storybook/                   # Storybook config
+```
+
+### The Shader System — Where the Rendering Actually Happens
+
+This is where new developers get confused. The shaders exist in TWO places:
+
+1. **Inline in visualizer `.js` files**: `QuantumVisualizer.js`, `FacetedSystem.js`, `HolographicVisualizer.js` all contain GLSL shader source as template literals. This is what actually runs.
+
+2. **External files in `src/shaders/`**: GLSL and WGSL files that are supposed to mirror the inline versions. These exist for tooling, documentation, and future build pipeline integration.
+
+**The drift problem**: When someone edits the inline shader and forgets to update the external file (or vice versa), they desync. This was a real bug (the `u_breath` uniform existed inline but not externally). The `shader-sync-verify.js` tool (937 lines) parses both, compares uniforms/fields, and reports differences. Always run `pnpm verify:shaders` after touching any shader code.
+
+### The Canvas Architecture
+
+Each visualization system gets five HTML `<canvas>` elements stacked via CSS:
+
+```
+background-canvas  (z-index lowest, lowest opacity)
+shadow-canvas
+content-canvas     (primary rendering happens here)
+highlight-canvas
+accent-canvas      (z-index highest)
+```
+
+Canvas IDs follow system-specific naming:
+- Quantum: `quantum-background-canvas`, `quantum-shadow-canvas`, etc.
+- Faceted: `background-canvas`, `shadow-canvas`, etc. (no prefix — historical quirk)
+- Holographic: `holo-background-canvas`, `holo-shadow-canvas`, etc.
+
+`CanvasManager.js` handles creation, sizing, and destruction. It was completely rewritten on Feb 6, 2026 because its API didn't match what VIB3Engine expected. The new version is 110 lines and provides `createSystemCanvases()`, `registerContext()`, and `destroy()`.
+
+### The SpatialInputSystem
+
+This is one of VIB3+'s most distinctive features. It decouples "card tilting" from physical device orientation, creating a universal spatial input layer:
+
+**Input sources** (8): deviceTilt, mousePosition, gyroscope, gamepad, perspective, programmatic, audio, MIDI
+
+**Built-in profiles** (6): cardTilt (default), wearablePerspective, gameAsset, vjAudioSpatial, uiElement, immersiveXR
+
+**How it works**: Any input source feeds a normalized spatial state (pitch/yaw/roll/x/y/z/intensity/velocity). A profile defines how that state maps to visualization parameters. Per-axis lerp smoothing prevents jitter. "Dramatic mode" applies 8x amplification for live performance.
+
+The system is integrated into VIB3Engine with 7 methods: `enableSpatialInput()`, `disableSpatialInput()`, `feedSpatialInput()`, `setSpatialSensitivity()`, `setSpatialDramaticMode()`, `getSpatialState()`, `setSpatialProfile()`.
+
+### The MCP Agent Layer
+
+The MCP server (`src/agent/mcp/stdio-server.js`) implements JSON-RPC 2.0 over stdio per the Model Context Protocol spec. It exposes:
+
+- **19 tools** for controlling the engine: create visualizations, set rotation, change geometry, manage gallery, get state, randomize/reset, etc.
+- **4 documentation resources**: CLAUDE.md, geometry summary, control reference, live state
+- **Proper protocol handshake**: `initialize`/`initialized`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`
+
+The `vib3-mcp` binary in package.json makes it installable as an MCP server for Claude Desktop, Cursor, and other MCP clients. Agent config packs in `agent-config/` provide drop-in setup for Claude and OpenAI agents.
+
+### The Creative Tooling Layer
+
+Four systems in `src/creative/` that add production-quality creative control:
+
+- **ColorPresetsSystem** (980 lines): 22 themed presets (Ocean, Lava, Neon, Monochrome, etc.) that set multiple parameters at once
+- **TransitionAnimator** (683 lines): 14 easing functions (linear, easeInOutCubic, elastic, bounce, etc.) for smooth interpolation between states. Supports sequencing.
+- **PostProcessingPipeline** (1,113 lines): 14 composable GPU effects (bloom, chromatic aberration, vignette, film grain, scanlines, etc.) with 7 preset chains (cinematic, retro, neon, etc.)
+- **ParameterTimeline** (1,061 lines): Keyframe-based parameter animation with BPM sync. Drive any parameter on a musical timeline.
+
+### The Breath System
+
+A global organic breathing cycle from `VitalitySystem.js` — a 6-second cosine wave oscillating 0 to 1 to 0, modulating all three visualization systems via the `u_breath` uniform:
+
+| System | Effect | Strength |
+|---|---|---|
+| Quantum | Lattice brightness pulse | +40% at full exhale |
+| Faceted | Pattern intensity pulse | +30% at full exhale |
+| Holographic | Projection expansion + glow + density | +20% / +10% / +40% |
+
+A bug was found in Feb 2026 where HolographicVisualizer had its own independent breath cycle running out of sync with the centralized one. Fixed to use the centralized value with 0.0 default.
+
+---
+
+## 8. Gotchas, Traps, and Hard-Won Lessons
+
+These are the things that waste hours if you don't know them:
+
+1. **Use pnpm, not npm**. `pnpm-lock.yaml` is the canonical lockfile. Running `npm install` creates a `package-lock.json` that conflicts. The stale `package-lock.json` was already removed once (Feb 2026). Don't recreate it.
+
+2. **`RealHolographicSystem`, not `HolographicSystem`**. The class was renamed during development. Old references and imports may still say `HolographicSystem`. The actual export is `RealHolographicSystem`.
+
+3. **Version strings are in 4 places**. `package.json`, `VIB3Engine.exportState()`, `Parameters.exportConfiguration()`, and `ErrorReporter`. When bumping the version, update ALL FOUR. They were unified to 2.0.1 in Feb 2026 (previously VIB3Engine said 1.2.0 while package.json said 2.0.0).
+
+4. **Two different ReactivityManagers**. `src/viewer/ViewerInputHandler.js` (renamed from ReactivityManager) handles viewer-level input (mouse, touch, tilt for the card-bending UI). `src/reactivity/ReactivityManager.js` is the SDK-level reactivity system. They are DIFFERENT files with different purposes. Don't confuse them.
+
+5. **Inline shaders are the source of truth for rendering**. External shader files in `src/shaders/` are secondary. If they conflict, the inline version is what actually runs. But always keep them in sync — run `pnpm verify:shaders`.
+
+6. **6D rotation order is XY, XZ, YZ, XW, YW, ZW**. This is hardcoded in WASM, GLSL, and WGSL. Changing the order in one implementation without changing the others will produce subtly wrong rotations that are very hard to debug.
+
+7. **WASM is optional — JS fallback exists**. The math library in `src/math/` (Vec4, Rotor4D, Mat4x4, Projection) provides pure JS implementations of everything the C++ core does. If WASM fails to load (10-second timeout), the engine silently falls back. This is by design.
+
+8. **WebGPU is optional — WebGL fallback exists**. `UnifiedRenderBridge` tries WebGPU first but falls back to WebGL. Currently WebGL is the well-tested path. WebGPU backend is a scaffold.
+
+9. **The `u_breath` uniform**. This is a global organic breathing cycle from `VitalitySystem.js` — a 6-second cosine wave (0 to 1 to 0) that modulates all three systems. A bug was found in Feb 2026 where HolographicVisualizer had its own independent breath cycle that ran out of sync. Fixed to use centralized value with 0.0 default.
+
+10. **Faceted canvas naming quirk**. Quantum uses `quantum-*-canvas`, Holographic uses `holo-*-canvas`, but Faceted uses unprefixed names (`background-canvas`, `content-canvas`, etc.). This is historical and affects DOM queries.
+
+11. **The landing page is in `site/`, not root**. Root `index.html` is a redirect. The SDK demo is in `demo/index.html`. The landing page with GSAP choreography is `site/index.html` with JS in `site/js/`. Don't accidentally edit the wrong `index.html`.
+
+12. **CanvasManager was rewritten**. If you see old code or references assuming the pre-Feb-2026 CanvasManager API (which was 217 lines with a different interface), it's stale. The current version is 110 lines with `createSystemCanvases()`, `registerContext()`, `destroy()`.
+
+---
+
+## 9. Documentation Map
+
+| What you need | Where to find it |
+|---|---|
+| **Quick project onboarding** | `CLAUDE.md` — concise brief, start here |
+| **Full architecture & module inventory** | `DOCS/SYSTEM_INVENTORY.md` — canonical technical reference |
+| **Product strategy & personas** | `DOCS/PRODUCT_STRATEGY.md` |
+| **Quarterly roadmap & milestones** | `DOCS/ROADMAP.md` |
+| **Licensing tiers & commercial model** | `DOCS/LICENSING_TIERS.md` |
+| **Master plan (comprehensive backlog)** | `DOCS/MASTER_PLAN_2026-01-31.md` — 43 items across 6 phases |
+| **All parameter details & UI controls** | `DOCS/CONTROL_REFERENCE.md` |
+| **Project setup from scratch** | `DOCS/PROJECT_SETUP.md` + `DOCS/ENV_SETUP.md` |
+| **CI/CD & testing** | `DOCS/CI_TESTING.md` |
+| **Renderer lifecycle & contracts** | `DOCS/RENDERER_LIFECYCLE.md` |
+| **GPU resource disposal** | `DOCS/GPU_DISPOSAL_GUIDE.md` |
+| **WebGPU backend status** | `DOCS/WEBGPU_STATUS.md` |
+| **XR benchmarks** | `DOCS/XR_BENCHMARKS.md` |
+| **Export formats** | `DOCS/EXPORT_FORMATS.md` |
+| **Agent CLI onboarding** | `DOCS/CLI_ONBOARDING.md` |
+| **Landing page handoff** | `DOCS/HANDOFF_LANDING_PAGE.md` — visual quality issues + GSAP patterns |
+| **Site refactor details** | `DOCS/SITE_REFACTOR_PLAN.md` |
+| **Full docs index + reading paths** | `DOCS/README.md` |
+| **Dev session logs** | `DOCS/dev-tracks/` (Jan 31, Feb 6 2026) |
+
+---
+
+## 10. Commands
+
+```bash
+pnpm install                    # Install deps (NOT npm)
+pnpm dev                        # Vite dev server (opens browser)
+pnpm test                       # Vitest unit tests (933+ passing)
+pnpm test:e2e                   # Playwright browser tests (69 passing)
+pnpm test:all                   # Both
+pnpm verify:shaders             # Check inline vs external shader sync
+pnpm build:web                  # Production build
+pnpm build:lib                  # UMD + ESM library build for CDN/npm
+pnpm lint                       # ESLint
+pnpm bench                      # Performance benchmarks
+```
+
+Build WASM core (requires Emscripten): `cd cpp && ./build.sh`
+
+---
+
+## 11. Session Workflow
+
+1. Read `CLAUDE.md` for the concise brief
+2. Read this document for full context
+3. Read `DOCS/SYSTEM_INVENTORY.md` if you need the complete module map
+4. Run `pnpm test` to verify baseline before making changes
+5. Always run `pnpm test` after changes
+6. If touching shaders, run `pnpm verify:shaders`
+7. Commit with descriptive messages referencing what was changed and why
+8. Check `DOCS/ROADMAP.md` for current milestone context
+
+---
+
+**VIB3+ SDK — Clear Seas Solutions LLC**