@snaptrude/plugin-core 0.2.9 → 0.5.0

package/src/api/core/math/quat.ts

@@ -1,295 +1,172 @@
-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 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 {
-    return { x, y, z, w }
-  }
-
+  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 {
-    return { x: 0, y: 0, z: 0, w: 1 }
-  }
-
+  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 {
-    const halfAngle = angle / 2
-    const s = Math.sin(halfAngle)
-    const len = Math.sqrt(axis.x * axis.x + axis.y * axis.y + axis.z * axis.z)
-    if (len === 0) return { x: 0, y: 0, z: 0, w: 1 }
-    return {
-      x: (axis.x / len) * s,
-      y: (axis.y / len) * s,
-      z: (axis.z / len) * s,
-      w: Math.cos(halfAngle),
-    }
-  }
-
+  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 {
-    const cx = Math.cos(x / 2)
-    const sx = Math.sin(x / 2)
-    const cy = Math.cos(y / 2)
-    const sy = Math.sin(y / 2)
-    const cz = Math.cos(z / 2)
-    const sz = Math.sin(z / 2)
-    return {
-      x: sx * cy * cz + cx * sy * sz,
-      y: cx * sy * cz - sx * cy * sz,
-      z: cx * cy * sz + sx * sy * cz,
-      w: cx * cy * cz - sx * sy * sz,
-    }
-  }
-
+  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 {
-    return {
-      x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
-      y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
-      z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
-      w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
-    }
-  }
-
+  abstract multiply(a: QuatHandle, b: QuatHandle): PluginApiReturn<QuatHandle>
   /**
-   * Compute the conjugate of a quaternion.
+   * Compute the conjugate of a quaternion (negated vector part).
    *
-   * For unit quaternions the conjugate equals the inverse.
-   *
-   * @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 {
-    return { x: -q.x, y: -q.y, z: -q.z, w: q.w }
-  }
-
+  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 {
-    return Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w)
-  }
-
+  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
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.new(0, 0, 1, 1)
+   * const unit = await snaptrude.core.math.quat.normalize(q)
+   * ```
    */
-  normalize(q: PQuat): PQuat {
-    const len = this.length(q)
-    if (len === 0) return { x: 0, y: 0, z: 0, w: 1 }
-    return { x: q.x / len, y: q.y / len, z: q.z / len, w: q.w / len }
-  }
-
+  abstract normalize(q: QuatHandle): PluginApiReturn<QuatHandle>
   /**
-   * Compute the inverse of a quaternion.
+   * Compute the inverse quaternion — the rotation that undoes `q`.
    *
-   * 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.fromEuler(0, Math.PI / 2, 0)
+   * const undo = await snaptrude.core.math.quat.inverse(q)
+   * ```
    */
-  inverse(q: PQuat): PQuat {
-    const lenSq = q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w
-    if (lenSq === 0) return { x: 0, y: 0, z: 0, w: 1 }
-    return { x: -q.x / lenSq, y: -q.y / lenSq, z: -q.z / lenSq, w: q.w / lenSq }
-  }
-
+  abstract inverse(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}
+   * Decompose a quaternion into its rotation axis and angle (radians).
    *
    * # 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 / 3, 0)
+   * const { axis, angle } = await snaptrude.core.math.quat.toAxisAngle(q)
+   * const { x, y, z } = await snaptrude.core.math.vec3.components(axis)
    * ```
    */
-  rotateVec3(q: PQuat, v: PVec3): PVec3 {
-    const vq: PQuat = { x: v.x, y: v.y, z: v.z, w: 0 }
-    const conj = this.conjugate(q)
-    const result = this.multiply(this.multiply(q, vq), conj)
-    return { x: result.x, y: result.y, z: result.z }
-  }
-
+  abstract toAxisAngle(q: QuatHandle): PluginApiReturn<{ axis: Vec3Handle; angle: number }>
   /**
-   * Convert a quaternion to axis-angle representation.
+   * Spherically interpolate (slerp) between two rotations by factor `t`.
    *
-   * @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 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)
+   * ```
    */
-  toAxisAngle(q: PQuat): { axis: PVec3; angle: number } {
-    const nq = this.normalize(q)
-    const angle = 2 * Math.acos(Math.min(1, Math.max(-1, nq.w)))
-    const s = Math.sin(angle / 2)
-    if (s < 1e-6) {
-      return { axis: { x: 1, y: 0, z: 0 }, angle: 0 }
-    }
-    return {
-      axis: { x: nq.x / s, y: nq.y / s, z: nq.z / s },
-      angle,
-    }
-  }
-
+  abstract slerp(a: QuatHandle, b: QuatHandle, t: number): PluginApiReturn<QuatHandle>
   /**
-   * Spherical linear interpolation between two quaternions.
-   *
-   * Produces smooth constant-speed rotation between {@linkcode a} and {@linkcode b}.
+   * Compute the dot product of two quaternions.
    *
-   * @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 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)
+   * ```
    */
-  slerp(a: PQuat, b: PQuat, t: number): PQuat {
-    let cosHalf = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w
-    let bx = b.x, by = b.y, bz = b.z, bw = b.w
-    if (cosHalf < 0) {
-      cosHalf = -cosHalf
-      bx = -bx; by = -by; bz = -bz; bw = -bw
-    }
-    if (cosHalf >= 1.0) {
-      return { x: a.x, y: a.y, z: a.z, w: a.w }
-    }
-    const halfAngle = Math.acos(cosHalf)
-    const sinHalf = Math.sin(halfAngle)
-    const ratioA = Math.sin((1 - t) * halfAngle) / sinHalf
-    const ratioB = Math.sin(t * halfAngle) / sinHalf
-    return {
-      x: a.x * ratioA + bx * ratioB,
-      y: a.y * ratioA + by * ratioB,
-      z: a.z * ratioA + bz * ratioB,
-      w: a.w * ratioA + bw * ratioB,
-    }
-  }
-
+  abstract dot(a: QuatHandle, b: QuatHandle): PluginApiReturn<number>
   /**
-   * 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.
+   * Test whether two quaternions have exactly equal components.
    *
-   * @param a - First quaternion
-   * @param b - Second quaternion
-   * @returns The scalar dot product
+   * # 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
+   * ```
    */
-  dot(a: PQuat, b: PQuat): number {
-    return a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w
-  }
-
+  abstract equals(a: QuatHandle, b: QuatHandle): PluginApiReturn<boolean>
   /**
-   * Check if two quaternions are exactly equal (strict equality per component).
-   *
-   * For floating-point comparisons, prefer {@linkcode PluginQuatApi.equalsApprox}.
+   * 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 {
-    return a.x === b.x && a.y === b.y && a.z === b.z && a.w === b.w
-  }
-
+  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 = 1e-6): boolean {
-    return (
-      Math.abs(a.x - b.x) < epsilon &&
-      Math.abs(a.y - b.y) < epsilon &&
-      Math.abs(a.z - b.z) < epsilon &&
-      Math.abs(a.w - b.w) < epsilon
-    )
-  }
+  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 const PQuat = z.object({
-  x: z.number(),
-  y: z.number(),
-  z: z.number(),
-  w: z.number(),
-})
-
-export type PQuat = z.infer<typeof PQuat>