@snaptrude/plugin-core 0.0.5 → 0.0.6

package/dist/index.cjs

@@ -57,7 +57,7 @@ __export(index_exports, {
   PluginSpaceCreateFromProfileResult: () => PluginSpaceCreateFromProfileResult,
   PluginSpaceCreateRectangularArgs: () => PluginSpaceCreateRectangularArgs,
   PluginSpaceCreateRectangularResult: () => PluginSpaceCreateRectangularResult,
-  PluginSpaceDeleteByIdArgs: () => PluginSpaceDeleteByIdArgs,
+  PluginSpaceDeleteArgs: () => PluginSpaceDeleteArgs,
   PluginSpaceGetAllResult: () => PluginSpaceGetAllResult,
   PluginSpaceGetArgs: () => PluginSpaceGetArgs,
   PluginSpaceGetProperty: () => PluginSpaceGetProperty,
@@ -87,27 +87,78 @@ var z = __toESM(require("zod"), 1);
 var PluginVec3Api = class {
   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, y, z12) {
     return { x, y, z: z12 };
   }
-  /** 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, b) {
     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, b) {
     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, scalar) {
     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, b) {
     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, b) {
     return {
       x: a.y * b.z - a.z * b.y,
@@ -115,25 +166,57 @@ var PluginVec3Api = class {
       z: a.x * b.y - a.y * b.x
     };
   }
-  /** 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) {
     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) {
     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) {
     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, b) {
     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, b, t) {
     return {
       x: a.x + (b.x - a.x) * t,
@@ -141,15 +224,35 @@ var PluginVec3Api = class {
       z: a.z + (b.z - a.z) * t
     };
   }
-  /** 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) {
     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, b) {
     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, b, epsilon = 1e-6) {
     return Math.abs(a.x - b.x) < epsilon && Math.abs(a.y - b.y) < epsilon && Math.abs(a.z - b.z) < epsilon;
   }
@@ -165,15 +268,43 @@ var z2 = __toESM(require("zod"), 1);
 var PluginQuatApi = class {
   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, y, z12, w) {
     return { x, y, z: z12, w };
   }
-  /** Create an identity quaternion (no rotation). */
+  /**
+   * Create an identity quaternion representing no rotation.
+   *
+   * @returns `{ x: 0, y: 0, z: 0, w: 1 }`
+   */
   identity() {
     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, angle) {
     const halfAngle = angle / 2;
     const s = Math.sin(halfAngle);
@@ -186,7 +317,14 @@ var PluginQuatApi = class {
       w: Math.cos(halfAngle)
     };
   }
-  /** 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, y, z12) {
     const cx = Math.cos(x / 2);
     const sx = Math.sin(x / 2);
@@ -201,7 +339,16 @@ var PluginQuatApi = class {
       w: cx * cy * cz - sx * sy * sz
     };
   }
-  /** 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, b) {
     return {
       x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
@@ -210,34 +357,83 @@ var PluginQuatApi = class {
       w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z
     };
   }
-  /** 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) {
     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) {
     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) {
     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) {
     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, v) {
     const vq = { 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 };
   }
-  /** 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) {
     const nq = this.normalize(q);
     const angle = 2 * Math.acos(Math.min(1, Math.max(-1, nq.w)));
@@ -250,7 +446,16 @@ var PluginQuatApi = class {
       angle
     };
   }
-  /** 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, b, t) {
     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;
@@ -275,15 +480,39 @@ var PluginQuatApi = class {
       w: a.w * ratioA + bw * ratioB
     };
   }
-  /** 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, b) {
     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, b) {
     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, b, epsilon = 1e-6) {
     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;
   }
@@ -306,7 +535,21 @@ var z3 = __toESM(require("zod"), 1);
 var PluginLineApi = class {
   constructor() {
   }
-  /** Create a new PLine from start and end points. */
+  /**
+   * Create a new line segment between two points.
+   *
+   * @param startPoint - The start point as a {@linkcode PVec3}
+   * @param endPoint - The end point as a {@linkcode PVec3}
+   * @returns A new {@linkcode PLine}
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * const { line } = snaptrude.core.geom
+   *
+   * const edge = line.new(vec3.new(0, 0, 0), vec3.new(5, 0, 0))
+   * ```
+   */
   new(startPoint, endPoint) {
     return { curveType: "Line", startPoint, endPoint };
   }
@@ -322,7 +565,34 @@ var z4 = __toESM(require("zod"), 1);
 var PluginArcApi = class {
   constructor() {
   }
-  /** Create a new PArc from start, end, centre and axis. */
+  /**
+   * Create a new arc from start, end, centre, and axis.
+   *
+   * The arc sweeps from {@linkcode startPoint} to {@linkcode endPoint}
+   * along the circle centred at {@linkcode centrePoint}, in the
+   * direction determined by the right-hand rule around {@linkcode axis}.
+   *
+   * @param startPoint - The start point as a {@linkcode PVec3}
+   * @param endPoint - The end point as a {@linkcode PVec3}
+   * @param centrePoint - The centre of the arc's circle as a {@linkcode PVec3}
+   * @param axis - The arc's rotation axis as a {@linkcode PVec3}
+   *   (perpendicular to the arc's plane)
+   * @returns A new {@linkcode PArc}
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * const { arc } = snaptrude.core.geom
+   *
+   * // Quarter-circle arc on the XZ plane
+   * const a = arc.new(
+   *   vec3.new(1, 0, 0),  // start
+   *   vec3.new(0, 0, 1),  // end
+   *   vec3.new(0, 0, 0),  // centre
+   *   vec3.new(0, 1, 0),  // Y-up axis
+   * )
+   * ```
+   */
   new(startPoint, endPoint, centrePoint, axis) {
     return { curveType: "Arc", startPoint, endPoint, centrePoint, axis };
   }
@@ -340,7 +610,15 @@ var z5 = __toESM(require("zod"), 1);
 var PluginCurveApi = class {
   constructor() {
   }
-  /** Create a PCurve from a PLine or PArc. */
+  /**
+   * Wrap a {@linkcode PLine} or {@linkcode PArc} as a {@linkcode PCurve}.
+   *
+   * This is an identity operation — it simply returns the input unchanged.
+   * It exists for type-level clarity when building mixed curve lists.
+   *
+   * @param curve - A {@linkcode PLine} or {@linkcode PArc} to wrap
+   * @returns The same value typed as {@linkcode PCurve}
+   */
   new(curve) {
     return curve;
   }
@@ -352,7 +630,15 @@ var z6 = __toESM(require("zod"), 1);
 var PluginProfileApi = class {
   constructor() {
   }
-  /** Create a new PProfile from an array of PCurves. */
+  /**
+   * Create a profile from an ordered list of curves.
+   *
+   * The curves should form a closed loop — the end point of each curve
+   * should coincide with the start point of the next.
+   *
+   * @param curves - An ordered array of {@linkcode PCurve}s forming a closed loop
+   * @returns A new {@linkcode PProfile}
+   */
   new(curves) {
     return { curves };
   }
@@ -432,7 +718,7 @@ var PluginSpaceGetResult = z7.object({
 var PluginSpaceGetAllResult = z7.object({
   spacesIds: z7.array(z7.string())
 });
-var PluginSpaceDeleteByIdArgs = z7.object({
+var PluginSpaceDeleteArgs = z7.object({
   spaceId: z7.string()
 });
 
@@ -595,7 +881,7 @@ var PluginApi = class {
   PluginSpaceCreateFromProfileResult,
   PluginSpaceCreateRectangularArgs,
   PluginSpaceCreateRectangularResult,
-  PluginSpaceDeleteByIdArgs,
+  PluginSpaceDeleteArgs,
   PluginSpaceGetAllResult,
   PluginSpaceGetArgs,
   PluginSpaceGetProperty,