@vib3code/sdk 2.0.3-canary.89c05e0 → 2.0.3-canary.8d2fdcd

package/src/math/Vec4.js

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

package/src/scene/Node4D.js

@@ -500,29 +500,74 @@ export class Node4D {
      * @private
      */
     _updateLocalMatrix() {
-        // Start with identity
-        this._localMatrix = Mat4x4.identity();
+        // Ensure matrix exists
+        if (!this._localMatrix) {
+            this._localMatrix = new Mat4x4();
+        }
+
+        const m = this._localMatrix.data;
+        const s = this._scale;
+        const p = this._position;
+
+        // 1. Write rotation directly to local matrix (No allocation)
+        this._rotation.toMatrix(m);
+
+        // 2. Apply scale (Diagonal matrix multiplication on the right)
+        // M = M * S
+        // Columns of M are scaled by s.x, s.y, s.z, s.w
+
+        // Col 0
+        m[0] *= s.x; m[1] *= s.x; m[2] *= s.x; m[3] *= s.x;
+        // Col 1
+        m[4] *= s.y; m[5] *= s.y; m[6] *= s.y; m[7] *= s.y;
+        // Col 2
+        m[8] *= s.z; m[9] *= s.z; m[10] *= s.z; m[11] *= s.z;
+        // Col 3
+        m[12] *= s.w; m[13] *= s.w; m[14] *= s.w; m[15] *= s.w;
+
+        // 3. Apply translation (Matrix multiplication on the left)
+        // M = T * M
+        // T is standard 3D translation:
+        // [ 1 0 0 px ]
+        // [ 0 1 0 py ]
+        // [ 0 0 1 pz ]
+        // [ 0 0 0 1  ]
+        //
+        // Row 0 += px * Row 3
+        // Row 1 += py * Row 3
+        // Row 2 += pz * Row 3
+
+        const px = p.x;
+        const py = p.y;
+        const pz = p.z;
+
+        // Row 3 elements of M (which are used in the calculation)
+        const m3 = m[3];
+        const m7 = m[7];
+        const m11 = m[11];
+        const m15 = m[15];
+
+        if (px !== 0) {
+            m[0] += px * m3;
+            m[4] += px * m7;
+            m[8] += px * m11;
+            m[12] += px * m15;
+        }
+
+        if (py !== 0) {
+            m[1] += py * m3;
+            m[5] += py * m7;
+            m[9] += py * m11;
+            m[13] += py * m15;
+        }
+
+        if (pz !== 0) {
+            m[2] += pz * m3;
+            m[6] += pz * m7;
+            m[10] += pz * m11;
+            m[14] += pz * m15;
+        }
 
-        // Apply scale
-        const scaleMatrix = Mat4x4.identity();
-        scaleMatrix.set(0, 0, this._scale.x);
-        scaleMatrix.set(1, 1, this._scale.y);
-        scaleMatrix.set(2, 2, this._scale.z);
-        scaleMatrix.set(3, 3, this._scale.w);
-
-        // Apply rotation (toMatrix returns Float32Array, wrap in Mat4x4)
-        const rotationMatrix = new Mat4x4(this._rotation.toMatrix());
-
-        // Apply translation (in 4D, translation is stored in last column, keep [3,3]=1)
-        const translationMatrix = Mat4x4.identity();
-        translationMatrix.set(0, 3, this._position.x);
-        translationMatrix.set(1, 3, this._position.y);
-        translationMatrix.set(2, 3, this._position.z);
-        // Note: position.w is the 4th spatial coordinate, handled separately
-        // Matrix[3,3] must remain 1 for proper transformation
-
-        // Compose: T * R * S
-        this._localMatrix = translationMatrix.multiply(rotationMatrix).multiply(scaleMatrix);
         this._localDirty = false;
     }
 
@@ -535,10 +580,15 @@ export class Node4D {
             this._updateLocalMatrix();
         }
 
+        // Ensure matrix exists
+        if (!this._worldMatrix) {
+            this._worldMatrix = new Mat4x4();
+        }
+
         if (this._parent) {
-            this._worldMatrix = this._parent.worldMatrix.multiply(this._localMatrix);
+            this._parent.worldMatrix.multiply(this._localMatrix, this._worldMatrix);
         } else {
-            this._worldMatrix = this._localMatrix.clone();
+            this._worldMatrix.copy(this._localMatrix);
         }
 
         this._worldDirty = false;

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/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")