@vib3code/sdk 2.0.3-canary.4e0dace → 2.0.3-canary.4fbf680

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib3code/sdk",
-  "version": "2.0.3-canary.4e0dace",
+  "version": "2.0.3-canary.4fbf680",
   "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/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

@@ -354,12 +354,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 +421,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

package/src/math/Projection.js

@@ -72,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);
     }
 
@@ -107,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);
     }
 

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);
     }