@snaptrude/plugin-core 0.3.0 → 0.6.0

package/src/api/core/geom/profile.ts

@@ -1,94 +0,0 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { PVec3 } from "../math/vec3"
-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 abstract class PluginProfileApi {
-  constructor() {}
-
-  /**
-   * 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 {
-    return { curves }
-  }
-
-  /**
-   * 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),
-   *   ],
-   * })
-   * ```
-   */
-  public abstract fromLinePoints(
-    args: PluginProfileFromLinePointsArgs
-  ): PluginApiReturn<PProfile>
-}
-
-/**
- * Arguments for {@linkcode PluginProfileApi.fromLinePoints}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `points` | {@linkcode PVec3}`[]` | Ordered vertices of the profile |
- */
-export const PluginProfileFromLinePointsArgs = z.object({
-  points: z.array(PVec3),
-})
-
-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 const PProfile = z.object({
-  curves: z.array(PCurve),
-})
-
-export type PProfile = z.infer<typeof PProfile>

package/src/api/tools/copy.ts

@@ -1,55 +0,0 @@
-import * as z from "zod"
-import type { ComponentId } from "../../types"
-import { PVec3 } from "../core/math/vec3"
-
-/**
- * Copy mode for `snaptrude.tools.copy`.
- *
- * | Value | Description |
- * |---|---|
- * | `"instance"` | Create instanced copies where possible |
- * | `"unique"` | Create independent geometry copies |
- */
-export const PluginCopyMode = z.enum(["instance", "unique"])
-
-export type PluginCopyMode = z.infer<typeof PluginCopyMode>
-
-/**
- * Arguments for `snaptrude.tools.copy`.
- *
- * Creates one or more copies for each component in `componentIds`. Copy `i` is
- * offset by `displacement * i`, where `i` starts at `1`. Source positions are
- * preserved. In `"instance"` mode, a unique source mesh can be replaced by an
- * instance at the same position so the source and copied objects remain in the
- * same instance family. The created copy stack becomes the active editor
- * selection, matching the native paste workflow.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `componentIds` | `string[]` | Component IDs to copy |
- * | `displacement` | {@linkcode PVec3} | Offset applied to each copy in Babylon units |
- * | `count` | `number` | Number of copies per component. Defaults to `1` |
- * | `copyMode` | {@linkcode PluginCopyMode} | `"instance"` or `"unique"`. Defaults to `"instance"` |
- */
-export const PluginCopyArgs = z.object({
-  componentIds: z.array(z.string()).min(1),
-  displacement: PVec3,
-  count: z.number().int().positive().optional(),
-  copyMode: PluginCopyMode.optional(),
-})
-
-export type PluginCopyArgs = z.infer<typeof PluginCopyArgs>
-
-/**
- * Result of `snaptrude.tools.copy`.
- *
- * Returned IDs are Snaptrude component IDs for the newly created copies, not
- * Babylon mesh IDs.
- */
-export const PluginCopyResult = z.object({
-  copiedIds: z.array(z.string()),
-})
-
-export type PluginCopyResult = {
-  copiedIds: ComponentId[]
-}

package/src/api/tools/index.ts

@@ -1,39 +0,0 @@
-import { PluginMaterialApi } from "./material"
-import { PluginSelectionApi } from "./selection"
-import { PluginTransformApi } from "./transform"
-import type { PluginApiReturn } from "../../types"
-import type { PluginCopyArgs, PluginCopyResult } from "./copy"
-import type { PluginOffsetArgs, PluginOffsetResult } from "./offset"
-
-/**
- * Snaptrude editor tools for querying and manipulating scene components.
- *
- * - {@linkcode PluginToolsApi.selection} — Query the current user selection
- * - {@linkcode PluginToolsApi.transform} — Move and rotate components
- * - {@linkcode PluginToolsApi.copy} — Copy components
- * - {@linkcode PluginToolsApi.offset} — Offset or split component profiles
- */
-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
-  /** Apply materials to the current user selection in the Snaptrude editor or passed component ids if any. See {@linkcode PluginMaterialApi}. */
-  public abstract material: PluginMaterialApi
-
-  /** Copy components by ID. See {@linkcode PluginCopyArgs}. */
-  public abstract copy(args: PluginCopyArgs): PluginApiReturn<PluginCopyResult>
-
-  /** Offset or split a component profile. See {@linkcode PluginOffsetArgs}. */
-  public abstract offset(
-    args: PluginOffsetArgs,
-  ): PluginApiReturn<PluginOffsetResult>
-
-  constructor() {}
-}
-
-export * from "./copy"
-export * from "./offset"
-export * from "./selection"
-export * from "./transform"
-export * from "./material"

package/src/api/tools/material.ts

@@ -1,49 +0,0 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Apply materials to the current user selection in the Snaptrude editor or passed component ids if any.
- *
- * Accessed via `snaptrude.tools.material`.
- */
-export abstract class PluginMaterialApi {
-  constructor() {}
-
-  /**
-   * Apply materials to the current user selection in the Snaptrude editor or passed component ids if any.
-   *
-   * @param args - An object containing:
-   *   - {@linkcode PluginMaterialArgs.materialName args.materialName} — Material to apply
-   *   - {@linkcode PluginMaterialArgs.componentIds args.componentIds} — Array of component
-   *     ID strings to apply materials to if provided, if not provided, the current user selection will be used
-   */
-  public abstract apply({
-    materialName,
-    componentIds,
-  }: PluginMaterialArgs): PluginApiReturn<void>
-}
-
-enum DEFAULT_MATERIALS {
-  GLASS = 'glass',
-  WOOD = 'wood',
-  METAL = 'metal',
-  STONE = 'stone',
-  TILES = 'tiles',
-  CONCRETE = 'concrete',
-  BRICK = 'brick',
-}
-
-/**
- * Arguments for {@linkcode PluginMaterialApi.apply}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `materialName` | `DEFAULT_MATERIALS` | Material to apply |
- * | `componentIds` | `string[]` | Component IDs to apply materials to if provided |
- */
-export const PluginMaterialArgs = z.object({
-  materialName: z.enum(Object.values(DEFAULT_MATERIALS)),
-  componentIds: z.array(z.string()),
-})
-
-export type PluginMaterialArgs = z.infer<typeof PluginMaterialArgs>

package/src/api/tools/offset.ts

@@ -1,43 +0,0 @@
-import * as z from "zod"
-import type { ComponentId } from "../../types"
-import { PVec3 } from "../core/math/vec3"
-
-/**
- * Arguments for `snaptrude.tools.offset`.
- *
- * Runs Snaptrude's offset/split operation on the top profile of a scene
- * component. A positive distance offsets outward from the selected profile;
- * a negative distance offsets inward. If `profilePickPoint` is omitted, the
- * outer top profile is used. If `profilePickPoint` is provided, the nearest top
- * contour profile to that point is used, matching the interactive offset tool's
- * pick behavior.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `componentId` | `string` | Component ID to offset |
- * | `distance` | `number` | Signed offset distance in Snaptrude units |
- * | `profilePickPoint` | {@linkcode PVec3} | Optional point used to choose a top contour profile |
- */
-export const PluginOffsetArgs = z.object({
-  componentId: z.string().min(1),
-  distance: z.number(),
-  profilePickPoint: PVec3.optional(),
-})
-
-export type PluginOffsetArgs = z.infer<typeof PluginOffsetArgs>
-
-/**
- * Result of `snaptrude.tools.offset`.
- *
- * `createdIds` are the components created by the offset operation. `deletedIds`
- * are components removed by split-style offsets.
- */
-export const PluginOffsetResult = z.object({
-  createdIds: z.array(z.string()),
-  deletedIds: z.array(z.string()),
-})
-
-export type PluginOffsetResult = {
-  createdIds: ComponentId[]
-  deletedIds: ComponentId[]
-}

package/src/api/tools/selection.ts

@@ -1,51 +0,0 @@
-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()),
-})
-
-export type PluginSelectionGetResult = z.infer<typeof PluginSelectionGetResult>

package/src/api/tools/transform.ts

@@ -1,117 +0,0 @@
-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,
-    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 const PluginMoveArgs = z.object({
-  componentIds: z.array(z.string()),
-  displacement: PVec3,
-})
-
-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(),
-  axis: PVec3,
-  pivot: PVec3,
-})
-
-export type PluginRotateArgs = z.infer<typeof PluginRotateArgs>

package/src/api/units/index.ts

@@ -1,163 +0,0 @@
-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 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 - 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
-   * ```ts
-   * // Convert 5 meters to Babylon units for use in API calls
-   * const result = await snaptrude.units.convertFrom({ unit: "meters", value: 5 })
-   * 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(
-    args: PluginUnitsConvertFromArgs,
-  ): PluginApiReturn<PluginUnitsConvertFromResult>
-
-  /**
-   * 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 - 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
-   * ```ts
-   * // 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(
-    args: PluginUnitsConvertToArgs,
-  ): PluginApiReturn<PluginUnitsConvertToResult>
-}
-
-/**
- * Supported unit types for conversion.
- *
- * - `meters` — Metric meters
- * - `feet-inches` — Imperial feet (1 foot = 12 inches)
- * - `inches` — Imperial inches
- * - `centimeters` — Metric centimeters
- * - `millimeters` — Metric millimeters
- * - `kilometers` — Metric kilometers
- * - `miles` — Imperial miles
- */
-export const PUnitType = z.enum([
-  "meters",
-  "feet-inches",
-  "inches",
-  "centimeters",
-  "millimeters",
-  "kilometers",
-  "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 |
- * | `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(),
-})
-
-export type PluginUnitsConvertToResult = z.infer<typeof PluginUnitsConvertToResult>