@vib3code/sdk 2.0.3-canary.590fbae → 2.0.3-canary.69d53b3

package/DOCS/archive/WEBGPU_STATUS_2026-02-15_STALE.md

@@ -1,38 +1 @@
-# WebGPU status and testing requirements
-
-This document records the current WebGPU backend state, what is implemented, and what is required
-to validate it in local development or CI.
-
-## Current status
-- **Backend scaffold:** `WebGPUBackend` initializes adapter/device, configures the canvas, manages
-  resize, and supports a clear-pass `renderFrame()` path.
-- **Async context creation:** `createRenderContextAsync()` can instantiate WebGPU contexts using
-  `{ backend: 'webgpu' }`.
-- **Resource tracking:** depth textures are registered in the shared `RenderResourceRegistry`.
-
-## What is still needed
-1. **Pipeline parity:** implement basic shader pipelines (vertex/fragment) and buffer binding that
-   match the WebGL backend command flow.
-2. **Command buffer bridge:** map existing render commands to WebGPU render passes.
-3. **Feature gating:** add host-app controls to toggle WebGPU via feature flags.
-4. **Diagnostics:** add per-frame stats and resource delta reporting for WebGPU.
-
-## Testing requirements
-### Local smoke test
-Prerequisites:
-- A browser with WebGPU enabled (Chrome/Edge with `chrome://flags/#enable-unsafe-webgpu`, or a
-  Chromium build with WebGPU support).
-- A device with WebGPU-capable GPU drivers.
-
-Suggested smoke flow:
-1. Create a canvas and call `createRenderContextAsync(canvas, { backend: 'webgpu' })`.
-2. Call `backend.renderFrame({ clearColor: [0.1, 0.1, 0.2, 1] })` and confirm the canvas clears.
-3. Resize the canvas and ensure the clear pass still succeeds.
-
-### CI validation
-- WebGPU cannot be reliably validated in headless CI without GPU support.
-- CI should instead run WebGL tests and lint/static checks; keep a manual WebGPU smoke checklist.
-
-## File locations
-- `src/render/backends/WebGPUBackend.js`
-- `src/render/index.js` (`createRenderContextAsync`)
+Last reviewed: 2026-02-17

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-01-31.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Dev Track Session — January 31, 2026
 
 **Branch**: `claude/review-project-status-BwVbr`

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

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Development Session — 2026-02-06
 
 **Session type**: Full codebase audit + hygiene + MCP server + agent docs + testing

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

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Development Session — 2026-02-13
 
 **Session type**: Agent Harness Implementation — MCP tools, ChoreographyPlayer, aesthetic mapping, headless rendering

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

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Development Session — 2026-02-15
 
 **Session type**: Layer Architecture Redesign, Codebase Audit, Preset/Reactivity Expansion

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

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Development Session — 2026-02-16
 
 **Session type**: Architecture Bug Fixes, Shader Consistency, Documentation Sweep

package/DOCS/dev-tracks/PERF_UPGRADE_2026-02-16.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Performance Upgrade Report — 2026-02-16
 
 **Type**: CPU-side math optimization (Rotor4D + Vec4)

package/DOCS/dev-tracks/README.md

@@ -1,3 +1,5 @@
+Last reviewed: 2026-02-17
+
 # Development Track Logs
 
 Detailed, session-level implementation notes are stored here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib3code/sdk",
-  "version": "2.0.3-canary.590fbae",
+  "version": "2.0.3-canary.69d53b3",
   "description": "VIB3+ 4D Visualization SDK - Unified engine with 6D rotation, MCP agentic integration, and cross-platform support",
   "type": "module",
   "main": "src/core/VIB3Engine.js",

package/src/experimental/GameLoop.js

@@ -0,0 +1,72 @@
+/**
+ * GameLoop - Fixed-Timestep Physics Loop
+ *
+ * Provides a robust game loop that decouples physics updates (fixed step)
+ * from rendering (variable step). This is crucial for consistent physics
+ * and smooth rendering across different device capabilities.
+ *
+ * @experimental
+ */
+export class GameLoop {
+    /**
+     * @param {function(number)} updateFn - Physics update (fixed dt)
+     * @param {function(number)} renderFn - Render update (interpolated alpha)
+     * @param {number} step - Physics step size in seconds (default 1/60)
+     */
+    constructor(updateFn, renderFn, step = 1 / 60) {
+        this.updateFn = updateFn;
+        this.renderFn = renderFn;
+        this.step = step;
+        this.dt = 0;
+        this.last = 0;
+        this.now = 0;
+        this.accumulator = 0;
+        this.running = false;
+        this.rafId = null;
+
+        // Bind loop
+        this.frame = this.frame.bind(this);
+    }
+
+    start() {
+        if (this.running) return;
+        this.running = true;
+        this.last = performance.now();
+        this.accumulator = 0;
+        this.rafId = requestAnimationFrame(this.frame);
+        console.log('GameLoop: Started.');
+    }
+
+    stop() {
+        this.running = false;
+        if (this.rafId) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        console.log('GameLoop: Stopped.');
+    }
+
+    frame(timestamp) {
+        if (!this.running) return;
+
+        this.now = timestamp;
+        // Cap dt to avoid "spiral of death" on lag spikes (max 1s)
+        this.dt = Math.min(1, (this.now - this.last) / 1000);
+        this.last = this.now;
+
+        this.accumulator += this.dt;
+
+        // Consume accumulator in fixed steps
+        while (this.accumulator >= this.step) {
+            this.updateFn(this.step);
+            this.accumulator -= this.step;
+        }
+
+        // Render with interpolation factor alpha
+        // alpha = accumulator / step
+        // Allows renderer to interpolate between previous and current physics state
+        this.renderFn(this.accumulator / this.step);
+
+        this.rafId = requestAnimationFrame(this.frame);
+    }
+}

package/src/experimental/LatticePhysics.js

@@ -0,0 +1,100 @@
+/**
+ * LatticePhysics - Function-Based Collision Detection
+ *
+ * Provides a physics engine for "Lattice Worlds" where geometry is defined
+ * by mathematical density functions (SDFs, fractals).
+ *
+ * @experimental
+ */
+export class LatticePhysics {
+    constructor() {
+        this.gravity = 9.8; // m/s²
+        this.friction = 0.95; // Velocity decay per step
+        this.densityThreshold = 0.8; // Collision threshold (0-1)
+    }
+
+    /**
+     * Update physics for all entities in the universe.
+     * @param {Map<string, object>} entities
+     * @param {number} dt
+     */
+    update(entities, dt) {
+        entities.forEach(entity => {
+            if (entity.physics && entity.active) {
+                this.updateEntity(entity, dt);
+            }
+        });
+    }
+
+    /**
+     * Update a single entity's physics state.
+     * @param {object} entity
+     * @param {number} dt
+     */
+    updateEntity(entity, dt) {
+        const { pos, vel, acc } = entity.physics;
+
+        // Apply forces (Gravity)
+        // In this abstract world, gravity pulls "down" in Y
+        acc.y -= this.gravity * dt;
+
+        // Integrate Velocity (Euler)
+        vel.x += acc.x * dt;
+        vel.y += acc.y * dt;
+        vel.z += acc.z * dt;
+
+        // Reset acceleration (forces are transient)
+        acc.x = 0; acc.y = 0; acc.z = 0;
+
+        // Collision Check (Projected Position)
+        const nextX = pos.x + vel.x * dt;
+        const nextY = pos.y + vel.y * dt;
+        const nextZ = pos.z + vel.z * dt;
+
+        // Sample density at next position
+        const density = this.getDensityAt(nextX, nextY, nextZ);
+
+        if (density > this.densityThreshold) {
+            // Collision!
+            // Simple response: Stop velocity component and push out
+            // A real engine would calculate surface normal from gradient
+
+            // Simplified: Just stop movement and bounce slightly
+            vel.x *= -0.5;
+            vel.y *= -0.5;
+            vel.z *= -0.5;
+
+            // Don't update position into solid
+        } else {
+            // Move freely
+            pos.x = nextX;
+            pos.y = nextY;
+            pos.z = nextZ;
+        }
+
+        // Apply Friction (Air/Ether drag)
+        vel.x *= this.friction;
+        vel.y *= this.friction;
+        vel.z *= this.friction;
+    }
+
+    /**
+     * Sample the "world density" at a given point.
+     * This mimics the shader's generation logic (e.g., fractal noise).
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number} Density 0.0 to 1.0
+     */
+    getDensityAt(x, y, z) {
+        // Mock function: simple floor plane at y = -2
+        if (y < -2) return 1.0;
+
+        // Mock function: occasional "floating islands" based on sine waves
+        // simulating the VIB3 lattice structure
+        const noise = (Math.sin(x * 0.5) + Math.cos(z * 0.5)) * 0.5 + 0.5;
+        if (y > 0 && y < 1 && noise > 0.8) return 1.0;
+
+        return 0.0;
+    }
+}

package/src/experimental/LiveDirector.js

@@ -0,0 +1,143 @@
+/**
+ * LiveDirector - Autonomous Creative Agent
+ *
+ * An AI agent that analyzes user input ("Audience Reaction") and adjusts the
+ * VIB3Universe in real-time to maintain engagement, flow, and narrative tension.
+ *
+ * @experimental
+ */
+export class LiveDirector {
+    constructor(universe) {
+        this.universe = universe;
+        this.active = false;
+
+        // Audience State
+        this.audience = {
+            energy: 0.5, // 0.0 (Bored) -> 1.0 (Excited)
+            attention: 0.8, // 0.0 (Distracted) -> 1.0 (Focused)
+            sentiment: 0.0, // -1.0 (Negative) -> 1.0 (Positive)
+        };
+
+        // Directing State
+        this.pacing = 'build'; // 'intro', 'build', 'climax', 'resolve'
+        this.lastActionTime = 0;
+        this.decisionInterval = 2000; // ms
+
+        // Bind methods
+        this.update = this.update.bind(this);
+    }
+
+    /**
+     * Start the director loop.
+     */
+    start() {
+        if (this.active) return;
+        this.active = true;
+        this.lastActionTime = performance.now();
+        requestAnimationFrame(this.update);
+        console.log('LiveDirector: Started directing.');
+    }
+
+    /**
+     * Stop the director loop.
+     */
+    stop() {
+        this.active = false;
+        console.log('LiveDirector: Stopped directing.');
+    }
+
+    /**
+     * Feed audience input signal.
+     * @param {string} type - 'audio', 'video', 'input'
+     * @param {object} data - Analysis data
+     */
+    feedInput(type, data) {
+        if (type === 'audio') {
+            // Loud audio = high energy
+            this.audience.energy = Math.min(1.0, this.audience.energy + data.volume * 0.1);
+        } else if (type === 'input') {
+            // Interaction = high attention
+            this.audience.attention = Math.min(1.0, this.audience.attention + 0.05);
+        }
+
+        // Decay logic runs in update loop
+    }
+
+    /**
+     * Main decision loop.
+     * @param {number} timestamp
+     */
+    update(timestamp) {
+        if (!this.active) return;
+
+        const dt = (timestamp - this.lastActionTime);
+
+        // Decay audience metrics over time
+        this.audience.energy = Math.max(0, this.audience.energy - 0.001);
+        this.audience.attention = Math.max(0, this.audience.attention - 0.0005);
+
+        // Make a directing decision periodically
+        if (dt > this.decisionInterval) {
+            this.makeDecision();
+            this.lastActionTime = timestamp;
+        }
+
+        requestAnimationFrame(this.update);
+    }
+
+    /**
+     * The "Brain" of the Director.
+     * Decides what to change based on current state.
+     */
+    makeDecision() {
+        const { energy, attention } = this.audience;
+
+        console.log(`LiveDirector: Audience state - Energy: ${energy.toFixed(2)}, Attention: ${attention.toFixed(2)}`);
+
+        // Strategy: Maintain a "Sine Wave" of tension
+        // If energy is too low, spike it. If too high, calm it down.
+
+        if (attention < 0.3) {
+            // Lost attention -> TRIGGER EVENT
+            this.triggerEvent('focus_snap');
+        } else if (energy < 0.2) {
+            // Boring -> INCREASE INTENSITY
+            this.adjustGlobalParams({ speed: 1.5, chaos: 0.4 });
+        } else if (energy > 0.8) {
+            // Too frantic -> CALM DOWN
+            this.adjustGlobalParams({ speed: 0.5, chaos: 0.1 });
+        } else {
+            // Just right -> DO NOTHING or subtle shift
+            // Maybe drift hue slightly?
+        }
+    }
+
+    /**
+     * Execute a parameter adjustment across all actors.
+     * @param {object} params
+     */
+    adjustGlobalParams(params) {
+        console.log('LiveDirector: Adjusting global parameters', params);
+        this.universe.actors.forEach(actor => {
+            if (actor.animator) {
+                actor.animator.transition(params, 2000, 'easeInOut');
+            }
+        });
+    }
+
+    /**
+     * Trigger a specific scripted event.
+     * @param {string} eventName
+     */
+    triggerEvent(eventName) {
+        console.log(`LiveDirector: Triggering event '${eventName}'`);
+        // Example: Flash screen, spawn particle burst, etc.
+        if (eventName === 'focus_snap') {
+             // Quick snap zoom / flash
+             this.adjustGlobalParams({ intensity: 1.0, speed: 0.0 });
+             setTimeout(() => {
+                 this.adjustGlobalParams({ intensity: 0.5, speed: 1.0 });
+             }, 200);
+        }
+    }
+}

package/src/experimental/PlayerController4D.js

@@ -0,0 +1,154 @@
+/**
+ * PlayerController4D - Navigation in Hyperspace
+ *
+ * Maps 2D/3D inputs (WASD, Mouse) into 4D motion vectors (X, Y, Z, W).
+ * Handles movement, strafing, and "portal rotation" (XW/YW planes).
+ *
+ * @experimental
+ */
+export class PlayerController4D {
+    /**
+     * @param {HTMLElement} domElement - Element to listen for events on
+     * @param {object} engine - VIB3Engine instance to drive
+     */
+    constructor(domElement, engine) {
+        this.domElement = domElement;
+        this.engine = engine;
+
+        // Input State
+        this.keys = {
+            w: false, a: false, s: false, d: false,
+            q: false, e: false, space: false, shift: false
+        };
+
+        this.mouse = {
+            dx: 0, dy: 0,
+            down: false
+        };
+
+        // Player Physics State
+        this.velocity = { x: 0, y: 0, z: 0, w: 0 };
+        this.rotation = { x: 0, y: 0 }; // Looking direction (Pitch/Yaw)
+        this.portalRot = 0; // XW plane rotation
+
+        // Config
+        this.speed = 5.0;
+        this.sensitivity = 0.002;
+        this.damping = 0.9;
+
+        // Bind events
+        this.onKeyDown = this.onKeyDown.bind(this);
+        this.onKeyUp = this.onKeyUp.bind(this);
+        this.onMouseMove = this.onMouseMove.bind(this);
+        this.onMouseDown = this.onMouseDown.bind(this);
+        this.onMouseUp = this.onMouseUp.bind(this);
+
+        this.setupListeners();
+    }
+
+    setupListeners() {
+        window.addEventListener('keydown', this.onKeyDown);
+        window.addEventListener('keyup', this.onKeyUp);
+        this.domElement.addEventListener('mousemove', this.onMouseMove);
+        this.domElement.addEventListener('mousedown', this.onMouseDown);
+        this.domElement.addEventListener('mouseup', this.onMouseUp);
+    }
+
+    onKeyDown(e) {
+        const k = e.key.toLowerCase();
+        if (this.keys.hasOwnProperty(k)) this.keys[k] = true;
+    }
+
+    onKeyUp(e) {
+        const k = e.key.toLowerCase();
+        if (this.keys.hasOwnProperty(k)) this.keys[k] = false;
+    }
+
+    onMouseDown() { this.mouse.down = true; }
+    onMouseUp() { this.mouse.down = false; }
+
+    onMouseMove(e) {
+        if (this.mouse.down) {
+            this.mouse.dx += e.movementX;
+            this.mouse.dy += e.movementY;
+        }
+    }
+
+    /**
+     * Update loop called by GameLoop.
+     * @param {number} dt
+     */
+    update(dt) {
+        // 1. Process Rotation (Mouse)
+        this.rotation.y -= this.mouse.dx * this.sensitivity; // Yaw
+        this.rotation.x -= this.mouse.dy * this.sensitivity; // Pitch
+
+        // Clamp pitch to avoid flipping
+        this.rotation.x = Math.max(-Math.PI/2, Math.min(Math.PI/2, this.rotation.x));
+
+        // Reset mouse delta (consumed)
+        this.mouse.dx = 0;
+        this.mouse.dy = 0;
+
+        // 2. Process Movement (WASD)
+        // Forward vector derived from Yaw
+        const fwdX = Math.sin(this.rotation.y);
+        const fwdZ = Math.cos(this.rotation.y);
+        const rightX = Math.cos(this.rotation.y); // Perpendicular
+        const rightZ = -Math.sin(this.rotation.y);
+
+        const moveSpeed = this.speed * dt;
+
+        if (this.keys.w) {
+            this.velocity.x += fwdX * moveSpeed;
+            this.velocity.z -= fwdZ * moveSpeed; // WebGL Z is negative forward
+        }
+        if (this.keys.s) {
+            this.velocity.x -= fwdX * moveSpeed;
+            this.velocity.z += fwdZ * moveSpeed;
+        }
+        if (this.keys.a) {
+            this.velocity.x -= rightX * moveSpeed;
+            this.velocity.z += rightZ * moveSpeed;
+        }
+        if (this.keys.d) {
+            this.velocity.x += rightX * moveSpeed;
+            this.velocity.z -= rightZ * moveSpeed;
+        }
+
+        // Vertical Movement (Space/Shift)
+        if (this.keys.space) this.velocity.y += moveSpeed;
+        if (this.keys.shift) this.velocity.y -= moveSpeed;
+
+        // 4D Portal Rotation (Q/E)
+        if (this.keys.q) this.portalRot -= moveSpeed;
+        if (this.keys.e) this.portalRot += moveSpeed;
+
+        // Apply Damping (Friction)
+        this.velocity.x *= this.damping;
+        this.velocity.y *= this.damping;
+        this.velocity.z *= this.damping;
+
+        // 3. Apply to VIB3Engine Parameters
+        // Map 4D position to shader uniforms (e.g., u_noiseOffset or camera pos)
+        // Here we map to rotation parameters as a proxy for camera movement
+
+        // Visual feedback: Velocity tilts the view
+        this.engine.setParameter('rot4dXY', this.rotation.y + this.velocity.x * 0.1);
+        this.engine.setParameter('rot4dYZ', this.rotation.x + this.velocity.y * 0.1);
+
+        // Portal rotation affects XW plane
+        this.engine.setParameter('rot4dXW', this.portalRot);
+
+        // "Moving forward" increases grid density/scale to simulate zooming through
+        // In a real implementation, we'd update a u_cameraPosition uniform
+    }
+
+    destroy() {
+        window.removeEventListener('keydown', this.onKeyDown);
+        window.removeEventListener('keyup', this.onKeyUp);
+        this.domElement.removeEventListener('mousemove', this.onMouseMove);
+        this.domElement.removeEventListener('mousedown', this.onMouseDown);
+        this.domElement.removeEventListener('mouseup', this.onMouseUp);
+    }
+}