@snaptrude/plugin-core 0.0.5 → 0.0.6

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

@@ -1,20 +1,57 @@
 import * as z from "zod"
 import type { PVec3 } from "./vec3"
 
+/**
+ * Quaternion operations for 3D rotations.
+ *
+ * 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`.
+ */
 export abstract class PluginQuatApi {
   constructor() {}
 
-  /** Create a new PQuat. */
+  /**
+   * Create a new quaternion from raw components.
+   *
+   * For most use cases prefer {@linkcode PluginQuatApi.fromAxisAngle}
+   * or {@linkcode PluginQuatApi.fromEuler} instead.
+   *
+   * @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}
+   */
   new(x: number, y: number, z: number, w: number): PQuat {
     return { x, y, z, w }
   }
 
-  /** Create an identity quaternion (no rotation). */
+  /**
+   * Create an identity quaternion representing no rotation.
+   *
+   * @returns `{ x: 0, y: 0, z: 0, w: 1 }`
+   */
   identity(): PQuat {
     return { x: 0, y: 0, z: 0, w: 1 }
   }
 
-  /** Create a quaternion from an axis and angle (radians). */
+  /**
+   * 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
+   *
+   * # 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)
+   * ```
+   */
   fromAxisAngle(axis: PVec3, angle: number): PQuat {
     const halfAngle = angle / 2
     const s = Math.sin(halfAngle)
@@ -28,7 +65,14 @@ export abstract class PluginQuatApi {
     }
   }
 
-  /** Create a quaternion from Euler angles (radians, XYZ order). */
+  /**
+   * Create a quaternion from Euler angles in **XYZ** rotation order.
+   *
+   * @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}
+   */
   fromEuler(x: number, y: number, z: number): PQuat {
     const cx = Math.cos(x / 2)
     const sx = Math.sin(x / 2)
@@ -44,7 +88,16 @@ export abstract class PluginQuatApi {
     }
   }
 
-  /** Multiply two quaternions (a * b). */
+  /**
+   * Multiply two quaternions, combining their rotations.
+   *
+   * 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
+   */
   multiply(a: PQuat, b: PQuat): PQuat {
     return {
       x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
@@ -54,31 +107,72 @@ export abstract class PluginQuatApi {
     }
   }
 
-  /** Conjugate of a quaternion. */
+  /**
+   * Compute the conjugate of a quaternion.
+   *
+   * 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)`
+   */
   conjugate(q: PQuat): PQuat {
     return { x: -q.x, y: -q.y, z: -q.z, w: q.w }
   }
 
-  /** Length (magnitude) of a quaternion. */
+  /**
+   * Compute the length (magnitude) of a quaternion.
+   *
+   * @param q - The quaternion
+   * @returns The magnitude `√(x² + y² + z² + w²)`
+   */
   length(q: PQuat): number {
     return Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w)
   }
 
-  /** Normalize a quaternion to unit length. Returns identity if length is 0. */
+  /**
+   * 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 {
     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 }
   }
 
-  /** Inverse of a quaternion (conjugate / lengthSquared). */
+  /**
+   * 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
+   */
   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 }
   }
 
-  /** Rotate a vector by a quaternion. */
+  /**
+   * 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}
+   *
+   * # 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 }
+   * ```
+   */
   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)
@@ -86,7 +180,15 @@ export abstract class PluginQuatApi {
     return { x: result.x, y: result.y, z: result.z }
   }
 
-  /** Convert a quaternion to axis-angle representation. */
+  /**
+   * Convert a quaternion to axis-angle representation.
+   *
+   * @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**
+   */
   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)))
@@ -100,7 +202,16 @@ export abstract class PluginQuatApi {
     }
   }
 
-  /** Spherical linear interpolation between two quaternions. */
+  /**
+   * Spherical linear interpolation between two quaternions.
+   *
+   * Produces smooth constant-speed rotation between {@linkcode a} and {@linkcode b}.
+   *
+   * @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}
+   */
   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
@@ -123,17 +234,41 @@ export abstract class PluginQuatApi {
     }
   }
 
-  /** Dot product of two quaternions. */
+  /**
+   * 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
+   */
   dot(a: PQuat, b: PQuat): number {
     return a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w
   }
 
-  /** Check if two quaternions are equal (exact). */
+  /**
+   * Check if two quaternions are exactly equal (strict equality per component).
+   *
+   * For floating-point comparisons, prefer {@linkcode PluginQuatApi.equalsApprox}.
+   *
+   * @param a - First quaternion
+   * @param b - Second quaternion
+   * @returns `true` if all components match exactly
+   */
   equals(a: PQuat, b: PQuat): boolean {
     return a.x === b.x && a.y === b.y && a.z === b.z && a.w === b.w
   }
 
-  /** Check if two quaternions are approximately equal within an epsilon. */
+  /**
+   * Check if two quaternions are approximately equal within a tolerance.
+   *
+   * @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
+   */
   equalsApprox(a: PQuat, b: PQuat, epsilon: number = 1e-6): boolean {
     return (
       Math.abs(a.x - b.x) < epsilon &&
@@ -144,6 +279,12 @@ export abstract class PluginQuatApi {
   }
 }
 
+/**
+ * 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(),

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

@@ -1,34 +1,93 @@
 import * as z from "zod"
 
+/**
+ * 3D vector operations for positions, directions, and displacements.
+ *
+ * All methods are **pure** — they return new {@linkcode PVec3} values
+ * without mutating the inputs.
+ *
+ * Accessed via `snaptrude.core.math.vec3`.
+ */
 export abstract class PluginVec3Api {
   constructor() {}
 
-  /** Create a new PVec3. */
+  /**
+   * 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}
+   *
+   * # Example
+   * ```ts
+   * const position = snaptrude.core.math.vec3.new(1, 2, 3)
+   * // { x: 1, y: 2, z: 3 }
+   * ```
+   */
   new(x: number, y: number, z: number): PVec3 {
     return { x, y, z }
   }
 
-  /** Add two vectors. */
+  /**
+   * Add two vectors component-wise.
+   *
+   * @param a - First vector
+   * @param b - Second vector
+   * @returns A new {@linkcode PVec3} where each component is `a[i] + b[i]`
+   */
   add(a: PVec3, b: PVec3): PVec3 {
     return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }
   }
 
-  /** Subtract b from a. */
+  /**
+   * Subtract vector {@linkcode b} from vector {@linkcode a} component-wise.
+   *
+   * @param a - Vector to subtract from
+   * @param b - Vector to subtract
+   * @returns A new {@linkcode PVec3} where each component is `a[i] - b[i]`
+   */
   subtract(a: PVec3, b: PVec3): PVec3 {
     return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }
   }
 
-  /** Scale a vector by a scalar. */
+  /**
+   * Scale a vector by a scalar value.
+   *
+   * @param v - The vector to scale
+   * @param scalar - The scalar multiplier
+   * @returns A new {@linkcode PVec3} where each component is `v[i] * scalar`
+   */
   scale(v: PVec3, scalar: number): PVec3 {
     return { x: v.x * scalar, y: v.y * scalar, z: v.z * scalar }
   }
 
-  /** Dot product of two vectors. */
+  /**
+   * 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
+   */
   dot(a: PVec3, b: PVec3): number {
     return a.x * b.x + a.y * b.y + a.z * b.z
   }
 
-  /** Cross product of two vectors. */
+  /**
+   * 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.
+   *
+   * @param a - First vector
+   * @param b - Second vector
+   * @returns A new {@linkcode PVec3} perpendicular to both {@linkcode a} and {@linkcode b}
+   */
   cross(a: PVec3, b: PVec3): PVec3 {
     return {
       x: a.y * b.z - a.z * b.y,
@@ -37,29 +96,61 @@ export abstract class PluginVec3Api {
     }
   }
 
-  /** Length (magnitude) of a vector. */
+  /**
+   * Compute the length (magnitude) of a vector.
+   *
+   * @param v - The vector
+   * @returns The Euclidean length `√(x² + y² + z²)`
+   */
   length(v: PVec3): number {
     return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z)
   }
 
-  /** Squared length of a vector (avoids sqrt). */
+  /**
+   * Compute the squared length of a vector.
+   *
+   * Avoids the `sqrt` call — prefer this over {@linkcode PluginVec3Api.length}
+   * when comparing relative magnitudes.
+   *
+   * @param v - The vector
+   * @returns The squared length `x² + y² + z²`
+   */
   lengthSquared(v: PVec3): number {
     return v.x * v.x + v.y * v.y + v.z * v.z
   }
 
-  /** Normalize a vector to unit length. Returns zero vector if length is 0. */
+  /**
+   * Normalize a vector to unit length.
+   *
+   * @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
+   */
   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 }
   }
 
-  /** Distance between two points. */
+  /**
+   * Compute the Euclidean distance between two points.
+   *
+   * @param a - First point
+   * @param b - Second point
+   * @returns The distance `|a - b|`
+   */
   distance(a: PVec3, b: PVec3): number {
     return this.length(this.subtract(a, b))
   }
 
-  /** Linearly interpolate between two vectors. */
+  /**
+   * Linearly interpolate between two vectors.
+   *
+   * @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`
+   */
   lerp(a: PVec3, b: PVec3, t: number): PVec3 {
     return {
       x: a.x + (b.x - a.x) * t,
@@ -68,17 +159,37 @@ export abstract class PluginVec3Api {
     }
   }
 
-  /** Negate a vector. */
+  /**
+   * Negate a vector (reverse its direction).
+   *
+   * @param v - The vector to negate
+   * @returns A new {@linkcode PVec3} with all components negated
+   */
   negate(v: PVec3): PVec3 {
     return { x: -v.x, y: -v.y, z: -v.z }
   }
 
-  /** Check if two vectors are equal (exact). */
+  /**
+   * Check if two vectors are exactly equal (strict equality per component).
+   *
+   * For floating-point comparisons, prefer {@linkcode PluginVec3Api.equalsApprox}.
+   *
+   * @param a - First vector
+   * @param b - Second vector
+   * @returns `true` if all components match exactly
+   */
   equals(a: PVec3, b: PVec3): boolean {
     return a.x === b.x && a.y === b.y && a.z === b.z
   }
 
-  /** Check if two vectors are approximately equal within an epsilon. */
+  /**
+   * Check if two vectors are approximately equal within a tolerance.
+   *
+   * @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
+   */
   equalsApprox(a: PVec3, b: PVec3, epsilon: number = 1e-6): boolean {
     return (
       Math.abs(a.x - b.x) < epsilon &&
@@ -88,6 +199,12 @@ export abstract class PluginVec3Api {
   }
 }
 
+/**
+ * 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(),

package/src/api/entity/index.ts

@@ -1,8 +1,16 @@
 import { PluginSpaceApi } from "./space"
 import { PluginStoryApi } from "./story"
 
+/**
+ * CRUD operations on Snaptrude building entities.
+ *
+ * - {@linkcode PluginEntityApi.space} — Create, query, and delete spaces (rooms/masses)
+ * - {@linkcode PluginEntityApi.story} — Create, query, and update stories (floors)
+ */
 export abstract class PluginEntityApi {
+  /** Space (room/mass) operations. See {@linkcode PluginSpaceApi}. */
   public abstract space: PluginSpaceApi
+  /** Story (floor/storey) operations. See {@linkcode PluginStoryApi}. */
   public abstract story: PluginStoryApi
 
   constructor() {}