@snaptrude/plugin-core 0.0.4 → 0.0.6

package/dist/api/core/geom/arc.d.ts

@@ -1,10 +1,59 @@
 import * as z from "zod";
 import { PVec3 } from "../math/vec3";
+/**
+ * Arc construction.
+ *
+ * A {@linkcode PArc} represents a circular arc in 3D space, defined by
+ * start/end points, a centre, and a rotation axis. Arcs can be wrapped
+ * as a {@linkcode PCurve} and combined into a {@linkcode PProfile}.
+ *
+ * Accessed via `snaptrude.core.geom.arc`.
+ */
 export declare abstract class PluginArcApi {
     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: PVec3, endPoint: PVec3, centrePoint: PVec3, axis: PVec3): PArc;
 }
+/**
+ * A circular arc defined by start, end, centre, and axis.
+ *
+ * Discriminated by `curveType: "Arc"` within the {@linkcode PCurve} union.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveType` | `"Arc"` | Discriminator tag |
+ * | `startPoint` | {@linkcode PVec3} | Start point of the arc |
+ * | `endPoint` | {@linkcode PVec3} | End point of the arc |
+ * | `centrePoint` | {@linkcode PVec3} | Centre of the arc's circle |
+ * | `axis` | {@linkcode PVec3} | Rotation axis (normal to the arc's plane) |
+ */
 export declare const PArc: z.ZodObject<{
     curveType: z.ZodLiteral<"Arc">;
     startPoint: z.ZodObject<{

package/dist/api/core/geom/arc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arc.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/arc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAEpC,8BAAsB,YAAY;;IAGhC,0DAA0D;IAC1D,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;CAG/E;AAED,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;iBAMf,CAAA;AAEF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA"}
+{"version":3,"file":"arc.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/arc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAEpC;;;;;;;;GAQG;AACH,8BAAsB,YAAY;;IAGhC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;CAG/E;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;iBAMf,CAAA;AAEF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA"}

package/dist/api/core/geom/curve.d.ts

@@ -1,11 +1,36 @@
 import * as z from "zod";
 import { PLine } from "./line";
 import { PArc } from "./arc";
+/**
+ * Unified curve wrapper — either a {@linkcode PLine} or a {@linkcode PArc}.
+ *
+ * Use this to build heterogeneous curve lists (mixing lines and arcs)
+ * when constructing a {@linkcode PProfile}.
+ *
+ * Accessed via `snaptrude.core.geom.curve`.
+ */
 export declare abstract class PluginCurveApi {
     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: PLine | PArc): PCurve;
 }
+/**
+ * A discriminated union of {@linkcode PLine} and {@linkcode PArc}.
+ *
+ * Discriminated on the `curveType` field:
+ * - `"Line"` → {@linkcode PLine}
+ * - `"Arc"` → {@linkcode PArc}
+ *
+ * Use `curve.curveType` to narrow the type in a switch or if-statement.
+ */
 export declare const PCurve: z.ZodDiscriminatedUnion<[z.ZodObject<{
     curveType: z.ZodLiteral<"Line">;
     startPoint: z.ZodObject<{

package/dist/api/core/geom/curve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"curve.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/curve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAE5B,8BAAsB,cAAc;;IAGlC,4CAA4C;IAC5C,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM;CAGjC;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAAmD,CAAA;AAEtE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAA"}
+{"version":3,"file":"curve.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/curve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAE5B;;;;;;;GAOG;AACH,8BAAsB,cAAc;;IAGlC;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM;CAGjC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAAmD,CAAA;AAEtE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAA"}

package/dist/api/core/geom/index.d.ts

@@ -2,10 +2,26 @@ import { PluginLineApi } from "./line";
 import { PluginArcApi } from "./arc";
 import { PluginCurveApi } from "./curve";
 import { PluginProfileApi } from "./profile";
+/**
+ * Geometry primitives for constructing 2D/3D shapes.
+ *
+ * Build geometry bottom-up: points ({@linkcode PVec3}) → lines/arcs → curves → profiles.
+ * Profiles can then be used with entity creation methods like
+ * {@linkcode PluginSpaceApi.createFromProfile}.
+ *
+ * - {@linkcode PluginGeomApi.line} — Line segment construction
+ * - {@linkcode PluginGeomApi.arc} — Arc construction
+ * - {@linkcode PluginGeomApi.curve} — Unified curve wrapper (line or arc)
+ * - {@linkcode PluginGeomApi.profile} — Closed loop of curves
+ */
 export declare abstract class PluginGeomApi {
+    /** Line segment construction. See {@linkcode PluginLineApi}. */
     abstract line: PluginLineApi;
+    /** Arc construction. See {@linkcode PluginArcApi}. */
     abstract arc: PluginArcApi;
+    /** Unified curve wrapper. See {@linkcode PluginCurveApi}. */
     abstract curve: PluginCurveApi;
+    /** Closed profile (loop of curves). See {@linkcode PluginProfileApi}. */
     abstract profile: PluginProfileApi;
     constructor();
 }

package/dist/api/core/geom/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE5C,8BAAsB,aAAa;IACjC,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,SAAgB,GAAG,EAAE,YAAY,CAAA;IACjC,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,SAAgB,OAAO,EAAE,gBAAgB,CAAA;;CAG1C;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,OAAO,CAAA;AACrB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE5C;;;;;;;;;;;GAWG;AACH,8BAAsB,aAAa;IACjC,gEAAgE;IAChE,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,sDAAsD;IACtD,SAAgB,GAAG,EAAE,YAAY,CAAA;IACjC,6DAA6D;IAC7D,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,yEAAyE;IACzE,SAAgB,OAAO,EAAE,gBAAgB,CAAA;;CAG1C;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,OAAO,CAAA;AACrB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA"}

package/dist/api/core/geom/line.d.ts

@@ -1,10 +1,44 @@
 import * as z from "zod";
 import { PVec3 } from "../math/vec3";
+/**
+ * Line segment construction.
+ *
+ * A {@linkcode PLine} is the simplest curve primitive — a straight
+ * segment between two 3D points. Lines can be wrapped as a
+ * {@linkcode PCurve} and combined into a {@linkcode PProfile}.
+ *
+ * Accessed via `snaptrude.core.geom.line`.
+ */
 export declare abstract class PluginLineApi {
     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: PVec3, endPoint: PVec3): PLine;
 }
+/**
+ * A line segment defined by a start and end point.
+ *
+ * Discriminated by `curveType: "Line"` within the {@linkcode PCurve} union.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveType` | `"Line"` | Discriminator tag |
+ * | `startPoint` | {@linkcode PVec3} | Start point of the segment |
+ * | `endPoint` | {@linkcode PVec3} | End point of the segment |
+ */
 export declare const PLine: z.ZodObject<{
     curveType: z.ZodLiteral<"Line">;
     startPoint: z.ZodObject<{

package/dist/api/core/geom/line.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"line.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/line.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAEpC,8BAAsB,aAAa;;IAGjC,oDAAoD;IACpD,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,KAAK;CAG/C;AAED,eAAO,MAAM,KAAK;;;;;;;;;;;;iBAIhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA"}
+{"version":3,"file":"line.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/line.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAEpC;;;;;;;;GAQG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,KAAK;CAG/C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;iBAIhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA"}

package/dist/api/core/geom/profile.d.ts

@@ -1,13 +1,67 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../../types";
 import { PCurve } from "./curve";
+/**
+ * Profile construction — a closed loop of {@linkcode PCurve}s.
+ *
+ * Profiles are the primary 2D shape primitive used for creating
+ * extruded entities like spaces. Build profiles either from an
+ * explicit list of curves or from a list of points (auto-connected
+ * with line segments).
+ *
+ * Accessed via `snaptrude.core.geom.profile`.
+ */
 export declare abstract class PluginProfileApi {
     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: PCurve[]): PProfile;
-    /** Create a PProfile from an array of points, connecting them with lines. */
+    /**
+     * Create a profile by connecting a list of points with line segments.
+     *
+     * The points are connected in order, with the last point automatically
+     * connected back to the first to close the loop.
+     *
+     * This is a **host API call** — it returns a `Promise`.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginProfileFromLinePointsArgs.points args.points} — An ordered
+     *     array of {@linkcode PVec3} forming the profile vertices
+     * @returns A {@linkcode PProfile} with line-segment curves connecting the points
+     *
+     * # Example
+     * ```ts
+     * const { vec3 } = snaptrude.core.math
+     *
+     * // Create an L-shaped profile
+     * const profile = await snaptrude.core.geom.profile.fromLinePoints({
+     *   points: [
+     *     vec3.new(0, 0, 0),
+     *     vec3.new(10, 0, 0),
+     *     vec3.new(10, 0, 5),
+     *     vec3.new(5, 0, 5),
+     *     vec3.new(5, 0, 10),
+     *     vec3.new(0, 0, 10),
+     *   ],
+     * })
+     * ```
+     */
     abstract fromLinePoints(args: PluginProfileFromLinePointsArgs): PluginApiReturn<PProfile>;
 }
+/**
+ * Arguments for {@linkcode PluginProfileApi.fromLinePoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `points` | {@linkcode PVec3}`[]` | Ordered vertices of the profile |
+ */
 export declare const PluginProfileFromLinePointsArgs: z.ZodObject<{
     points: z.ZodArray<z.ZodObject<{
         x: z.ZodNumber;
@@ -16,6 +70,16 @@ export declare const PluginProfileFromLinePointsArgs: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginProfileFromLinePointsArgs = z.infer<typeof PluginProfileFromLinePointsArgs>;
+/**
+ * A closed profile composed of an ordered list of curves.
+ *
+ * Profiles are used as input to entity creation methods like
+ * {@linkcode PluginSpaceApi.createFromProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curves` | {@linkcode PCurve}`[]` | Ordered curves forming a closed loop |
+ */
 export declare const PProfile: z.ZodObject<{
     curves: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         curveType: z.ZodLiteral<"Line">;

package/dist/api/core/geom/profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEhC,8BAAsB,gBAAgB;;IAGpC,sDAAsD;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ;IAI/B,6EAA6E;aAC7D,cAAc,CAC5B,IAAI,EAAE,+BAA+B,GACpC,eAAe,CAAC,QAAQ,CAAC;CAC7B;AAED,eAAO,MAAM,+BAA+B;;;;;;iBAE1C,CAAA;AAEF,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA;AAE7F,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEnB,CAAA;AAEF,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA"}
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../../src/api/core/geom/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEhC;;;;;;;;;GASG;AACH,8BAAsB,gBAAgB;;IAGpC;;;;;;;;OAQG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ;IAI/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;aACa,cAAc,CAC5B,IAAI,EAAE,+BAA+B,GACpC,eAAe,CAAC,QAAQ,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B;;;;;;iBAE1C,CAAA;AAEF,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA;AAE7F;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEnB,CAAA;AAEF,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA"}

package/dist/api/core/index.d.ts

@@ -1,7 +1,15 @@
 import { PluginMathApi } from "./math";
 import { PluginGeomApi } from "./geom";
+/**
+ * Core primitives used across the plugin API.
+ *
+ * - {@linkcode PluginCoreApi.math} — Vector and quaternion operations
+ * - {@linkcode PluginCoreApi.geom} — Geometry primitives (lines, arcs, curves, profiles)
+ */
 export declare abstract class PluginCoreApi {
+    /** Vector and quaternion math utilities. See {@linkcode PluginMathApi}. */
     abstract math: PluginMathApi;
+    /** Geometry primitives and constructors. See {@linkcode PluginGeomApi}. */
     abstract geom: PluginGeomApi;
     constructor();
 }

package/dist/api/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC,8BAAsB,aAAa;IACjC,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,SAAgB,IAAI,EAAE,aAAa,CAAA;;CAGpC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC;;;;;GAKG;AACH,8BAAsB,aAAa;IACjC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;;CAGpC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA"}

package/dist/api/core/math/index.d.ts

@@ -1,7 +1,15 @@
 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 declare abstract class PluginMathApi {
+    /** 3D vector operations. See {@linkcode PluginVec3Api}. */
     abstract vec3: PluginVec3Api;
+    /** Quaternion operations. See {@linkcode PluginQuatApi}. */
     abstract quat: PluginQuatApi;
     constructor();
 }

package/dist/api/core/math/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC,8BAAsB,aAAa;IACjC,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,SAAgB,IAAI,EAAE,aAAa,CAAA;;CAGpC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC;;;;;GAKG;AACH,8BAAsB,aAAa;IACjC,2DAA2D;IAC3D,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,4DAA4D;IAC5D,SAAgB,IAAI,EAAE,aAAa,CAAA;;CAGpC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA"}

package/dist/api/core/math/quat.d.ts

@@ -1,41 +1,182 @@
 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 declare 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;
-    /** Create an identity quaternion (no rotation). */
+    /**
+     * Create an identity quaternion representing no rotation.
+     *
+     * @returns `{ x: 0, y: 0, z: 0, w: 1 }`
+     */
     identity(): PQuat;
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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;
     };
-    /** 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;
-    /** 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;
-    /** 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;
-    /** 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): boolean;
 }
+/**
+ * A quaternion with `x`, `y`, `z`, and `w` components.
+ *
+ * Used for representing 3D rotations without gimbal lock.
+ * Equivalent to `BABYLON.Quaternion`.
+ */
 export declare const PQuat: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;

package/dist/api/core/math/quat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quat.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/quat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEnC,8BAAsB,aAAa;;IAGjC,0BAA0B;IAC1B,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAItD,mDAAmD;IACnD,QAAQ,IAAI,KAAK;IAIjB,4DAA4D;IAC5D,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK;IAahD,kEAAkE;IAClE,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAejD,wCAAwC;IACxC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IASnC,iCAAiC;IACjC,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAI1B,0CAA0C;IAC1C,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM;IAIxB,8EAA8E;IAC9E,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAM1B,2DAA2D;IAC3D,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAMxB,uCAAuC;IACvC,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IAOrC,yDAAyD;IACzD,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAarD,8DAA8D;IAC9D,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAsB3C,sCAAsC;IACtC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM;IAI/B,kDAAkD;IAClD,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO;IAInC,0EAA0E;IAC1E,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO;CAQlE;AAED,eAAO,MAAM,KAAK;;;;;iBAKhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA"}
+{"version":3,"file":"quat.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/quat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEnC;;;;;;;;GAQG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAItD;;;;OAIG;IACH,QAAQ,IAAI,KAAK;IAIjB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK;IAahD;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAejD;;;;;;;;;OASG;IACH,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IASnC;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAI1B;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM;IAIxB;;;;;OAKG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAM1B;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAMxB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK;IAOrC;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAarD;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAsB3C;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM;IAI/B;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO;IAInC;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO;CAQlE;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;iBAKhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA"}