@snaptrude/plugin-core 0.3.0 → 0.6.0

package/dist/api/core/math/quat.d.ts

@@ -1,187 +1,170 @@
-import * as z from "zod";
-import type { PVec3 } from "./vec3";
+import { PluginApiReturn } from "../../../types";
+import { Vec3Handle, QuatHandle, QuatComponents } from "../../../handles";
 /**
- * Quaternion operations for 3D rotations.
+ * Quaternion operations (all-handle model, §11).
  *
- * Quaternions avoid gimbal lock and provide smooth interpolation
- * compared to Euler angles. All methods are **pure** — they return
- * new {@linkcode PQuat} values without mutating the inputs.
- *
- * Accessed via `snaptrude.core.math.quat`.
+ * Quaternions are opaque {@linkcode QuatHandle}s; every operation is a host call
+ * returning a new handle. Read primitive components back with
+ * {@linkcode PluginQuatApi.components}. Accessed via `snaptrude.core.math.quat`.
  */
 export declare abstract class PluginQuatApi {
     constructor();
     /**
-     * Create a new quaternion from raw components.
-     *
-     * For most use cases prefer {@linkcode PluginQuatApi.fromAxisAngle}
-     * or {@linkcode PluginQuatApi.fromEuler} instead.
+     * Create a quaternion from primitive components.
      *
-     * @param x - The X component
-     * @param y - The Y component
-     * @param z - The Z component
-     * @param w - The W (scalar) component
-     * @returns A new {@linkcode PQuat}
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+     * const { x, y, z, w } = await snaptrude.core.math.quat.components(q)
+     * ```
      */
-    new(x: number, y: number, z: number, w: number): PQuat;
+    abstract new(x: number, y: number, z: number, w: number): PluginApiReturn<QuatHandle>;
     /**
-     * Create an identity quaternion representing no rotation.
+     * Return the identity quaternion (no rotation).
      *
-     * @returns `{ x: 0, y: 0, z: 0, w: 1 }`
+     * # Example
+     * ```ts
+     * const noRotation = await snaptrude.core.math.quat.identity()
+     * ```
      */
-    identity(): PQuat;
+    abstract identity(): PluginApiReturn<QuatHandle>;
     /**
-     * Create a quaternion from an axis and an angle.
-     *
-     * @param axis - The rotation axis as a {@linkcode PVec3} (will be normalized internally)
-     * @param angle - The rotation angle in **radians**
-     * @returns A new unit {@linkcode PQuat}, or identity if {@linkcode axis} has zero length
+     * Build a quaternion from a rotation axis and an angle in radians.
      *
      * # Example
      * ```ts
-     * const { vec3, quat } = snaptrude.core.math
-     * // 90° rotation around the Y axis
-     * const rot = quat.fromAxisAngle(vec3.new(0, 1, 0), Math.PI / 2)
+     * const axis = await snaptrude.core.math.vec3.new(0, 0, 1)
+     * const quarterTurn = await snaptrude.core.math.quat.fromAxisAngle(axis, Math.PI / 2)
      * ```
      */
-    fromAxisAngle(axis: PVec3, angle: number): PQuat;
+    abstract fromAxisAngle(axis: Vec3Handle, angle: number): PluginApiReturn<QuatHandle>;
     /**
-     * Create a quaternion from Euler angles in **XYZ** rotation order.
+     * Build a quaternion from Euler angles in radians.
      *
-     * @param x - Rotation around X axis in **radians**
-     * @param y - Rotation around Y axis in **radians**
-     * @param z - Rotation around Z axis in **radians**
-     * @returns A new {@linkcode PQuat}
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+     * ```
      */
-    fromEuler(x: number, y: number, z: number): PQuat;
+    abstract fromEuler(x: number, y: number, z: number): PluginApiReturn<QuatHandle>;
     /**
-     * Multiply two quaternions, combining their rotations.
+     * Compose two rotations with the Hamilton product `a * b` (apply `b` then `a`).
      *
-     * Quaternion multiplication is **not commutative**: `a * b ≠ b * a`.
-     * The result applies rotation {@linkcode b} first, then {@linkcode a}.
-     *
-     * @param a - First quaternion (applied second)
-     * @param b - Second quaternion (applied first)
-     * @returns A new {@linkcode PQuat} representing the combined rotation
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+     * const b = await snaptrude.core.math.quat.fromEuler(Math.PI / 4, 0, 0)
+     * const combined = await snaptrude.core.math.quat.multiply(a, b) // b first, then a
+     * ```
      */
-    multiply(a: PQuat, b: PQuat): PQuat;
+    abstract multiply(a: QuatHandle, b: QuatHandle): PluginApiReturn<QuatHandle>;
     /**
-     * Compute the conjugate of a quaternion.
-     *
-     * For unit quaternions the conjugate equals the inverse.
+     * Compute the conjugate of a quaternion (negated vector part).
      *
-     * @param q - The quaternion
-     * @returns A new {@linkcode PQuat} with negated vector part `(-x, -y, -z, w)`
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 4, 0)
+     * const conj = await snaptrude.core.math.quat.conjugate(q)
+     * ```
      */
-    conjugate(q: PQuat): PQuat;
+    abstract conjugate(q: QuatHandle): PluginApiReturn<QuatHandle>;
     /**
-     * Compute the length (magnitude) of a quaternion.
+     * Compute the magnitude (norm) of a quaternion.
      *
-     * @param q - The quaternion
-     * @returns The magnitude `√(x² + y² + z² + w²)`
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+     * const len = await snaptrude.core.math.quat.length(q) // 1
+     * ```
      */
-    length(q: PQuat): number;
+    abstract length(q: QuatHandle): PluginApiReturn<number>;
     /**
      * Normalize a quaternion to unit length.
      *
-     * @param q - The quaternion to normalize
-     * @returns A new unit-length {@linkcode PQuat}, or identity if the input has zero length
-     */
-    normalize(q: PQuat): PQuat;
-    /**
-     * Compute the inverse of a quaternion.
-     *
-     * The inverse satisfies `q * inverse(q) = identity`.
-     *
-     * @param q - The quaternion to invert
-     * @returns A new {@linkcode PQuat} that is the multiplicative inverse,
-     *   or identity if the input has zero length
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.new(0, 0, 1, 1)
+     * const unit = await snaptrude.core.math.quat.normalize(q)
+     * ```
      */
-    inverse(q: PQuat): PQuat;
+    abstract normalize(q: QuatHandle): PluginApiReturn<QuatHandle>;
     /**
-     * Rotate a 3D vector by a quaternion.
-     *
-     * Computes `q * v * conjugate(q)` using the Hamilton product.
-     *
-     * @param q - The rotation quaternion (should be unit-length)
-     * @param v - The vector to rotate as a {@linkcode PVec3}
-     * @returns A new rotated {@linkcode PVec3}
+     * Compute the inverse quaternion — the rotation that undoes `q`.
      *
      * # Example
      * ```ts
-     * const { vec3, quat } = snaptrude.core.math
-     * const rot = quat.fromAxisAngle(vec3.new(0, 1, 0), Math.PI / 2)
-     * const rotated = quat.rotateVec3(rot, vec3.new(1, 0, 0))
-     * // ≈ { x: 0, y: 0, z: -1 }
+     * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+     * const undo = await snaptrude.core.math.quat.inverse(q)
      * ```
      */
-    rotateVec3(q: PQuat, v: PVec3): PVec3;
+    abstract inverse(q: QuatHandle): PluginApiReturn<QuatHandle>;
     /**
-     * Convert a quaternion to axis-angle representation.
+     * Decompose a quaternion into its rotation axis and angle (radians).
      *
-     * @param q - The quaternion to convert
-     * @returns An object with:
-     *   - `axis` — The rotation axis as a unit {@linkcode PVec3}
-     *     (defaults to `(1, 0, 0)` when angle is zero)
-     *   - `angle` — The rotation angle in **radians**
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 3, 0)
+     * const { axis, angle } = await snaptrude.core.math.quat.toAxisAngle(q)
+     * const { x, y, z } = await snaptrude.core.math.vec3.components(axis)
+     * ```
      */
-    toAxisAngle(q: PQuat): {
-        axis: PVec3;
+    abstract toAxisAngle(q: QuatHandle): PluginApiReturn<{
+        axis: Vec3Handle;
         angle: number;
-    };
+    }>;
     /**
-     * Spherical linear interpolation between two quaternions.
-     *
-     * Produces smooth constant-speed rotation between {@linkcode a} and {@linkcode b}.
+     * Spherically interpolate (slerp) between two rotations by factor `t`.
      *
-     * @param a - Start quaternion (returned when `t = 0`)
-     * @param b - End quaternion (returned when `t = 1`)
-     * @param t - Interpolation factor, typically in `[0, 1]`
-     * @returns A new interpolated {@linkcode PQuat}
+     * # Example
+     * ```ts
+     * const start = await snaptrude.core.math.quat.identity()
+     * const end = await snaptrude.core.math.quat.fromEuler(0, Math.PI, 0)
+     * const halfway = await snaptrude.core.math.quat.slerp(start, end, 0.5)
+     * ```
      */
-    slerp(a: PQuat, b: PQuat, t: number): PQuat;
+    abstract slerp(a: QuatHandle, b: QuatHandle, t: number): PluginApiReturn<QuatHandle>;
     /**
      * Compute the dot product of two quaternions.
      *
-     * A value close to `1` or `-1` indicates similar orientations;
-     * a value close to `0` indicates maximally different orientations.
-     *
-     * @param a - First quaternion
-     * @param b - Second quaternion
-     * @returns The scalar dot product
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.quat.identity()
+     * const b = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+     * const d = await snaptrude.core.math.quat.dot(a, b)
+     * ```
      */
-    dot(a: PQuat, b: PQuat): number;
+    abstract dot(a: QuatHandle, b: QuatHandle): PluginApiReturn<number>;
     /**
-     * Check if two quaternions are exactly equal (strict equality per component).
+     * Test whether two quaternions have exactly equal components.
      *
-     * For floating-point comparisons, prefer {@linkcode PluginQuatApi.equalsApprox}.
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+     * const b = await snaptrude.core.math.quat.identity()
+     * const same = await snaptrude.core.math.quat.equals(a, b) // true
+     * ```
+     */
+    abstract equals(a: QuatHandle, b: QuatHandle): PluginApiReturn<boolean>;
+    /**
+     * Test whether two quaternions are equal within a tolerance `epsilon` (default `1e-6`).
      *
-     * @param a - First quaternion
-     * @param b - Second quaternion
-     * @returns `true` if all components match exactly
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+     * const b = await snaptrude.core.math.quat.fromEuler(0, 1.5711, 0)
+     * const close = await snaptrude.core.math.quat.equalsApprox(a, b, 1e-3) // true
+     * ```
      */
-    equals(a: PQuat, b: PQuat): boolean;
+    abstract equalsApprox(a: QuatHandle, b: QuatHandle, epsilon?: number): PluginApiReturn<boolean>;
     /**
-     * Check if two quaternions are approximately equal within a tolerance.
+     * Read the primitive `{ x, y, z, w }` components of a quaternion handle.
      *
-     * @param a - First quaternion
-     * @param b - Second quaternion
-     * @param epsilon - Maximum allowed difference per component (default `1e-6`)
-     * @returns `true` if `|a[i] - b[i]| < epsilon` for all components
+     * # Example
+     * ```ts
+     * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+     * const { x, y, z, w } = await snaptrude.core.math.quat.components(q)
+     * ```
      */
-    equalsApprox(a: PQuat, b: PQuat, epsilon?: number): boolean;
+    abstract components(q: QuatHandle): PluginApiReturn<QuatComponents>;
 }
-/**
- * A quaternion with `x`, `y`, `z`, and `w` components.
- *
- * Used for representing 3D rotations without gimbal lock.
- * Equivalent to `BABYLON.Quaternion`.
- */
-export declare const PQuat: z.ZodObject<{
-    x: z.ZodNumber;
-    y: z.ZodNumber;
-    z: z.ZodNumber;
-    w: z.ZodNumber;
-}, z.core.$strip>;
-export type PQuat = z.infer<typeof PQuat>;
 //# sourceMappingURL=quat.d.ts.map

package/dist/api/core/math/quat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quat.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/quat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEnC;;;;;;;;GAQG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAItD;;;;OAIG;IACH,QAAQ,IAAI,KAAK;IAIjB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK;IAahD;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAejD;;;;;;;;;OASG;IACH,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IASnC;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAI1B;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM;IAIxB;;;;;OAKG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAM1B;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAMxB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IAOrC;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAarD;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAsB3C;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM;IAI/B;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO;IAInC;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO;CAQlE;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;iBAKhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA"}
+{"version":3,"file":"quat.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/quat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEzE;;;;;;GAMG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACrF;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,IAAI,eAAe,CAAC,UAAU,CAAC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACpF;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IAChF;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC5E;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC5D;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACpF;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACnE;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC;IACvE;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CACnB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,OAAO,CAAC,EAAE,MAAM,GACf,eAAe,CAAC,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,cAAc,CAAC;CACpE"}

package/dist/api/core/math/vec3.d.ts

@@ -1,156 +1,174 @@
-import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+import { Vec3Handle, Vec3Components } from "../../../handles";
 /**
- * 3D vector operations for positions, directions, and displacements.
+ * 3D vector operations (all-handle model, §11).
  *
- * All methods are **pure** — they return new {@linkcode PVec3} values
- * without mutating the inputs.
- *
- * Accessed via `snaptrude.core.math.vec3`.
+ * Vectors are opaque {@linkcode Vec3Handle}s; every operation is a host call
+ * returning a new handle (vectors are immutable). Read primitive components back
+ * with {@linkcode PluginVec3Api.components}. Accessed via `snaptrude.core.math.vec3`.
  */
 export declare abstract class PluginVec3Api {
     constructor();
     /**
-     * Create a new 3D vector.
-     *
-     * @param x - The X component
-     * @param y - The Y component
-     * @param z - The Z component
-     * @returns A new {@linkcode PVec3}
+     * Create a vector from primitive components.
      *
      * # Example
      * ```ts
-     * const position = snaptrude.core.math.vec3.new(1, 2, 3)
-     * // { x: 1, y: 2, z: 3 }
+     * const v = await snaptrude.core.math.vec3.new(10, 0, 5)
+     * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
      * ```
      */
-    new(x: number, y: number, z: number): PVec3;
+    abstract new(x: number, y: number, z: number): PluginApiReturn<Vec3Handle>;
     /**
-     * Add two vectors component-wise.
+     * Add two vectors component-wise (`a + b`).
      *
-     * @param a - First vector
-     * @param b - Second vector
-     * @returns A new {@linkcode PVec3} where each component is `a[i] + b[i]`
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+     * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
+     * const sum = await snaptrude.core.math.vec3.add(a, b)
+     * ```
      */
-    add(a: PVec3, b: PVec3): PVec3;
+    abstract add(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>;
     /**
-     * Subtract vector {@linkcode b} from vector {@linkcode a} component-wise.
+     * Subtract vector `b` from `a` component-wise (`a - b`).
      *
-     * @param a - Vector to subtract from
-     * @param b - Vector to subtract
-     * @returns A new {@linkcode PVec3} where each component is `a[i] - b[i]`
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(3, 2, 1)
+     * const b = await snaptrude.core.math.vec3.new(1, 1, 1)
+     * const diff = await snaptrude.core.math.vec3.subtract(a, b)
+     * ```
      */
-    subtract(a: PVec3, b: PVec3): PVec3;
+    abstract subtract(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>;
     /**
-     * Scale a vector by a scalar value.
+     * Scale `v` by a scalar.
      *
-     * @param v - The vector to scale
-     * @param scalar - The scalar multiplier
-     * @returns A new {@linkcode PVec3} where each component is `v[i] * scalar`
+     * # Example
+     * ```ts
+     * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+     * const doubled = await snaptrude.core.math.vec3.scale(v, 2)
+     * ```
      */
-    scale(v: PVec3, scalar: number): PVec3;
+    abstract scale(v: Vec3Handle, scalar: number): PluginApiReturn<Vec3Handle>;
     /**
      * Compute the dot product of two vectors.
      *
-     * The dot product equals `|a| * |b| * cos(θ)` where `θ` is the angle
-     * between the vectors. Useful for checking orthogonality (result = 0)
-     * or projection.
-     *
-     * @param a - First vector
-     * @param b - Second vector
-     * @returns The scalar dot product
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+     * const b = await snaptrude.core.math.vec3.new(0.5, 0.5, 0)
+     * const d = await snaptrude.core.math.vec3.dot(a, b) // 0.5
+     * ```
      */
-    dot(a: PVec3, b: PVec3): number;
+    abstract dot(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>;
     /**
-     * Compute the cross product of two vectors.
-     *
-     * The result is a vector perpendicular to both inputs, with magnitude
-     * equal to the area of the parallelogram they span. Useful for computing
-     * surface normals.
+     * Compute the cross product `a × b` — the vector perpendicular to both.
      *
-     * @param a - First vector
-     * @param b - Second vector
-     * @returns A new {@linkcode PVec3} perpendicular to both {@linkcode a} and {@linkcode b}
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+     * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
+     * const perpendicular = await snaptrude.core.math.vec3.cross(a, b)
+     * ```
      */
-    cross(a: PVec3, b: PVec3): PVec3;
+    abstract cross(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>;
     /**
-     * Compute the length (magnitude) of a vector.
+     * Compute the Euclidean length (magnitude) of a vector.
      *
-     * @param v - The vector
-     * @returns The Euclidean length `√(x² + y² + z²)`
+     * # Example
+     * ```ts
+     * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
+     * const len = await snaptrude.core.math.vec3.length(v) // 5
+     * ```
      */
-    length(v: PVec3): number;
+    abstract length(v: Vec3Handle): PluginApiReturn<number>;
     /**
-     * Compute the squared length of a vector.
-     *
-     * Avoids the `sqrt` call — prefer this over {@linkcode PluginVec3Api.length}
-     * when comparing relative magnitudes.
+     * Compute the squared Euclidean length of a vector (avoids the sqrt).
      *
-     * @param v - The vector
-     * @returns The squared length `x² + y² + z²`
+     * # Example
+     * ```ts
+     * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
+     * const sq = await snaptrude.core.math.vec3.lengthSquared(v) // 25
+     * ```
      */
-    lengthSquared(v: PVec3): number;
+    abstract lengthSquared(v: Vec3Handle): PluginApiReturn<number>;
     /**
-     * Normalize a vector to unit length.
+     * Return the unit vector in the same direction (the zero vector if length is 0).
      *
-     * @param v - The vector to normalize
-     * @returns A new unit-length {@linkcode PVec3} in the same direction,
-     *   or a zero vector `(0, 0, 0)` if the input has zero length
+     * # Example
+     * ```ts
+     * const v = await snaptrude.core.math.vec3.new(0, 0, 10)
+     * const unit = await snaptrude.core.math.vec3.normalize(v) // (0, 0, 1)
+     * ```
      */
-    normalize(v: PVec3): PVec3;
+    abstract normalize(v: Vec3Handle): PluginApiReturn<Vec3Handle>;
     /**
-     * Compute the Euclidean distance between two points.
+     * Measure the straight-line (Euclidean) distance between two points.
      *
-     * @param a - First point
-     * @param b - Second point
-     * @returns The distance `|a - b|`
+     * @examplePrompt What is the distance between these two points?
+     * @examplePrompt Measure how far apart these two points are
+     *
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+     * const b = await snaptrude.core.math.vec3.new(3, 4, 0)
+     * const dist = await snaptrude.core.math.vec3.distance(a, b) // 5
+     * ```
      */
-    distance(a: PVec3, b: PVec3): number;
+    abstract distance(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>;
     /**
-     * Linearly interpolate between two vectors.
+     * Linearly interpolate between two vectors: `a + (b - a) * t`.
      *
-     * @param a - Start vector (returned when `t = 0`)
-     * @param b - End vector (returned when `t = 1`)
-     * @param t - Interpolation factor, typically in `[0, 1]`
-     * @returns A new {@linkcode PVec3} at `a + (b - a) * t`
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+     * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+     * const midpoint = await snaptrude.core.math.vec3.lerp(a, b, 0.5)
+     * ```
      */
-    lerp(a: PVec3, b: PVec3, t: number): PVec3;
+    abstract lerp(a: Vec3Handle, b: Vec3Handle, t: number): PluginApiReturn<Vec3Handle>;
     /**
-     * Negate a vector (reverse its direction).
+     * Negate a vector, reversing its direction.
      *
-     * @param v - The vector to negate
-     * @returns A new {@linkcode PVec3} with all components negated
+     * # Example
+     * ```ts
+     * const v = await snaptrude.core.math.vec3.new(1, -2, 3)
+     * const reversed = await snaptrude.core.math.vec3.negate(v) // (-1, 2, -3)
+     * ```
      */
-    negate(v: PVec3): PVec3;
+    abstract negate(v: Vec3Handle): PluginApiReturn<Vec3Handle>;
     /**
-     * Check if two vectors are exactly equal (strict equality per component).
+     * Test whether two vectors have exactly equal components.
      *
-     * For floating-point comparisons, prefer {@linkcode PluginVec3Api.equalsApprox}.
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
+     * const b = await snaptrude.core.math.vec3.new(1, 2, 3)
+     * const same = await snaptrude.core.math.vec3.equals(a, b) // true
+     * ```
+     */
+    abstract equals(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<boolean>;
+    /**
+     * Test whether two vectors are equal within a tolerance `epsilon` (default `1e-6`).
      *
-     * @param a - First vector
-     * @param b - Second vector
-     * @returns `true` if all components match exactly
+     * # Example
+     * ```ts
+     * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
+     * const b = await snaptrude.core.math.vec3.new(1.0004, 2, 3)
+     * const close = await snaptrude.core.math.vec3.equalsApprox(a, b, 1e-3) // true
+     * ```
      */
-    equals(a: PVec3, b: PVec3): boolean;
+    abstract equalsApprox(a: Vec3Handle, b: Vec3Handle, epsilon?: number): PluginApiReturn<boolean>;
     /**
-     * Check if two vectors are approximately equal within a tolerance.
+     * Read the primitive `{ x, y, z }` components of a vector handle.
      *
-     * @param a - First vector
-     * @param b - Second vector
-     * @param epsilon - Maximum allowed difference per component (default `1e-6`)
-     * @returns `true` if `|a[i] - b[i]| < epsilon` for all components
+     * # Example
+     * ```ts
+     * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+     * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
+     * ```
      */
-    equalsApprox(a: PVec3, b: PVec3, epsilon?: number): boolean;
+    abstract components(v: Vec3Handle): PluginApiReturn<Vec3Components>;
 }
-/**
- * A 3D vector with `x`, `y`, and `z` components.
- *
- * Used throughout the plugin API for positions, directions, displacements,
- * and Euler rotation angles. Equivalent to `BABYLON.Vector3`.
- */
-export declare const PVec3: z.ZodObject<{
-    x: z.ZodNumber;
-    y: z.ZodNumber;
-    z: z.ZodNumber;
-}, z.core.$strip>;
-export type PVec3 = z.infer<typeof PVec3>;
 //# sourceMappingURL=vec3.d.ts.map

package/dist/api/core/math/vec3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vec3.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/vec3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAExB;;;;;;;GAOG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAI3C;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IAI9B;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IAInC;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK;IAItC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM;IAI/B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IAQhC;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM;IAIxB;;;;;;;;OAQG;IACH,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM;IAI/B;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAM1B;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM;IAIpC;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAQ1C;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAIvB;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO;IAInC;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO;CAOlE;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;iBAIhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA"}
+{"version":3,"file":"vec3.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/vec3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAE7D;;;;;;GAMG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IAC1E;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IACvE;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC5E;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IAC1E;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACnE;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IACzE;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IAC9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC9D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACxE;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACnF;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC3D;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC;IACvE;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CACnB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,OAAO,CAAC,EAAE,MAAM,GACf,eAAe,CAAC,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,cAAc,CAAC;CACpE"}