@snaptrude/plugin-core 0.3.0 → 0.5.0

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

@@ -1,214 +1,179 @@
-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 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 {
-    return { x, y, z }
-  }
-
+  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 {
-    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }
-  }
-
+  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 {
-    return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }
-  }
-
+  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 {
-    return { x: v.x * scalar, y: v.y * scalar, z: v.z * scalar }
-  }
-
+  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 {
-    return a.x * b.x + a.y * b.y + a.z * b.z
-  }
-
+  abstract dot(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
   /**
-   * Compute the cross product of two vectors.
+   * Compute the cross product `a × b` — the vector perpendicular to both.
    *
-   * 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.
-   *
-   * @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 {
-    return {
-      x: a.y * b.z - a.z * b.y,
-      y: a.z * b.x - a.x * b.z,
-      z: a.x * b.y - a.y * b.x,
-    }
-  }
-
+  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 {
-    return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z)
-  }
-
+  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 {
-    return v.x * v.x + v.y * v.y + v.z * v.z
-  }
-
+  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 {
-    const len = this.length(v)
-    if (len === 0) return { x: 0, y: 0, z: 0 }
-    return { x: v.x / len, y: v.y / len, z: v.z / len }
-  }
-
+  abstract normalize(v: Vec3Handle): PluginApiReturn<Vec3Handle>
   /**
-   * Compute the Euclidean distance between two points.
+   * Measure the straight-line (Euclidean) distance between two points.
+   *
+   * @examplePrompt What is the distance between these two points?
+   * @examplePrompt Measure how far apart these two points are
    *
-   * @param a - First point
-   * @param b - Second point
-   * @returns The distance `|a - b|`
+   * # 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 {
-    return this.length(this.subtract(a, b))
-  }
-
+  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 {
-    return {
-      x: a.x + (b.x - a.x) * t,
-      y: a.y + (b.y - a.y) * t,
-      z: a.z + (b.z - a.z) * t,
-    }
-  }
-
+  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 {
-    return { x: -v.x, y: -v.y, z: -v.z }
-  }
-
+  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 {
-    return a.x === b.x && a.y === b.y && a.z === b.z
-  }
-
+  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 = 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
-    )
-  }
+  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 const PVec3 = z.object({
-  x: z.number(),
-  y: z.number(),
-  z: z.number(),
-})
-
-export type PVec3 = z.infer<typeof PVec3>