@vib3code/sdk 2.0.1 → 2.0.3-canary.91a95f3

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to VIB3+ CORE (`@vib3code/sdk`) will be documented in this file.
 
+## [2.0.2] — 2026-02-07
+
+### Fixed
+- **Distribution** — Added `cpp/` directory to `package.json` files list to ensure full C++ source tree (including `geometry` and `tests`) is included in the npm package. This resolves native build failures in downstream applications.
+
+## [2.0.1] — 2026-02-03
+
+### Added
+- **Vitality System** (`src/core/VitalitySystem.js`) — Organic breath-cycle modulation driving `u_breath` uniform across all 3 systems
+- **Exhale feature** — Breath modulation integrated into Quantum, Faceted, and Holographic fragment shaders (inline + external GLSL/WGSL)
+- **Polychora stub** (`src/polychora/PolychoraSystem.js`) — Placeholder for future 4D polytope system
+
+### Fixed
+- Quantum/Faceted external shader flashing — synced shader logic between inline and external files
+- Faceted shader logic bug (wrong SDF replaced with correct lattice-based shader)
+- Holographic shader sync with exhale breathing effect
+
+### Changed
+- Package renamed from `@vib3/sdk` to `@vib3code/sdk` for npm scope availability
+- Published to npm registry as `@vib3code/sdk@2.0.1`
+
+## [2.0.1-hygiene] — 2026-02-06
+
+### Fixed
+- **CanvasManager.js** — Rewrote to match VIB3Engine API contract (`createSystemCanvases`, `registerContext`, `destroy`); old version had no matching methods
+- **HolographicRendererAdapter.js** — Fixed broken import: `HolographicSystem` (non-existent) → `RealHolographicSystem`
+- **TradingCardManager.js** — Fixed imports pointing to non-existent `*Exact.js` and `*MultiLayer.js` generator files; now points to actual generators
+- **Version string inconsistencies** — Unified VIB3Engine (`1.2.0`→`2.0.1`), Parameters (`1.0.0`→`2.0.1`), ErrorReporter (`2.0.0`→`2.0.1`)
+- **External shader sync** — Added `u_breath` uniform to `quantum.frag.glsl`, `faceted.frag.glsl`, `quantum.frag.wgsl`, `faceted.frag.wgsl` (was present in inline shaders but missing from external files)
+
+### Changed
+- **Renamed** `src/viewer/ReactivityManager.js` → `ViewerInputHandler.js` to avoid naming collision with `src/reactivity/ReactivityManager.js` (different classes with different purposes)
+- **Removed** stale `package-lock.json` (project uses pnpm; `pnpm-lock.yaml` is canonical)
+
+---
+
 ## [2.0.0] — 2026-01-30
 
 ### Added

package/DOCS/AGENT_HARNESS_ARCHITECTURE.md

@@ -0,0 +1,243 @@
+# VIB3+ Agent Harness Architecture
+
+**Purpose**: Close the feedback loop between AI agents and VIB3+ visualization, enabling agents to design ultra-intricate reactive choreographed visuals that would be impractical via manual UI.
+
+---
+
+## Current State (What Exists)
+
+- 19 MCP tools for parameter control, system switching, gallery, reactivity, export
+- Agent context packs for Claude and OpenAI
+- Claude Code skills (`/vib3-design`, `/vib3-dev`) for design and development workflows
+- Telemetry instrumentation on all tool calls
+
+## New Additions (This Session)
+
+- **7 new MCP tools** (26 total): `describe_visual_state`, `batch_set_parameters`, `create_timeline`, `play_transition`, `apply_color_preset`, `set_post_processing`, `create_choreography`
+- **Claude Code skills**: `.claude/commands/vib3-design.md` and `.claude/commands/vib3-dev.md`
+- **Shader validation hook**: Pre-commit hook for `.glsl`/`.wgsl` changes
+
+---
+
+## Recommended Next Steps
+
+### Phase 1: Visual Feedback Loop (Highest Impact)
+
+**Problem**: Agents set parameters but can't see the result. They're designing blind.
+
+**Solution**: Screenshot capture + visual analysis pipeline.
+
+#### 1A. `capture_screenshot` MCP Tool
+
+Add a tool that captures the current visualization as an image:
+
+```javascript
+// Implementation approach:
+// 1. Use canvas.toDataURL('image/png') on the content-canvas layer
+// 2. Composite all 5 layers into a single image
+// 3. Return base64-encoded PNG
+
+capture_screenshot: {
+    name: 'capture_screenshot',
+    description: 'Captures current visualization as a base64 PNG image',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            width: { type: 'integer', default: 512 },
+            height: { type: 'integer', default: 512 },
+            layers: { type: 'string', enum: ['all', 'content', 'composite'], default: 'composite' }
+        }
+    }
+}
+```
+
+For multimodal agents (Claude with vision, GPT-4V), this enables:
+1. Set parameters → capture → analyze → refine → capture → analyze...
+2. "Make it more blue" → agent can verify the blue shift happened
+3. A/B testing: capture state A, modify, capture state B, compare
+
+#### 1B. Headless Rendering Server
+
+For CI/automated pipelines where no browser is available:
+
+```javascript
+// Using Puppeteer or Playwright in headless mode
+// Start VIB3+ in headless browser → apply MCP commands → capture frames
+import puppeteer from 'puppeteer';
+
+class HeadlessVIB3Renderer {
+    async launch() {
+        this.browser = await puppeteer.launch({ headless: true });
+        this.page = await this.browser.newPage();
+        await this.page.goto('http://localhost:3000'); // dev server
+    }
+
+    async captureFrame(params) {
+        await this.page.evaluate((p) => {
+            for (const [k, v] of Object.entries(p)) {
+                window.engine.setParameter(k, v);
+            }
+        }, params);
+        // Wait one frame
+        await this.page.evaluate(() => new Promise(r => requestAnimationFrame(r)));
+        return await this.page.screenshot({ type: 'png' });
+    }
+}
+```
+
+### Phase 2: Agent Choreography Runtime
+
+**Problem**: `create_choreography` generates a JSON spec, but there's no runtime to play it back.
+
+**Solution**: Build a `ChoreographyPlayer` class that consumes choreography JSON and orchestrates the engine.
+
+```javascript
+// src/creative/ChoreographyPlayer.js
+export class ChoreographyPlayer {
+    constructor(engine) {
+        this.engine = engine;
+        this.timeline = new ParameterTimeline((n, v) => engine.setParameter(n, v));
+        this.transition = new TransitionAnimator(
+            (n, v) => engine.setParameter(n, v),
+            (n) => engine.getParameter(n)
+        );
+    }
+
+    async loadChoreography(spec) {
+        // Parse multi-scene choreography
+        // Set up scene transitions
+        // Wire timeline tracks per scene
+        // Handle system switching at scene boundaries
+    }
+
+    play() { /* Start playback with scene management */ }
+    pause() { /* Pause all active timelines/transitions */ }
+    seek(timeMs) { /* Jump to specific time, load correct scene */ }
+}
+```
+
+### Phase 3: Design-by-Description (Text → Visual)
+
+**Problem**: Users describe what they want in natural language. Agents need to map that to parameters.
+
+**Solution**: Extend `AIPresetGenerator.js` with a more structured mapping:
+
+```javascript
+// Emotional/aesthetic vocabulary → parameter ranges
+const AESTHETIC_MAPS = {
+    // Emotions
+    serene:    { speed: [0.1, 0.3], chaos: [0, 0.05], intensity: [0.3, 0.5] },
+    energetic: { speed: [2.0, 3.0], chaos: [0.5, 1.0], intensity: [0.7, 1.0] },
+    mysterious:{ speed: [0.3, 0.6], chaos: [0.1, 0.3], hue: [220, 280], intensity: [0.2, 0.4] },
+    joyful:    { speed: [1.0, 1.5], chaos: [0.2, 0.4], hue: [30, 60], intensity: [0.7, 0.9] },
+
+    // Visual styles
+    minimal:   { gridDensity: [4, 10], chaos: [0, 0.02], morphFactor: [0, 0.1] },
+    intricate: { gridDensity: [40, 80], chaos: [0.1, 0.3], morphFactor: [0.3, 1.0] },
+    organic:   { chaos: [0.3, 0.7], morphFactor: [0.5, 1.5], speed: [0.5, 1.0] },
+    geometric: { chaos: [0, 0.05], gridDensity: [15, 30], morphFactor: [0, 0.2] },
+
+    // Depth effects
+    deep:      { dimension: [3.0, 3.3], gridDensity: [30, 60] },
+    flat:      { dimension: [4.0, 4.5], gridDensity: [8, 15] },
+    immersive: { dimension: [3.0, 3.5], rot4dXW: [0.5, 2.0], rot4dYW: [0.3, 1.5] }
+};
+```
+
+### Phase 4: Collaborative Multi-Agent Workflow
+
+Multiple agents working together on a choreography:
+
+1. **Director Agent** — Defines the high-level narrative (scenes, moods, transitions)
+2. **Color Agent** — Picks color presets and post-processing for each scene
+3. **Motion Agent** — Designs rotation and parameter timelines
+4. **Audio Agent** — Maps audio reactivity bands to parameters
+
+Each agent uses the same MCP server, different tool subsets.
+
+### Phase 5: Hooks for Agent Workflow
+
+#### Pre-export validation hook
+
+```bash
+# .claude/settings.json — validate before export
+{
+    "hooks": {
+        "PreToolCall": [
+            {
+                "tool": "export_package",
+                "command": "node tools/validate-export.js"
+            }
+        ]
+    }
+}
+```
+
+#### Auto-gallery-save hook
+
+After every `batch_set_parameters` or `create_choreography`, auto-save to a rotating gallery slot:
+
+```bash
+# .claude/settings.json
+{
+    "hooks": {
+        "PostToolCall": [
+            {
+                "tool": "batch_set_parameters",
+                "command": "echo 'Auto-saved state to gallery'"
+            }
+        ]
+    }
+}
+```
+
+---
+
+## Architecture Diagram: Agent Feedback Loop
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    AI AGENT (Claude/GPT)                  │
+│                                                          │
+│  1. describe_visual_state → understand current visual    │
+│  2. batch_set_parameters  → change visualization         │
+│  3. describe_visual_state → verify change                │
+│  4. create_timeline       → design animation             │
+│  5. create_choreography   → compose full performance     │
+│  6. [future] capture_screenshot → get actual pixels      │
+│                                                          │
+└────────────────────┬────────────────────────────────────┘
+                     │ MCP Protocol (stdio)
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│                    MCP SERVER (26 tools)                  │
+│                                                          │
+│  Tool handlers → VIB3Engine API → Render Pipeline        │
+│                                                          │
+│  Telemetry ← Event Stream ← Instrumentation             │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│                    VIB3+ ENGINE                           │
+│                                                          │
+│  Quantum │ Faceted │ Holographic                         │
+│  24 geometries × 6D rotation × creative tooling          │
+│  Audio reactivity × Spatial input × Post-processing      │
+│                                                          │
+│  Output: 5-layer canvas composite                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Why This Matters
+
+Agents can:
+1. **Generate mathematically precise timelines** — 50+ parameter keyframes across 8+ tracks, perfectly synced to BPM, with easing functions humans couldn't manually coordinate
+2. **Explore the parameter space systematically** — Try all 24 geometries × 3 systems × 6 rotation planes in seconds
+3. **Design by description** — "Make it feel like being underwater at night" maps to specific parameter ranges
+4. **Compose multi-scene choreographies** — 10+ scenes with cross-fades, system switches, and per-scene timelines
+5. **Iterate without visual fatigue** — Agents don't get "used to" a look — they objectively assess parameter states
+
+The agent harness transforms VIB3+ from a tool you use into a creative medium agents can compose with.

package/DOCS/CLI_ONBOARDING.md

@@ -11,7 +11,7 @@ This guide aligns the current CLI surface (package scripts and telemetry helpers
 - Optional: renderer lifecycle overview for system orchestration is in [`DOCS/RENDERER_LIFECYCLE.md`](DOCS/RENDERER_LIFECYCLE.md).
 - Optional: GCP + Firebase provisioning steps live in [`DOCS/PROJECT_SETUP.md`](DOCS/PROJECT_SETUP.md).
 - Optional: repository directory manifest is in [`DOCS/REPO_MANIFEST.md`](DOCS/REPO_MANIFEST.md).
-- Optional: development track analysis is in [`DOCS/DEV_TRACK_ANALYSIS.md`](DOCS/DEV_TRACK_ANALYSIS.md).
+- Optional: development track analysis is in [`DOCS/archive/DEV_TRACK_ANALYSIS.md`](DOCS/archive/DEV_TRACK_ANALYSIS.md).
 - Optional: WebGPU status/testing notes are in [`DOCS/WEBGPU_STATUS.md`](DOCS/WEBGPU_STATUS.md).
 
 ## Baseline setup

package/DOCS/CROSS_SITE_DESIGN_PATTERNS.md

@@ -0,0 +1,117 @@
+# Cross-Site Design Pattern Synthesis
+
+**Based on actual visual analysis of 4 reference sites via Playwright screenshots**
+**Sites**: weare-simone.webflow.io, facetad.com, clickerss.com, tableside.com.au
+**Date**: 2026-02-10
+
+---
+
+## Universal Patterns (Found in 3+ Sites)
+
+### 1. Typography-as-Hero
+**Simone**: Giant "SIMONE" wordmark fills viewport
+**Clickerss**: Massive B&W portrait, then enormous serif text sections
+**Tableside**: "FOOD & DRINK DIGITAL CREATIVES" in bold coral fills 70% of viewport
+**Facetad**: Single sentence in vast emptiness
+
+**What it means**: The hero section is ONE thing — either giant text or a giant image. No competing elements. No "learn more" buttons, no description paragraphs, no gradient overlays.
+
+**VIB3+ action**: The opening cinematic must be ONLY the text mask + visualizer. Kill any secondary UI that competes with the hero moment.
+
+### 2. Asymmetric Card Layouts
+**Simone**: Zigzag case study cards (image RIGHT, then LEFT, then RIGHT)
+**Facetad**: Text LEFT + floating image RIGHT (services section)
+**Tableside**: 50/50 split cards (photo one side, text other side)
+**Clickerss**: Text-image interweaving (overlapping, not split)
+
+**What it means**: No site uses centered, symmetric card layouts. Everything is offset, asymmetric, or alternating. Visual rhythm comes from the alternation pattern.
+
+**VIB3+ action**: Cascade cards should have asymmetric overlay positioning. Alternate text LEFT/RIGHT between cards. The card overlays shouldn't be centered — push them to one side.
+
+### 3. Non-Rectangular Image Boundaries
+**Facetad**: ALL images use parallelogram clip-paths
+**Simone**: Rounded-corner containers (~24px radius)
+**Facetad**: Diagonal section dividers (30-40 degree angle)
+**Clickerss**: Images overlapping text boundaries
+
+**What it means**: Rectangular images are boring. Every site transforms image boundaries through clip-paths, rounded corners, diagonal edges, or overlap.
+
+**VIB3+ action**: The clip-path polygon morphing system (rect → hex → diamond → oct → narrow) is exactly right. Also consider adding parallelogram/skewed shapes to the shape vocabulary.
+
+### 4. Extreme Negative Space
+**Facetad**: Hero is 95% empty
+**Simone**: Hero is pure text, no images
+**Clickerss**: Large gaps between sections
+**Tableside**: Generous padding around portfolio cards
+
+**What it means**: Premium sites use MORE empty space, not less. The content is given room to breathe.
+
+**VIB3+ action**: Resist the urge to pack every section with content. The morph experience should have moments of sparse visualization (low density, simple geometry) as breathing room between intense moments.
+
+---
+
+## Distinctive Patterns (Site-Specific but Highly Applicable)
+
+### 5. Diagonal Section Dividers (Facetad)
+All section boundaries use a consistent diagonal angle. Cream → photo → cream → red → cream transitions happen along diagonal slashes, never horizontal lines.
+
+**VIB3+ action**: Section dividers could use CSS `clip-path: polygon()` with angled edges instead of straight horizontal borders. A 15-20 degree angle would add visual energy.
+
+### 6. Hard Dark/Light Mode Switches (Simone)
+Cream → dark teal happens as a sharp boundary. The entire palette inverts. No cross-fade.
+
+**VIB3+ action**: The morph stages already switch visualization parameters sharply between stages. Could also switch the page background color sharply at section boundaries (not just the visualizer hue).
+
+### 7. Text-Image Interweaving (Clickerss)
+Typography at 100-200px+ runs through/behind portfolio images. Text and images share the same spatial zone.
+
+**VIB3+ action**: Section titles could extend BEHIND the cascade cards, visible through the clip-path window. This creates depth between the text layer and the visualizer layer.
+
+### 8. Scattered Floating Gallery (Facetad)
+Portfolio images scattered across viewport at various sizes and positions, all in parallelogram shapes, overlapping each other.
+
+**VIB3+ action**: Could be used for a "gallery" or "showcase" section where multiple small visualizer thumbnails float at different positions with skewed clip-paths, each showing a different geometry.
+
+### 9. Color Palette Discipline (All Sites)
+**Simone**: cream + dark teal + chartreuse green (3 colors)
+**Facetad**: cream + terracotta red (2 colors)
+**Clickerss**: white + black (2 colors)
+**Tableside**: cream + coral + navy (3 colors)
+
+**What it means**: Maximum 3 colors. The visualizer provides the color variety — the page itself should be restrained.
+
+### 10. Footer Echo (Simone)
+The hero's filled "SIMONE" becomes outlined/stroked at the footer. Same shape, different rendering.
+
+**VIB3+ action**: The CTA section should echo the hero — same visualizer geometry but in a different system (e.g., Quantum in hero → Faceted outline in CTA) or with inverted parameters.
+
+### 11. Marquee/Infinite Scroll (Simone)
+"Work with us" repeats horizontally as a continuous scrolling marquee.
+
+**VIB3+ action**: A parameter ticker or geometry name marquee could add persistent horizontal motion independent of vertical scroll.
+
+---
+
+## Priority Actions for VIB3+ Landing Page
+
+### Immediate (Apply to existing choreography)
+1. **Add parallelogram shapes** to SHAPES vocabulary in choreography.js (`skewR`, `skewL` with angled edges)
+2. **Asymmetric overlay positioning** — alternate cascade-overlay text LEFT/RIGHT per card
+3. **Increase negative space** — add padding/margins between morph stages
+4. **Increase hero text size** — opening cinematic text should fill more viewport
+5. **Add service/parameter metadata** to cascade card overlays (geometry name, system type)
+
+### Medium-term (New section patterns)
+6. **Diagonal section dividers** — angled `clip-path` on section boundaries
+7. **Footer echo** — CTA section uses same geometry as hero but different system
+8. **Split-color CTA** — vertical or diagonal color split in CTA section
+9. **Text-behind-card** effect — section titles visible through clip-path windows
+
+### Aspirational (Major new features)
+10. **Scattered gallery section** — multiple small visualizer thumbnails floating with parallelogram clip-paths
+11. **Horizontal marquee** — continuous ticker with geometry names or parameter readouts
+12. **Variable card sizing** — some cascade cards appear larger/smaller via clip-path window size
+
+---
+
+*Synthesized from actual Playwright visual analysis of 4 reference sites.*