@snaptrude/plugin-core 0.2.2 → 0.2.3

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()