@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,20 +1,20 @@
-import { PluginVec3Api } from "./vec3"
-import { PluginQuatApi } from "./quat"
-
-/**
- * Math primitives for 3D vector and quaternion operations.
- *
- * - {@linkcode PluginMathApi.vec3} — 3D vector creation and arithmetic
- * - {@linkcode PluginMathApi.quat} — Quaternion creation and rotation operations
- */
-export abstract class PluginMathApi {
-  /** 3D vector operations. See {@linkcode PluginVec3Api}. */
-  public abstract vec3: PluginVec3Api
-  /** Quaternion operations. See {@linkcode PluginQuatApi}. */
-  public abstract quat: PluginQuatApi
-
-  constructor() {}
-}
-
-export * from "./vec3"
-export * from "./quat"
+import { PluginVec3Api } from "./vec3"
+import { PluginQuatApi } from "./quat"
+
+/**
+ * Math primitives for 3D vector and quaternion operations.
+ *
+ * - {@linkcode PluginMathApi.vec3} — 3D vector creation and arithmetic
+ * - {@linkcode PluginMathApi.quat} — Quaternion creation and rotation operations
+ */
+export abstract class PluginMathApi {
+  /** 3D vector operations. See {@linkcode PluginVec3Api}. */
+  public abstract vec3: PluginVec3Api
+  /** Quaternion operations. See {@linkcode PluginQuatApi}. */
+  public abstract quat: PluginQuatApi
+
+  constructor() {}
+}
+
+export * from "./vec3"
+export * from "./quat"

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

@@ -1,172 +1,172 @@
-import { PluginApiReturn } from "../../../types"
-import { Vec3Handle, QuatHandle, QuatComponents } from "../../../handles"
-
-/**
- * Quaternion operations (all-handle model, §11).
- *
- * 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 quaternion from primitive components.
-   *
-   * # 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)
-   * ```
-   */
-  abstract new(x: number, y: number, z: number, w: number): PluginApiReturn<QuatHandle>
-  /**
-   * Return the identity quaternion (no rotation).
-   *
-   * # Example
-   * ```ts
-   * const noRotation = await snaptrude.core.math.quat.identity()
-   * ```
-   */
-  abstract identity(): PluginApiReturn<QuatHandle>
-  /**
-   * Build a quaternion from a rotation axis and an angle in radians.
-   *
-   * # Example
-   * ```ts
-   * const axis = await snaptrude.core.math.vec3.new(0, 0, 1)
-   * const quarterTurn = await snaptrude.core.math.quat.fromAxisAngle(axis, Math.PI / 2)
-   * ```
-   */
-  abstract fromAxisAngle(axis: Vec3Handle, angle: number): PluginApiReturn<QuatHandle>
-  /**
-   * Build a quaternion from Euler angles in radians.
-   *
-   * # Example
-   * ```ts
-   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
-   * ```
-   */
-  abstract fromEuler(x: number, y: number, z: number): PluginApiReturn<QuatHandle>
-  /**
-   * Compose two rotations with the Hamilton product `a * b` (apply `b` then `a`).
-   *
-   * # 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
-   * ```
-   */
-  abstract multiply(a: QuatHandle, b: QuatHandle): PluginApiReturn<QuatHandle>
-  /**
-   * Compute the conjugate of a quaternion (negated vector part).
-   *
-   * # Example
-   * ```ts
-   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 4, 0)
-   * const conj = await snaptrude.core.math.quat.conjugate(q)
-   * ```
-   */
-  abstract conjugate(q: QuatHandle): PluginApiReturn<QuatHandle>
-  /**
-   * Compute the magnitude (norm) of a quaternion.
-   *
-   * # Example
-   * ```ts
-   * const q = await snaptrude.core.math.quat.new(0, 0, 0, 1)
-   * const len = await snaptrude.core.math.quat.length(q) // 1
-   * ```
-   */
-  abstract length(q: QuatHandle): PluginApiReturn<number>
-  /**
-   * Normalize a quaternion to unit length.
-   *
-   * # Example
-   * ```ts
-   * const q = await snaptrude.core.math.quat.new(0, 0, 1, 1)
-   * const unit = await snaptrude.core.math.quat.normalize(q)
-   * ```
-   */
-  abstract normalize(q: QuatHandle): PluginApiReturn<QuatHandle>
-  /**
-   * Compute the inverse quaternion — the rotation that undoes `q`.
-   *
-   * # Example
-   * ```ts
-   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
-   * const undo = await snaptrude.core.math.quat.inverse(q)
-   * ```
-   */
-  abstract inverse(q: QuatHandle): PluginApiReturn<QuatHandle>
-  /**
-   * Decompose a quaternion into its rotation axis and angle (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)
-   * ```
-   */
-  abstract toAxisAngle(q: QuatHandle): PluginApiReturn<{ axis: Vec3Handle; angle: number }>
-  /**
-   * Spherically interpolate (slerp) between two rotations by factor `t`.
-   *
-   * # 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)
-   * ```
-   */
-  abstract slerp(a: QuatHandle, b: QuatHandle, t: number): PluginApiReturn<QuatHandle>
-  /**
-   * Compute the dot product of two quaternions.
-   *
-   * # 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)
-   * ```
-   */
-  abstract dot(a: QuatHandle, b: QuatHandle): PluginApiReturn<number>
-  /**
-   * Test whether two quaternions have exactly equal components.
-   *
-   * # 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`).
-   *
-   * # 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
-   * ```
-   */
-  abstract equalsApprox(
-    a: QuatHandle,
-    b: QuatHandle,
-    epsilon?: number,
-  ): PluginApiReturn<boolean>
-  /**
-   * Read the primitive `{ x, y, z, w }` components of a quaternion handle.
-   *
-   * # 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)
-   * ```
-   */
-  abstract components(q: QuatHandle): PluginApiReturn<QuatComponents>
-}
+import { PluginApiReturn } from "../../../types"
+import { Vec3Handle, QuatHandle, QuatComponents } from "../../../handles"
+
+/**
+ * Quaternion operations (all-handle model, §11).
+ *
+ * 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 quaternion from primitive components.
+   *
+   * # 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)
+   * ```
+   */
+  abstract new(x: number, y: number, z: number, w: number): PluginApiReturn<QuatHandle>
+  /**
+   * Return the identity quaternion (no rotation).
+   *
+   * # Example
+   * ```ts
+   * const noRotation = await snaptrude.core.math.quat.identity()
+   * ```
+   */
+  abstract identity(): PluginApiReturn<QuatHandle>
+  /**
+   * Build a quaternion from a rotation axis and an angle in radians.
+   *
+   * # Example
+   * ```ts
+   * const axis = await snaptrude.core.math.vec3.new(0, 0, 1)
+   * const quarterTurn = await snaptrude.core.math.quat.fromAxisAngle(axis, Math.PI / 2)
+   * ```
+   */
+  abstract fromAxisAngle(axis: Vec3Handle, angle: number): PluginApiReturn<QuatHandle>
+  /**
+   * Build a quaternion from Euler angles in radians.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * ```
+   */
+  abstract fromEuler(x: number, y: number, z: number): PluginApiReturn<QuatHandle>
+  /**
+   * Compose two rotations with the Hamilton product `a * b` (apply `b` then `a`).
+   *
+   * # 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
+   * ```
+   */
+  abstract multiply(a: QuatHandle, b: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the conjugate of a quaternion (negated vector part).
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 4, 0)
+   * const conj = await snaptrude.core.math.quat.conjugate(q)
+   * ```
+   */
+  abstract conjugate(q: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the magnitude (norm) of a quaternion.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+   * const len = await snaptrude.core.math.quat.length(q) // 1
+   * ```
+   */
+  abstract length(q: QuatHandle): PluginApiReturn<number>
+  /**
+   * Normalize a quaternion to unit length.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.new(0, 0, 1, 1)
+   * const unit = await snaptrude.core.math.quat.normalize(q)
+   * ```
+   */
+  abstract normalize(q: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the inverse quaternion — the rotation that undoes `q`.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * const undo = await snaptrude.core.math.quat.inverse(q)
+   * ```
+   */
+  abstract inverse(q: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Decompose a quaternion into its rotation axis and angle (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)
+   * ```
+   */
+  abstract toAxisAngle(q: QuatHandle): PluginApiReturn<{ axis: Vec3Handle; angle: number }>
+  /**
+   * Spherically interpolate (slerp) between two rotations by factor `t`.
+   *
+   * # 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)
+   * ```
+   */
+  abstract slerp(a: QuatHandle, b: QuatHandle, t: number): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the dot product of two quaternions.
+   *
+   * # 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)
+   * ```
+   */
+  abstract dot(a: QuatHandle, b: QuatHandle): PluginApiReturn<number>
+  /**
+   * Test whether two quaternions have exactly equal components.
+   *
+   * # 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`).
+   *
+   * # 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
+   * ```
+   */
+  abstract equalsApprox(
+    a: QuatHandle,
+    b: QuatHandle,
+    epsilon?: number,
+  ): PluginApiReturn<boolean>
+  /**
+   * Read the primitive `{ x, y, z, w }` components of a quaternion handle.
+   *
+   * # 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)
+   * ```
+   */
+  abstract components(q: QuatHandle): PluginApiReturn<QuatComponents>
+}