@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

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,245 @@
+Last reviewed: 2026-02-17
+
+# 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/ANDROID_DEPLOYMENT.md

@@ -0,0 +1,59 @@
+Last reviewed: 2026-02-17
+
+# Building VIB3+ Ultra for Android
+
+This guide explains how to build the "Crystal Labyrinth" demo as an Android APK using the existing Flutter integration.
+
+## Prerequisites
+
+- Flutter SDK installed
+- Android Studio / Android SDK installed
+- Connected Android device or emulator
+
+## Quick Build (GitHub Actions)
+
+The repository includes a workflow `.github/workflows/flutter-apk.yml` that automatically builds an APK on push to `examples/flutter_demo/`.
+
+To trigger a build for the Crystal Labyrinth demo:
+1.  Copy the built web assets to the Flutter assets directory (see Local Build below).
+2.  Push changes.
+3.  Download the artifact from the Actions tab.
+
+## Local Build Instructions
+
+1.  **Build the Web Demo**
+    Run the Vite build to bundle the Crystal Labyrinth demo:
+    ```bash
+    npm install
+    npm run build:web
+    ```
+    This will output optimized files to `dist/`.
+
+2.  **Prepare Flutter Assets**
+    Copy the build output to the Flutter project's asset folder:
+    ```bash
+    mkdir -p examples/flutter_demo/assets/vib3/
+    cp -r dist/* examples/flutter_demo/assets/vib3/
+    ```
+
+3.  **Configure Entry Point**
+    Open `examples/flutter_demo/lib/vib3_controller.dart` and ensure the WebView points to the local index file or the deployed GitHub Pages URL:
+    `https://<your-username>.github.io/vib3codeSDK/examples/dogfood/crystal_labyrinth.html`
+
+4.  **Build APK**
+    Navigate to the Flutter directory and build:
+    ```bash
+    cd examples/flutter_demo
+    flutter build apk --release
+    ```
+
+5.  **Install**
+    ```bash
+    flutter install
+    ```
+
+## VIB3Link Networking on Android
+
+For multi-user features (`VIB3Link`) to work on Android:
+- Ensure the device has internet access.
+- If using local dev server, use `adb reverse tcp:5173 tcp:5173` to forward ports.

package/DOCS/ARCHITECTURE.md

@@ -0,0 +1 @@
+Last reviewed: 2026-02-17

package/DOCS/CI_TESTING.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # CI and testing guide
 
 This guide outlines the baseline CI/test expectations for the project and a recommended set of

package/DOCS/CLI_ONBOARDING.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Agentic CLI onboarding
 
 This guide aligns the current CLI surface (package scripts and telemetry helpers) with an agentic workflow. It is intentionally explicit so automation agents and humans can share the same runbook.
@@ -11,7 +13,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/CONTROL_REFERENCE.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Control & API Reference
 
 This document walks through every control surface in `index.html` and the JavaScript entry points they call so you can quickly map UI inputs to runtime behavior.

package/DOCS/CROSS_SITE_DESIGN_PATTERNS.md

@@ -0,0 +1,119 @@
+Last reviewed: 2026-02-17
+
+# 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.*

package/DOCS/ENV_SETUP.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Environment setup (Firebase, gcloud, Flutter, Android, GH CLI)
 
 This doc provides a **copy/paste** bootstrap script to install and configure: