@vib3code/sdk 2.0.3-canary.74aebb4 → 2.0.3-canary.7b9491f

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.74aebb4",
+  "version": "2.0.3-canary.7b9491f",
   "description": "VIB3+ 4D Visualization SDK - Unified engine with 6D rotation, MCP agentic integration, and cross-platform support",
   "type": "module",
   "main": "src/core/VIB3Engine.js",
@@ -9,9 +9,7 @@
     "vib3": "./src/cli/index.js",
     "vib3-mcp": "./src/agent/mcp/stdio-server.js"
   },
-  "sideEffects": [
-    "./src/geometry/builders/*.js"
-  ],
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./types/adaptive-sdk.d.ts",

package/src/geometry/warp/HypersphereCore.js

@@ -16,13 +16,14 @@ import { Vec4 } from '../../math/Vec4.js';
  * @param {number} radius - Hypersphere radius
  * @returns {Vec4} Point on hypersphere
  */
-export function projectToHypersphere(point, radius = 1) {
+export function projectToHypersphere(point, radius = 1, target = null) {
     const len = point.length();
     if (len < 0.0001) {
         // Handle origin - project to north pole
+        if (target) return target.set(0, 0, 0, radius);
         return new Vec4(0, 0, 0, radius);
     }
-    return point.scale(radius / len);
+    return point.scale(radius / len, target);
 }
 
 /**
@@ -30,9 +31,10 @@ export function projectToHypersphere(point, radius = 1) {
  * Maps all of 3D space onto the 4D hypersphere
  * @param {Vec4} point - Input point (uses x, y, z)
  * @param {number} radius - Hypersphere radius
+ * @param {Vec4} [target=null] - Optional target vector
  * @returns {Vec4} Point on hypersphere
  */
-export function stereographicToHypersphere(point, radius = 1) {
+export function stereographicToHypersphere(point, radius = 1, target = null) {
     const x = point.x;
     const y = point.y;
     const z = point.z;
@@ -40,6 +42,15 @@ export function stereographicToHypersphere(point, radius = 1) {
     const sumSq = x * x + y * y + z * z;
     const denom = sumSq + 1;
 
+    if (target) {
+        return target.set(
+            (2 * x) / denom * radius,
+            (2 * y) / denom * radius,
+            (2 * z) / denom * radius,
+            (sumSq - 1) / denom * radius
+        );
+    }
+
     return new Vec4(
         (2 * x) / denom * radius,
         (2 * y) / denom * radius,
@@ -56,12 +67,22 @@ export function stereographicToHypersphere(point, radius = 1) {
  * @param {number} phi - Azimuth on base S² (0 to 2π)
  * @param {number} psi - Fiber angle (0 to 2π)
  * @param {number} radius - Hypersphere radius
+ * @param {Vec4} [target=null] - Optional target vector
  * @returns {Vec4} Point on hypersphere
  */
-export function hopfFibration(theta, phi, psi, radius = 1) {
+export function hopfFibration(theta, phi, psi, radius = 1, target = null) {
     const cosTheta2 = Math.cos(theta / 2);
     const sinTheta2 = Math.sin(theta / 2);
 
+    if (target) {
+        return target.set(
+            cosTheta2 * Math.cos((phi + psi) / 2) * radius,
+            cosTheta2 * Math.sin((phi + psi) / 2) * radius,
+            sinTheta2 * Math.cos((phi - psi) / 2) * radius,
+            sinTheta2 * Math.sin((phi - psi) / 2) * radius
+        );
+    }
+
     return new Vec4(
         cosTheta2 * Math.cos((phi + psi) / 2) * radius,
         cosTheta2 * Math.sin((phi + psi) / 2) * radius,
@@ -78,8 +99,9 @@ export function hopfFibration(theta, phi, psi, radius = 1) {
  * @returns {Vec4[]} Warped vertices
  */
 export function warpRadial(vertices, radius = 1, blendFactor = 1) {
+    const onSphere = new Vec4();
     return vertices.map(v => {
-        const onSphere = projectToHypersphere(v, radius);
+        projectToHypersphere(v, radius, onSphere);
         return v.lerp(onSphere, blendFactor);
     });
 }
@@ -93,8 +115,9 @@ export function warpRadial(vertices, radius = 1, blendFactor = 1) {
  * @returns {Vec4[]} Warped vertices
  */
 export function warpStereographic(vertices, radius = 1, scale = 1) {
+    const scaled = new Vec4();
     return vertices.map(v => {
-        const scaled = v.scale(scale);
+        v.scale(scale, scaled);
         return stereographicToHypersphere(scaled, radius);
     });
 }
@@ -146,25 +169,31 @@ export function warpHypersphereCore(geometry, options = {}) {
         twist = 1
     } = options;
 
-    let warpedVertices;
-
-    // Pre-scale vertices
-    const scaledVertices = geometry.vertices.map(v => v.scale(scale));
-
-    switch (method) {
-        case 'stereographic':
-            warpedVertices = warpStereographic(scaledVertices, radius, 1);
-            break;
-
-        case 'hopf':
-            warpedVertices = warpHopf(scaledVertices, radius, twist);
-            break;
+    const temp = new Vec4();
+    const warpedVertices = geometry.vertices.map(v => {
+        // Combined scaling and warping to minimize allocations
+        const result = v.scale(scale);
+
+        if (method === 'stereographic') {
+            stereographicToHypersphere(result, radius, result);
+        } else if (method === 'hopf') {
+            const r = result.length();
+            if (r < 0.0001) {
+                result.set(0, 0, 0, radius);
+            } else {
+                const theta = Math.acos(result.z / r);
+                const phi = Math.atan2(result.y, result.x);
+                const psi = result.w * twist + phi * 0.5;
+                hopfFibration(theta, phi, psi, radius, result);
+            }
+        } else {
+            // Radial (default)
+            projectToHypersphere(result, radius, temp);
+            result.lerp(temp, blend, result);
+        }
 
-        case 'radial':
-        default:
-            warpedVertices = warpRadial(scaledVertices, radius, blend);
-            break;
-    }
+        return result;
+    });
 
     return {
         ...geometry,

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,