@snaptrude/plugin-core 0.2.1 → 0.2.2

package/src/api/entity/buildableEnvelope.ts

@@ -0,0 +1,277 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Buildable Envelope management — create and update parametric zoning envelopes.
+ *
+ * A **buildable envelope** is the regulated volume inside which a building may
+ * be massed. The host owns envelope identity: {@linkcode PluginBuildableEnvelopeApi.create create}
+ * mints a `buildableEnvelopeId` and returns it; {@linkcode PluginBuildableEnvelopeApi.update update}
+ * requires that id to target the existing envelope.
+ *
+ * Accessed via `snaptrude.entity.buildableEnvelope`.
+ */
+export abstract class PluginBuildableEnvelopeApi {
+  constructor() {}
+
+  /**
+   * Create a new parametric buildable envelope.
+   *
+   * @param args - A {@linkcode PluginBuildableEnvelopeCreateArgs} object.
+   * @returns A {@linkcode PluginBuildableEnvelopeCreateResult} with the
+   *   `buildableEnvelopeId` of the created envelope.
+   * @throws If validation fails or generation produces no renderable geometry.
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create({
+   *   sitePolygon: [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   lengthUnit: "ft",
+   *   setbacks: [
+   *     { aboveHeight: 0, front: 10, side: 5, rear: 10 },
+   *     { aboveHeight: 100, front: 20, side: 10, rear: 20 },
+   *   ],
+   *   verticalCap: { kind: "max_height", maxHeight: 150 },
+   *   floorToFloor: 12,
+   * })
+   * ```
+   */
+  public abstract create(
+    args: PluginBuildableEnvelopeCreateArgs
+  ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
+
+  /**
+   * Update an existing parametric buildable envelope.
+   *
+   * @param args - A {@linkcode PluginBuildableEnvelopeUpdateArgs} object.
+   *   `buildableEnvelopeId` is required and must match an existing envelope on
+   *   the canvas.
+   * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
+   *   `buildableEnvelopeId` of the updated envelope.
+   * @throws If validation fails, the envelope does not exist, or generation
+   *   produces no renderable geometry.
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update({
+   *   buildableEnvelopeId: existingId,
+   *   sitePolygon: [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   lengthUnit: "ft",
+   *   setbacks: [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+   *   verticalCap: { kind: "max_height", maxHeight: 175 },
+   *   floorToFloor: 12,
+   * })
+   * ```
+   */
+  public abstract update(
+    args: PluginBuildableEnvelopeUpdateArgs
+  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
+}
+
+/**
+ * Site polygon vertex in the request `lengthUnit`.
+ *
+ * Vertices may be passed as `{x, z}` objects or `[x, z]` tuples. Numeric
+ * values must be finite (no `NaN` or `±Infinity`).
+ */
+export const PluginBuildableEnvelopePolygonVertex = z.union([
+  z.object({ x: z.number().finite(), z: z.number().finite() }).strict(),
+  z.tuple([z.number().finite(), z.number().finite()]),
+])
+
+export type PluginBuildableEnvelopePolygonVertex = z.infer<
+  typeof PluginBuildableEnvelopePolygonVertex
+>
+
+/**
+ * Vertical cap for a buildable envelope.
+ *
+ * Use exactly one shape:
+ * - `{ kind: "max_height", maxHeight }`
+ * - `{ kind: "max_floors", maxFloors }`
+ *
+ * Floor-to-floor height is not nested here; it is always supplied as the
+ * top-level `floorToFloor` argument.
+ */
+export const PluginBuildableEnvelopeVerticalCap = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("max_height"),
+    maxHeight: z.number().finite().positive(),
+  }).strict(),
+  z.object({
+    kind: z.literal("max_floors"),
+    maxFloors: z.number().finite().int().positive(),
+  }).strict(),
+])
+
+export type PluginBuildableEnvelopeVerticalCap = z.infer<
+  typeof PluginBuildableEnvelopeVerticalCap
+>
+
+/**
+ * One tier of a buildable envelope's setback profile.
+ *
+ * Tiers are ordered by `aboveHeight`. The first tier (index 0) must have
+ * `aboveHeight: 0` and describes the ground footprint; each subsequent tier
+ * describes the complete setback at a strictly greater height. Each tier
+ * carries its own `front`, `side`, and `rear` values — there is no
+ * inheritance from earlier tiers.
+ *
+ * All numeric values must be finite and nonnegative, in the request
+ * `lengthUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `aboveHeight` | `number` | Height at or above which this tier applies; the ground tier uses `0` |
+ * | `front` | `number` | Front setback for this tier |
+ * | `side` | `number` | Side setback for this tier |
+ * | `rear` | `number` | Rear setback for this tier |
+ */
+export const PluginBuildableEnvelopeSetbackTier = z.object({
+  aboveHeight: z.number().finite().nonnegative(),
+  front: z.number().finite().nonnegative(),
+  side: z.number().finite().nonnegative(),
+  rear: z.number().finite().nonnegative(),
+}).strict()
+
+export type PluginBuildableEnvelopeSetbackTier = z.infer<
+  typeof PluginBuildableEnvelopeSetbackTier
+>
+
+// Enforces setback tier ordering invariants on the parsed args shape:
+//   - setbacks[0].aboveHeight === 0
+//   - aboveHeight strictly increasing thereafter
+// Length >= 1 is enforced earlier by z.array(...).min(1).
+function refineSetbackTiers(
+  args: { setbacks: PluginBuildableEnvelopeSetbackTier[] },
+  ctx: z.RefinementCtx
+): void {
+  const tiers = args.setbacks
+  if (tiers.length === 0) return
+  if (tiers[0].aboveHeight !== 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["setbacks", 0, "aboveHeight"],
+      message: "Ground tier required: setbacks[0].aboveHeight must be 0.",
+    })
+  }
+  for (let i = 1; i < tiers.length; i++) {
+    if (!(tiers[i].aboveHeight > tiers[i - 1].aboveHeight)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["setbacks", i, "aboveHeight"],
+        message:
+          "Setback tiers must be ordered by strictly increasing aboveHeight.",
+      })
+    }
+  }
+}
+
+/**
+ * Arguments for {@linkcode PluginBuildableEnvelopeApi.create}.
+ *
+ * Strict schema. The host owns identity — no `buildableEnvelopeId` is accepted
+ * on create; the id is minted by the host and returned in
+ * {@linkcode PluginBuildableEnvelopeCreateResult}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
+ * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
+ * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
+ * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
+ * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
+ * | `farRatio` | `number?` | Optional FAR value, positive when provided |
+ * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
+ */
+export const PluginBuildableEnvelopeCreateArgs = z
+  .object({
+    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
+    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
+    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: z.number().finite().positive(),
+    farRatio: z.number().finite().positive().optional(),
+    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
+  })
+  .strict()
+  .superRefine(refineSetbackTiers)
+
+export type PluginBuildableEnvelopeCreateArgs = z.infer<
+  typeof PluginBuildableEnvelopeCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginBuildableEnvelopeApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the created buildable envelope |
+ */
+export const PluginBuildableEnvelopeCreateResult = z.object({
+  buildableEnvelopeId: z.string().min(1),
+}).strict()
+
+export type PluginBuildableEnvelopeCreateResult = z.infer<
+  typeof PluginBuildableEnvelopeCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginBuildableEnvelopeApi.update}.
+ *
+ * Strict schema. `buildableEnvelopeId` is required and identifies the prior
+ * envelope on the canvas to update.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Existing envelope ID to update; non-empty |
+ * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
+ * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
+ * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
+ * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
+ * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
+ * | `farRatio` | `number?` | Optional FAR value, positive when provided |
+ * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
+ */
+export const PluginBuildableEnvelopeUpdateArgs = z
+  .object({
+    buildableEnvelopeId: z.string().min(1),
+    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
+    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
+    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: z.number().finite().positive(),
+    farRatio: z.number().finite().positive().optional(),
+    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
+  })
+  .strict()
+  .superRefine(refineSetbackTiers)
+
+export type PluginBuildableEnvelopeUpdateArgs = z.infer<
+  typeof PluginBuildableEnvelopeUpdateArgs
+>
+
+/**
+ * Result of {@linkcode PluginBuildableEnvelopeApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the updated buildable envelope |
+ */
+export const PluginBuildableEnvelopeUpdateResult = z.object({
+  buildableEnvelopeId: z.string().min(1),
+}).strict()
+
+export type PluginBuildableEnvelopeUpdateResult = z.infer<
+  typeof PluginBuildableEnvelopeUpdateResult
+>

package/src/api/entity/index.ts

@@ -1,3 +1,4 @@
+import { PluginBuildableEnvelopeApi } from "./buildableEnvelope"
 import { PluginDepartmentApi } from "./department"
 import { PluginReferenceLineApi } from "./referenceLine"
 import { PluginSpaceApi } from "./space"
@@ -10,6 +11,7 @@ import { PluginStoryApi } from "./story"
  * - {@linkcode PluginEntityApi.story} — Create, query, and update stories (floors)
  * - {@linkcode PluginEntityApi.referenceLine} — Create, query, and delete reference lines
  * - {@linkcode PluginEntityApi.department} — Create and query departments
+ * - {@linkcode PluginEntityApi.buildableEnvelope} — Create or update parametric buildable envelopes
  */
 export abstract class PluginEntityApi {
   /** Space (room/mass) operations. See {@linkcode PluginSpaceApi}. */
@@ -20,10 +22,13 @@ export abstract class PluginEntityApi {
   public abstract referenceLine: PluginReferenceLineApi
   /** Department operations. See {@linkcode PluginDepartmentApi}. */
   public abstract department: PluginDepartmentApi
+  /** Buildable Envelope operations. See {@linkcode PluginBuildableEnvelopeApi}. */
+  public abstract buildableEnvelope: PluginBuildableEnvelopeApi
 
   constructor() {}
 }
 
+export * from "./buildableEnvelope"
 export * from "./department"
 export * from "./referenceLine"
 export * from "./space"

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, update, and delete spaces.
+ * Space (room/mass) management — create, query, 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,63 +99,6 @@ 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.
    *
@@ -326,40 +269,6 @@ 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.
  *
@@ -397,7 +306,6 @@ export type PluginSpaceUpdateGeometryFromProfileResult = 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
@@ -423,7 +331,6 @@ export const PluginSpaceGetProperty = z.enum([
   "rotationQuaternion",
   // Derived from brep
   "planPoints",
-  "profile",
 ])
 
 /**
@@ -503,7 +410,6 @@ export const PluginSpaceGetResult = z
     rotationQuaternion: PQuat.nullable(),
     // Derived from brep
     planPoints: z.array(PVec3),
-    profile: PProfile,
   })
   .partial()