@snaptrude/plugin-core 0.1.3 → 0.2.1

package/src/api/entity/space.ts

@@ -5,7 +5,7 @@ import { PQuat } from "../core/math/quat"
 import { PProfile } from "../core/geom/profile"
 
 /**
- * Space (room/mass) management — create, query, and delete spaces.
+ * Space (room/mass) management — create, query, update, and delete spaces.
  *
  * A **space** is a 3D volume representing a room or mass in the
  * Snaptrude scene. Spaces live on a particular story and carry
@@ -99,6 +99,63 @@ export abstract class PluginSpaceApi {
     position,
   }: PluginSpaceCreateFromProfileArgs): PluginApiReturn<PluginSpaceCreateFromProfileResult>
 
+  /**
+   * Update a space's BRep and mesh geometry by extruding a 2D profile.
+   *
+   * The {@linkcode PluginSpaceUpdateGeometryFromProfileArgs.profile profile} is
+   * extruded upward (along the Y axis) by
+   * {@linkcode PluginSpaceUpdateGeometryFromProfileArgs.extrudeHeight extrudeHeight}
+   * and applied to the existing space. The space keeps the same `spaceId`,
+   * metadata, department, and transform; only its geometry is replaced.
+   *
+   * Profile points are interpreted in scene coordinates. Profiles returned by
+   * {@linkcode PluginSpaceApi.get} with `"profile"` can be passed back directly;
+   * `"planPoints"` can be used to construct line-only profiles in the same X/Z
+   * plan coordinate space.
+   *
+   * Use {@linkcode PluginProfileApi.fromLinePoints} to quickly build a profile
+   * from a list of points.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceUpdateGeometryFromProfileArgs.spaceId args.spaceId} —
+   *     The unique space ID to update
+   *   - {@linkcode PluginSpaceUpdateGeometryFromProfileArgs.profile args.profile} —
+   *     A closed {@linkcode PProfile} defining the new floor shape
+   *   - {@linkcode PluginSpaceUpdateGeometryFromProfileArgs.extrudeHeight
+   *     args.extrudeHeight} — New extrusion height in Babylon units
+   * @returns A {@linkcode PluginSpaceUpdateGeometryFromProfileResult} with the
+   *   `spaceId` of the updated space
+   * @throws If the space does not exist, the component is not a space/mass, the
+   *   height is not positive, or the profile cannot create valid geometry
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const profile = await snaptrude.core.geom.profile.fromLinePoints({
+   *   points: [
+   *     vec3.new(0, 0, 0),
+   *     vec3.new(12, 0, 0),
+   *     vec3.new(12, 0, 6),
+   *     vec3.new(0, 0, 6),
+   *   ],
+   * })
+   *
+   * const { spaceId } = await snaptrude.entity.space.updateGeometryFromProfile({
+   *   spaceId: "some-space-id",
+   *   profile,
+   *   extrudeHeight: 4,
+   * })
+   * ```
+   */
+  public abstract updateGeometryFromProfile({
+    spaceId,
+    profile,
+    extrudeHeight,
+  }: PluginSpaceUpdateGeometryFromProfileArgs): PluginApiReturn<
+    PluginSpaceUpdateGeometryFromProfileResult
+  >
+
   /**
    * Get the IDs of all spaces in the current project.
    *
@@ -269,6 +326,40 @@ export type PluginSpaceCreateFromProfileResult = z.infer<
   typeof PluginSpaceCreateFromProfileResult
 >
 
+/**
+ * Arguments for {@linkcode PluginSpaceApi.updateGeometryFromProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | Space to update |
+ * | `profile` | {@linkcode PProfile} | Closed 2D profile defining the new floor shape |
+ * | `extrudeHeight` | `number` | New extrusion height in Babylon units |
+ */
+export const PluginSpaceUpdateGeometryFromProfileArgs = z.object({
+  spaceId: z.string(),
+  profile: PProfile,
+  extrudeHeight: z.number(),
+})
+
+export type PluginSpaceUpdateGeometryFromProfileArgs = z.infer<
+  typeof PluginSpaceUpdateGeometryFromProfileArgs
+>
+
+/**
+ * Result of {@linkcode PluginSpaceApi.updateGeometryFromProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | Unique ID of the updated space |
+ */
+export const PluginSpaceUpdateGeometryFromProfileResult = z.object({
+  spaceId: z.string(),
+})
+
+export type PluginSpaceUpdateGeometryFromProfileResult = z.infer<
+  typeof PluginSpaceUpdateGeometryFromProfileResult
+>
+
 /**
  * Available properties that can be queried on a space.
  *
@@ -306,6 +397,7 @@ export type PluginSpaceCreateFromProfileResult = z.infer<
  * | Value | Return Type | Description |
  * |---|---|---|
  * | `"planPoints"` | {@linkcode PVec3}`[]` | Bottom outer profile points in world space with `y = 0` (2D plan). No closing duplicate point. |
+ * | `"profile"` | {@linkcode PProfile} | Bottom outer profile in world space, preserving line/arc curve data. |
  */
 export const PluginSpaceGetProperty = z.enum([
   // Basic
@@ -331,6 +423,7 @@ export const PluginSpaceGetProperty = z.enum([
   "rotationQuaternion",
   // Derived from brep
   "planPoints",
+  "profile",
 ])
 
 /**
@@ -410,6 +503,7 @@ export const PluginSpaceGetResult = z
     rotationQuaternion: PQuat.nullable(),
     // Derived from brep
     planPoints: z.array(PVec3),
+    profile: PProfile,
   })
   .partial()
 

package/src/api/index.ts

@@ -10,13 +10,13 @@ import { PluginUnitsApi } from "./units"
  *
  * - {@linkcode PluginApi.core} — Math and geometry primitives
  * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
- * - {@linkcode PluginApi.tools} — Selection, transform and material tools
+ * - {@linkcode PluginApi.tools} — Copy, offset, 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, transform and material tools. See {@linkcode PluginToolsApi}. */
+  /** Copy, offset, selection, and transform tools. See {@linkcode PluginToolsApi}. */
   public abstract tools: PluginToolsApi
   /** CRUD operations on Snaptrude entities. See {@linkcode PluginEntityApi}. */
   public abstract entity: PluginEntityApi

package/src/api/tools/copy.ts

@@ -0,0 +1,55 @@
+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,24 +1,35 @@
-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/offset.ts

@@ -0,0 +1,43 @@
+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/dist/api/tools/material.d.ts

@@ -1,51 +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 declare 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
-     */
-    abstract apply({ materialName, componentIds, }: PluginMaterialArgs): PluginApiReturn<void>;
-}
-declare 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 declare const PluginMaterialArgs: z.ZodObject<{
-    materialName: z.ZodEnum<{
-        glass: DEFAULT_MATERIALS.GLASS;
-        wood: DEFAULT_MATERIALS.WOOD;
-        metal: DEFAULT_MATERIALS.METAL;
-        stone: DEFAULT_MATERIALS.STONE;
-        tiles: DEFAULT_MATERIALS.TILES;
-        concrete: DEFAULT_MATERIALS.CONCRETE;
-        brick: DEFAULT_MATERIALS.BRICK;
-    }>;
-    componentIds: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
-export type PluginMaterialArgs = z.infer<typeof PluginMaterialArgs>;
-export {};
-//# sourceMappingURL=material.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"material.d.ts","sourceRoot":"","sources":["../../../src/api/tools/material.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;GAIG;AACH,8BAAsB,iBAAiB;;IAGrC;;;;;;;OAOG;aACa,KAAK,CAAC,EACpB,YAAY,EACZ,YAAY,GACb,EAAE,kBAAkB,GAAG,eAAe,CAAC,IAAI,CAAC;CAC9C;AAED,aAAK,iBAAiB;IACpB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,KAAK,UAAU;IACf,KAAK,UAAU;IACf,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,KAAK,UAAU;CAChB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;iBAG7B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA"}

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>