@vib3code/sdk 2.0.3-canary.3b3ca18 → 2.0.3-canary.4e0dace

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.3b3ca18",
+  "version": "2.0.3-canary.4e0dace",
   "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/cli/index.js

@@ -5,9 +5,34 @@
  */
 
 import { performance } from 'node:perf_hooks';
+import path from 'node:path';
 import { mcpServer, toolDefinitions } from '../agent/index.js';
 import { schemaRegistry } from '../schemas/index.js';
 
+/**
+ * Resolves a file path and ensures it is within the current working directory.
+ * @param {string} filePath The path to validate
+ * @returns {string} The resolved absolute path
+ * @throws {Error} If the path is outside the allowed directory
+ */
+function getSafePath(filePath) {
+    if (!filePath) return filePath;
+
+    const cwd = process.cwd();
+    const resolvedPath = path.resolve(cwd, filePath);
+    const relative = path.relative(cwd, resolvedPath);
+
+    const isOutside = relative.startsWith('..') || path.isAbsolute(relative);
+
+    if (isOutside) {
+        const error = new Error('Security Error: Path traversal detected. Access denied.');
+        error.code = 'EACCES';
+        throw error;
+    }
+
+    return resolvedPath;
+}
+
 /**
  * CLI Configuration
  */
@@ -446,7 +471,7 @@ async function handleTools(parsed, startTime) {
  */
 async function handleValidate(parsed, startTime) {
     const subcommand = parsed.subcommand || 'pack';
-    const filePath = parsed.options.file || parsed.options.f || parsed.positional[0];
+    let filePath = parsed.options.file || parsed.options.f || parsed.positional[0];
 
     if (!filePath && subcommand !== 'schema') {
         return wrapResponse('validate', {
@@ -460,6 +485,10 @@ async function handleValidate(parsed, startTime) {
     }
 
     try {
+        if (filePath) {
+            filePath = getSafePath(filePath);
+        }
+
         switch (subcommand) {
             case 'pack': {
                 // Validate a .vib3 scene pack file
@@ -533,6 +562,17 @@ async function handleValidate(parsed, startTime) {
                 }, false, performance.now() - startTime);
         }
     } catch (error) {
+        if (error.code === 'EACCES') {
+            return wrapResponse('validate', {
+                error: {
+                    type: 'SecurityError',
+                    code: 'ACCESS_DENIED',
+                    message: error.message,
+                    suggestion: 'Ensure the file path is within the project directory'
+                }
+            }, false, performance.now() - startTime);
+        }
+
         if (error.code === 'ENOENT') {
             return wrapResponse('validate', {
                 error: {
@@ -659,7 +699,6 @@ async function main() {
  */
 async function handleInit(parsed, startTime) {
     const { writeFileSync, mkdirSync, existsSync } = await import('node:fs');
-    const { join } = await import('node:path');
 
     const projectName = parsed.subcommand || parsed.positional[0] || 'my-vib3-app';
     const template = parsed.options.template || parsed.options.t || 'vanilla';
@@ -677,7 +716,22 @@ async function handleInit(parsed, startTime) {
         }, false, performance.now() - startTime);
     }
 
-    const projectDir = join(process.cwd(), projectName);
+    let projectDir;
+    try {
+        projectDir = getSafePath(projectName);
+    } catch (error) {
+        if (error.code === 'EACCES') {
+            return wrapResponse('init', {
+                error: {
+                    type: 'SecurityError',
+                    code: 'ACCESS_DENIED',
+                    message: error.message,
+                    suggestion: 'Choose a project name that results in a valid subdirectory'
+                }
+            }, false, performance.now() - startTime);
+        }
+        throw error;
+    }
 
     if (existsSync(projectDir)) {
         return wrapResponse('init', {
@@ -695,8 +749,8 @@ async function handleInit(parsed, startTime) {
     const files = getTemplateFiles(template, projectName);
 
     for (const [filename, content] of Object.entries(files)) {
-        const filepath = join(projectDir, filename);
-        const dir = join(projectDir, filename.split('/').slice(0, -1).join('/'));
+        const filepath = path.join(projectDir, filename);
+        const dir = path.join(projectDir, filename.split('/').slice(0, -1).join('/'));
         if (dir !== projectDir) {
             mkdirSync(dir, { recursive: true });
         }

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);
     }
 
     /**
@@ -161,7 +164,7 @@ export class Mat4x4 {
      * @returns {Mat4x4} New matrix = this * m
      */
     multiply(m, target = null) {
-        const out = target || new Mat4x4();
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
         const r = out.data;
         const a = this.data;
         const b = m.data;
@@ -321,7 +324,7 @@ export class Mat4x4 {
      * @returns {Mat4x4} New matrix
      */
     add(m, target = null) {
-        const out = target || new Mat4x4();
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
         const r = out.data;
         const a = this.data;
         const b = m.data;
@@ -339,7 +342,7 @@ export class Mat4x4 {
      * @returns {Mat4x4} New matrix
      */
     scale(s, target = null) {
-        const out = target || new Mat4x4();
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
         const r = out.data;
         const a = this.data;
 
@@ -355,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;
     }
 
     /**
@@ -415,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];
@@ -476,7 +481,7 @@ export class Mat4x4 {
             inv[i] *= invDet;
         }
 
-        return new Mat4x4(inv);
+        return out;
     }
 
     /**
@@ -689,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;
     }
 
     /**
@@ -705,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;
     }
 
     /**
@@ -721,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;
     }
 
     /**
@@ -738,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;
     }
 
     /**
@@ -754,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;
     }
 
     /**
@@ -770,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;
     }
 
     /**
@@ -847,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;
     }
 
     /**
@@ -864,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;
     }
 
     /**
@@ -885,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;
     }
 }