@snaptrude/plugin-core 0.0.4 → 0.0.6

package/dist/api/entity/story.d.ts

@@ -1,12 +1,125 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
+/**
+ * Story (floor/storey) management.
+ *
+ * A story represents a building floor in the Snaptrude project. Stories
+ * are identified by their integer **story value** (e.g. `1` for ground
+ * floor, `2` for first floor, `-1` for a basement).
+ *
+ * All methods are **host API calls** that return Promises and support
+ * undo/redo via Snaptrude's command system.
+ *
+ * Accessed via `snaptrude.entity.story`.
+ */
 export declare abstract class PluginStoryApi {
     constructor();
+    /**
+     * Get properties of a story by its storey number.
+     *
+     * Only the properties listed in {@linkcode PluginStoryGetArgs.properties args.properties}
+     * are returned — unlisted properties will be `undefined` in the result.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginStoryGetArgs.storyValue args.storyValue} — Integer storey number
+     *     (e.g. `1` for ground floor, `2` for first floor, `-1` for basement)
+     *   - {@linkcode PluginStoryGetArgs.properties args.properties} — Array of property names
+     *     to retrieve. See {@linkcode PluginStoryGetProperty} for available values.
+     * @returns A partial {@linkcode PluginStoryGetResult} containing only the requested properties
+     * @throws If the story with the given value does not exist
+     *
+     * # Example
+     * ```ts
+     * const info = await snaptrude.entity.story.get({
+     *   storyValue: 1,
+     *   properties: ["height", "name", "spacesCount"],
+     * })
+     * console.log(info.name, info.height, info.spacesCount)
+     * ```
+     */
     abstract get({ storyValue, properties, }: PluginStoryGetArgs): PluginApiReturn<PluginStoryGetResult>;
+    /**
+     * Get all stories in the current project.
+     *
+     * Returns basic identification data for every storey. Stories are sorted
+     * from **top to bottom** (highest story value first).
+     *
+     * @returns A {@linkcode PluginStoryGetAllResult} with a `stories` array,
+     *   each entry containing `value`, `id`, and `name`
+     *
+     * # Example
+     * ```ts
+     * const { stories } = await snaptrude.entity.story.getAll()
+     * for (const s of stories) {
+     *   console.log(`Story ${s.value}: ${s.name} (id: ${s.id})`)
+     * }
+     * ```
+     */
     abstract getAll(): PluginApiReturn<PluginStoryGetAllResult>;
+    /**
+     * Create a new story (floor) in the project.
+     *
+     * The new story is inserted at the position specified by
+     * {@linkcode PluginStoryCreateArgs.storyValue args.storyValue}. This
+     * operation is undoable.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginStoryCreateArgs.storyValue args.storyValue} — Integer storey number
+     *     to create (e.g. `3` to add a third floor)
+     *   - {@linkcode PluginStoryCreateArgs.height args.height} — Optional height in Babylon
+     *     units. If omitted, the project's default storey height is used.
+     * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
+     * @throws If a story with the given value already exists or creation fails
+     *
+     * # Example
+     * ```ts
+     * // Create a new third floor with custom height
+     * const { storyId } = await snaptrude.entity.story.create({
+     *   storyValue: 3,
+     *   height: 4.5,
+     * })
+     * ```
+     */
     abstract create({ storyValue, height, }: PluginStoryCreateArgs): PluginApiReturn<PluginStoryCreateResult>;
+    /**
+     * Update a story's height.
+     *
+     * Changes the floor-to-floor height of the specified story. This
+     * operation is undoable.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginStoryUpdateArgs.storyValue args.storyValue} — Integer storey number
+     *     identifying the story to update
+     *   - {@linkcode PluginStoryUpdateArgs.height args.height} — New height value in Babylon
+     *     units
+     * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
+     * @throws If the story does not exist or the update fails
+     *
+     * # Example
+     * ```ts
+     * // Set ground floor height to 5 Babylon units
+     * const result = await snaptrude.entity.story.update({
+     *   storyValue: 1,
+     *   height: 5,
+     * })
+     * ```
+     */
     abstract update({ storyValue, height, }: PluginStoryUpdateArgs): PluginApiReturn<PluginStoryUpdateResult>;
 }
+/**
+ * Available properties that can be queried on a story.
+ *
+ * | Value | Type | Description |
+ * |---|---|---|
+ * | `"value"` | `number` | The integer storey number |
+ * | `"id"` | `string` | Unique story identifier |
+ * | `"name"` | `string` | Display name of the story |
+ * | `"height"` | `number` | Floor-to-floor height in Babylon units |
+ * | `"base"` | `number` | Base elevation in Babylon units |
+ * | `"hidden"` | `boolean` | Whether the story is hidden in the viewport |
+ * | `"spacesCount"` | `number` | Number of spaces on this story |
+ * | `"totalArea"` | `number` | Total floor area of this story |
+ */
 export declare const PluginStoryGetProperty: z.ZodEnum<{
     height: "height";
     id: "id";
@@ -17,6 +130,14 @@ export declare const PluginStoryGetProperty: z.ZodEnum<{
     spacesCount: "spacesCount";
     totalArea: "totalArea";
 }>;
+/**
+ * Arguments for {@linkcode PluginStoryApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | The storey number to query |
+ * | `properties` | {@linkcode PluginStoryGetProperty}`[]` | Properties to retrieve |
+ */
 export declare const PluginStoryGetArgs: z.ZodObject<{
     storyValue: z.ZodNumber;
     properties: z.ZodArray<z.ZodEnum<{
@@ -31,6 +152,12 @@ export declare const PluginStoryGetArgs: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type PluginStoryGetArgs = z.infer<typeof PluginStoryGetArgs>;
+/**
+ * Result of {@linkcode PluginStoryApi.get}.
+ *
+ * A partial object — only the properties that were requested in
+ * {@linkcode PluginStoryGetArgs.properties} will be present.
+ */
 export declare const PluginStoryGetResult: z.ZodObject<{
     value: z.ZodOptional<z.ZodNumber>;
     id: z.ZodOptional<z.ZodString>;
@@ -42,6 +169,13 @@ export declare const PluginStoryGetResult: z.ZodObject<{
     totalArea: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PluginStoryGetResult = z.infer<typeof PluginStoryGetResult>;
+/**
+ * Result of {@linkcode PluginStoryApi.getAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `stories` | `Array<{ value, id, name }>` | All stories, sorted top to bottom |
+ */
 export declare const PluginStoryGetAllResult: z.ZodObject<{
     stories: z.ZodArray<z.ZodObject<{
         value: z.ZodNumber;
@@ -50,21 +184,53 @@ export declare const PluginStoryGetAllResult: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginStoryGetAllResult = z.infer<typeof PluginStoryGetAllResult>;
+/**
+ * Arguments for {@linkcode PluginStoryApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | The storey number for the new story |
+ * | `height` | `number?` | Optional height in Babylon units |
+ */
 export declare const PluginStoryCreateArgs: z.ZodObject<{
     storyValue: z.ZodNumber;
     height: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PluginStoryCreateArgs = z.infer<typeof PluginStoryCreateArgs>;
+/**
+ * Result of {@linkcode PluginStoryApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyId` | `string` | Unique ID of the created story |
+ * | `storyValue` | `number` | The storey number of the created story |
+ */
 export declare const PluginStoryCreateResult: z.ZodObject<{
     storyId: z.ZodString;
     storyValue: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginStoryCreateResult = z.infer<typeof PluginStoryCreateResult>;
+/**
+ * Arguments for {@linkcode PluginStoryApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number of the story to update |
+ * | `height` | `number` | New height in Babylon units |
+ */
 export declare const PluginStoryUpdateArgs: z.ZodObject<{
     storyValue: z.ZodNumber;
     height: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginStoryUpdateArgs = z.infer<typeof PluginStoryUpdateArgs>;
+/**
+ * Result of {@linkcode PluginStoryApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number of the updated story |
+ * | `height` | `number` | The new height after the update |
+ */
 export declare const PluginStoryUpdateResult: z.ZodObject<{
     storyValue: z.ZodNumber;
     height: z.ZodNumber;

package/dist/api/entity/story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/api/entity/story.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,8BAAsB,cAAc;;aAGlB,GAAG,CAAC,EAClB,UAAU,EACV,UAAU,GACX,EAAE,kBAAkB,GAAG,eAAe,CAAC,oBAAoB,CAAC;aAE7C,MAAM,IAAI,eAAe,CAAC,uBAAuB,CAAC;aAElD,MAAM,CAAC,EACrB,UAAU,EACV,MAAM,GACP,EAAE,qBAAqB,GAAG,eAAe,CAAC,uBAAuB,CAAC;aAEnD,MAAM,CAAC,EACrB,UAAU,EACV,MAAM,GACP,EAAE,qBAAqB,GAAG,eAAe,CAAC,uBAAuB,CAAC;CACpE;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;EASjC,CAAA;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;iBAG7B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE,eAAO,MAAM,oBAAoB;;;;;;;;;iBAWrB,CAAA;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,uBAAuB;;;;;;iBAQlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/api/entity/story.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;GAWG;AACH,8BAAsB,cAAc;;IAGlC;;;;;;;;;;;;;;;;;;;;;;OAsBG;aACa,GAAG,CAAC,EAClB,UAAU,EACV,UAAU,GACX,EAAE,kBAAkB,GAAG,eAAe,CAAC,oBAAoB,CAAC;IAE7D;;;;;;;;;;;;;;;;OAgBG;aACa,MAAM,IAAI,eAAe,CAAC,uBAAuB,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;aACa,MAAM,CAAC,EACrB,UAAU,EACV,MAAM,GACP,EAAE,qBAAqB,GAAG,eAAe,CAAC,uBAAuB,CAAC;IAEnE;;;;;;;;;;;;;;;;;;;;;;OAsBG;aACa,MAAM,CAAC,EACrB,UAAU,EACV,MAAM,GACP,EAAE,qBAAqB,GAAG,eAAe,CAAC,uBAAuB,CAAC;CACpE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;EASjC,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;iBAG7B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAWrB,CAAA;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;iBAQlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA"}

package/dist/api/index.d.ts

@@ -2,10 +2,24 @@ import { PluginCoreApi } from "./core";
 import { PluginEntityApi } from "./entity";
 import { PluginToolsApi } from "./tools";
 import { PluginUnitsApi } from "./units";
+/**
+ * Root API surface for Snaptrude plugins.
+ *
+ * Access all plugin capabilities through the namespaced properties:
+ *
+ * - {@linkcode PluginApi.core} — Math and geometry primitives
+ * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
+ * - {@linkcode PluginApi.tools} — Selection and transform tools
+ * - {@linkcode PluginApi.units} — Unit conversion utilities
+ */
 export declare abstract class PluginApi {
+    /** Core math and geometry primitives. See {@linkcode PluginCoreApi}. */
     abstract core: PluginCoreApi;
+    /** Selection and transform tools. See {@linkcode PluginToolsApi}. */
     abstract tools: PluginToolsApi;
+    /** CRUD operations on Snaptrude entities. See {@linkcode PluginEntityApi}. */
     abstract entity: PluginEntityApi;
+    /** Unit conversion utilities. See {@linkcode PluginUnitsApi}. */
     abstract units: PluginUnitsApi;
     constructor();
 }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAExC,8BAAsB,SAAS;IAC7B,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,SAAgB,KAAK,EAAE,cAAc,CAAA;;CAGtC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAExC;;;;;;;;;GASG;AACH,8BAAsB,SAAS;IAC7B,wEAAwE;IACxE,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,qEAAqE;IACrE,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,8EAA8E;IAC9E,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,iEAAiE;IACjE,SAAgB,KAAK,EAAE,cAAc,CAAA;;CAGtC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA"}

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

@@ -1,7 +1,15 @@
 import { PluginSelectionApi } from "./selection";
 import { PluginTransformApi } from "./transform";
+/**
+ * Snaptrude editor tools for querying and manipulating scene components.
+ *
+ * - {@linkcode PluginToolsApi.selection} — Query the current user selection
+ * - {@linkcode PluginToolsApi.transform} — Move and rotate components
+ */
 export declare abstract class PluginToolsApi {
+    /** Query the current selection. See {@linkcode PluginSelectionApi}. */
     abstract selection: PluginSelectionApi;
+    /** Move and rotate components. See {@linkcode PluginTransformApi}. */
     abstract transform: PluginTransformApi;
     constructor();
 }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD,8BAAsB,cAAc;IAClC,SAAgB,SAAS,EAAE,kBAAkB,CAAA;IAC7C,SAAgB,SAAS,EAAE,kBAAkB,CAAA;;CAG9C;AAED,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;GAKG;AACH,8BAAsB,cAAc;IAClC,uEAAuE;IACvE,SAAgB,SAAS,EAAE,kBAAkB,CAAA;IAC7C,sEAAsE;IACtE,SAAgB,SAAS,EAAE,kBAAkB,CAAA;;CAG9C;AAED,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/dist/api/tools/selection.d.ts

@@ -1,9 +1,46 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
+/**
+ * Query the current user selection in the Snaptrude editor.
+ *
+ * Accessed via `snaptrude.tools.selection`.
+ */
 export declare abstract class PluginSelectionApi {
     constructor();
+    /**
+     * Get the IDs of all currently selected components.
+     *
+     * Returns the component IDs from the editor's active selection stack.
+     * If nothing is selected, returns an empty array.
+     *
+     * The returned IDs can be used with {@linkcode PluginTransformApi.move},
+     * {@linkcode PluginTransformApi.rotate}, or entity query methods like
+     * {@linkcode PluginSpaceApi.get}.
+     *
+     * @returns A {@linkcode PluginSelectionGetResult} with a `selected` array
+     *   of component ID strings
+     *
+     * # Example
+     * ```ts
+     * const { selected } = await snaptrude.tools.selection.get()
+     * if (selected.length > 0) {
+     *   // Move selected components 5 units along X
+     *   await snaptrude.tools.transform.move({
+     *     componentIds: selected,
+     *     displacement: snaptrude.core.math.vec3.new(5, 0, 0),
+     *   })
+     * }
+     * ```
+     */
     abstract get(): PluginApiReturn<PluginSelectionGetResult>;
 }
+/**
+ * Result of {@linkcode PluginSelectionApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `selected` | `string[]` | Component IDs of the current selection |
+ */
 export declare const PluginSelectionGetResult: z.ZodObject<{
     selected: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;

package/dist/api/tools/selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/api/tools/selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,8BAAsB,kBAAkB;;aAGtB,GAAG,IAAI,eAAe,CAAC,wBAAwB,CAAC;CACjE;AAED,eAAO,MAAM,wBAAwB;;iBAEnC,CAAA;AAEF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/api/tools/selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;GAIG;AACH,8BAAsB,kBAAkB;;IAGtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,GAAG,IAAI,eAAe,CAAC,wBAAwB,CAAC;CACjE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;iBAEnC,CAAA;AAEF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}

package/dist/api/tools/transform.d.ts

@@ -1,10 +1,82 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
+/**
+ * Transform operations — move and rotate scene components.
+ *
+ * All transform methods accept an array of component IDs and apply the
+ * transformation to each. Operations are recorded in Snaptrude's
+ * command system for undo/redo support.
+ *
+ * Accessed via `snaptrude.tools.transform`.
+ */
 export declare abstract class PluginTransformApi {
     constructor();
+    /**
+     * Translate components by a displacement vector.
+     *
+     * Each component's position is offset by the given
+     * {@linkcode PluginMoveArgs.displacement displacement} vector.
+     * This operation is undoable.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginMoveArgs.componentIds args.componentIds} — Array of component
+     *     ID strings to move
+     *   - {@linkcode PluginMoveArgs.displacement args.displacement} — Translation vector
+     *     as a {@linkcode PVec3} in Babylon units
+     * @throws If any component ID is not found in the scene
+     *
+     * # Example
+     * ```ts
+     * const { vec3 } = snaptrude.core.math
+     *
+     * // Move a space 10 units along the X axis
+     * await snaptrude.tools.transform.move({
+     *   componentIds: ["some-space-id"],
+     *   displacement: vec3.new(10, 0, 0),
+     * })
+     * ```
+     */
     abstract move({ componentIds, displacement, }: PluginMoveArgs): PluginApiReturn<void>;
+    /**
+     * Rotate components around an axis through a pivot point.
+     *
+     * Each component is rotated by {@linkcode PluginRotateArgs.angle angle}
+     * radians around the {@linkcode PluginRotateArgs.axis axis} vector,
+     * pivoting about the {@linkcode PluginRotateArgs.pivot pivot} point.
+     * This operation is undoable.
+     *
+     * @param args - An object containing:
+     *   - {@linkcode PluginRotateArgs.componentIds args.componentIds} — Array of component
+     *     ID strings to rotate
+     *   - {@linkcode PluginRotateArgs.angle args.angle} — Rotation angle in **radians**
+     *   - {@linkcode PluginRotateArgs.axis args.axis} — Rotation axis as a {@linkcode PVec3}
+     *   - {@linkcode PluginRotateArgs.pivot args.pivot} — Pivot point as a {@linkcode PVec3}
+     *     in Babylon units
+     * @throws If any component ID is not found in the scene
+     *
+     * # Example
+     * ```ts
+     * const { vec3 } = snaptrude.core.math
+     *
+     * // Rotate a space 45° around the Y axis at the origin
+     * await snaptrude.tools.transform.rotate({
+     *   componentIds: ["some-space-id"],
+     *   angle: Math.PI / 4,
+     *   axis: vec3.new(0, 1, 0),
+     *   pivot: vec3.new(0, 0, 0),
+     * })
+     * ```
+     */
     abstract rotate({ componentIds, angle, axis, pivot, }: PluginRotateArgs): PluginApiReturn<void>;
 }
+/**
+ * Arguments for {@linkcode PluginTransformApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `string[]` | Component IDs to move |
+ * | `displacement` | {@linkcode PVec3} | Translation vector in Babylon units |
+ */
 export declare const PluginMoveArgs: z.ZodObject<{
     componentIds: z.ZodArray<z.ZodString>;
     displacement: z.ZodObject<{
@@ -14,6 +86,16 @@ export declare const PluginMoveArgs: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type PluginMoveArgs = z.infer<typeof PluginMoveArgs>;
+/**
+ * Arguments for {@linkcode PluginTransformApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `string[]` | Component IDs to rotate |
+ * | `angle` | `number` | Rotation angle in radians |
+ * | `axis` | {@linkcode PVec3} | Rotation axis direction |
+ * | `pivot` | {@linkcode PVec3} | Pivot point in Babylon units |
+ */
 export declare const PluginRotateArgs: z.ZodObject<{
     componentIds: z.ZodArray<z.ZodString>;
     angle: z.ZodNumber;

package/dist/api/tools/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/api/tools/transform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C,8BAAsB,kBAAkB;;aAGtB,IAAI,CAAC,EACnB,YAAY,EACZ,YAAY,GACb,EAAE,cAAc,GAAG,eAAe,CAAC,IAAI,CAAC;aAEzB,MAAM,CAAC,EACrB,YAAY,EACZ,KAAK,EACL,IAAI,EACJ,KAAK,GACN,EAAE,gBAAgB,GAAG,eAAe,CAAC,IAAI,CAAC;CAC5C;AAED,eAAO,MAAM,cAAc;;;;;;;iBAGzB,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAK3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/api/tools/transform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C;;;;;;;;GAQG;AACH,8BAAsB,kBAAkB;;IAGtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,IAAI,CAAC,EACnB,YAAY,EACZ,YAAY,GACb,EAAE,cAAc,GAAG,eAAe,CAAC,IAAI,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;aACa,MAAM,CAAC,EACrB,YAAY,EACZ,KAAK,EACL,IAAI,EACJ,KAAK,GACN,EAAE,gBAAgB,GAAG,eAAe,CAAC,IAAI,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;;iBAGzB,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAK3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

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

@@ -1,38 +1,67 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
+/**
+ * Unit conversion between real-world units and Snaptrude's internal
+ * (Babylon) coordinate system.
+ *
+ * Snaptrude uses an internal unit system (Babylon units) for all
+ * coordinates and dimensions. Use these methods to convert between
+ * real-world measurements and Babylon units.
+ *
+ * Accessed via `snaptrude.units`.
+ */
 export declare abstract class PluginUnitsApi {
     constructor();
     /**
-     * Convert a value from the given unit to Snaptrude's internal (Babylon) units.
+     * Convert a value from a real-world unit to Snaptrude's internal (Babylon) units.
      *
      * Use this when you have a measurement in real-world units (e.g. meters, feet)
      * and need to convert it to the coordinate system used by Snaptrude internally.
      *
-     * @param args.unit - The source unit to convert from (e.g. `"meters"`, `"feet-inches"`)
-     * @param args.value - The numeric value in the source unit
-     * @returns An object containing the converted `value` in Snaptrude/Babylon units
+     * @param args - An object containing:
+     *   - {@linkcode PluginUnitsConvertFromArgs.unit args.unit} — The source unit
+     *     to convert from. See {@linkcode PUnitType} for supported values.
+     *   - {@linkcode PluginUnitsConvertFromArgs.value args.value} — The numeric
+     *     value in the source unit
+     * @returns A {@linkcode PluginUnitsConvertFromResult} containing the converted
+     *   `value` in Babylon units
      *
-     * @example
+     * # Example
      * ```ts
+     * // Convert 5 meters to Babylon units for use in API calls
      * const result = await snaptrude.units.convertFrom({ unit: "meters", value: 5 })
-     * // result.value is 5 meters expressed in Babylon units
+     * const { spaceId } = await snaptrude.entity.space.createRectangular({
+     *   position: snaptrude.core.math.vec3.new(0, 0, 0),
+     *   dimensions: { width: result.value, height: result.value, depth: result.value },
+     * })
      * ```
      */
     abstract convertFrom(args: PluginUnitsConvertFromArgs): PluginApiReturn<PluginUnitsConvertFromResult>;
     /**
-     * Convert a value from Snaptrude's internal (Babylon) units to the given unit.
+     * Convert a value from Snaptrude's internal (Babylon) units to a real-world unit.
      *
      * Use this when you have a value in Snaptrude's internal coordinate system
      * and need to express it in real-world units (e.g. meters, feet).
      *
-     * @param args.unit - The target unit to convert to (e.g. `"meters"`, `"feet-inches"`)
-     * @param args.value - The numeric value in Snaptrude/Babylon units
-     * @returns An object containing the converted `value` in the target unit
+     * @param args - An object containing:
+     *   - {@linkcode PluginUnitsConvertToArgs.unit args.unit} — The target unit
+     *     to convert to. See {@linkcode PUnitType} for supported values.
+     *   - {@linkcode PluginUnitsConvertToArgs.value args.value} — The numeric
+     *     value in Babylon units
+     * @returns A {@linkcode PluginUnitsConvertToResult} containing the converted
+     *   `value` in the target unit
      *
-     * @example
+     * # Example
      * ```ts
-     * const result = await snaptrude.units.convertTo({ unit: "feet-inches", value: 1.2 })
-     * // result.value is 1.2 Babylon units expressed in feet
+     * // Get a space's area in square meters
+     * const info = await snaptrude.entity.space.get({
+     *   spaceId: "some-id",
+     *   properties: ["area"],
+     * })
+     * const areaInMeters = await snaptrude.units.convertTo({
+     *   unit: "meters",
+     *   value: info.area!,
+     * })
      * ```
      */
     abstract convertTo(args: PluginUnitsConvertToArgs): PluginApiReturn<PluginUnitsConvertToResult>;
@@ -58,6 +87,14 @@ export declare const PUnitType: z.ZodEnum<{
     miles: "miles";
 }>;
 export type PUnitType = z.infer<typeof PUnitType>;
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `unit` | {@linkcode PUnitType} | Source real-world unit |
+ * | `value` | `number` | Numeric value in the source unit |
+ */
 export declare const PluginUnitsConvertFromArgs: z.ZodObject<{
     unit: z.ZodEnum<{
         meters: "meters";
@@ -71,10 +108,25 @@ export declare const PluginUnitsConvertFromArgs: z.ZodObject<{
     value: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginUnitsConvertFromArgs = z.infer<typeof PluginUnitsConvertFromArgs>;
+/**
+ * Result of {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in Babylon units |
+ */
 export declare const PluginUnitsConvertFromResult: z.ZodObject<{
     value: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginUnitsConvertFromResult = z.infer<typeof PluginUnitsConvertFromResult>;
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convertTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `unit` | {@linkcode PUnitType} | Target real-world unit |
+ * | `value` | `number` | Numeric value in Babylon units |
+ */
 export declare const PluginUnitsConvertToArgs: z.ZodObject<{
     unit: z.ZodEnum<{
         meters: "meters";
@@ -88,6 +140,13 @@ export declare const PluginUnitsConvertToArgs: z.ZodObject<{
     value: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginUnitsConvertToArgs = z.infer<typeof PluginUnitsConvertToArgs>;
+/**
+ * Result of {@linkcode PluginUnitsApi.convertTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in the target unit |
+ */
 export declare const PluginUnitsConvertToResult: z.ZodObject<{
     value: z.ZodNumber;
 }, z.core.$strip>;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/units/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,8BAAsB,cAAc;;IAGlC;;;;;;;;;;;;;;;OAeG;aACa,WAAW,CACzB,IAAI,EAAE,0BAA0B,GAC/B,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;OAeG;aACa,SAAS,CACvB,IAAI,EAAE,wBAAwB,GAC7B,eAAe,CAAC,0BAA0B,CAAC;CAC/C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS;;;;;;;;EAQpB,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD,eAAO,MAAM,0BAA0B;;;;;;;;;;;iBAGrC,CAAA;AAEF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AAEF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF,eAAO,MAAM,wBAAwB;;;;;;;;;;;iBAGnC,CAAA;AAEF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,eAAO,MAAM,0BAA0B;;iBAErC,CAAA;AAEF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/units/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;GASG;AACH,8BAAsB,cAAc;;IAGlC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;aACa,WAAW,CACzB,IAAI,EAAE,0BAA0B,GAC/B,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;aACa,SAAS,CACvB,IAAI,EAAE,wBAAwB,GAC7B,eAAe,CAAC,0BAA0B,CAAC;CAC/C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS;;;;;;;;EAQpB,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;iBAGrC,CAAA;AAEF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AAEF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;iBAGnC,CAAA;AAEF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;iBAErC,CAAA;AAEF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA"}