@snaptrude/plugin-core 0.0.5 → 0.0.7

package/src/api/entity/story.ts

@@ -1,27 +1,140 @@
 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 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)
+   * ```
+   */
   public 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})`)
+   * }
+   * ```
+   */
   public 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,
+   * })
+   * ```
+   */
   public 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,
+   * })
+   * ```
+   */
   public 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 const PluginStoryGetProperty = z.enum([
   "value",
   "id",
@@ -33,6 +146,14 @@ export const PluginStoryGetProperty = z.enum([
   "totalArea",
 ])
 
+/**
+ * Arguments for {@linkcode PluginStoryApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | The storey number to query |
+ * | `properties` | {@linkcode PluginStoryGetProperty}`[]` | Properties to retrieve |
+ */
 export const PluginStoryGetArgs = z.object({
   storyValue: z.number().int(),
   properties: z.array(PluginStoryGetProperty),
@@ -40,6 +161,12 @@ export const PluginStoryGetArgs = z.object({
 
 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 const PluginStoryGetResult = z
   .object({
     value: z.number(),
@@ -55,6 +182,13 @@ export const PluginStoryGetResult = z
 
 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 const PluginStoryGetAllResult = z.object({
   stories: z.array(
     z.object({
@@ -67,6 +201,14 @@ export const PluginStoryGetAllResult = z.object({
 
 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 const PluginStoryCreateArgs = z.object({
   storyValue: z.number().int(),
   height: z.number().optional(),
@@ -74,6 +216,14 @@ export const PluginStoryCreateArgs = z.object({
 
 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 const PluginStoryCreateResult = z.object({
   storyId: z.string(),
   storyValue: z.number(),
@@ -81,6 +231,14 @@ export const PluginStoryCreateResult = z.object({
 
 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 const PluginStoryUpdateArgs = z.object({
   storyValue: z.number().int(),
   height: z.number(),
@@ -88,6 +246,14 @@ export const PluginStoryUpdateArgs = z.object({
 
 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 const PluginStoryUpdateResult = z.object({
   storyValue: z.number(),
   height: z.number(),

package/src/api/index.ts

@@ -3,10 +3,24 @@ 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 abstract class PluginApi {
+  /** Core math and geometry primitives. See {@linkcode PluginCoreApi}. */
   public abstract core: PluginCoreApi
+  /** Selection and transform tools. See {@linkcode PluginToolsApi}. */
   public abstract tools: PluginToolsApi
+  /** CRUD operations on Snaptrude entities. See {@linkcode PluginEntityApi}. */
   public abstract entity: PluginEntityApi
+  /** Unit conversion utilities. See {@linkcode PluginUnitsApi}. */
   public abstract units: PluginUnitsApi
 
   constructor() {}

package/src/api/tools/index.ts

@@ -1,8 +1,16 @@
 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 abstract class PluginToolsApi {
+  /** Query the current selection. See {@linkcode PluginSelectionApi}. */
   public abstract selection: PluginSelectionApi
+  /** Move and rotate components. See {@linkcode PluginTransformApi}. */
   public abstract transform: PluginTransformApi
 
   constructor() {}

package/src/api/tools/selection.ts

@@ -1,12 +1,49 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 
+/**
+ * Query the current user selection in the Snaptrude editor.
+ *
+ * Accessed via `snaptrude.tools.selection`.
+ */
 export 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),
+   *   })
+   * }
+   * ```
+   */
   public abstract get(): PluginApiReturn<PluginSelectionGetResult>
 }
 
+/**
+ * Result of {@linkcode PluginSelectionApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `selected` | `string[]` | Component IDs of the current selection |
+ */
 export const PluginSelectionGetResult = z.object({
   selected: z.array(z.string()),
 })

package/src/api/tools/transform.ts

@@ -2,14 +2,78 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PVec3 } from "../core/math/vec3"
 
+/**
+ * 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 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),
+   * })
+   * ```
+   */
   public 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),
+   * })
+   * ```
+   */
   public abstract rotate({
     componentIds,
     angle,
@@ -18,6 +82,14 @@ export abstract class PluginTransformApi {
   }: 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 const PluginMoveArgs = z.object({
   componentIds: z.array(z.string()),
   displacement: PVec3,
@@ -25,6 +97,16 @@ export const PluginMoveArgs = z.object({
 
 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 const PluginRotateArgs = z.object({
   componentIds: z.array(z.string()),
   angle: z.number(),

package/src/api/units/index.ts

@@ -1,23 +1,43 @@
 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 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
+   *   - {@linkcode PluginUnitsConvertFromArgs.degree args.degree} — (Optional)
+   *     Degree of the unit: 1 for length, 2 for area, 3 for volume. Defaults to 1
+   * @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 },
+   * })
    * ```
    */
   public abstract convertFrom(
@@ -25,19 +45,33 @@ export abstract class PluginUnitsApi {
   ): 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
+   *   - {@linkcode PluginUnitsConvertToArgs.degree args.degree} — (Optional)
+   *     Degree of the unit: 1 for length, 2 for area, 3 for volume. Defaults to 1
+   * @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!,
+   *   degree: 2,
+   * })
    * ```
    */
   public abstract convertTo(
@@ -68,26 +102,60 @@ export const PUnitType = z.enum([
 
 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 |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) Degree of the unit (e.g. 1 for length, 2 for area, 3 for volume). Defaults to 1 |
+ */
 export const PluginUnitsConvertFromArgs = z.object({
   unit: PUnitType,
   value: z.number(),
+  degree: z.number().int().min(1).max(3).optional(),
 })
 
 export type PluginUnitsConvertFromArgs = z.infer<typeof PluginUnitsConvertFromArgs>
 
+/**
+ * Result of {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in Babylon units |
+ */
 export const PluginUnitsConvertFromResult = z.object({
   value: z.number(),
 })
 
 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 |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) Degree of the unit (e.g. 1 for length, 2 for area, 3 for volume). Defaults to 1 |
+ */
 export const PluginUnitsConvertToArgs = z.object({
   unit: PUnitType,
   value: z.number(),
+  degree: z.number().int().min(1).max(3).optional(),
 })
 
 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 const PluginUnitsConvertToResult = z.object({
   value: z.number(),
 })

package/src/types.ts

@@ -1,9 +1,16 @@
 /**
- * A ComponentId is a unique identifier for a component in the scene.
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
  */
 export type ComponentId = string
 
 /**
  * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
  */
 export type PluginApiReturn<T> = Promise<T> | T

package/tsup.config.ts

@@ -6,7 +6,6 @@ export default defineConfig( (options) => {
     format: ["cjs", "esm"],
     dts: false,
     sourcemap: true,
-    clean: true,
     onSuccess: "tsc", // Run tsc to generate d.ts and d.ts.map
     watch: options.watch,
   }