@snaptrude/plugin-core 0.2.7 → 0.2.9

package/src/api/documentation/index.ts

@@ -0,0 +1,15 @@
+import { PluginDocumentationAIInspirationApi } from "./aiInspiration"
+
+/**
+ * Present documentation APIs for Snaptrude plugins.
+ *
+ * Accessed via `snaptrude.documentation`.
+ */
+export abstract class PluginDocumentationApi {
+  /** AI Inspiration image, video, workflow, and recipe APIs. */
+  public abstract aiInspiration: PluginDocumentationAIInspirationApi
+
+  constructor() {}
+}
+
+export * from "./aiInspiration"

package/src/api/entity/space.ts

@@ -320,7 +320,8 @@ export abstract class PluginSpaceApi {
    *
    * Each item targets an existing space by `spaceId` and may change its
    * geometry (`profile` + `extrudeHeight`, which must be supplied together) and/or
-   * its `properties` (`room_type`, `massType`, `spaceType`, `departmentId` —
+   * its `properties` (`room_type`, `massType`, `spaceType`, `areaClass`,
+   * `departmentId` —
    * nested under `properties`, mirroring {@linkcode PluginSpaceApi.update}). All
    * changes are batched into **one** command, so the entire batch is
    * undone/redone in a single step.
@@ -500,6 +501,7 @@ export type PluginSpaceUpdateGeometryFromProfileResult = z.infer<
  * | `"height"` | `number` | Height dimension |
  * | `"massType"` | `string \| null` | Mass type classification |
  * | `"spaceType"` | `string \| null` | Space type classification (Room, Balcony, etc.) |
+ * | `"areaClass"` | {@linkcode PluginAreaClass} | Effective area classification (`"NET"`, `"GROSS"`, or `"EXCLUDED"`), resolving any per-space override then the space-type default. Never null. |
  * | `"storey"` | `number \| null` | Story the space belongs to |
  * | `"departmentId"` | `string \| null` | Assigned department ID |
  * | `"departmentName"` | `string` | Assigned department name |
@@ -518,6 +520,8 @@ export type PluginSpaceUpdateGeometryFromProfileResult = z.infer<
  * |---|---|---|
  * | `"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. |
+ * | `"innerProfiles"` | {@linkcode PProfile}`[]` | Bottom inner profiles (holes) in world space, preserving line/arc curve data. Empty array when the space has no holes. |
+ * | `"innerPlanPoints"` | {@linkcode PVec3}`[][]` | One point loop per inner profile (hole) in world space with `y = 0` (2D plan). No closing duplicate point. Empty array when the space has no holes. |
  */
 export const PluginSpaceGetProperty = z.enum([
   // Basic
@@ -532,6 +536,7 @@ export const PluginSpaceGetProperty = z.enum([
   "height",
   "massType",
   "spaceType",
+  "areaClass",
   "storey",
   "departmentId",
   "departmentName",
@@ -544,6 +549,8 @@ export const PluginSpaceGetProperty = z.enum([
   // Derived from brep
   "planPoints",
   "profile",
+  "innerProfiles",
+  "innerPlanPoints",
   // Derived from adjacency manager
   "adjacency",
 ])
@@ -594,6 +601,21 @@ export const PluginSpaceType = z.enum([
   "Parking",
 ])
 
+/**
+ * Area classification for a space — controls which area total the space's
+ * footprint contributes to.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"NET"` | Counted toward the net (carpet) area total |
+ * | `"GROSS"` | Counted toward the gross (built-up) area total |
+ * | `"EXCLUDED"` | Counted toward neither total |
+ *
+ * The classification does **not** change a space's own footprint area — it
+ * only decides which project-level total that footprint is summed into.
+ */
+export const PluginAreaClass = z.enum(["NET", "GROSS", "EXCLUDED"])
+
 /**
  * Result of {@linkcode PluginSpaceApi.get}.
  *
@@ -614,6 +636,7 @@ export const PluginSpaceGetResult = z
     height: z.number(),
     massType: z.string().nullable(),
     spaceType: PluginSpaceType.nullable(),
+    areaClass: PluginAreaClass,
     storey: z.number().nullable(),
     departmentId: z.string().nullable(),
     departmentName: z.string(),
@@ -626,6 +649,8 @@ export const PluginSpaceGetResult = z
     // Derived from brep
     planPoints: z.array(PVec3),
     profile: PProfile,
+    innerProfiles: z.array(PProfile),
+    innerPlanPoints: z.array(z.array(PVec3)),
     // Derived from adjacency manager
     adjacency: z.array(z.object({
       spaceId: z.string(),
@@ -735,6 +760,7 @@ export const PluginDepartmentId = z.union([
  * | `properties` | `object` | Key/value pairs of properties to update (all optional) |
  * | `properties.room_type` | `string?` | New room type label |
  * | `properties.massType` | {@linkcode PluginMassType}`?` | New mass type |
+ * | `properties.areaClass` | {@linkcode PluginAreaClass}`?` | New area classification. Sets an explicit per-space override (`"NET"`, `"GROSS"`, or `"EXCLUDED"`) that wins over the space-type default. |
  * | `properties.departmentId` | {@linkcode PluginDepartmentId}`?` | New department ID |
  */
 export const PluginSpaceUpdateArgs = z.object({
@@ -743,6 +769,7 @@ export const PluginSpaceUpdateArgs = z.object({
     room_type: z.string().optional(),
     massType: PluginMassType.optional(),
     spaceType: PluginSpaceType.optional(),
+    areaClass: PluginAreaClass.optional(),
     departmentId: PluginDepartmentId.optional(),
   }),
 })
@@ -761,6 +788,7 @@ export type PluginSpaceUpdateArgs = z.infer<typeof PluginSpaceUpdateArgs>
  * | `room_type` | `string?` | Updated room type (if changed) |
  * | `massType` | `string?` | Updated mass type (if changed) |
  * | `spaceType` | `string?` | Updated space type (if changed) |
+ * | `areaClass` | {@linkcode PluginAreaClass}`?` | Updated area classification (if changed) |
  * | `departmentId` | `string \| null?` | Updated department ID (if changed) |
  */
 export const PluginSpaceUpdateResult = z.object({
@@ -768,6 +796,7 @@ export const PluginSpaceUpdateResult = z.object({
   room_type: z.string().optional(),
   massType: z.string().optional(),
   spaceType: z.string().optional(),
+  areaClass: PluginAreaClass.optional(),
   departmentId: z.string().nullable().optional(),
 })
 
@@ -871,6 +900,7 @@ export const PluginSpaceBulkUpdateItem = z.object({
       room_type: z.string().optional(),
       massType: PluginMassType.optional(),
       spaceType: PluginSpaceType.optional(),
+      areaClass: PluginAreaClass.optional(),
       departmentId: PluginDepartmentId.optional(),
     })
     .optional(),

package/src/api/index.ts

@@ -2,6 +2,7 @@ import { PluginCoreApi } from "./core"
 import { PluginEntityApi } from "./entity"
 import { PluginToolsApi } from "./tools"
 import { PluginUnitsApi } from "./units"
+import { PluginDocumentationApi } from "./documentation"
 
 /**
  * Root API surface for Snaptrude plugins.
@@ -12,6 +13,7 @@ import { PluginUnitsApi } from "./units"
  * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
  * - {@linkcode PluginApi.tools} — Copy, offset, selection, and transform tools
  * - {@linkcode PluginApi.units} — Unit conversion utilities
+ * - {@linkcode PluginApi.documentation} — Present documentation APIs
  */
 export abstract class PluginApi {
   /** Core math and geometry primitives. See {@linkcode PluginCoreApi}. */
@@ -22,11 +24,14 @@ export abstract class PluginApi {
   public abstract entity: PluginEntityApi
   /** Unit conversion utilities. See {@linkcode PluginUnitsApi}. */
   public abstract units: PluginUnitsApi
+  /** Present documentation APIs. See {@linkcode PluginDocumentationApi}. */
+  public abstract documentation: PluginDocumentationApi
 
   constructor() {}
 }
 
 export * from "./core"
+export * from "./documentation"
 export * from "./entity"
 export * from "./tools"
 export * from "./units"