@vib3code/sdk 2.0.3-canary.19bcbe1 → 2.0.3-canary.1f10a9c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib3code/sdk",
-  "version": "2.0.3-canary.19bcbe1",
+  "version": "2.0.3-canary.1f10a9c",
   "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/export/SVGExporter.js

@@ -355,17 +355,21 @@ function projectPoints(points, rotor, dimension, width, height) {
     const centerY = height / 2;
     const scale = Math.min(width, height) * 0.4;
 
+    // Reuse vectors to minimize allocation
+    const rotatedBuffer = new Vec4();
+    const projectedBuffer = new Vec4();
+
     for (const point of points) {
         // Apply 4D rotation
-        const rotated = rotor.rotate(point);
+        rotor.rotate(point, rotatedBuffer);
 
         // Project to 3D (perspective from W)
-        const proj3d = rotated.projectPerspective(dimension);
+        rotatedBuffer.projectPerspective(dimension, projectedBuffer);
 
         // Project to 2D (simple orthographic for clean SVG)
-        const x = centerX + proj3d.x * scale;
-        const y = centerY - proj3d.y * scale; // Flip Y for SVG coordinates
-        const depth = proj3d.z; // Keep depth for styling
+        const x = centerX + projectedBuffer.x * scale;
+        const y = centerY - projectedBuffer.y * scale; // Flip Y for SVG coordinates
+        const depth = projectedBuffer.z; // Keep depth for styling
 
         projected.push({ x, y, depth, original: point });
     }

package/src/math/Mat4x4.js

@@ -48,6 +48,19 @@ export class Mat4x4 {
         }
     }
 
+    /**
+     * Reset to identity matrix
+     * @returns {Mat4x4} this
+     */
+    identity() {
+        const d = this.data;
+        d[0] = 1; d[1] = 0; d[2] = 0; d[3] = 0;
+        d[4] = 0; d[5] = 1; d[6] = 0; d[7] = 0;
+        d[8] = 0; d[9] = 0; d[10] = 1; d[11] = 0;
+        d[12] = 0; d[13] = 0; d[14] = 0; d[15] = 1;
+        return this;
+    }
+
     /**
      * Create identity matrix
      * @returns {Mat4x4}
@@ -354,12 +367,18 @@ export class Mat4x4 {
 
     /**
      * Transpose matrix
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4} New transposed matrix
      */
-    transpose() {
+    transpose(target = null) {
         const m = this.data;
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || new Mat4x4(Mat4x4.UNINITIALIZED);
         const r = out.data;
+        // If target is same as source, use intermediate or careful swap
+        if (target === this) {
+            return this.transposeInPlace();
+        }
+
         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];
@@ -415,62 +434,85 @@ export class Mat4x4 {
 
     /**
      * Calculate inverse matrix
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4|null} Inverse matrix or null if singular
      */
-    inverse() {
+    inverse(target = null) {
         const m = this.data;
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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];
+        // Note: For in-place inversion (target === this), we need to be careful.
+        // The standard algorithm uses input values for every output cell.
+        // We can check for aliasing or use local variables if we wanted full safety,
+        // but simplest is to compute to temp if aliased, or just computing to the array directly works
+        // IF we cache everything first. But here we are writing to `inv` index by index.
+        // If inv === m, writing inv[0] destroys m[0] which is needed for inv[5] etc.
+        // So aliasing is NOT safe with this direct write approach.
+
+        // Handle aliasing by cloning first if needed, or using temp array.
+        // Since we want performance, let's detect aliasing.
+        let sourceData = m;
+        if (target === this) {
+            // Copy source data to temp array so we can write to 'this.data' safely
+            // We can't avoid allocation entirely in this specific edge case easily without unrolling everything into locals,
+            // which is huge for 4x4 inverse.
+            // Using a static temp buffer would be unsafe for threading/recursion (not an issue in JS single thread usually but still).
+            // Let's just clone the source data for the calculation.
+            sourceData = new Float32Array(m);
+        }
+
+        const s = sourceData;
+
+        inv[0] = s[5] * s[10] * s[15] - s[5] * s[11] * s[14] - s[9] * s[6] * s[15] +
+            s[9] * s[7] * s[14] + s[13] * s[6] * s[11] - s[13] * s[7] * s[10];
 
-        inv[4] = -m[4] * m[10] * m[15] + m[4] * m[11] * m[14] + m[8] * m[6] * m[15] -
-            m[8] * m[7] * m[14] - m[12] * m[6] * m[11] + m[12] * m[7] * m[10];
+        inv[4] = -s[4] * s[10] * s[15] + s[4] * s[11] * s[14] + s[8] * s[6] * s[15] -
+            s[8] * s[7] * s[14] - s[12] * s[6] * s[11] + s[12] * s[7] * s[10];
 
-        inv[8] = m[4] * m[9] * m[15] - m[4] * m[11] * m[13] - m[8] * m[5] * m[15] +
-            m[8] * m[7] * m[13] + m[12] * m[5] * m[11] - m[12] * m[7] * m[9];
+        inv[8] = s[4] * s[9] * s[15] - s[4] * s[11] * s[13] - s[8] * s[5] * s[15] +
+            s[8] * s[7] * s[13] + s[12] * s[5] * s[11] - s[12] * s[7] * s[9];
 
-        inv[12] = -m[4] * m[9] * m[14] + m[4] * m[10] * m[13] + m[8] * m[5] * m[14] -
-            m[8] * m[6] * m[13] - m[12] * m[5] * m[10] + m[12] * m[6] * m[9];
+        inv[12] = -s[4] * s[9] * s[14] + s[4] * s[10] * s[13] + s[8] * s[5] * s[14] -
+            s[8] * s[6] * s[13] - s[12] * s[5] * s[10] + s[12] * s[6] * s[9];
 
-        inv[1] = -m[1] * m[10] * m[15] + m[1] * m[11] * m[14] + m[9] * m[2] * m[15] -
-            m[9] * m[3] * m[14] - m[13] * m[2] * m[11] + m[13] * m[3] * m[10];
+        inv[1] = -s[1] * s[10] * s[15] + s[1] * s[11] * s[14] + s[9] * s[2] * s[15] -
+            s[9] * s[3] * s[14] - s[13] * s[2] * s[11] + s[13] * s[3] * s[10];
 
-        inv[5] = m[0] * m[10] * m[15] - m[0] * m[11] * m[14] - m[8] * m[2] * m[15] +
-            m[8] * m[3] * m[14] + m[12] * m[2] * m[11] - m[12] * m[3] * m[10];
+        inv[5] = s[0] * s[10] * s[15] - s[0] * s[11] * s[14] - s[8] * s[2] * s[15] +
+            s[8] * s[3] * s[14] + s[12] * s[2] * s[11] - s[12] * s[3] * s[10];
 
-        inv[9] = -m[0] * m[9] * m[15] + m[0] * m[11] * m[13] + m[8] * m[1] * m[15] -
-            m[8] * m[3] * m[13] - m[12] * m[1] * m[11] + m[12] * m[3] * m[9];
+        inv[9] = -s[0] * s[9] * s[15] + s[0] * s[11] * s[13] + s[8] * s[1] * s[15] -
+            s[8] * s[3] * s[13] - s[12] * s[1] * s[11] + s[12] * s[3] * s[9];
 
-        inv[13] = m[0] * m[9] * m[14] - m[0] * m[10] * m[13] - m[8] * m[1] * m[14] +
-            m[8] * m[2] * m[13] + m[12] * m[1] * m[10] - m[12] * m[2] * m[9];
+        inv[13] = s[0] * s[9] * s[14] - s[0] * s[10] * s[13] - s[8] * s[1] * s[14] +
+            s[8] * s[2] * s[13] + s[12] * s[1] * s[10] - s[12] * s[2] * s[9];
 
-        inv[2] = m[1] * m[6] * m[15] - m[1] * m[7] * m[14] - m[5] * m[2] * m[15] +
-            m[5] * m[3] * m[14] + m[13] * m[2] * m[7] - m[13] * m[3] * m[6];
+        inv[2] = s[1] * s[6] * s[15] - s[1] * s[7] * s[14] - s[5] * s[2] * s[15] +
+            s[5] * s[3] * s[14] + s[13] * s[2] * s[7] - s[13] * s[3] * s[6];
 
-        inv[6] = -m[0] * m[6] * m[15] + m[0] * m[7] * m[14] + m[4] * m[2] * m[15] -
-            m[4] * m[3] * m[14] - m[12] * m[2] * m[7] + m[12] * m[3] * m[6];
+        inv[6] = -s[0] * s[6] * s[15] + s[0] * s[7] * s[14] + s[4] * s[2] * s[15] -
+            s[4] * s[3] * s[14] - s[12] * s[2] * s[7] + s[12] * s[3] * s[6];
 
-        inv[10] = m[0] * m[5] * m[15] - m[0] * m[7] * m[13] - m[4] * m[1] * m[15] +
-            m[4] * m[3] * m[13] + m[12] * m[1] * m[7] - m[12] * m[3] * m[5];
+        inv[10] = s[0] * s[5] * s[15] - s[0] * s[7] * s[13] - s[4] * s[1] * s[15] +
+            s[4] * s[3] * s[13] + s[12] * s[1] * s[7] - s[12] * s[3] * s[5];
 
-        inv[14] = -m[0] * m[5] * m[14] + m[0] * m[6] * m[13] + m[4] * m[1] * m[14] -
-            m[4] * m[2] * m[13] - m[12] * m[1] * m[6] + m[12] * m[2] * m[5];
+        inv[14] = -s[0] * s[5] * s[14] + s[0] * s[6] * s[13] + s[4] * s[1] * s[14] -
+            s[4] * s[2] * s[13] - s[12] * s[1] * s[6] + s[12] * s[2] * s[5];
 
-        inv[3] = -m[1] * m[6] * m[11] + m[1] * m[7] * m[10] + m[5] * m[2] * m[11] -
-            m[5] * m[3] * m[10] - m[9] * m[2] * m[7] + m[9] * m[3] * m[6];
+        inv[3] = -s[1] * s[6] * s[11] + s[1] * s[7] * s[10] + s[5] * s[2] * s[11] -
+            s[5] * s[3] * s[10] - s[9] * s[2] * s[7] + s[9] * s[3] * s[6];
 
-        inv[7] = m[0] * m[6] * m[11] - m[0] * m[7] * m[10] - m[4] * m[2] * m[11] +
-            m[4] * m[3] * m[10] + m[8] * m[2] * m[7] - m[8] * m[3] * m[6];
+        inv[7] = s[0] * s[6] * s[11] - s[0] * s[7] * s[10] - s[4] * s[2] * s[11] +
+            s[4] * s[3] * s[10] + s[8] * s[2] * s[7] - s[8] * s[3] * s[6];
 
-        inv[11] = -m[0] * m[5] * m[11] + m[0] * m[7] * m[9] + m[4] * m[1] * m[11] -
-            m[4] * m[3] * m[9] - m[8] * m[1] * m[7] + m[8] * m[3] * m[5];
+        inv[11] = -s[0] * s[5] * s[11] + s[0] * s[7] * s[9] + s[4] * s[1] * s[11] -
+            s[4] * s[3] * s[9] - s[8] * s[1] * s[7] + s[8] * s[3] * s[5];
 
-        inv[15] = m[0] * m[5] * m[10] - m[0] * m[6] * m[9] - m[4] * m[1] * m[10] +
-            m[4] * m[2] * m[9] + m[8] * m[1] * m[6] - m[8] * m[2] * m[5];
+        inv[15] = s[0] * s[5] * s[10] - s[0] * s[6] * s[9] - s[4] * s[1] * s[10] +
+            s[4] * s[2] * s[9] + s[8] * s[1] * s[6] - s[8] * s[2] * s[5];
 
-        const det = m[0] * inv[0] + m[1] * inv[4] + m[2] * inv[8] + m[3] * inv[12];
+        const det = s[0] * inv[0] + s[1] * inv[4] + s[2] * inv[8] + s[3] * inv[12];
 
         if (Math.abs(det) < 1e-10) {
             return null; // Singular matrix
@@ -689,51 +731,78 @@ export class Mat4x4 {
     /**
      * Create XY plane rotation matrix (standard Z-axis rotation in 3D)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationXY(angle) {
+    static rotationXY(angle, target = null) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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;
+
+        if (target) {
+            r[0] = c; r[1] = s; r[2] = 0; r[3] = 0;
+            r[4] = -s; r[5] = c; r[6] = 0; r[7] = 0;
+            r[8] = 0; r[9] = 0; r[10] = 1; r[11] = 0;
+            r[12] = 0; r[13] = 0; r[14] = 0; r[15] = 1;
+        } else {
+            r[0] = c; r[1] = s;
+            r[4] = -s; r[5] = c;
+            r[10] = 1;
+            r[15] = 1;
+        }
         return out;
     }
 
     /**
      * Create XZ plane rotation matrix (standard Y-axis rotation in 3D)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationXZ(angle) {
+    static rotationXZ(angle, target = null) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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;
+
+        if (target) {
+            r[0] = c; r[1] = 0; r[2] = -s; r[3] = 0;
+            r[4] = 0; r[5] = 1; r[6] = 0; r[7] = 0;
+            r[8] = s; r[9] = 0; r[10] = c; r[11] = 0;
+            r[12] = 0; r[13] = 0; r[14] = 0; r[15] = 1;
+        } else {
+            r[0] = c; r[2] = -s;
+            r[5] = 1;
+            r[8] = s; r[10] = c;
+            r[15] = 1;
+        }
         return out;
     }
 
     /**
      * Create YZ plane rotation matrix (standard X-axis rotation in 3D)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationYZ(angle) {
+    static rotationYZ(angle, target = null) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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;
+
+        if (target) {
+            r[0] = 1; r[1] = 0; r[2] = 0; r[3] = 0;
+            r[4] = 0; r[5] = c; r[6] = s; r[7] = 0;
+            r[8] = 0; r[9] = -s; r[10] = c; r[11] = 0;
+            r[12] = 0; r[13] = 0; r[14] = 0; r[15] = 1;
+        } else {
+            r[0] = 1;
+            r[5] = c; r[6] = s;
+            r[9] = -s; r[10] = c;
+            r[15] = 1;
+        }
         return out;
     }
 
@@ -741,51 +810,78 @@ export class Mat4x4 {
      * Create XW plane rotation matrix (4D hyperspace rotation)
      * Creates "inside-out" effect when w approaches viewer
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationXW(angle) {
+    static rotationXW(angle, target = null) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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;
+
+        if (target) {
+            r[0] = c; r[1] = 0; r[2] = 0; r[3] = s;
+            r[4] = 0; r[5] = 1; r[6] = 0; r[7] = 0;
+            r[8] = 0; r[9] = 0; r[10] = 1; r[11] = 0;
+            r[12] = -s; r[13] = 0; r[14] = 0; r[15] = c;
+        } else {
+            r[0] = c; r[3] = s;
+            r[5] = 1;
+            r[10] = 1;
+            r[12] = -s; r[15] = c;
+        }
         return out;
     }
 
     /**
      * Create YW plane rotation matrix (4D hyperspace rotation)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationYW(angle) {
+    static rotationYW(angle, target = null) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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;
+
+        if (target) {
+            r[0] = 1; r[1] = 0; r[2] = 0; r[3] = 0;
+            r[4] = 0; r[5] = c; r[6] = 0; r[7] = s;
+            r[8] = 0; r[9] = 0; r[10] = 1; r[11] = 0;
+            r[12] = 0; r[13] = -s; r[14] = 0; r[15] = c;
+        } else {
+            r[0] = 1;
+            r[5] = c; r[7] = s;
+            r[10] = 1;
+            r[13] = -s; r[15] = c;
+        }
         return out;
     }
 
     /**
      * Create ZW plane rotation matrix (4D hyperspace rotation)
      * @param {number} angle - Rotation angle in radians
+     * @param {Mat4x4} [target=null] - Optional target matrix
      * @returns {Mat4x4}
      */
-    static rotationZW(angle) {
+    static rotationZW(angle, target = null) {
         const c = Math.cos(angle);
         const s = Math.sin(angle);
-        const out = new Mat4x4(Mat4x4.UNINITIALIZED);
+        const out = target || 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;
+
+        if (target) {
+            r[0] = 1; r[1] = 0; r[2] = 0; r[3] = 0;
+            r[4] = 0; r[5] = 1; r[6] = 0; r[7] = 0;
+            r[8] = 0; r[9] = 0; r[10] = c; r[11] = s;
+            r[12] = 0; r[13] = 0; r[14] = -s; r[15] = c;
+        } else {
+            r[0] = 1;
+            r[5] = 1;
+            r[10] = c; r[11] = s;
+            r[14] = -s; r[15] = c;
+        }
         return out;
     }
 
@@ -812,24 +908,58 @@ export class Mat4x4 {
      * Create combined rotation matrix from all 6 angles
      * Order: XY, XZ, YZ, XW, YW, ZW
      *
-     * @param {object} angles - Rotation angles
-     * @param {number} [angles.xy=0] - XY plane rotation
-     * @param {number} [angles.xz=0] - XZ plane rotation
-     * @param {number} [angles.yz=0] - YZ plane rotation
-     * @param {number} [angles.xw=0] - XW plane rotation
-     * @param {number} [angles.yw=0] - YW plane rotation
-     * @param {number} [angles.zw=0] - ZW plane rotation
+     * Supports two signatures:
+     * 1. rotationFromAngles(angles, target?)
+     * 2. rotationFromAngles(xy, xz, yz, xw, yw, zw, target?)
+     *
+     * @param {object|number} anglesOrXY - Rotation angles object OR XY angle
+     * @param {number|Mat4x4} [xzOrTarget] - XZ angle OR target matrix
+     * @param {number} [yz=0] - YZ angle
+     * @param {number} [xw=0] - XW angle
+     * @param {number} [yw=0] - YW angle
+     * @param {number} [zw=0] - ZW angle
+     * @param {Mat4x4} [target=null] - Target matrix (if using 6-arg signature)
      * @returns {Mat4x4}
      */
-    static rotationFromAngles(angles) {
-        let result = Mat4x4.identity();
+    static rotationFromAngles(anglesOrXY, xzOrTarget, yz, xw, yw, zw, target) {
+        let xy = 0, xz = 0;
+        let _yz = 0, _xw = 0, _yw = 0, _zw = 0;
+        let out = null;
+
+        if (typeof anglesOrXY === 'number') {
+            // Signature: (xy, xz, yz, xw, yw, zw, target)
+            xy = anglesOrXY;
+            xz = typeof xzOrTarget === 'number' ? xzOrTarget : 0;
+            _yz = yz || 0;
+            _xw = xw || 0;
+            _yw = yw || 0;
+            _zw = zw || 0;
+            out = target || null;
+        } else {
+            // Signature: (angles, target)
+            const angles = anglesOrXY || {};
+            xy = angles.xy || 0;
+            xz = angles.xz || 0;
+            _yz = angles.yz || 0;
+            _xw = angles.xw || 0;
+            _yw = angles.yw || 0;
+            _zw = angles.zw || 0;
+            // The second argument is the target in this case
+            // Use duck typing or check constructor name to avoid circular dependency issues if any
+            if (xzOrTarget && typeof xzOrTarget === 'object' && xzOrTarget.data) {
+                out = xzOrTarget;
+            }
+        }
+
+        const result = out || new Mat4x4(); // Default constructor is identity
+        if (out) result.identity(); // Reset if reused
 
-        if (angles.xy) result.rotateXY(angles.xy);
-        if (angles.xz) result.rotateXZ(angles.xz);
-        if (angles.yz) result.rotateYZ(angles.yz);
-        if (angles.xw) result.rotateXW(angles.xw);
-        if (angles.yw) result.rotateYW(angles.yw);
-        if (angles.zw) result.rotateZW(angles.zw);
+        if (xy) result.rotateXY(xy);
+        if (xz) result.rotateXZ(xz);
+        if (_yz) result.rotateYZ(_yz);
+        if (_xw) result.rotateXW(_xw);
+        if (_yw) result.rotateYW(_yw);
+        if (_zw) result.rotateZW(_zw);
 
         return result;
     }

package/src/math/Projection.js

@@ -36,16 +36,28 @@ export class Projection {
      *
      * @param {Vec4} v - 4D point
      * @param {number} d - Distance parameter (typically 1.5-5)
+     * @param {object} [options] - Projection options
+     * @param {Vec4} [target] - Optional target vector to write result to
      * @returns {Vec4} Projected point (w=0)
      */
-    static perspective(v, d = 2, options = {}) {
+    static perspective(v, d = 2, options = {}, target = null) {
         if (typeof d === 'object') {
             options = d;
             d = options.d ?? 2;
         }
-        const epsilon = options.epsilon ?? DEFAULT_EPSILON;
+
+        // Handle options overload or direct target argument
+        if (!target && options && options.target) {
+            target = options.target;
+        }
+
+        const epsilon = (options && options.epsilon) ?? DEFAULT_EPSILON;
         const denom = clampDenominator(d - v.w, epsilon);
         const scale = 1 / denom;
+
+        if (target) {
+            return target.set(v.x * scale, v.y * scale, v.z * scale, 0);
+        }
         return new Vec4(v.x * scale, v.y * scale, v.z * scale, 0);
     }
 
@@ -60,12 +72,23 @@ export class Projection {
      * The projection point is at (0, 0, 0, 1) - the "north pole"
      *
      * @param {Vec4} v - 4D point (ideally on unit hypersphere)
+     * @param {object|Vec4} [options] - Projection options or target vector
+     * @param {Vec4} [target] - Optional target vector to write result to
      * @returns {Vec4} Projected point (w=0)
      */
-    static stereographic(v, options = {}) {
-        const epsilon = options.epsilon ?? DEFAULT_EPSILON;
+    static stereographic(v, options = {}, target = null) {
+        if (options instanceof Vec4) {
+            target = options;
+            options = {};
+        }
+
+        const epsilon = (options && options.epsilon) ?? DEFAULT_EPSILON;
         const denom = clampDenominator(1 - v.w, epsilon);
         const scale = 1 / denom;
+
+        if (target) {
+            return target.set(v.x * scale, v.y * scale, v.z * scale, 0);
+        }
         return new Vec4(v.x * scale, v.y * scale, v.z * scale, 0);
     }
 
@@ -95,9 +118,13 @@ export class Projection {
      * Parallel projection - no perspective distortion.
      *
      * @param {Vec4} v - 4D point
+     * @param {Vec4} [target] - Optional target vector to write result to
      * @returns {Vec4} Projected point (w=0)
      */
-    static orthographic(v) {
+    static orthographic(v, target = null) {
+        if (target) {
+            return target.set(v.x, v.y, v.z, 0);
+        }
         return new Vec4(v.x, v.y, v.z, 0);
     }
 
@@ -126,10 +153,33 @@ export class Projection {
      * Project array of Vec4s using perspective projection
      * @param {Vec4[]} vectors
      * @param {number} d
+     * @param {object} [options]
+     * @param {Vec4[]} [target] - Optional target array to write results to
      * @returns {Vec4[]}
      */
-    static perspectiveArray(vectors, d = 2, options = {}) {
-        return vectors.map(v => Projection.perspective(v, d, options));
+    static perspectiveArray(vectors, d = 2, options = {}, target = null) {
+        // Handle options overload for 'd'
+        if (typeof d === 'object') {
+             options = d;
+             d = options.d ?? 2;
+        }
+
+        if (!target) {
+            return vectors.map(v => Projection.perspective(v, d, options));
+        }
+
+        const count = vectors.length;
+        // Iterate and reuse
+        for (let i = 0; i < count; i++) {
+            const out = target[i];
+            if (out) {
+                Projection.perspective(vectors[i], d, options, out);
+            } else {
+                target[i] = Projection.perspective(vectors[i], d, options);
+            }
+        }
+
+        return target;
     }
 
     /**

package/src/math/Rotor4D.js

@@ -276,48 +276,54 @@ export class Rotor4D {
      * The result applies this rotation, then r's rotation
      *
      * @param {Rotor4D} r - Right operand
+     * @param {Rotor4D} [target=null] - Optional target rotor to write result into
      * @returns {Rotor4D} Composed rotor
      */
-    multiply(r) {
+    multiply(r, target = null) {
         // Full geometric product of two rotors in 4D
         // This is derived from the geometric algebra product rules
 
         const a = this;
         const b = r;
 
-        return new Rotor4D(
-            // Scalar component
-            a.s * b.s - a.xy * b.xy - a.xz * b.xz - a.yz * b.yz -
-            a.xw * b.xw - a.yw * b.yw - a.zw * b.zw - a.xyzw * b.xyzw,
+        // Compute all components first to ensure safety if target aliases a or b
+        const s = a.s * b.s - a.xy * b.xy - a.xz * b.xz - a.yz * b.yz -
+            a.xw * b.xw - a.yw * b.yw - a.zw * b.zw - a.xyzw * b.xyzw;
 
-            // XY bivector
-            a.s * b.xy + a.xy * b.s + a.xz * b.yz - a.yz * b.xz +
-            a.xw * b.yw - a.yw * b.xw - a.zw * b.xyzw - a.xyzw * b.zw,
+        const xy = a.s * b.xy + a.xy * b.s + a.xz * b.yz - a.yz * b.xz +
+            a.xw * b.yw - a.yw * b.xw - a.zw * b.xyzw - a.xyzw * b.zw;
 
-            // XZ bivector
-            a.s * b.xz + a.xz * b.s - a.xy * b.yz + a.yz * b.xy +
-            a.xw * b.zw + a.yw * b.xyzw - a.zw * b.xw + a.xyzw * b.yw,
+        const xz = a.s * b.xz + a.xz * b.s - a.xy * b.yz + a.yz * b.xy +
+            a.xw * b.zw + a.yw * b.xyzw - a.zw * b.xw + a.xyzw * b.yw;
 
-            // YZ bivector
-            a.s * b.yz + a.yz * b.s + a.xy * b.xz - a.xz * b.xy -
-            a.xw * b.xyzw + a.yw * b.zw - a.zw * b.yw - a.xyzw * b.xw,
+        const yz = a.s * b.yz + a.yz * b.s + a.xy * b.xz - a.xz * b.xy -
+            a.xw * b.xyzw + a.yw * b.zw - a.zw * b.yw - a.xyzw * b.xw;
 
-            // XW bivector
-            a.s * b.xw + a.xw * b.s - a.xy * b.yw + a.xz * b.zw +
-            a.yz * b.xyzw + a.yw * b.xy - a.zw * b.xz + a.xyzw * b.yz,
+        const xw = a.s * b.xw + a.xw * b.s - a.xy * b.yw + a.xz * b.zw +
+            a.yz * b.xyzw + a.yw * b.xy - a.zw * b.xz + a.xyzw * b.yz;
 
-            // YW bivector
-            a.s * b.yw + a.yw * b.s + a.xy * b.xw - a.xz * b.xyzw -
-            a.yz * b.zw - a.xw * b.xy + a.zw * b.yz - a.xyzw * b.xz,
+        const yw = a.s * b.yw + a.yw * b.s + a.xy * b.xw - a.xz * b.xyzw -
+            a.yz * b.zw - a.xw * b.xy + a.zw * b.yz - a.xyzw * b.xz;
 
-            // ZW bivector
-            a.s * b.zw + a.zw * b.s + a.xy * b.xyzw + a.xz * b.xw +
-            a.yz * b.yw - a.xw * b.xz - a.yw * b.yz + a.xyzw * b.xy,
+        const zw = a.s * b.zw + a.zw * b.s + a.xy * b.xyzw + a.xz * b.xw +
+            a.yz * b.yw - a.xw * b.xz - a.yw * b.yz + a.xyzw * b.xy;
 
-            // Pseudoscalar XYZW
-            a.s * b.xyzw + a.xyzw * b.s + a.xy * b.zw - a.xz * b.yw +
-            a.yz * b.xw + a.xw * b.yz - a.yw * b.xz + a.zw * b.xy
-        );
+        const xyzw = a.s * b.xyzw + a.xyzw * b.s + a.xy * b.zw - a.xz * b.yw +
+            a.yz * b.xw + a.xw * b.yz - a.yw * b.xz + a.zw * b.xy;
+
+        if (target) {
+            target.s = s;
+            target.xy = xy;
+            target.xz = xz;
+            target.yz = yz;
+            target.xw = xw;
+            target.yw = yw;
+            target.zw = zw;
+            target.xyzw = xyzw;
+            return target;
+        }
+
+        return new Rotor4D(s, xy, xz, yz, xw, yw, zw, xyzw);
     }
 
     /**

package/src/math/Vec4.js

@@ -313,7 +313,11 @@ export class Vec4 {
      * @returns {number}
      */
     distanceTo(v) {
-        return this.sub(v).length();
+        const dx = this._x - v._x;
+        const dy = this._y - v._y;
+        const dz = this._z - v._z;
+        const dw = this._w - v._w;
+        return Math.sqrt(dx * dx + dy * dy + dz * dz + dw * dw);
     }
 
     /**
@@ -322,7 +326,11 @@ export class Vec4 {
      * @returns {number}
      */
     distanceToSquared(v) {
-        return this.sub(v).lengthSquared();
+        const dx = this._x - v._x;
+        const dy = this._y - v._y;
+        const dz = this._z - v._z;
+        const dw = this._w - v._w;
+        return dx * dx + dy * dy + dz * dz + dw * dw;
     }
 
     /**
@@ -408,42 +416,91 @@ export class Vec4 {
     /**
      * Project 4D point to 3D using perspective projection
      * Projects from 4D to 3D by dividing by (d - w)
-     * @param {number} d - Distance parameter (usually 2-5)
-     * @param {object} [options] - Projection options (epsilon, distance)
+     * @param {number|object} d - Distance parameter (usually 2-5) or options object
+     * @param {object|Vec4} [options] - Projection options or target vector
+     * @param {Vec4} [target] - Target vector to store result
      * @returns {Vec4} Projected point (w component is 0)
      */
-    projectPerspective(d = 2, options = {}) {
+    projectPerspective(d = 2, options = {}, target = null) {
         if (typeof d === 'object') {
+            // usage: projectPerspective({ distance: 2, ... }, target?)
+            if (options instanceof Vec4) {
+                target = options;
+            }
             options = d;
             d = options.distance ?? options.d ?? 2;
+        } else {
+            // usage: projectPerspective(d, options?, target?)
+            // usage: projectPerspective(d, target?)
+            if (options instanceof Vec4) {
+                target = options;
+                options = {};
+            }
         }
+
+        options = options || {};
+
         const epsilon = options.epsilon ?? 1e-5;
         const denom = d - this._w;
         const clamped = Math.abs(denom) < epsilon ? (denom >= 0 ? epsilon : -epsilon) : denom;
         const scale = 1 / clamped;
+
+        if (target) {
+            target._x = this._x * scale;
+            target._y = this._y * scale;
+            target._z = this._z * scale;
+            target._w = 0;
+            return target;
+        }
+
         return new Vec4(this._x * scale, this._y * scale, this._z * scale, 0);
     }
 
     /**
      * Project 4D point to 3D using stereographic projection
      * Maps 4D hypersphere to 3D space
-     * @param {object} [options] - Projection options (epsilon)
+     * @param {object|Vec4} [options] - Projection options or target vector
+     * @param {Vec4} [target] - Target vector to store result
      * @returns {Vec4} Projected point (w component is 0)
      */
-    projectStereographic(options = {}) {
+    projectStereographic(options = {}, target = null) {
+        if (options instanceof Vec4) {
+            target = options;
+            options = {};
+        }
+
+        options = options || {};
+
         const epsilon = options.epsilon ?? 1e-5;
         const denom = 1 - this._w;
         const clamped = Math.abs(denom) < epsilon ? (denom >= 0 ? epsilon : -epsilon) : denom;
         const scale = 1 / clamped;
+
+        if (target) {
+            target._x = this._x * scale;
+            target._y = this._y * scale;
+            target._z = this._z * scale;
+            target._w = 0;
+            return target;
+        }
+
         return new Vec4(this._x * scale, this._y * scale, this._z * scale, 0);
     }
 
     /**
      * Project 4D point to 3D using orthographic projection
      * Simply drops the W component
+     * @param {Vec4} [target=null] - Optional target vector
      * @returns {Vec4} Projected point (w component is 0)
      */
-    projectOrthographic() {
+    projectOrthographic(target = null) {
+        if (target) {
+            target._x = this._x;
+            target._y = this._y;
+            target._z = this._z;
+            target._w = 0;
+            return target;
+        }
         return new Vec4(this._x, this._y, this._z, 0);
     }
 

package/src/quantum/QuantumVisualizer.js

@@ -787,6 +787,11 @@ void main() {
 }`;
         
         this.program = this.createProgram(vertexShaderSource, fragmentShaderSource);
+
+        if (!this.program) {
+            return;
+        }
+
         this.uniforms = {
             resolution: this.gl.getUniformLocation(this.program, 'u_resolution'),
             time: this.gl.getUniformLocation(this.program, 'u_time'),
@@ -817,6 +822,18 @@ void main() {
      * Create WebGL program from shaders
      */
     createProgram(vertexSource, fragmentSource) {
+        // CRITICAL FIX: Check WebGL context state before shader operations
+        if (!this.gl) {
+            console.error('❌ Cannot create program: WebGL context is null');
+            return null;
+        }
+
+        if (this.gl.isContextLost()) {
+            console.error('❌ Cannot create program: WebGL context is lost');
+            this._contextLost = true;
+            return null;
+        }
+
         const vertexShader = this.createShader(this.gl.VERTEX_SHADER, vertexSource);
         const fragmentShader = this.createShader(this.gl.FRAGMENT_SHADER, fragmentSource);
         
@@ -860,6 +877,7 @@ void main() {
         
         if (this.gl.isContextLost()) {
             console.error('❌ Cannot create shader: WebGL context is lost');
+            this._contextLost = true;
             if (window.mobileDebug) {
                 window.mobileDebug.log(`❌ ${this.canvas?.id}: Cannot create shader - WebGL context is lost`);
             }
@@ -924,6 +942,11 @@ void main() {
      * Initialize vertex buffers
      */
     initBuffers() {
+        // CRITICAL FIX: Check WebGL context state before buffer operations
+        if (!this.gl || this.gl.isContextLost()) {
+            return;
+        }
+
         const positions = new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]);
         
         this.buffer = this.gl.createBuffer();
@@ -939,6 +962,11 @@ void main() {
      * Resize canvas and viewport
      */
     resize() {
+        // CRITICAL FIX: Check WebGL context state before viewport operations
+        if (!this.gl || this.gl.isContextLost()) {
+            return;
+        }
+
         // Mobile-optimized canvas sizing
         const dpr = Math.min(window.devicePixelRatio || 1, 2); // Cap at 2x for mobile performance
         const width = this.canvas.clientWidth;

package/src/testing/ProjectionClass.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import Projection from '../math/Projection.js';
+import Vec4 from '../math/Vec4.js';
+
+describe('Projection Class', () => {
+    it('should project using perspective', () => {
+        const v = new Vec4(1, 1, 1, 0);
+        const p = Projection.perspective(v, 2);
+        expect(p.x).toBeCloseTo(0.5);
+        expect(p.y).toBeCloseTo(0.5);
+        expect(p.z).toBeCloseTo(0.5);
+        expect(p.w).toBe(0);
+    });
+
+    it('should support target vector in perspective', () => {
+        const v = new Vec4(1, 1, 1, 0);
+        const target = new Vec4();
+        const result = Projection.perspective(v, 2, {}, target);
+        expect(result).toBe(target);
+        expect(target.x).toBeCloseTo(0.5);
+    });
+
+    it('should project array using perspectiveArray', () => {
+        const vectors = [new Vec4(1, 1, 1, 0), new Vec4(2, 2, 2, 0)];
+        const result = Projection.perspectiveArray(vectors, 2);
+        expect(result.length).toBe(2);
+        expect(result[0].x).toBeCloseTo(0.5);
+        expect(result[1].x).toBeCloseTo(1.0);
+    });
+
+    it('should reuse target array in perspectiveArray', () => {
+        const vectors = [new Vec4(1, 1, 1, 0)];
+        const targetArray = [new Vec4()];
+        const result = Projection.perspectiveArray(vectors, 2, {}, targetArray);
+        expect(result).toBe(targetArray);
+        expect(targetArray[0].x).toBeCloseTo(0.5);
+    });
+});

package/src/wasm/WasmLoader.js

@@ -200,12 +200,17 @@ function createFallbackModule() {
         ),
 
         // Projections
-        projectPerspective: JsProjection.perspectiveProject,
-        projectStereographic: JsProjection.stereographicProject,
-        projectOrthographic: JsProjection.orthographicProject,
-        projectOblique: JsProjection.obliqueProject,
-        projectSlice: JsProjection.sliceProject,
-        projectToFloatArray: JsProjection.projectToFloatArray
+        projectPerspective: JsProjection.Projection.perspective,
+        projectStereographic: JsProjection.Projection.stereographic,
+        projectOrthographic: JsProjection.Projection.orthographic,
+        projectOblique: JsProjection.Projection.oblique,
+        projectSlice: (v, wPlane, tolerance) => {
+            if (JsProjection.SliceProjection.isInSlice(v, wPlane, tolerance)) {
+                return JsProjection.Projection.orthographic(v);
+            }
+            return null;
+        },
+        projectToFloatArray: JsProjection.Projection.perspectivePacked
     };
 }
 

package/tools/update_projection.py

@@ -0,0 +1,109 @@
+import re
+
+file_path = 'src/math/Projection.js'
+
+with open(file_path, 'r') as f:
+    content = f.read()
+
+# Replace perspective JSDoc and Implementation
+perspective_old = r"""     * @param {Vec4} v - 4D point
+     * @param {number} d - Distance parameter (typically 1.5-5)
+     * @returns {Vec4} Projected point (w=0)
+     */
+    static perspective(v, d = 2, options = {}) {
+        if (typeof d === 'object') {
+            options = d;
+            d = options.d ?? 2;
+        }
+        const epsilon = options.epsilon ?? DEFAULT_EPSILON;
+        const denom = clampDenominator(d - v.w, epsilon);
+        const scale = 1 / denom;
+        return new Vec4(v.x * scale, v.y * scale, v.z * scale, 0);
+    }"""
+
+perspective_new = r"""     * @param {Vec4} v - 4D point
+     * @param {number} d - Distance parameter (typically 1.5-5)
+     * @param {object} [options] - Projection options
+     * @param {Vec4} [target] - Optional target vector to write result to
+     * @returns {Vec4} Projected point (w=0)
+     */
+    static perspective(v, d = 2, options = {}, target = null) {
+        if (typeof d === 'object') {
+            options = d;
+            d = options.d ?? 2;
+        }
+
+        // Handle options overload or direct target argument
+        if (!target && options && options.target) {
+            target = options.target;
+        }
+
+        const epsilon = (options && options.epsilon) ?? DEFAULT_EPSILON;
+        const denom = clampDenominator(d - v.w, epsilon);
+        const scale = 1 / denom;
+
+        if (target) {
+            return target.set(v.x * scale, v.y * scale, v.z * scale, 0);
+        }
+        return new Vec4(v.x * scale, v.y * scale, v.z * scale, 0);
+    }"""
+
+if perspective_old in content:
+    content = content.replace(perspective_old, perspective_new)
+else:
+    print("Could not find perspective implementation to replace.")
+    # Attempt more robust search if exact match fails? No, simpler is safer for now.
+
+# Replace perspectiveArray JSDoc and Implementation
+perspective_array_old = r"""    /**
+     * Project array of Vec4s using perspective projection
+     * @param {Vec4[]} vectors
+     * @param {number} d
+     * @returns {Vec4[]}
+     */
+    static perspectiveArray(vectors, d = 2, options = {}) {
+        return vectors.map(v => Projection.perspective(v, d, options));
+    }"""
+
+perspective_array_new = r"""    /**
+     * Project array of Vec4s using perspective projection
+     * @param {Vec4[]} vectors
+     * @param {number} d
+     * @param {object} [options]
+     * @param {Vec4[]} [target] - Optional target array to write results to
+     * @returns {Vec4[]}
+     */
+    static perspectiveArray(vectors, d = 2, options = {}, target = null) {
+        // Handle options overload for 'd'
+        if (typeof d === 'object') {
+             options = d;
+             d = options.d ?? 2;
+        }
+
+        if (!target) {
+            return vectors.map(v => Projection.perspective(v, d, options));
+        }
+
+        const count = vectors.length;
+        // Iterate and reuse
+        for (let i = 0; i < count; i++) {
+            const out = target[i];
+            if (out) {
+                Projection.perspective(vectors[i], d, options, out);
+            } else {
+                target[i] = Projection.perspective(vectors[i], d, options);
+            }
+        }
+
+        return target;
+    }"""
+
+if perspective_array_old in content:
+    content = content.replace(perspective_array_old, perspective_array_new)
+else:
+    print("Could not find perspectiveArray implementation to replace.")
+
+with open(file_path, 'w') as f:
+    f.write(content)
+
+print("Updated Projection.js")