@vib3code/sdk 2.0.3-canary.d0c4221 → 2.0.3-canary.d677f12

package/DOCS/AGENT_HARNESS_ARCHITECTURE.md

@@ -1,3 +1,5 @@
+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.

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.

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

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Cross-Site Design Pattern Synthesis
 
 **Based on actual visual analysis of 4 reference sites via Playwright screenshots**

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:

package/DOCS/EPIC_SCROLL_EVENTS.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # EPIC SCROLL EVENTS — VIB3+ Landing Page Choreography Plan
 
 **20 scroll-driven events that combine GSAP, GPU visualizers, CSS effects, and masking layers

package/DOCS/EXPANSION_DESIGN.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # VIB3+ Premium Tier — Expansion Design Document
 
 **Purpose**: Technical specification for `@vib3code/premium`, a separate npm package that extends the free `@vib3code/sdk` with fine-grained shader control, axis locking, per-layer geometry, event-triggered state changes, and live CSS/framework integration.

package/DOCS/EXPANSION_DESIGN_ULTRA.md

@@ -0,0 +1,389 @@
+Last reviewed: 2026-02-17
+
+# VIB3+ Ultra — The Emergent Media Engine
+
+**Purpose**: This document defines the **Ultra Tier** expansion for VIB3+. While the Premium Tier (`EXPANSION_DESIGN.md`) focuses on professional visualization tools, the Ultra Tier transforms the SDK into a **full-stack emergent media engine** capable of powering 4D video games, generative cartoons, and multi-user hallucinations.
+
+**Status**: Vision Document / Technical Specification.
+**Dependencies**: Requires `@vib3code/sdk` (core) and `@vib3code/premium` (for fine-grained control).
+
+---
+
+## I. Architecture: The VIB3 Universe
+
+The core shift is from **Single Instance** to **Orchestrated Universe**.
+
+### The Concept
+Instead of "a canvas on a page," we treat the browser window as a **Universe** containing multiple **Entities** (VIB3 instances). These entities share a clock, a physics lattice, and a narrative context.
+
+### The `VIB3Orchestrator`
+A new singleton that manages the lifecycle and coordination of all VIB3 instances.
+
+```javascript
+class VIB3Orchestrator {
+    constructor() {
+        this.entities = new Map(); // id -> VIB3Entity
+        this.clock = new MasterClock({ bpm: 120 }); // Shared beat sync
+        this.physics = new LatticePhysicsEngine(); // 4D collision detection
+        this.link = new VIB3Link(); // WebRTC multi-user sync
+    }
+
+    // Spawn a new entity (actor, prop, or environment)
+    spawn(type, config) { ... }
+
+    // Global tick loop
+    tick(deltaTime) {
+        this.physics.update(this.entities, deltaTime);
+        this.entities.forEach(e => e.update(deltaTime));
+        this.link.sync(this.entities);
+    }
+}
+```
+
+---
+
+## II. HyperNarrative: Animating Stories & Cartoons
+
+VIB3+ can tell stories. Characters are not mesh rigs but **VIB3 Actors** — distinct visualization instances with "souls" (parameter personalities) that express emotion through math.
+
+### 1. The `VIB3Actor`
+Wraps a `VIB3Engine` instance with identity, role, and emotional state.
+
+```javascript
+class VIB3Actor {
+    constructor(engine, personalityProfile) {
+        this.engine = engine;
+        this.profile = personalityProfile; // e.g., 'AnxiousGlitch', 'StoicCrystal'
+        this.emotion = { valence: 0, arousal: 0 }; // -1 to 1
+        this.voice = new AudioEmitter(); // Spatial audio source
+    }
+
+    // Express an emotion (modulates parameters based on profile)
+    emote(emotionName, intensity) {
+        const params = this.profile.mapEmotion(emotionName, intensity);
+        this.engine.transition(params, 500, 'easeOut');
+    }
+
+    // "Speak" with audio-reactive mouth modulation
+    speak(audioBuffer) {
+        this.voice.play(audioBuffer);
+        this.voice.onAnalysis((amplitude) => {
+            // Modulate geometry to simulate speech/expression
+            this.engine.setParameter('morphFactor', 0.5 + amplitude * 1.5);
+            this.engine.setParameter('intensity', 0.6 + amplitude * 0.4);
+        });
+    }
+}
+```
+
+### 2. The Script Format (`.vib3script`)
+A JSON-based screenplay format that controls actors, cameras, and environment.
+
+```json
+{
+  "title": "The Geometric Encounter",
+  "bpm": 110,
+  "cast": {
+    "Hero": { "system": "faceted", "geometry": 0, "profile": "heroic" },
+    "Villain": { "system": "quantum", "geometry": 16, "profile": "chaotic" }
+  },
+  "sequence": [
+    {
+      "time": "0:00",
+      "action": "camera_cut",
+      "target": "Hero",
+      "shot": "close_up" // Adjusts zoom/projection
+    },
+    {
+      "time": "0:02",
+      "actor": "Hero",
+      "action": "speak",
+      "text": "Why do you disturb the lattice?",
+      "audio": "hero_line_1.mp3",
+      "emotion": "stern"
+    },
+    {
+      "time": "0:05",
+      "actor": "Villain",
+      "action": "emote",
+      "emotion": "rage",
+      "intensity": 0.8 // Triggers red hue, high chaos, spike geometry
+    }
+  ]
+}
+```
+
+### 3. LipSync & Performance
+Use `WebAudioAPI` analysis on dialogue tracks to drive `morphFactor` (mouth opening) and `intensity` (energy).
+- **Consonants (High Freq)**: Trigger `chaos` spikes (sharp edges).
+- **Vowels (Mid Freq)**: Trigger `morphFactor` swells (round shapes).
+- **Volume**: Drives `gridDensity` (louder = larger/closer).
+
+---
+
+## III. HyperGame: FPV Gameplay Engine
+
+Transform VIB3+ from a passive visualizer into an active **4D Game Engine**.
+
+### 1. 4D Player Controller (`FPVController`)
+Maps WASD + Mouse to 6D motion, allowing navigation *through* the hyperspace lattice.
+
+- **W/S**: Move forward/back in Z (depth).
+- **A/D**: Strafe in X.
+- **Space/Shift**: Move in Y (up/down).
+- **Q/E**: Rotate in XW plane (portal strafe).
+- **Mouse**: Rotate XY (look left/right) and YZ (look up/down).
+
+```javascript
+// Inside game loop
+if (input.forward) {
+    // Move "camera" through 4D noise space
+    // We don't move geometry; we offset the noise coordinate system!
+    uniforms.u_noiseOffset.z += speed * dt;
+}
+if (input.portalLeft) {
+    // Rotate the entire world in 4D
+    uniforms.u_rot4dXW += rotationSpeed * dt;
+}
+```
+
+### 2. Lattice Physics (`LatticeCollider`)
+Collision detection is not mesh-based (too expensive/abstract). It is **Function-Based**.
+Since VIB3+ geometries are defined by math functions (SDFs or lattice grids), we check the player's coordinate against the active function.
+
+```javascript
+function checkCollision(playerPos, activeGeometry) {
+    // Sample the density function at player position
+    const density = getDensityAt(playerPos, activeGeometry);
+    if (density > 0.8) {
+        // Hit a "solid" part of the fractal/lattice
+        return true;
+    }
+    return false;
+}
+```
+
+### 3. Entity System
+Game objects are lightweight VIB3 instances or simplified shader particles.
+- **Projectiles**: Small `Quantum` instances (single particle geometry) moving in XYZW.
+- **Pickups**: `Faceted` geometries (spinning crystals) that trigger events on collision.
+- **Enemies**: `Holographic` instances that track player position.
+
+### 4. Game State Manager
+Tracks score, health, and inventory.
+- **Health**: Low health = high `chromaticAberration` + desaturation + `glitch` effect.
+- **Powerup**: Ingesting a "hypercube" powerup transitions the player's view to `HyperMode` (geometry 17, max color).
+
+---
+
+## IV. Emergent Media: AI & Multi-User Sync
+
+The final frontier: VIB3+ experiences that are alive, shared, and intelligent.
+
+### 1. VIB3Link (Multi-User Hallucination)
+Uses WebRTC/WebSockets to synchronize the `VIB3Orchestrator` state across clients.
+- **Shared Seed**: All clients start with same RNG seed.
+- **Input Sync**: Player A's rotation is broadcast to Player B.
+- **State Consensus**: "If Player A explodes the star, Player B sees it explode."
+
+**Use Case**: A shared "VR" room (on flat screens) where users float in a 4D chatroom, represented by their `VIB3Actor` avatars.
+
+### 2. The Live Director (AI Agent)
+An autonomous agent (MCP-connected) that watches the "audience" (user input, webcam, mic) and adjusts the show.
+
+- **Sentiment Analysis**: If audience audio is loud/happy -> increase `speed` and `saturation`.
+- **Attention Tracking**: If user stops interacting -> trigger `FocusLock` or `Explosion` to regain attention.
+- **Generative Scripting**: The AI writes the `.vib3script` in real-time based on a prompt ("Make it scary", "Make it romantic").
+
+---
+
+## V. New MCP Tools for Ultra Tier
+
+To empower agents to build these experiences, we add the following tools:
+
+### `spawn_actor`
+Creates a `VIB3Actor` with a specific personality and role.
+```json
+{ "role": "protagonist", "personality": "glitch_witch", "system": "holographic" }
+```
+
+### `direct_scene`
+Issues a high-level direction to the `LiveDirector`.
+```json
+{ "mood": "increasing_tension", "pacing": "frenetic", "focus_target": "villain" }
+```
+
+### `configure_game_rules`
+Sets up the `HyperGame` mechanics.
+```json
+{ "physics": "lattice_heavy", "collision_damage": 10, "goal": "collect_shards" }
+```
+
+### `sync_session`
+Initializes `VIB3Link` for a multi-user session.
+```json
+{ "room_id": "lobby_1", "max_users": 4, "sync_mode": "strict" }
+```
+
+---
+
+## VI. Deep Multilayer Architecture
+
+To support `VIB3Universe`, we need a robust system for managing interactions between multiple VIB3 instances. This is not just visual layering; it's logic layering.
+
+### 1. Visual Compositing (`VIB3Compositor`)
+Managing 10+ layers (e.g., 2 instances × 5 holographic layers) requires a dedicated compositor to avoid DOM explosion and Z-fighting.
+
+*   **Render Targets**: Instead of rendering directly to the DOM, each VIB3 instance renders to an offscreen canvas.
+*   **Unified Stage**: The Compositor draws these offscreen buffers onto a single `GlobalCanvas` using WebGL blending.
+*   **Depth Sorting**: Instances are sorted by their "World Z" coordinate.
+*   **Masking**: Instances can mask each other (e.g., a character standing behind a portal).
+
+```javascript
+class VIB3Compositor {
+    registerInstance(instanceId, textureSource) { ... }
+    setLayerOrder(instanceIds) { ... }
+    render() {
+        // Draw background instances
+        // Draw foreground instances with blending
+        // Apply global post-processing (unifying the look)
+    }
+}
+```
+
+### 2. Logic Layering (`LoopCoordinator`)
+We have three distinct loops running at different frequencies:
+1.  **Physics Loop (Fixed Step, 60hz)**: Collision detection, movement integration. Deterministic for multiplayer sync.
+2.  **Narrative Loop (Event Driven)**: Script execution, state machine transitions.
+3.  **Reactive Loop (Frame Rate)**: Audio analysis, visual parameter smoothing.
+
+The `VIB3Orchestrator` must prioritize these:
+*   Physics updates *must* happen before Visual updates.
+*   Narrative events trigger Physics state changes.
+
+### 3. State Hydration (`UniverseSerializer`)
+Saving a multi-instance universe is complex. We need a schema that captures the relationships, not just individual parameters.
+
+```json
+{
+  "universe_id": "u_8823",
+  "timestamp": 12044,
+  "entities": [
+    { "id": "hero", "type": "actor", "pos": [0,0,0], "params": {...} },
+    { "id": "world", "type": "environment", "params": {...} }
+  ],
+  "global_state": {
+    "gravity": 9.8,
+    "tension": 0.4
+  }
+}
+```
+
+This allows "save games" for HyperGame and "bookmarks" for HyperNarrative.
+
+---
+
+## VII. VIB3Link Protocol
+
+VIB3Link uses WebRTC DataChannels for low-latency state synchronization between clients in a `VIB3Universe`.
+
+### Protocol Message Format
+
+Messages are JSON-encoded packets:
+```json
+{
+  "t": "type",  // 'update', 'event', 'sync'
+  "s": 1023,    // sequence number (for ordering)
+  "p": { ... }  // payload
+}
+```
+
+### Core Message Types
+
+1.  **Entity Update (`upd`)**: High-frequency (20Hz) updates of position/rotation.
+    ```json
+    { "t": "upd", "id": "actor_1", "pos": [x,y,z], "rot": [x,y,z,w] }
+    ```
+2.  **Parameter Delta (`prm`)**: When a visual parameter changes.
+    ```json
+    { "t": "prm", "id": "actor_1", "k": "chaos", "v": 0.8 }
+    ```
+3.  **Universe Event (`evt`)**: Narrative triggers or game events.
+    ```json
+    { "t": "evt", "n": "explosion", "loc": [10, 0, 5], "pow": 0.9 }
+    ```
+
+### Synchronization Strategy
+
+*   **Authority**: One client is the **Host** (orchestrator). Others are **Peers**.
+*   **Prediction**: Peers predict entity movement based on velocity.
+*   **Reconciliation**: If Peer state diverges > threshold from Host state, snap to Host.
+*   **Interpolation**: Visuals render at `t - buffer` to ensure smooth interpolation between network packets.
+
+---
+
+## VIII. HyperGame Engine
+
+The VIB3+ Ultra HyperGame Engine enables 4D First-Person View (FPV) experiences. It decouples the physics simulation from the render loop and provides a 4D-native player controller.
+
+### 1. The Game Loop (`GameLoop`)
+A fixed-timestep loop for physics and logic, separate from the variable-timestep render loop. This ensures deterministic physics and smooth rendering even under load.
+
+```javascript
+class GameLoop {
+    constructor(updateFn, renderFn) {
+        this.accumulator = 0;
+        this.step = 1 / 60; // 60hz physics
+    }
+    // ... accumulates time and calls update() multiple times if needed
+}
+```
+
+### 2. Lattice Physics (`LatticePhysics`)
+Physics in VIB3+ is not about mesh-mesh intersection. It is about **Point-Field intersection**. We define the world as a scalar field (density) and check if the player's 4D point is inside a high-density region.
+
+*   **Collision**: `getDensity(pos) > threshold`
+*   **Gravity**: Constant force in -Y (or arbitrary 4D vector)
+*   **Friction**: Velocity decay
+
+### 3. Player Controller 4D (`PlayerController4D`)
+Handles input mapping for 6-degree-of-freedom movement.
+
+*   **Input**: WASD (Translation), Mouse (Rotation), QE (Portal/4D Rotation).
+*   **State**: Position (Vec4), Rotation (Rotor4D/Quat).
+*   **Smoothing**: Inputs are smoothed to prevent motion sickness in 4D space.
+
+```javascript
+update(dt) {
+    // Apply inputs to velocity
+    // Apply physics (gravity, friction)
+    // Integrate position: pos += vel * dt
+    // Resolve collisions: if (collision) pos -= normal * penetration
+}
+```
+
+---
+
+## IX. Demo: The Crystal Labyrinth
+
+A vertical slice demo showcasing all Ultra capabilities in one cohesive experience.
+
+### Story & Premise
+The player is a **Lattice Runner** navigating a fractured 4D hyperspace maze. The goal is to collect **Resonance Crystals** (Facet engines) while avoiding **Void Shadows** (Holographic engines) that hunt based on noise (movement speed).
+
+### Gameplay Loop
+1.  **Explore**: Navigate the 4D maze using WASD+Mouse+QE.
+2.  **Collect**: Find blue crystals. Touching one triggers a `VIB3Actor` "Collection" animation (implosion + sound).
+3.  **Evade**: Red "Shadows" drift towards you. If they touch you, the screen glitches (`chromaticAberration` spike) and health drops.
+4.  **Win**: Collect 5 crystals to stabilize the universe (trigger "Victory" state).
+
+### Technical Integration
+*   **Universe**: One `VIB3Universe` managing the Player, 5 Crystal Actors, and 3 Shadow Actors.
+*   **Physics**: `LatticePhysics` handles wall collisions (fractal noise walls).
+*   **AI**: `LiveDirector` adjusts Shadow aggression based on player movement speed (stealth mechanic).
+*   **Networking**: (Optional) `VIB3Link` allows a spectator to watch the runner.
+
+---
+
+*VIB3+ Ultra — The Future of Emergent Media*
+*Draft v5.0 — Added Crystal Labyrinth Demo Design — Feb 16, 2026*

package/DOCS/EXPORT_FORMATS.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Export formats
 
 This reference documents the target export formats supported by the agentic pipelines and how they are validated.

package/DOCS/GPU_DISPOSAL_GUIDE.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # GPU disposal patterns
 
 This guide documents safe GPU resource disposal patterns to prevent memory leaks across rendering backends.

package/DOCS/HANDOFF_LANDING_PAGE.md

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

package/DOCS/HANDOFF_SDK_DEVELOPMENT.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # VIB3+ SDK — Comprehensive Agent Handoff
 
 **Copy this entire document as the initial prompt when starting a new session focused on SDK development.**

package/DOCS/LICENSING_TIERS.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Licensing tiers (draft)
 
 This document outlines the proposed licensing tiers for the VIB3+ SDK and agentic tooling. It is intended as a working draft for Phase 5.

package/DOCS/MASTER_PLAN_2026-01-31.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # VIB3+ CORE — Master Plan & Full Audit
 
 **Date**: January 31, 2026

package/DOCS/MULTIVIZ_CHOREOGRAPHY_PATTERNS.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # VIB3+ Multi-Visualizer Choreography Patterns
 
 **Generated: 2026-02-09**
@@ -11,7 +13,7 @@
 1. [Depth Illusion Engine](#1-depth-illusion-engine)
 2. [Multi-Visualizer Coordination Modes](#2-multi-visualizer-coordination-modes)
 3. [Section-by-Section Choreography Upgrades](#3-section-by-section-choreography-upgrades)
-4. [Accent & Texture Effects Library](#4-accent--texture-effects-library)
+4. [Accent & Texture Effects Library](#4-accent-texture-effects-library)
 5. [Mathematical Intertwining Functions](#5-mathematical-intertwining-functions)
 6. [Implementation Priority Map](#6-implementation-priority-map)
 

package/DOCS/OBS_SETUP_GUIDE.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # VIB3+ OBS Setup Guide
 
 Use VIB3+ as a live visualization overlay in OBS Studio.