@snaptrude/plugin-core 0.0.0-dev-20260708130115

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

@@ -0,0 +1,402 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Layers — read and toggle the drawing/reference layers of a storey.
+ *
+ * These are the **drawing/reference** layers shown in the storey's Layers panel —
+ * the surfaces you sketch on and the imported underlays (CAD, PDF, images,
+ * terrain). They are **not** wall/floor construction-assembly material layers,
+ * which are a property of the built element, not this namespace.
+ *
+ * Reads return plain records and never throw for a missing layer (`get` and
+ * `getActive` return `null`, `list` returns `[]`).
+ *
+ * v1 exposes reads plus visibility edits and the active-layer switch.
+ * Creating and deleting layers are intentionally not part of this contract yet.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.layers`.
+ */
+export declare abstract class PluginCoreLayersApi {
+    constructor();
+    /**
+     * List the drawing layers of a storey.
+     *
+     * Optionally filter to a single {@linkcode PluginCoreLayerType}.
+     *
+     * @param storeyId - The storey whose layers to read.
+     * @param layerType - Optional {@linkcode PluginCoreLayerType} filter.
+     * @returns A {@linkcode PluginCoreLayersListResult} with a `layers` array
+     *   (empty when the storey is missing or has no matching layers).
+     *
+     * @examplePrompt List the drawing layers on this storey
+     * @examplePrompt Show all the PDF underlays on storey st_2
+     * @examplePrompt What CAD layers are on the ground floor?
+     *
+     * # Example
+     * ```ts
+     * const { layers } = await snaptrude.core.layers.list("st_2")
+     * for (const l of layers) console.log(l.name, l.layerType, l.hidden)
+     * ```
+     */
+    abstract list(storeyId: string, layerType?: PluginCoreLayerType): PluginApiReturn<PluginCoreLayersListResult>;
+    /**
+     * Get a single drawing layer by id.
+     *
+     * @param layerId - The id of the layer to read.
+     * @returns The matching {@linkcode PluginCoreLayer}, or `null` if no layer has
+     *   that id.
+     *
+     * @examplePrompt Get the drawing layer with id ly_5
+     * @examplePrompt Is layer ly_5 hidden or locked?
+     * @examplePrompt Look up a single drawing layer by its id
+     *
+     * # Example
+     * ```ts
+     * const layer = await snaptrude.core.layers.get("ly_5")
+     * if (layer) console.log(layer.name, layer.hidden, layer.locked)
+     * ```
+     */
+    abstract get(layerId: string): PluginApiReturn<PluginCoreLayersGetResult>;
+    /**
+     * Get the active drawing layer of a storey.
+     *
+     * The active layer is the one new sketch geometry is drawn onto. Paired with
+     * {@linkcode PluginCoreLayersApi.setActive}.
+     *
+     * @param storeyId - The storey whose active layer to read.
+     * @returns The active {@linkcode PluginCoreLayer}, or `null` if the storey is
+     *   missing or has no active layer.
+     *
+     * @examplePrompt Which drawing layer is active on this storey?
+     * @examplePrompt Get the current layer on storey st_2
+     * @examplePrompt What layer am I drawing on?
+     *
+     * # Example
+     * ```ts
+     * const active = await snaptrude.core.layers.getActive("st_2")
+     * if (active) console.log(active.name)
+     * ```
+     */
+    abstract getActive(storeyId: string): PluginApiReturn<PluginCoreLayersGetActiveResult>;
+    /**
+     * Make a drawing layer the active layer of its storey.
+     *
+     * Paired with {@linkcode PluginCoreLayersApi.getActive}.
+     *
+     * @param layerId - The id of the layer to activate.
+     * @returns The id of the now-active layer.
+     * @throws If no layer has the given id.
+     *
+     * @examplePrompt Draw on layer ly_5
+     * @examplePrompt Make this the active layer
+     * @examplePrompt Switch the active layer to the CAD underlay
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.layers.setActive("ly_5")
+     * ```
+     */
+    abstract setActive(layerId: string): PluginApiReturn<PluginCoreLayersSetActiveResult>;
+    /**
+     * Update a drawing layer's visibility.
+     *
+     * A **sparse** update: omit `hidden` to leave it unchanged. This edit is **not
+     * undoable**. Locking and renaming are not exposed — layer `locked` is a
+     * read-only status here (setting it at runtime does not lock the live meshes or
+     * flip the panel padlock until a reload), and a rename cascades to every member
+     * mesh's `layerName`, a corruption hazard.
+     *
+     * @param layerId - The id of the layer to update.
+     * @param hidden - New hidden state (unchanged if omitted).
+     * @returns The updated {@linkcode PluginCoreLayer}.
+     * @throws If no layer has the given id.
+     *
+     * @examplePrompt Hide the PDF underlay layer
+     * @examplePrompt Show the CAD layer again
+     * @examplePrompt Hide layer ly_5
+     *
+     * # Example
+     * ```ts
+     * const layer = await snaptrude.core.layers.update("ly_5", true)
+     * ```
+     */
+    abstract update(layerId: string, hidden?: boolean): PluginApiReturn<PluginCoreLayersUpdateResult>;
+}
+/**
+ * The kind of a drawing layer.
+ *
+ * Author-drawable kinds (`floor`, `wall`, `ceiling`, `rough`, `default`) plus
+ * read-only imported underlays (`image`, `cad`, `pdf`, `terrain`, `buildings`).
+ */
+export declare const PluginCoreLayerType: z.ZodEnum<{
+    default: "default";
+    buildings: "buildings";
+    floor: "floor";
+    wall: "wall";
+    ceiling: "ceiling";
+    rough: "rough";
+    image: "image";
+    cad: "cad";
+    pdf: "pdf";
+    terrain: "terrain";
+}>;
+export type PluginCoreLayerType = z.infer<typeof PluginCoreLayerType>;
+/**
+ * A drawing/reference layer on a storey.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public layer id (e.g. `"ly_5"`) |
+ * | `name` | `string` | Display name |
+ * | `layerType` | {@linkcode PluginCoreLayerType} | The layer's kind |
+ * | `storeyId` | `string` | The stable id of the storey this layer belongs to |
+ * | `buildingId` | `string` | The stable id of the building this layer belongs to |
+ * | `hidden` | `boolean` | Whether the layer is hidden |
+ * | `locked` | `boolean` | Whether the layer is locked against edits |
+ * | `contentSummary` | `object` | A summary of what the layer holds (see below) |
+ *
+ * `contentSummary`:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `hasFloorplan` | `boolean` | Whether the layer holds drawn floorplan geometry |
+ * | `pdfCount` | `number` | Number of PDF underlays on the layer |
+ * | `hasTerrain` | `boolean` | Whether the layer holds terrain |
+ */
+export declare const PluginCoreLayer: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    layerType: z.ZodEnum<{
+        default: "default";
+        buildings: "buildings";
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+        rough: "rough";
+        image: "image";
+        cad: "cad";
+        pdf: "pdf";
+        terrain: "terrain";
+    }>;
+    storeyId: z.ZodString;
+    buildingId: z.ZodString;
+    hidden: z.ZodBoolean;
+    locked: z.ZodBoolean;
+    contentSummary: z.ZodObject<{
+        hasFloorplan: z.ZodBoolean;
+        pdfCount: z.ZodNumber;
+        hasTerrain: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginCoreLayer = z.infer<typeof PluginCoreLayer>;
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose layers to read |
+ * | `layerType` | {@linkcode PluginCoreLayerType}` \| undefined` | Optional layer-type filter |
+ */
+export declare const PluginCoreLayersListArgs: z.ZodObject<{
+    storeyId: z.ZodString;
+    layerType: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        buildings: "buildings";
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+        rough: "rough";
+        image: "image";
+        cad: "cad";
+        pdf: "pdf";
+        terrain: "terrain";
+    }>>;
+}, z.core.$strip>;
+export type PluginCoreLayersListArgs = z.infer<typeof PluginCoreLayersListArgs>;
+/**
+ * Result of {@linkcode PluginCoreLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layers` | {@linkcode PluginCoreLayer}`[]` | The storey's drawing layers (empty when missing or none match) |
+ */
+export declare const PluginCoreLayersListResult: z.ZodObject<{
+    layers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        layerType: z.ZodEnum<{
+            default: "default";
+            buildings: "buildings";
+            floor: "floor";
+            wall: "wall";
+            ceiling: "ceiling";
+            rough: "rough";
+            image: "image";
+            cad: "cad";
+            pdf: "pdf";
+            terrain: "terrain";
+        }>;
+        storeyId: z.ZodString;
+        buildingId: z.ZodString;
+        hidden: z.ZodBoolean;
+        locked: z.ZodBoolean;
+        contentSummary: z.ZodObject<{
+            hasFloorplan: z.ZodBoolean;
+            pdfCount: z.ZodNumber;
+            hasTerrain: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreLayersListResult = z.infer<typeof PluginCoreLayersListResult>;
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to read |
+ */
+export declare const PluginCoreLayersGetArgs: z.ZodObject<{
+    layerId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreLayersGetArgs = z.infer<typeof PluginCoreLayersGetArgs>;
+/**
+ * Result of {@linkcode PluginCoreLayersApi.get} — the layer, or `null`
+ * when no layer has the given id.
+ */
+export declare const PluginCoreLayersGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    layerType: z.ZodEnum<{
+        default: "default";
+        buildings: "buildings";
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+        rough: "rough";
+        image: "image";
+        cad: "cad";
+        pdf: "pdf";
+        terrain: "terrain";
+    }>;
+    storeyId: z.ZodString;
+    buildingId: z.ZodString;
+    hidden: z.ZodBoolean;
+    locked: z.ZodBoolean;
+    contentSummary: z.ZodObject<{
+        hasFloorplan: z.ZodBoolean;
+        pdfCount: z.ZodNumber;
+        hasTerrain: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+export type PluginCoreLayersGetResult = z.infer<typeof PluginCoreLayersGetResult>;
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.getActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose active layer to read |
+ */
+export declare const PluginCoreLayersGetActiveArgs: z.ZodObject<{
+    storeyId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreLayersGetActiveArgs = z.infer<typeof PluginCoreLayersGetActiveArgs>;
+/**
+ * Result of {@linkcode PluginCoreLayersApi.getActive} — the active layer,
+ * or `null` when the storey is missing or has no active layer.
+ */
+export declare const PluginCoreLayersGetActiveResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    layerType: z.ZodEnum<{
+        default: "default";
+        buildings: "buildings";
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+        rough: "rough";
+        image: "image";
+        cad: "cad";
+        pdf: "pdf";
+        terrain: "terrain";
+    }>;
+    storeyId: z.ZodString;
+    buildingId: z.ZodString;
+    hidden: z.ZodBoolean;
+    locked: z.ZodBoolean;
+    contentSummary: z.ZodObject<{
+        hasFloorplan: z.ZodBoolean;
+        pdfCount: z.ZodNumber;
+        hasTerrain: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+export type PluginCoreLayersGetActiveResult = z.infer<typeof PluginCoreLayersGetActiveResult>;
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to activate |
+ */
+export declare const PluginCoreLayersSetActiveArgs: z.ZodObject<{
+    layerId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreLayersSetActiveArgs = z.infer<typeof PluginCoreLayersSetActiveArgs>;
+/**
+ * Result of {@linkcode PluginCoreLayersApi.setActive} — the now-active
+ * layer's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the now-active layer |
+ */
+export declare const PluginCoreLayersSetActiveResult: z.ZodObject<{
+    layerId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreLayersSetActiveResult = z.infer<typeof PluginCoreLayersSetActiveResult>;
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to update |
+ * | `hidden` | `boolean \| undefined` | New hidden state (unchanged if omitted) |
+ */
+export declare const PluginCoreLayersUpdateArgs: z.ZodObject<{
+    layerId: z.ZodString;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginCoreLayersUpdateArgs = z.infer<typeof PluginCoreLayersUpdateArgs>;
+/** Result of {@linkcode PluginCoreLayersApi.update} — the updated layer. */
+export declare const PluginCoreLayersUpdateResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    layerType: z.ZodEnum<{
+        default: "default";
+        buildings: "buildings";
+        floor: "floor";
+        wall: "wall";
+        ceiling: "ceiling";
+        rough: "rough";
+        image: "image";
+        cad: "cad";
+        pdf: "pdf";
+        terrain: "terrain";
+    }>;
+    storeyId: z.ZodString;
+    buildingId: z.ZodString;
+    hidden: z.ZodBoolean;
+    locked: z.ZodBoolean;
+    contentSummary: z.ZodObject<{
+        hasFloorplan: z.ZodBoolean;
+        pdfCount: z.ZodNumber;
+        hasTerrain: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginCoreLayersUpdateResult = z.infer<typeof PluginCoreLayersUpdateResult>;
+//# sourceMappingURL=layers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../../src/api/core/layers.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,18 @@
+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();
+}
+export * from "./vec3";
+export * from "./quat";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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;;;;;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

@@ -0,0 +1,170 @@
+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 declare 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>;
+}
+//# sourceMappingURL=quat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quat.d.ts","sourceRoot":"","sources":["../../../../src/api/core/math/quat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEzE;;;;;;GAMG;AACH,8BAAsB,aAAa;;IAGjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACrF;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,IAAI,eAAe,CAAC,UAAU,CAAC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACpF;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IAChF;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC5E;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC;IAC5D;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC;IACpF;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;IACnE;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC;IACvE;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CACnB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,OAAO,CAAC,EAAE,MAAM,GACf,eAAe,CAAC,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAAC,cAAc,CAAC;CACpE"}