@vib3code/sdk 2.0.3-canary.20f0435 → 2.0.3-canary.3206d35

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.20f0435",
+  "version": "2.0.3-canary.3206d35",
   "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/math/Mat4x4.js

@@ -18,6 +18,12 @@
 import { Vec4 } from './Vec4.js';
 
 export class Mat4x4 {
+    /**
+     * Internal token to skip initialization during construction
+     * @private
+     */
+    static UNINITIALIZED = {};
+
     /**
      * Create a new 4x4 matrix
      * Default is identity matrix
@@ -26,6 +32,8 @@ export class Mat4x4 {
     constructor(elements = null) {
         this.data = new Float32Array(16);
 
+        if (elements === Mat4x4.UNINITIALIZED) return;
+
         if (elements) {
             if (elements.length !== 16) {
                 throw new Error('Mat4x4 requires exactly 16 elements');
@@ -45,12 +53,7 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static identity() {
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, 1, 0, 0,
-            0, 0, 1, 0,
-            0, 0, 0, 1
-        ]);
+        return new Mat4x4();
     }
 
     /**
@@ -58,7 +61,7 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static zero() {
-        return new Mat4x4(new Float32Array(16));
+        return new Mat4x4(Mat4x4.UNINITIALIZED);
     }
 
     /**
@@ -157,10 +160,11 @@ export class Mat4x4 {
     /**
      * Multiply two matrices
      * @param {Mat4x4} m - Right operand
+     * @param {Mat4x4} [target=null] - Optional target matrix to store result
      * @returns {Mat4x4} New matrix = this * m
      */
-    multiply(m) {
-        const out = new Mat4x4();
+    multiply(m, target = null) {
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
         const r = out.data;
         const a = this.data;
         const b = m.data;
@@ -259,16 +263,22 @@ export class Mat4x4 {
     /**
      * Transform a Vec4 by this matrix
      * @param {Vec4} v
+     * @param {Vec4} [target=null] - Optional target vector to store result
      * @returns {Vec4} Transformed vector
      */
-    multiplyVec4(v) {
+    multiplyVec4(v, target = null) {
         const m = this.data;
-        return new Vec4(
-            m[0] * v.x + m[4] * v.y + m[8] * v.z + m[12] * v.w,
-            m[1] * v.x + m[5] * v.y + m[9] * v.z + m[13] * v.w,
-            m[2] * v.x + m[6] * v.y + m[10] * v.z + m[14] * v.w,
-            m[3] * v.x + m[7] * v.y + m[11] * v.z + m[15] * v.w
-        );
+        const out = target || new Vec4();
+
+        // Cache components to support aliasing (target === v)
+        const x = v.x, y = v.y, z = v.z, w = v.w;
+
+        out.x = m[0] * x + m[4] * y + m[8] * z + m[12] * w;
+        out.y = m[1] * x + m[5] * y + m[9] * z + m[13] * w;
+        out.z = m[2] * x + m[6] * y + m[10] * z + m[14] * w;
+        out.w = m[3] * x + m[7] * y + m[11] * z + m[15] * w;
+
+        return out;
     }
 
     /**
@@ -310,27 +320,36 @@ export class Mat4x4 {
     /**
      * Add another matrix
      * @param {Mat4x4} m
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4} New matrix
      */
-    add(m) {
-        const result = new Float32Array(16);
+    add(m, target = null) {
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        const a = this.data;
+        const b = m.data;
+
         for (let i = 0; i < 16; i++) {
-            result[i] = this.data[i] + m.data[i];
+            r[i] = a[i] + b[i];
         }
-        return new Mat4x4(result);
+        return out;
     }
 
     /**
      * Multiply by scalar
      * @param {number} s
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4} New matrix
      */
-    scale(s) {
-        const result = new Float32Array(16);
+    scale(s, target = null) {
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        const a = this.data;
+
         for (let i = 0; i < 16; i++) {
-            result[i] = this.data[i] * s;
+            r[i] = a[i] * s;
         }
-        return new Mat4x4(result);
+        return out;
     }
 
     /**
@@ -339,12 +358,13 @@ export class Mat4x4 {
      */
     transpose() {
         const m = this.data;
-        return new Mat4x4([
-            m[0], m[4], m[8], m[12],
-            m[1], m[5], m[9], m[13],
-            m[2], m[6], m[10], m[14],
-            m[3], m[7], m[11], m[15]
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = m[0]; r[4] = m[1]; r[8] = m[2]; r[12] = m[3];
+        r[1] = m[4]; r[5] = m[5]; r[9] = m[6]; r[13] = m[7];
+        r[2] = m[8]; r[6] = m[9]; r[10] = m[10]; r[14] = m[11];
+        r[3] = m[12]; r[7] = m[13]; r[11] = m[14]; r[15] = m[15];
+        return out;
     }
 
     /**
@@ -399,7 +419,8 @@ export class Mat4x4 {
      */
     inverse() {
         const m = this.data;
-        const inv = new Float32Array(16);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const inv = out.data;
 
         inv[0] = m[5] * m[10] * m[15] - m[5] * m[11] * m[14] - m[9] * m[6] * m[15] +
             m[9] * m[7] * m[14] + m[13] * m[6] * m[11] - m[13] * m[7] * m[10];
@@ -460,7 +481,7 @@ export class Mat4x4 {
             inv[i] *= invDet;
         }
 
-        return new Mat4x4(inv);
+        return out;
     }
 
     /**
@@ -673,12 +694,13 @@ export class Mat4x4 {
     static rotationXY(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            c, s, 0, 0,
-            -s, c, 0, 0,
-            0, 0, 1, 0,
-            0, 0, 0, 1
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = c; r[1] = s;
+        r[4] = -s; r[5] = c;
+        r[10] = 1;
+        r[15] = 1;
+        return out;
     }
 
     /**
@@ -689,12 +711,13 @@ export class Mat4x4 {
     static rotationXZ(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            c, 0, -s, 0,
-            0, 1, 0, 0,
-            s, 0, c, 0,
-            0, 0, 0, 1
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = c; r[2] = -s;
+        r[5] = 1;
+        r[8] = s; r[10] = c;
+        r[15] = 1;
+        return out;
     }
 
     /**
@@ -705,12 +728,13 @@ export class Mat4x4 {
     static rotationYZ(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, c, s, 0,
-            0, -s, c, 0,
-            0, 0, 0, 1
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = c; r[6] = s;
+        r[9] = -s; r[10] = c;
+        r[15] = 1;
+        return out;
     }
 
     /**
@@ -722,12 +746,13 @@ export class Mat4x4 {
     static rotationXW(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            c, 0, 0, s,
-            0, 1, 0, 0,
-            0, 0, 1, 0,
-            -s, 0, 0, c
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = c; r[3] = s;
+        r[5] = 1;
+        r[10] = 1;
+        r[12] = -s; r[15] = c;
+        return out;
     }
 
     /**
@@ -738,12 +763,13 @@ export class Mat4x4 {
     static rotationYW(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, c, 0, s,
-            0, 0, 1, 0,
-            0, -s, 0, c
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = c; r[7] = s;
+        r[10] = 1;
+        r[13] = -s; r[15] = c;
+        return out;
     }
 
     /**
@@ -754,12 +780,13 @@ export class Mat4x4 {
     static rotationZW(angle) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, 1, 0, 0,
-            0, 0, c, s,
-            0, 0, -s, c
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = 1;
+        r[10] = c; r[11] = s;
+        r[14] = -s; r[15] = c;
+        return out;
     }
 
     /**
@@ -831,12 +858,13 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static uniformScale(s) {
-        return new Mat4x4([
-            s, 0, 0, 0,
-            0, s, 0, 0,
-            0, 0, s, 0,
-            0, 0, 0, s
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = s;
+        r[5] = s;
+        r[10] = s;
+        r[15] = s;
+        return out;
     }
 
     /**
@@ -848,12 +876,13 @@ export class Mat4x4 {
      * @returns {Mat4x4}
      */
     static scale(sx, sy, sz, sw = 1) {
-        return new Mat4x4([
-            sx, 0, 0, 0,
-            0, sy, 0, 0,
-            0, 0, sz, 0,
-            0, 0, 0, sw
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = sx;
+        r[5] = sy;
+        r[10] = sz;
+        r[15] = sw;
+        return out;
     }
 
     /**
@@ -869,12 +898,13 @@ export class Mat4x4 {
     static translation(tx, ty, tz, tw = 0) {
         // For true 4D translation, you need 5D homogeneous coordinates
         // This is a placeholder that adds the translation to the W column
-        return new Mat4x4([
-            1, 0, 0, 0,
-            0, 1, 0, 0,
-            0, 0, 1, 0,
-            tx, ty, tz, 1 + tw
-        ]);
+        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const r = out.data;
+        r[0] = 1;
+        r[5] = 1;
+        r[10] = 1;
+        r[12] = tx; r[13] = ty; r[14] = tz; r[15] = 1 + tw;
+        return out;
     }
 }
 

package/src/math/Rotor4D.js

@@ -429,9 +429,10 @@ export class Rotor4D {
 
     /**
      * Convert rotor to 4x4 rotation matrix (column-major for WebGL)
+     * @param {Float32Array|Array} [target] - Optional target array to write into
      * @returns {Float32Array} 16-element array in column-major order
      */
-    toMatrix() {
+    toMatrix(target = null) {
         // Normalize first for numerical stability
         const n = this.norm();
         const invN = n > 1e-10 ? 1 / n : 1;
@@ -495,6 +496,35 @@ export class Rotor4D {
         // Formula derived from sandwich product R v R†
         // Diagonal: s² minus bivectors containing that axis, plus others
         // Off-diagonal: 2*s*bivector terms for single-plane contributions
+
+        if (target) {
+            // Column 0 (transformed X axis)
+            target[0] = s2 - xy2 - xz2 + yz2 - xw2 + yw2 + zw2 - xyzw2;
+            target[1] = sxy + xzyz + xwyw - zwxyzw;
+            target[2] = sxz - xyyz + xwzw + ywxyzw;
+            target[3] = sxw - xyyw - xzzw - yzxyzw;
+
+            // Column 1 (transformed Y axis)
+            target[4] = -sxy + xzyz + xwyw + zwxyzw;
+            target[5] = s2 - xy2 + xz2 - yz2 + xw2 - yw2 + zw2 - xyzw2;
+            target[6] = syz + xyxz + ywzw - xwxyzw;
+            target[7] = syw + xyxw - yzzw + xzxyzw;
+
+            // Column 2 (transformed Z axis)
+            target[8] = -sxz - xyyz + xwzw - ywxyzw;
+            target[9] = -syz + xyxz + ywzw + xwxyzw;
+            target[10] = s2 + xy2 - xz2 - yz2 + xw2 + yw2 - zw2 - xyzw2;
+            target[11] = szw + xzxw + yzyw - xyxyzw;
+
+            // Column 3 (transformed W axis)
+            target[12] = -sxw - xyyw - xzzw + yzxyzw;
+            target[13] = -syw + xyxw - yzzw - xzxyzw;
+            target[14] = -szw + xzxw + yzyw + xyxyzw;
+            target[15] = s2 + xy2 + xz2 + yz2 - xw2 - yw2 - zw2 - xyzw2;
+
+            return target;
+        }
+
         return new Float32Array([
             // Column 0 (transformed X axis)
             s2 - xy2 - xz2 + yz2 - xw2 + yw2 + zw2 - xyzw2,

package/src/math/Vec4.js

@@ -128,11 +128,19 @@ export class Vec4 {
     }
 
     /**
-     * Add another vector (immutable)
+     * Add another vector (immutable unless target provided)
      * @param {Vec4} v
-     * @returns {Vec4} New vector
-     */
-    add(v) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    add(v, target = null) {
+        if (target) {
+            target._x = this._x + v._x;
+            target._y = this._y + v._y;
+            target._z = this._z + v._z;
+            target._w = this._w + v._w;
+            return target;
+        }
         return new Vec4(
             this._x + v._x,
             this._y + v._y,
@@ -155,11 +163,19 @@ export class Vec4 {
     }
 
     /**
-     * Subtract another vector (immutable)
+     * Subtract another vector (immutable unless target provided)
      * @param {Vec4} v
-     * @returns {Vec4} New vector
-     */
-    sub(v) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    sub(v, target = null) {
+        if (target) {
+            target._x = this._x - v._x;
+            target._y = this._y - v._y;
+            target._z = this._z - v._z;
+            target._w = this._w - v._w;
+            return target;
+        }
         return new Vec4(
             this._x - v._x,
             this._y - v._y,
@@ -182,11 +198,19 @@ export class Vec4 {
     }
 
     /**
-     * Multiply by scalar (immutable)
+     * Multiply by scalar (immutable unless target provided)
      * @param {number} s
-     * @returns {Vec4} New vector
-     */
-    scale(s) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    scale(s, target = null) {
+        if (target) {
+            target._x = this._x * s;
+            target._y = this._y * s;
+            target._z = this._z * s;
+            target._w = this._w * s;
+            return target;
+        }
         return new Vec4(
             this._x * s,
             this._y * s,
@@ -211,9 +235,17 @@ export class Vec4 {
     /**
      * Component-wise multiply (Hadamard product)
      * @param {Vec4} v
-     * @returns {Vec4} New vector
-     */
-    multiply(v) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
+     */
+    multiply(v, target = null) {
+        if (target) {
+            target._x = this._x * v._x;
+            target._y = this._y * v._y;
+            target._z = this._z * v._z;
+            target._w = this._w * v._w;
+            return target;
+        }
         return new Vec4(
             this._x * v._x,
             this._y * v._y,
@@ -223,10 +255,18 @@ export class Vec4 {
     }
 
     /**
-     * Negate vector (immutable)
-     * @returns {Vec4} New vector
+     * Negate vector (immutable unless target provided)
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New vector or target
      */
-    negate() {
+    negate(target = null) {
+        if (target) {
+            target._x = -this._x;
+            target._y = -this._y;
+            target._z = -this._z;
+            target._w = -this._w;
+            return target;
+        }
         return new Vec4(-this._x, -this._y, -this._z, -this._w);
     }
 
@@ -286,15 +326,23 @@ export class Vec4 {
     }
 
     /**
-     * Normalize to unit length (immutable)
-     * @returns {Vec4} New normalized vector
+     * Normalize to unit length (immutable unless target provided)
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New normalized vector or target
      */
-    normalize() {
+    normalize(target = null) {
         const len = this.length();
         if (len < 1e-10) {
+            if (target) {
+                target._x = 0;
+                target._y = 0;
+                target._z = 0;
+                target._w = 0;
+                return target;
+            }
             return new Vec4(0, 0, 0, 0);
         }
-        return this.scale(1 / len);
+        return this.scale(1 / len, target);
     }
 
     /**
@@ -314,9 +362,17 @@ export class Vec4 {
      * Linear interpolation to another vector
      * @param {Vec4} v - Target vector
      * @param {number} t - Interpolation factor (0-1)
-     * @returns {Vec4} New interpolated vector
-     */
-    lerp(v, t) {
+     * @param {Vec4} [target=null] - Optional target vector
+     * @returns {Vec4} New interpolated vector or target
+     */
+    lerp(v, t, target = null) {
+        if (target) {
+            target._x = this._x + (v._x - this._x) * t;
+            target._y = this._y + (v._y - this._y) * t;
+            target._z = this._z + (v._z - this._z) * t;
+            target._w = this._w + (v._w - this._w) * t;
+            return target;
+        }
         return new Vec4(
             this._x + (v._x - this._x) * t,
             this._y + (v._y - this._y) * t,